[Roadmap-commit] roadmap/howtos makemaps.txt,1.3,1.4

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/roadmap/roadmap/howtos
In directory 23jxhf1.ch3.sourceforge.com:/tmp/cvs-serv2766/howtos

Modified Files:
	makemaps.txt 
Log Message:
switch from aptconvert format to txt2tags (txt2tags.sourceforge.net) format.
aptconvert seems to be orphanced, txt2tags seems as capable, and is on
sourceforge and in debian.

Index: makemaps.txt
===================================================================
RCS file: /cvsroot/roadmap/roadmap/howtos/makemaps.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** makemaps.txt	12 Dec 2007 16:56:01 -0000	1.3
--- makemaps.txt	6 Nov 2008 20:23:07 -0000	1.4
***************
*** 1,11 ****
!                                ---------
!                     Creating a Map for RoadMap HOWTO
!                                ---------
!                  Pascal Martin (pas...@po...)
!                                ---------
!                                                                                                             December 2005

! INTRODUCTION

     This HOWTO describes how to create a new map for RoadMap. The intent is
--- 1,8 ----
! Creating a Map for RoadMap HOWTO
! Pascal Martin (pas...@po...)
! December 2005

! = INTRODUCTION =

     This HOWTO describes how to create a new map for RoadMap. The intent is
***************
*** 21,34 ****

! OVERVIEW

     There are four major phases involved when creating maps for RoadMap:

!    * One must decide how the maps will be organized. It is important to
     have a good idea of how the country is organized and how individual
     addresses are formatted (the format of addresses will have an influence
     on the maps organization).

!    * Then the format of the data source must be identified and analyzed.
     Knowing the data come in a shape file is not enough, as there are many
     different ways of organizing shape file data. Typical questions to answer
--- 18,31 ----

! = OVERVIEW =

     There are four major phases involved when creating maps for RoadMap:

!    - One must decide how the maps will be organized. It is important to
     have a good idea of how the country is organized and how individual
     addresses are formatted (the format of addresses will have an influence
     on the maps organization).

!    - Then the format of the data source must be identified and analyzed.
     Knowing the data come in a shape file is not enough, as there are many
     different ways of organizing shape file data. Typical questions to answer
***************
*** 36,45 ****
     feature? How does the data source layers match the Roadmap layers?

!    * A map builder input module may need to be modified or customized to
     handle the specific format used by the data source.

!    * The map builder application must be run and the map indexes created.

! * PLANNING THE MAP ORGANIZATION

     The preliminary step when building a map is always to decide how the
--- 33,42 ----
     feature? How does the data source layers match the Roadmap layers?

!    - A map builder input module may need to be modified or customized to
     handle the specific format used by the data source.

!    - The map builder application must be run and the map indexes created.

! - PLANNING THE MAP ORGANIZATION

     The preliminary step when building a map is always to decide how the
***************
*** 47,55 ****
     the main ones are:

!    * The map will represent a new class of features.

!    * The map will cover a new country.

!    * The map will cover an existing country and represent existing features.

     Even in the more complex cases when the map to be built represents new
--- 44,52 ----
     the main ones are:

!    - The map will represent a new class of features.

!    - The map will cover a new country.

!    - The map will cover an existing country and represent existing features.

     Even in the more complex cases when the map to be built represents new
***************
*** 73,77 ****
     files are organized.

! * DATA SOURCE FORMAT

     There are two main situations: either the format of the data source is
--- 70,74 ----
     files are organized.

! - DATA SOURCE FORMAT

     There are two main situations: either the format of the data source is
***************
*** 104,114 ****
     must be modified, or else the data must be merged using standard GIS tools.

! * BUILDMAP INPUT MODULES

     A buildmap input module must provide the following function:

! ----
     buildmap_xxx_process (const char *input, const char *class);
! ----

     This function must be called in buildmap_main.c
--- 101,111 ----
     must be modified, or else the data must be merged using standard GIS tools.

! - BUILDMAP INPUT MODULES

     A buildmap input module must provide the following function:

! ```
     buildmap_xxx_process (const char *input, const char *class);
! ```

     This function must be called in buildmap_main.c
***************
*** 125,131 ****

! LAYERS

! * LAYER CLASS

     Every feature stored in a RoadMap map file belongs to one layer. Layers
--- 122,128 ----

! = LAYERS =

! - LAYER CLASS

     Every feature stored in a RoadMap map file belongs to one layer. Layers
***************
*** 138,148 ****

! * DEFINING A NEW LAYER CLASS

     A layer class is made of two lists of layers:

!    * One list for all line features (for example: streets).

!    * One list for all polygon features (for example: lakes).

     Each list is an ordered sequence of layers. The order in the sequence
--- 135,145 ----

! - DEFINING A NEW LAYER CLASS

     A layer class is made of two lists of layers:

!    - One list for all line features (for example: streets).

!    - One list for all polygon features (for example: lakes).

     Each list is an ordered sequence of layers. The order in the sequence
***************
*** 176,180 ****

! MAP ORGANIZATION

     RoadMap divides earth into territories, usually defined by administrative
--- 173,177 ----

! = MAP ORGANIZATION =

     RoadMap divides earth into territories, usually defined by administrative
***************
*** 208,222 ****

! * MAPS IDENTIFICATION

     It is important to understand how maps are identified. RoadMap uses a
     32 bits integer named World Territory ID (wtid) and defined as follow:

!     * The wtid is made of 10 decimal digits. There are two major classes
      of wtid format: one is defined by legal boundaries and the other is
      defined by a longitude/latitude grid. At that time, only the legal
      boundaries class of wtid is supported in RoadMap.

!     * the legal-boundaries wtid for countries has the format 0CCCCXXXXX,
      where CCCC is the telephone dialing code for the country covered by the
      maps and XXXXX is a subdivision inside that country, wich format depends
--- 205,219 ----

! - MAPS IDENTIFICATION

     It is important to understand how maps are identified. RoadMap uses a
     32 bits integer named World Territory ID (wtid) and defined as follow:

!     - The wtid is made of 10 decimal digits. There are two major classes
      of wtid format: one is defined by legal boundaries and the other is
      defined by a longitude/latitude grid. At that time, only the legal
      boundaries class of wtid is supported in RoadMap.

!     - the legal-boundaries wtid for countries has the format 0CCCCXXXXX,
      where CCCC is the telephone dialing code for the country covered by the
      maps and XXXXX is a subdivision inside that country, wich format depends
***************
*** 224,233 ****
      whole country.

!     * The legal-boundaries wtid for the USA has the format 00000SSCCC where
      SSCCC is the county's FIPS code. Note that, in this case, the value of
      the wtid exactly matches the value of the FIPS code. A CCC of 000 means
      the whole state. A wtid value of 00000 represents the whole US.

!     * The grid wtid have the format: 1CCLLLLllll where LLLL is a number that
      represents the longitude span covered by the map and llll is a number
      that represents the latitude covered by the map. CC identifies the type
--- 221,230 ----
      whole country.

!     - The legal-boundaries wtid for the USA has the format 00000SSCCC where
      SSCCC is the county's FIPS code. Note that, in this case, the value of
      the wtid exactly matches the value of the FIPS code. A CCC of 000 means
      the whole state. A wtid value of 00000 represents the whole US.

!     - The grid wtid have the format: 1CCLLLLllll where LLLL is a number that
      represents the longitude span covered by the map and llll is a number
      that represents the latitude covered by the map. CC identifies the type
***************
*** 251,255 ****
     Bulletin No. 835. For more information, go to:

!       {{http://www.itu.int/itu-t/bulletin/annex.html}}

     RoadMap also use names to identify authorities (such as when it searches
--- 248,252 ----
     Bulletin No. 835. For more information, go to:

!       http://www.itu.int/itu-t/bulletin/annex.html

     RoadMap also use names to identify authorities (such as when it searches
***************
*** 262,266 ****
     The country code name follow the iso 3166-1 standard. See:

!       {{http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html}}

     The sub-authority levels must follow the local country convention for
--- 259,263 ----
     The country code name follow the iso 3166-1 standard. See:

!       http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html

     The sub-authority levels must follow the local country convention for
***************
*** 293,300 ****
     Continuing with the US example, the US can be represented in two ways:

!      * as a single index, which belongs to the US country, authorities are
       the US states and territories are the counties.

!      * as a two-level tree of indexes: the top-level index lists the states
       as authorities and contains no territory, map or cities tables; each
       lower level index represents one state, lists counties as territories
--- 290,297 ----
     Continuing with the US example, the US can be represented in two ways:

!      - as a single index, which belongs to the US country, authorities are
       the US states and territories are the counties.

!      - as a two-level tree of indexes: the top-level index lists the states
       as authorities and contains no territory, map or cities tables; each
       lower level index represents one state, lists counties as territories
***************
*** 305,309 ****

! * DEFINING A NEW COUNTRY

     If the country was not represented in RoadMap yet, the division of the
--- 302,306 ----

! - DEFINING A NEW COUNTRY

     If the country was not represented in RoadMap yet, the division of the
***************
*** 311,315 ****
     to consider:

!       * The territories must be compatible with the way postal addresses
        are organized. The major requirements are that city names should be
        unique inside a map file. If possible, the middle level authority levels
--- 308,312 ----
     to consider:

!       - The territories must be compatible with the way postal addresses
        are organized. The major requirements are that city names should be
        unique inside a map file. If possible, the middle level authority levels
***************
*** 317,321 ****
        convention as well.

!       * The territories should be compatible with the way the data source is
        organized. It is possible to reorganize the data according to different
        criteria, for example by splitting or merging files, but this introduces
--- 314,318 ----
        convention as well.

!       - The territories should be compatible with the way the data source is
        organized. It is possible to reorganize the data according to different
        criteria, for example by splitting or merging files, but this introduces
***************
*** 345,353 ****
     example  of a countries.txt file describing the US and canada:

! ------
         # List of countries, format: iso 3166-1, itu E.164A (except USA), name
         us,0,USA
         ca,1,Canada
! ------

     The country's list of parent territories must be described in a separate
--- 342,350 ----
     example  of a countries.txt file describing the US and canada:

! ```
         # List of countries, format: iso 3166-1, itu E.164A (except USA), name
         us,0,USA
         ca,1,Canada
! ```

     The country's list of parent territories must be described in a separate
***************
*** 358,364 ****
     The format of the file is:

! ------
          wtid,symbol,name[,parent-authority-symbol]
! ------

     The wtid must be empty if an authority is described (since no map file
--- 355,361 ----
     The format of the file is:

! ```
          wtid,symbol,name[,parent-authority-symbol]
! ```

     The wtid must be empty if an authority is described (since no map file
***************
*** 369,373 ****
     Here is an example that describes the state of Rhode Island (USA):

! ------
          ,RI,RHODE ISLAND
          44001,,Bristol,RI
--- 366,370 ----
     Here is an example that describes the state of Rhode Island (USA):

! ```
          ,RI,RHODE ISLAND
          44001,,Bristol,RI
***************
*** 376,380 ****
          44007,,Providence,RI
          44009,,Washington,RI
! ------

     For large countries it is recommended to locate the official description
--- 373,377 ----
          44007,,Providence,RI
          44009,,Washington,RI
! ```

     For large countries it is recommended to locate the official description