=encoding iso-8859-1

=head1 NAME

bbd - bbbike data format description

=for category bbbike

=head1 DESCRIPTION

Sorry - parts of this documentation are still in German...

C<bbd> is a simple format for describing points and polylines for
geographic information systems.

Bbd files consist of newline-terminated records in the format:

    Name TAB Category SPACE x,y SPACE x,y ...

=head2 Coordinate lines (data lines)

=over

=item Name

A descriptive name, for example the street name, or (for attribute
layers) a description of the attribute category. This field must not
contain any TAB characters.

If there is a main name and a descriptive part, then the latter should
be separated by a C<|> character. This helps for intelligent
labelling, i.e. leaving out unimportant parts if necessary. Example:
B<Ringenwalde|(Uckermark)> could be labelled as B<Ringenwalde> or
B<Ringenwalde (Uckermark)>.

=item Category

The category of this point or polyline. If the category matches
C<#rrggbb> (where C<rr>, C<gg> and C<bb> are hexadecimal values), then
this denotes a color for the representation in the Perl/Tk interface.
A prefix of C<F:> denotes that the polyline should be treated as a
polygon and filled with a solid color. Note that the polygon is always
closed, but it is optional to make the first and last the same.

If the category matches I<forwardcat>C<;>I<backwardcat>, then
I<forwardcat> applies to the street in forward direction and
I<backwardcat> applies to the street in backward direction. Either
I<forwardcat> or I<backwardcat> may be empty; in this case the
category applies only to the other direction.

The B<X> category should be used if there is no category.

Other predefined categories are listed below. The category should not
contain any spaces.

   DRAFT (not yet in use!): Change the category format to:

       <cat> = <onewaycat> ; <onewaycat> |
               <onewaycat>

       <onewaycat> = F=? <basiccat> (: <attrkey> (= <attrval>)?)*

       <basiccat>  = [^:;]+
       <attrkey>   = [^:;=]+
       <attrval>   = [^:;=]+

   Changes for data files:
     F:cat becomes F=cat
     ?::inwork becomes ?:inwork
     F:SW|IMG:church.gif|ANCHOR:s becomes F=SW:IMG=church.gif:ANCHOR=s
   Maybe (no, too much typing):
     #rrggbb becomes X:COLOR=#rrggbb

   cat is now really attr. Reflect in description, maybe also in
   variable names.

=item x,y

A coordinate. x and y should be integer or float values. The datum and
grid of the coordinates should be handled by the software. It is
recommended that x and y should denote the easting and northing in
meters (as in GKK or UTM). A record may contain an unlimited number of
coordinates, though there may be limitations in the interpreting
software. See also below for the B<map> directive in L</Directive
lines>.

=back

=head2 Directive lines

If a line begines with a hash sign followed by a color (C<#:>), then
the line is treated as a directive. There are global directives, line
directives and block directives. Global directives should be specified
at top of the file before the first data line and should be separated
by the data lines with an empty directive line. For example:

 #: encoding: utf-8
 #: map: polar
 #:
 ... data lines

Line directives are valid for the next line only:

 #: add_fragezeichen: Is this really correct?
 Main street: bad cobblestone	Q3 13.5,52.5 13.4,52.5

Block directives are valid for the specified block. Block directives
are markes as such:

 #: directive_name directive_arguments ... vvv
 ... data lines
 #: directive_name ^^^

The C<v> and C<^> markers can be repeated an indefinite number of
times, but at least three times.

Directives have always at least the directive name (the first word
token in the line) and zero, one or more directive values:

 #: directive_name
 #: directive_name: val1
 #: directive_name: val1 val2

The colon (:) after the directive name is optional. The following is
equivalent:

 #: encoding utf-8
 #: encoding: utf-8

=head3 Global directives

=over

=item C<type: I<bbd_type>>

This global directive sets the type of the bbd file. If given then it
should be put into the first line to serve as a kind of
E<quot>magicE<quot>. A possible type would be C<bbr> or C<bbbike
route>, once I get rid of the .bbr format.

=item C<map: I<maptype>>

This global directive sets the coordinate system of the bbd file. If
no C<map> directive is specified, then the proprietary bbbike
coordinate system is used. For WGS84 coordinates specified as DDD use
the maptype B<polar>.

=item C<title: I<title string>>

This global directive sets the title or some descriptive text for the
file.

It is possible to localize the title by using the C<< title.I<$lang> >> syntax, e.g.

    title.en: English title
    title.de: deutscher Titel

=item C<version: I<RCS or CVS identifier string>>

This global directive introduces an RCS/CVS Id string. Not recommended
if a modern version controlling system like git is used.

=item C<encoding: I<encoding name>>

Treat this file as encoded in the given encoding (all names accepted
by Perl's L<Encode> may be used, see L<Encode::Supported>). If not
set, then iso-8859-1 is assumed.

The degree of support for encodings in bbbike.cgi and the Perl/Tk
implementation differs. iso-8859-1 is supported best. utf-8 is
considered to work in most, if not all places of the code. Other
encodings are at least known to NOT work with the XS implementation
for the fast street and point plotting. The pure perl implementation
is fine.

=item C<listing_sort: I<sort_method>>

Define a sorting method for street/point listings. Normally listings
will be sorted alphabetically (sort method B<alphabetic>). If the
listing should appear as in the bbd file, specify B<unsorted>.
B<natural> should be used for E<quot>naturalE<quot> sorting (see
L<Sort::Naturally>).

=back

=head3 Plotting hint directives

Plotting hint directives are used to control plotting of items. The
directives can only be set as global directives. The directives
explained below exist in two forms:

=over

=item C<I<directive>: ...>

The directive is valid for all items (unless overriden by per-category
directives).

=item C<I<directive>.I<category>: ...>

The directive is valid for items with the named I<category> (this
overrides directives without category specification).

=back

The list of plotting hint directives:

=over

=item C<line_color: I<color>>

=item C<line_color.I<category>: I<color>>

Define the color for line items. I<color> should be in the form
C<#rrggbb>.

Example:

 #: line_color: #808080
 #: line_color.cat: #ff8080

Compatibility: C<category_color.I<category>> is still recognized as an
alternative to C<line_color.I<category>>. Maybe this will removed some
day.

XXX: Maybe use C<item_color> instead of C<line_color>, because colors
apply also to points and areas!

XXX: Hmmm, it seems that str_color is (also?) in use, see
tmp/streets-accurate.bbd

=item C<line_width: I<width>>

=item C<line_width.I<category>: I<width>>

Define the width of line items. The width should either be one value,
or six comma-separated values. If it's only one value, then it is
taken as the width at approx. 1:17000, and other widths are calculated
proportionally to $line_width{default}. If it's six values, then this
should represent the widths for the six standard scales defined by
bbbike.

=item C<line_length: I<length>>

=item C<line_length.I<category>: I<length>>

Define the length of line items. In the Perl/Tk interface this is
currently used for oneway and blocked symbols.

XXX: The form with category is NYI!

XXX: Maybe this should make it possible to define lengths for specific
zoom levels, like in the bbbike standard definitions.

=item C<line_dash: I<x, y, ...>>

=item C<line_dash.I<category>: I<x, y, ...>>

Define the default dash pattern for line items. See L<Tk::Canvas/DASH
PATTERNS> for the list integer syntax.

Example:

 #: line_dash: 1,1
 #: line_dash: 2,4

Compatibility: C<category_dash.I<category>> was formerly used instead
of C<line_dash.I<category>> and is still recognized, but will be
removed some day.

=item C<line_capstyle: I<capstyle>>

=item C<line_capstyle.I<category>: I<capstyle>>

Define the capstyle for line items. Valid values are C<butt>,
C<projecting>, or C<round> (see L<Tk::Canvas>).

XXX: Currently C<category_capstyle.category> is used instead of
C<line_capstyle.category>.

=item C<line_arrow: I<arrowspec>>

=item C<line_arrow.I<category>: I<arrowspec>>

Define whether arrows should be drawn on line items. Valid values
are C<none>, C<last>, C<first>, or C<both> (see L<Tk::Canvas>).

Example:

 #: line_arrow: last
 #: line_arrow.cat: both

Currently setting the C<line_arrow> directive (without category) to
C<last> has also the effect to center to the beginning of a feature
selected in the street list of the Perl/Tk application (otherwise the
default is the center of the feature).

=item C<line_shorten: I<boolean>>

=item C<line_shorten.I<category>: I<boolean>>

Define whether line items should be shortened on both ends.

XXX: Currently C<category_line_shorten.category> is used instead of
C<line_shorten.category>.

=item C<line_shorten_end: I<boolean>>

=item C<line_shorten_end.I<category>: I<boolean>>

Define whether line items should be shortened at the end.

XXX: Currently C<category_line_shorten_end.category> is used instead
of C<line_shorten_end.category>.

=item C<line_directed_weight: I<boolean>>

=item C<line_directed_weight.I<category>: I<boolean>>

Define whether lines are directed and present weights.

=item C<line_do_offset: I<boolean>>

=item C<line_do_offset.I<category>: I<boolean>>

Define whether lines should be plotted with an offset or not. By
default, lines which have a "splitted" category for the forward and
backward directory (e.g. C<A;B>) are plotted with an offset, but this
can be disabled by explicitely setting line_do_offset to a false
value.

=item C<item_size: I<integer>>

=item C<item_size.I<category>: I<integer>>

Define the size of items (for example base label font size or the size
of point items in pixels).

XXX: The category-less form is NYI!
XXX: Currently C<category_size.category> is used instead
C<item_size.category>.

=item C<item_image: I<image_name>>

=item C<item_image.I<category>: I<image_name>>

Define an image for point items. The image name is usually without
suffix and will be searched in the default bbbike image directories,
if specified relative.

XXX: The category-less form is NYI!
XXX: Currently C<category_image.category> is used instead
C<item_image.category>.

=item C<item_stipple: I<image_name>>

=item C<item_stipple.I<category>: I<image_name>>

Define a stipple (which is usually an xbm image) for area items.

XXX: The category-less form is NYI!
XXX: Currently C<category_stipple.category> is used instead C<item_stipple.category>.

=item C<layer_stack: I<how>:I<tag>>

Define how the data should appear in the layer stacking order. I<how>
is either C<above> or C<below> and I<tag> is another layering tag used
in bbbike (some examples are C<s> for the street layer or C<w> for the
water layer --- consult the bbbike source, variable
C<@normal_stack_order> for more tags).

XXX This is experimental and likely to change!

=back

=head3 Line/block directives

=over

=item C<by: I<source>>

=item C<according_to: I<source>>

Denotes that the information in the next block or line was provided by
I<source>. This may be an email address or full name of an author, an
URL providing more information, a Message-Id of a mail or posting, a
date, or a combination of all. C<according_to:> is an alias for
C<by:>.

=item C<by[nocache]>: I<URL>>

Like the L</by> directive, but the value must be an URL, and it is
marked as non-cacheable (for whatever reasons), but still linkable.

=item C<by[removed]>: I<URL>>

Like the L</by> directive, but the value must be an URL, and it is
marked as removed, probably generating a 404 response or the site does
not exist at all.

=item C<corrected_by: I<source> I<< previous -> current >> >

Used after a C<by> directive for a correction. It is advisable to put
the previous a small note of the previous and maybe also the current
entry after the I<source>.

=item C<confirmed_by: I<source>>

Denotes that the information in the next block or line was confirmed
by I<source>.

=item C<source_id: I<id>>

A special form of a C<by> directive where a formal id can be used.
Currently there are three id schemes in use: C<viz2021> (a pseudo id
for VIZ traffic reports), C<bvg2021> and C<bvg2024> (BVG traffic
reports: prefixed by the affected line, then a C<#>, then the id), and
scheme-less (a real VIZ id). Sometimes also other forms of pseudo ids
or even URLs are used here.

Note that it is allowed to use a real VIZ id followed by a viz2021
pseudo id (separated by a space).

=item C<source_id[inactive]: I<id>>

An inactive source id (typically not accessible anymore at the source
site and/or expired).

=item C<valid: YYYYMMDD-YYYYMMDD>

=item C<valid: YYYYMMDD->

=item C<valid: -YYYYMMDD>

Define the validity period of records. Other tools (e.g.
L<grepstrassen>) may remove non-valid records automatically.

If the value is preceded by a C<!>, then the validation period is
inverted.

Note: in future L<Strassen::Core> may deal automatically (or optional)
with removal of non-valid records.

NOTE: Makefile rules don't cope well with the ability that source
files are processed differently depending on time.

=item C<temporary:>

The next block or line is just a temporary feature. Typically there's
one large "temporary" block per bbd file, and typically entries within
this block are accompanied by C<next_check> directives to specify the
end date, so systems like "fragezeichen-nextcheck" can include these
entries in their lists.

=item C<XXX: I<why>>

The next block or line is unsure or unclear information, and usually
has to be researched on-site. The I<why> text specifies an additional
comment. This note should not appear in the processed data.

Earlier versions also defined C<unsure> as an alias for C<XXX> (or
even the other way around), but in reality C<unsure> was almost never
used and also never considered in supporting scripts, so its use is
now deprecated.

=item C<XXX_prog: I<why>>

The next block or line contains problematic information due to
problems in the using programs, i.e. bbbike and bbbike.cgi.

For example this can be used if stacking information has to be given
using ordering in the data file, but bbbike should really have a
layer_stack attribute.

In the past it was also used for the cyclepath layer, because of
suboptimal rendering in points with large angles (more than 45° or
so). Here the layer item has to be broken into two items to fix the
rendering problem. But this is solved in bbbike since July 2009.

=item C<XXX_indoor: I<why>>

The unclear information can only be researched E<quot>indoorE<quot>,
and usually not on-site.

=item C<XXX_osm: I<why>>

An issue in OpenStreetMap data, e.g. incorrectly spelled street name
or wrong ways.

=item C<alias: I<name>>

Define another known name for the next line.

=item C<alias_wide: I<name>>

Special alias name to be used for E<quot>wide regionE<quot> routings.
In E<quot>inner cityE<quot> routing the real name should be used
instead.

Examples:

    #: alias_wide: Oranienburg - Bernau (B273)
    Bernauer Str. (B273)	B ...,...

=item C<name: I<lang>: I<name>>

The name in another language, specified by I<lang> in ISO 639 codes.

=item C<oldname: I<when>: I<name>>

An old name for the next line. I<when> is a time specification (best:
some kind of ISO dates, but this is not yet specified). Unknown dates
in I<when> should be marked with a question mark. Multiple oldname
directives are allowed for one record.

Examples:

    #: oldname: ?-20001001: Oldname street
    #: oldname: 20001001-2005: Not-so-old-name street

=item C<ignore_oldname_file: yes>

Ignore this oldname entry when generating the F<oldnames> data file.
This is useful if for example only a part of the street was renamed.

=item C<ignore_check_net: yes>

Ignore this entry for "within network" checks.

=item C<carriageway_width: I<width>>

Width of the carriageway, that is, kerb to kerb. Usually a length like
I<numbers>m, but may also be informal (e.g. "6 lanes"). Used only in
F<strassen> or F<landstrassen>.

=item C<street_width: I<width>>

Width of the street, that is, including sidewalks and cyclepaths,
house to house. Usually a length like I<numbers>m. Used only in
F<strassen> or F<landstrassen>.

=item C<related>

Group related items. Currently used to group related traffic lights in
F<ampeln>. Can be used without an value, or with the value
C<antidromic>.

=item C<section: I<section name>>

The next block is part of a named section. Sections may be nested.

=item C<ignore>

The next line/block is ignored for some processing instructions. For
example, "busroute_N" entries in F<comments_misc-orig> are skipped when
creating F<comments_misc>.

=item C<append_comment: I<comment>>

Useful for preprocessing bbd data files to add a comment to each
record in the block.

=item C<attributes: I<attribute>, ...>

=item C<attrs: I<attribute>, ...>

Define additional attributes for the following line or block. The
attributes may be used in a preprocessing script to generate
additional layers. C<attrs> is an alias for C<attributes>.

=item C<note: I<string>>

A free text note, which shouldn't (but may) appear in the processed
data.

=item C<see_also: I<string>>

A free text note, which refers to more information. This should be
typically a URL.

=item C<last_checked: I<date>>

=item C<last_checked: I<date> (I<source>)>

Date (and optionally surveyor) of the last check for a feature. This
is useful in conjunction with C<XXX> or C<add_fragezeichen>
directives, to generate automatic list of streets to be surveyed
again.

=item C<next_check: I<date>>

=item C<next_check: I<date> (I<source>)>

Recommended date for a next survey for a feature. This could be for
instance the intended finish date of road construction.

For generating survey lists, it could also be useful to generate
synthetic C<next_check> directives out of C<last_checked> value, e.g.
one month after the last check. The default interval could be set by
the C<check_frequency> directive.

=item C<check_frequency>: I<days>C<d>

Set a check frequency for the synthetic generationg of C<next_check>
directives. If not set, then the default could be one month or so.

=item C<next_check_id: I<identifier>>

Used to group related to-be-surveyed feature, possibly spread over
multiple files. Should be used only if there are really multiple
features.

The bbbike emacs major mode generates buttons for these directives;
clicking on these buttons would start a search for this identifier
over all data files.

=item C<also_indoor: I<spec>>

Checks which may be done indoor. I<spec> may have the following
values:

=over

=item C<search> I<term>

Link to a search engine with the given search term.

=item C<traffic>

Link to a traffic map at the coordinate of the item.

=item C<url> I<url>

Link to a specific URL.

=item C<webcam> I<url>

Link to a specific URL, which is expected to show webcam imagery.

=back

Currently the script F<miscsrc/fragezeichen2org.pl> may handle
C<also_indoor> directives.

=item C<as_of: I<date>>

Last verified at the given date. The date should be in a ISO-8601-like
notation, with possible abbreviations: YYYY-MM-DD or YYYY-MM or YYYY.

The difference between C<last_checked> and C<as_of> is subtle; it is
expected that C<last_checked>-tagged entries should be actively
checked for changes, and C<as_of>-tagged entries only passively.

Currently C<as_of> directives appear in F<data/comments_ferry-orig>
for ferry timetable and fare information.

=item C<url: I<string>>

An (official) URL referring to more information useful for end users,
like opening or operating hours or fees. For other kind information
use the C<by:> directive.

=item C<url[gpx]: I<string>>

Link to a URL which contains a related GPX file. Usually used in
F<comments_route>.

=item C<add_fragezeichen: I<string>>

Some postprocessing code may add the following line with the
descriptive text I<string> to the F<fragezeichen> file.

=item C<osm_watch: relation|way|node id="I<element_id>" version="I<version>">

=item C<osm_watch: note I<note_id> I<comment_num>>

=item C<osm_watch[closed]: note I<note_id> I<comment_num>>

Link the following bbd item to an OpenStreetMap (OSM) element
(C<relation>, C<way>, C<node>) or note. I<version> or I<comment_num>
specify the latest checked version. The C<[closed]> variant is used
for notes which are already closed.

C<osm_watch> directives cause links when editing C<.bbd> files using
emacs with C<bbbike-mode>. F<miscsrc/fragezeichen2org.pl> also
generates links. F<miscsrc/check-osm-watch-list.pl> may be used to
find changed OSM elements and notes (the watch list for this script is
created by F<miscsrc/bbd_to_osm_watch_list>).

=item C<complete: yesI<|>no>

May be used to mark a feature as complete or incomplete (e.g. cycle
routes).

=item C<priority: I<string>>

A priority for checks. The priority string should be something between
C<#A> (highest, use for features which are important for many
routings) and C<#D> (lowest, use for features which are not used at
all for routings, e.g. zebras).

=item C<linked: I<string>>

May be used for check purposes. Currently only utilized in
F<ortsschilder-orig>, where the linked name is to be used to do checks
against F<orte-orig>/F<orte2-orig>.

=item C<source_file: I<filename>>

For generated files: the generated lines originate from the specified
I<filename>. This is usually specified as a non-block directive;
another C<source_file> directive would switch to a different source
file.

=item C<source_line: I<number>>

For generated files: the generated lines originate at the specified
line number. This directive has to be specified together with
L</source_file>.

=item C<id: I<string>>

An identifier string.

=item C<osm.highway: I<string>>

The value of an L<OSM highway
key|https://wiki.openstreetmap.org/wiki/Key:highway>. May be used when
converting bbd data to osm data, e.g. by L<bbd2osm>.

=item C<map_tube_other_link: I<type>:I<other_station>>

Used when generating data for L<Map::Tube> (e.g. L<Map::Tube::Berlin>)
for generating links between stations with a different name.

Example usage:

    #: map_tube_other_link: Street:Rathaus Spandau

The type (in this case "Street") denotes the kind of the link.

This directive is currently used in F<ubahnhof> and F<sbahnhof>.

=item C<off: I<YYYY-MM-DD WWW HH:MM> I<rest>>

Mark feature as being off at the specified time. Usually used for
traffic lights which are usually on, so it's found in F<ampeln-orig>.
I<WWW> is the weekday, or the string C<holiday>. I<HH:MM> may be
preceded by a C<~> if the time is not exact. The I<rest> part is
optional and if used, must follow after a tab character and consist of
one or more key=value pairs (e.g. C<by=...>, C<note=...>, also
separated by tab characters.

Example entries:

    #: off: 2001-12-25 holiday ~20:00	
    #: off: 2025-09-08 Mon 06:45 <tab> by=me <tab> note=something

=item C<off_rule: I<rule> I<rule> ... I<rest>>

One or more rule labels (separated by spaces) for off times. Currently
the following rule labels may be used:

=over

=item holiday

State holidays valid for this area.

=item weekend

Sat+Sun

=item Sat

=item Sun

Other weekday names may also be used, if needed

=item night

=item night=22:00..

=item night=22:00..05:00

The start and end time may be specified if known.

=item schooltime

=item outside_schooltime

=item businesstime

=item outside_businesstime

=item event

This one is usually used with C<on_rule> directives.

=back

Each rule label may have a C<?> attached if the rule is not certain.

=item C<on: I<YYYY-MM-DD WWW HH:MM> I<rest>>

Used in F<ampeln-orig> if a traffic light is (unexpectedly) on. Can
also be used as a data point for specifying exact on/off rules.

=item C<on_rule: I<rule> I<rule> ... I<rest>>

Use for traffic lights which are most of the time off. Notable
examples could be traffic lights which are only on during events (in
Berlin there are examples found around Olympiastadion). Usually such
traffic lights have the category C<X0> or C<F0>.

=back

=head3 Obsolete and to-be-decided directives

=over

=item C<internal_note: I<string>>

A free text note, which must not appear in the processed data. It is
just a note for editors.

Currently I think the C<XXX_...> is better suited for this task, as it
can give more specific information.

=item C<historical_note: I<string>>

A free text note with former data regarding the associated record.
Sometimes this may also be fetched using the version control system,
but this is sometimes cumbersome. Note that old names should instead
be specified using the L</oldname> directive.

=item C<traffic_note: I<string>>

A free text note for traffic-related (mostly car traffic) information.
Might be a candidate for transferring to F<comments_kfzverkehr>.

=item C<unverified_by: I<source>>

Same as E<quot>by:E<quot> for unverified data.
E<quot>UnverifiedE<quot> means that there's no communication channel
back to the information provider. Nowadays this would be a couple of
E<quot>by:E<quot> and E<quot>add_fragezeichen:E<quot> or
E<quot>XXX:E<quot> directives.

=item C<XXX_checklater: I<why>>

Like C<XXX>, and additionally attach the E<quot>checklaterE<quot>
attribute.

This tag is not supported anymore. Instead, use just C<XXX> in
conjunction with C<next_check> or C<last_checked>. The current
infrastructure (supporting scripts etc.) have better support for this.

=item C<XXX_outdoor: I<why>>

Deprecated. Usually this is the same as C<XXX>, and scripts don't
support this type anymore.

=item C<tempex: I<tempex_expression>>

Experimental temporal expression, usually used in periodic
F<bbbike-temp-blockings> entries. The tempex syntax is not fully
defined, and there's no code yet using these expressions.

=item C<begin_check: I<date>>

Belonging to the group of directives like C<last_checked> and
C<next_check>. May be used to define some filters differently. Rarely
used, but filter code already exist (see
F<miscsrc/StrassenNextCheck.pm>).

=item C<x-from: I<unixepoch>>

=item C<x-until: I<unixepoch>>

=item C<x-recurring: C<1|0>>

Directives generated when converting C<from>, C<until>, and
C<recurring> from F<bbbike-temp-blockings.pl> to a C<bbd> file.

=back

=head2 Comment lines

If a line begins with a hash sign (C<#>), then it is treated as a
comment. Empty lines are ignored.

=head1 CATEGORIES

Here's a list of special categories:

=head2 STREETS

Used in files: F<strassen>, F<landstrassen>, F<landstrassen2>.
Usually F<strassen> is used for city streets, F<landstrassen> for
streets in the region around the city, and F<landstrassen2> for
streets in the wider region. But it is also possible to work only with
one file F<strassen>.

=over

=item BAB

Freeways (Bundesautobahn)

=item B

Bundesstraßen

=item HH

Important main streets (wichtige Hauptstraßen). Entspricht von der
Kfz-Dichte meist Bundesstraßen. In osm this is a highway=primary
within cities.

=item H

Main streets (Hauptstraßen). In osm this is a highway=secondary.

=item NH

Experimental, not yet fully supported in bbbike. In osm this is a
highway=tertiary.

=item N

Nebenstraßen. In osm this is a highway=residential.

=item NN

Für Kfz gesperrte Straßen. In osm this is either a highway=footway or
highway=cycleway.

=item Pl

Places (Plätze).

=item Br

Bridges.

=back

=head2 BLOCKINGS

Used in files: F<gesperrt>, F<gesperrt_car>. F<gesperrt> is usually
used for blocked streets relevant for cyclists, while F<gesperrt_car>
is for blocked streets for motorized vehicles.

=over

=item * C<1>:

One way street. The blocking is in the direction of the polyline.

=item * C<1s>:

One way street (read E<quot>one softE<quot> or E<quot>one
sloppyE<quot>), but not strictly for cyclists which means: It is
non-legally possible to pass the street in the wrong direction. A
routing handicap may be specified for the "wrong direction" as a
category attribute (for example C<1s:q4> or C<1s:q3>). If none is
specified then typically the routing engine will add a default
handicap of class C<q4>.

=item * C<1h>:

One way street (read E<quot>one hardE<quot>), and there's no
possibility for a cyclist to use the street in wrong direction.

=item * C<1no>:

Not a one way street. Use only if a former one way street got
temporarily opened in both directions, and a directive like C<XXX> or
C<next_check> needs to be attached. May be rendered with a double-head
arrow, and has no routing consequences.

=item * C<2>:

Blocked street in both directions.

=item * C<2s>:

Blocked street (read E<quot>two softE<quot>), but not strictly for
cyclists (means: It is usually possible for bicyclists to pass the
street, maybe by pushing the bike. Typically an handicap addition like
C<2s:q4> or C<2s:q3> should be specified).

=item * C<0>:

The bicycle has to be carried. An optional penalty parameter expressed
in seconds of lost time may be added after the category, with a C<:>
as separator. Example: C<0:30> for a penalty of 30 seconds. This is
only for point records.

=item * C<3>:

A blocked route (gesperrte Wegführung). This means that the whole path
specified by the coordinates of this record are blocked, but parts of
the path are not.

=item * C<3nocross>:

Mark a street or street section which cannot be crossed. This category
is currently only used by the F<miscsrc/convert2hafas> conversion
script (the preprocessor of the F<*-orig> files to the real bbd
files). The conversion script generates a couple of blocked routes
with the category C<3>.

=item * C<BNP>:

A narrow passage (E<quot>DrE<auml>ngelgitterE<quot> etc.). An optional
penalty parameter may be added, like for the C<0> category.

=back

=head2 CYCLE PATHS (RADWEGE)

Used in files: F<radwege_exact>.

=over

=item C<RW0>

Kein Radweg.

=item C<RW1>

Normaler nicht benutzungspflichtiger Radweg.

=item C<RW2>

Benutzungspflichtiger Radweg.

=item C<RW3>

Suggestivstreifen für Radfahrer.

=item C<RW4>

Radstreifen.

=item C<RW5>

Busspur (eventuell nur temporär), auch für Radfahrer frei.

=item C<RW6>

Verkehrsberuhigte Straße.

=item C<RW7>

Fahrradstraße.

=item C<RW8>

Benutzungspflichtiger Zweirichtungsradweg, Gegenrichtung.

=item C<RW9>

Nicht benutzungspflichtiger Zweirichtungsradweg, Gegenrichtung.

=item C<RW10>

Hauptstraße mit zusätzlichem Nebenstreifen, aber auch von Kfz nutzbar
(Beispiele in Berlin: Heerstr., Unter den Eichen am Botanischen
Garten).

=item C<RW>

Radweg vorhanden, aber nicht weiter kategorisiert.

=back

Folgende Kategorien können in der "-orig"-Variante ein "?"
nachgestellt haben, um anzuzeigen, dass Informationen fehlen: C<RW3>,
C<RW4> (Benutzungspflicht unbekannt) und C<RW5> (Gültigkeitsdauer der
Busspur fehlt).

=head2 RAILROADS

Used in files: F<ubahn>, F<sbahn>, F<rbahn>, F<ubahnhof>, F<sbahnhof>,
F<rbahnhof>.

=over

=item C<R>

Regionalbahnen außerhalb des Stadtgebiets.

=item C<RA>

Regionalbahnen Zone A.

=item C<RB>

Regionalbahnen Zone B.

=item C<RC>

Regionalbahnen Zone C.

=item C<R0>

Regionalbahnen außer Betrieb oder ohne regelmäßigen Betrieb.

=item C<RBau>

Regionalbahnen in Bau.

=item C<RG>

Güterbahnen, Verbindungskurven.

=item C<RP>

Parkbahnen, Kleinbahnen.

=item C<S>

S-Bahnen außerhalb des Stadtgebiets.

=item C<SA>

S-Bahnen Zone A.

=item C<SB>

S-Bahnen Zone B.

=item C<SC>

S-Bahnen Zone C.

=item C<S0>

S-Bahnen außer Betrieb.

=item C<SBau>

S-Bahnlinien in Bau.

=item C<U>

U-Bahnen außerhalb des Stadtgebiets.

=item C<UA>

U-Bahnen Zone A.

=item C<UB>

U-Bahnen Zone B.

=item C<UC>

U-Bahnen Zone C.

=item C<U0>

U-Bahnen außer Betrieb.

=item C<UBau>

U-Bahnlinien in Bau.

=back

=head2 QUALITY

Qualität der Wege (Fahrbahnbeschaffenheit).

Used in files: F<quality_s>, F<quality_l>. F<quality_s> is usually
used for city streets, while F<quality_l> is for streets in the region
around the city.

=over

=item C<Q0>

Beste Qualität, keine Einschränkungen.

=item C<Q1>

Gute Kopfsteinpflasterstrecken, mäßiger Asphalt, etwa 25 km/h
Höchstgeschwindigkeit.

=item C<Q2>

Gewöhnliche Kopfsteinpflasterstrecken, schlechter Asphalt, Waldwege,
etwa 18 km/h Höchstgeschwindigkeit.

=item C<Q3>

Schlechte Kopfsteinpflasterstrecken, sandige Strecken, etwa 13 km/h
Höchstgeschwindigkeit.

=back

Es ist möglich, eine Tendenz mit einem angehängten C<-> (besser) oder
C<+> (schlechter) anzugeben, also beispielsweise C<Q2+> für eine
mäßige Qualität mit Tendenz zur guten Qualität. Diese Tendenzen werden
bislang nur bei der Erfassung verwendet, aber (noch) nicht beim
Routing oder der Kartendarstellung.

Andere, nicht fahrbahnbezogene Handicaps, zum Beispiel Beeinträchtigungen
durch Fußgänger oder enge Kurven. Used in files: F<handicap_s> (used
for city streets), F<handicap_l> (used for streets in the region
around the city).

=over

=item C<q0>

Keine.

=item C<q1>

Auf 25 km/h.

=item C<q2>

Auf 18 km/h.

=item C<q3>

Auf 13 km/h.

=item C<q4>

Auf Schrittgeschwindigkeit (z.B. in FuE<szlig>gE<auml>ngerzonen).

=back

=head2 RIGHT OF WAY

=over

=item C<Vf>

Vorfahrt

=item C<Vf::Tram>

Vorfahrt für Straßenbahnen

=item C<Kz>

Kreuzung ohne Vorfahrtsregelung

=back

=head2 COMMENTS

Used in files: F<comments_cyclepath> (alternative way to attribute
cyclepaths), F<comments_ferry> (e.g. time-tables or fares of ferries),
F<comments_kfzverkehr> (categorized amount of motorized traffic -
Abschätzung des Kfz-Verkehrs), F<comments_misc> (other comments),
F<comments_mount> (mounts with grades - Steigungen), F<comments_path>
(path instructions), F<comments_route> (numbered cycle routes -
ausgeschilderte Fahrradrouten), F<comments_tram> (tramway on street).

=over

=item C<CP;>

Only for records with three points. Comment is valid for point B if
driving from A to C.

=item C<CP2;>

Only for records with two points. Comment is valid for point A if
driving from A to B.

=item C<CP>

Same as C<CP;>, but valid for both directions.

=item C<CP2>

Same as C<CP2;>, but valid for both directions.

=item C<CS;>

Comment is valid for the whole route in this direction.

=item C<CS>

Comment is valid for the whole route in both directions.

=item C<PI;>

Path instruction (genauere Wegbeschreibung). (This is in fact a
generalisation of C<CP2;> allowing more than two points)

=item C<P0>

Dieser Weg ist gesperrt (z.B. Abbiegen nicht möglich), aber eine
Umfahrung ist möglich ... siehe auch Kategorie C<3> in L</BLOCKINGS>.

NB: Diese Kategorie wird bislang noch nicht verwendet und bedarf
deswegen einer Überprüfung.

=item C<-2> relativ ruhiger Kfz-Verkehr

=item C<-1>

=item C<+1>

=item C<+2> relativ starker Kfz-Verkehr

Relativ zu der Kategorie einer Straße (von Nebenstraße C<NN> bis zur
Bundesstraße C<B>) kann das subjektive Empfinden der Kfz-Dichte mit
C<-2> bis C<+2> angepasst werden.

=back

=head2 AREAS

Used in files: F<flaechen>. Mostly prefixed with C<F:>, see above.

=over

=item C<P>

Parks.

=item C<Forest>

Forests.

=item C<Cemetery>

Cemeteries. May have a religion tag, e.g. C<< F:Cemetery|religion=muslim >>
or C<< F:Cemetery|religion=jewish >>.

=item C<Ae>

Airports.

=item C<Orchard>

Orchards; especially allotments (Kleingärten).

=item C<Sport>

Sports fields.

=item C<Industrial>

Industrial area.

=item C<Mine>

Mining, surface mining (Tagebau).

=back

=head2 CITIES AND PLACES

The category interval span from C<0> to C<6> where C<0> denotes city
parts, C<1> villages and C<6> metropolises.

=head2 MISC

=over

=item C<radroute>

Haupt- oder Freizeitrouten.

=item C<Q>

Fähren.

=item C<X>

The category will not be used in this case.

=back

=head2 OTHER STANDARD FILES

=over

=item ampeln

File with point records for traffic lights (Ampeln). The category is
set to B<B> for railroad crossings, B<B0> for railroad crossing
without frequent traffic, B<F> for pedestrian-only traffic lights,
B<F0> for inactive pedestrian-only traffic lights, B<Zbr> for
drawbridges, B<X0> for inactive traffic lights, and otherwise (normal
traffic lights), B<X> is used.

Inactive traffic lights are currently only available in the
F<ampeln-orig> file and not processed into the final F<ampeln> file.

=item hoehe

File with elevation points. The C<Name> fields denotes the elevation
in meters, the category is not used.

=item sehenswuerdigkeit

File with sights, public buildings and other E<quot>interestingE<quot>
points. Possible categories are

=over

=item C<SW>

Unspecified sight. Use if nothing else applies.

=item C<Shop>

A shopping center.

=back

The category has usually an image attribute. The following standard
images are available in bbbike:

=over

=item C<museum>

=item C<theater>

=item C<church>

=item C<synagogue>

=item C<mosque>

=item C<airport>

=item C<hospital>

=item C<monument>

=item C<touristinfo>

=back

The pseudo image C<px_1t> may be used for invisible areas.

In area records, it is advisable to use the main entrance as the first
point.

=back

XXX To be continued

=head1 ATTRIBUTES

=over

=item inwork

Marks the map item to be E<quot>in workE<quot>. This could be rendered
with an additional E<quot>in workE<quot> sign along the map item. This
attribute is already handled in a couple of data files
(F<fragezeichen>, F<gesperrt>, F<handicap>, F<strassen_bab>).

=item Tu

The map item is in a tunnel. This is already handled in F<sbahn>,
F<rbahn>, F<ubahn>, F<strassen_bab>, and F<wasser*>.

Note that not every BBBike renderer may render a tunnel specially. The
Perl/Tk application has complete render support for all tunnel
categories (see also the below ones). The PDFCairo renderer has simple
support for tunnels (drawn as dashed lines). The PDF and GD renderers
draw tunnels like normal lines, except for tunneled waterways, which
are currently completely ignored. All other renderers (e.g. Mapserver)
draw all tunnels like normal lines.

=item Tu_

The map item is in a tunnel and a tunnel mound should only be drawn at the
beginning of the map item.

=item _Tu

The map item is in a tunnel and a tunnel mound should only be drawn at
the end of the map item.

=item _Tu_

The map item is in a tunnel and no tunnel mounds should be drawn at
all.

=item Br

The map item is on a bridge. This is already handled in
F<strassen_bab>.

=item Eb

The map item is on an embankment (Bahn- oder Straßendamm). This means
that the map item is typically over other map items. The attribute is
not used yet.

=item Cu

The map item is in a cutting (Einschnitt). This means that the map
item is typically under other map items. The attribute is not used
yet.

=item igndisp

Ignore display. Item will not be rendered, but may be used for other
purposes (i.e. routing). See L</ignrte>.

=item ignrte

Ignore in routing. Item will not be used in routing, but may be used
for other purposes (i.e. display). See L</igndisp>.

=item temp

Mark a "temporary" entry, which is non-recurring. Used in temp
blockings. Currently rendered with a "calendar" sign.

=item night

Mark a temporary blocking which is active only at night. Currently
rendered with a "moon" sign.

=item weekend

Mark a temporary blocking which is active at weekend. Currently not
rendered.

=item clock

Mark a temporary blocking which is recurring. Currently rendered with
a "clock" sign.

=item xmas

Mark a temporary blocking which is active typically before and after
Christmas. Currently rendered with a christmas tree sign.

=item bomb

Mark a temporary blocking due to bomb disposals. Currently rendered
with a "bomb" sign.

=item play

Mark a temporary play street.

=item mask

Mark a street with mandatory mask-wearing.

=item sign

Mainly used for roads that will either receive a new street name or
have other remarks regarding signage.

=item alternating

Used for traffic lights which control alternating traffic flow. Very
often used together with an "inwork" attribute. Currently rendered as
an up/down arrow.

=back

=head1 CONVENTIONS

Lines which are to be removed, but still should be kept as a kind of
"historical documentation", may be turned into a comment with
"REMOVED" as the first word. Multiple lines may be joined into one
line, separated by a "---". For example:

    # REMOVED --- #: confirmed_by: me --- old entry X 1234,5678 9876,5432

=head1 EXAMPLES

    #: map: polar
    #:
    # a comment
    Dudenstr.	H 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    Viktoriapark	F:P 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591

And a detailed explanation...

    Start of a directive
    v
    #: map: polar
       ^
       Coordinate system of this file is defined as WGS84, DDD

    Start of a comment
    v
    # a comment

(Note that spaces are insignificant in the following examples, but
C<< <TAB> >> and C<< <SPACE> >> should be inserted)
    
                              List of coordinates (x,y pairs)
                              v
    Dudenstr. <TAB> H <SPACE> 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    ^               ^
    Street name     Category (H = main street)

                                   List of coordinates for a polygon
                                   v
    Viktoriapark <TAB> F:P <SPACE> 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591
    ^                  ^
    Name of a park     Category (F = area (polygon, Fläche),
                                 P = park)

                    Category (S = S-Bahn, A = Tariff area A)
                    v
    S1,S2,S25 <TAB> SA::Tu_ <SPACE> coordinates ...
                        ^
                        Attribute (Tunnel, only draw tunnel entrance
                                   at beginning)

=head1 CAVEATS

Some category values may change. It is likely that either the blocking
and/or city category values will change, as both use digits.

=head1 AUTHOR

Slaven Rezic <slaven@rezic.de>

=head1 SEE ALSO

L<bbbike>, L<Strassen>, L<fragezeichen2org.pl>, F<miscsrc/bbbike.el>.

=cut
