Here's a patch that: adds some options to the help file
improves wording in the help file adds TODO items in the help file when I think something should be there but don't know the answer a bit of general cleanup in the help file removes option description from README, pointing people to the help file and README.examples I've gone through some of my saved mail messages - I'm trying to work the helpful hints in them into the docs so I no longer need to save the messages.
Index: README =================================================================== --- README (revision 1118) +++ README (working copy) @@ -32,69 +32,43 @@ there. Another way would be to use a USB memory card writer. Another convenient way is to use the sendmap program. -You should (depending on the particular Garmin model) see a OSM copyright message -on starting up, and the map name 'OSM Street map' should appear -in the map setup section. +You should (depending on the particular Garmin model) see a OSM +copyright message on starting up, and the map name 'OSM Street map' +should appear in the map setup section. For more help see: http://wiki.openstreetmap.org/index.php/Mkgmap/help -Options -------- +Invoking mgmap +-------------- + Most of the default names mentioned in the previous section can be altered -by suitable options. Example: +by suitable options. Run - java -jar mkgmap.jar --mapname=11225502 --charset=latin1 data.osm + java -jar mkgmap.jar --help=options --n <name> ---mapname=<name> - This option is followed by the name of the map. This must be an - eight digit number. The default if this option is ommited is 63240001 - for no particularly good reason. The name is used inside the map - it isn't enough to just rename the file. +to obtain a comprehensive listing of options, or see +resources/help/en/options. See doc/README.examples for examples of +invocation details that others have found useful. ---description=<text> - Set the description of the map that is stored inside the map itself. By - default it is 'OSM Street map' ---style=<style-name> - Select another built in style. Use --list-styles to show the available - styles. - ---list-styles - Show the available styles. - ---style-file=file - Supply another style. See http://wiki.openstreetmap.org/wiki/Mkgmap/help/Custom_styles - ---levels=<levels> - Set the levels within the map. See http://wiki.openstreetmap.org/wiki/Mkgmap/help/Custom_styles - ---charset={latin1|ascii} - Sets the encoding for the labels. - ---latin1 - Same as --charset=latin1 - ---input-file=<file> - This is another way of specifying an osm file to process. - ---help - For a more complete list of options. - Processing more than one file at a time --------------------------------------- -It is usual to split Garmin maps up into smaller tiles. This is because -older GPS units (before large SD cards were cheap) had a limited amount of memory -for maps, and secondly because there are limits within the map format -itself. +It is usual to split Garmin maps up into smaller tiles. This is +because older GPS units (before large SD cards were cheap) had a +limited amount of memory for maps, because there are limits within the +map format itself, and because mkgmap uses a significant amount of +memory to process each tile. You can give more than one .osm file on the command line at a time and they will each be converted to a separate garmin map tile. There will also be two other files created: 1) a file ending in .tdb and an overview .img map. +See also doc/README.splitter. + + Acknowledgements ================ Index: resources/help/en/options =================================================================== --- resources/help/en/options (revision 1118) +++ resources/help/en/options (working copy) @@ -1,9 +1,29 @@ -Options: +General options: --help=topic - Print help on the given topic. The topic is omitted then a + Print help on the given topic. If the topic is omitted then a list of all the help topics is printed instead. +--version + Output program version. + +--enable-assertions + Turn on assertions in the code. This will make the program + more likely to abort and less likely to do the wrong thing. + Use of this option is recommended. + +filename +--input-file=filename + Read input data from the give file. This option (or just a + filename) may be given more than once. + +--gmapsupp + Write a gmapsupp.img file that can be uploaded to a Garmin or + placed in "/Garmin" in a microSD card (such as by mounting the + device in USB mass storage mode). + TODO: explain if this is in addition to or instead of the + per-input files. + -c filename The given file is opened and each line is an option setting of the form option=value, just like on the command line except @@ -11,8 +31,8 @@ -n name --mapname=name - Change the name of the map. Garmin maps are named by 8 digit - numbers. The default is 63240001. It is best to change the + Set the name of the map. Garmin maps are named by 8 digit + numbers. The default is 63240001. It is best to use a different name if you are going to be making a map for others to use so that it is unique and does not clash with others. @@ -35,7 +55,7 @@ Label options: ---latin1 +--charset=name This option allows the use of non-ascii characters in street names. It is hardware dependant what is actually supported on a particular device. Some devices can only do ascii characters @@ -45,11 +65,15 @@ however and by default (without this option) it will transliterate characters to unaccented ascii characters where possible. ---charset=''name'' - Use the specified character set. +--latin1 + This is equivalent to --charset=latin1. ---code-page=''number'' +--code-page=number + TODO: is one really supposed to give two single quotes? Write the given code page number to the header of the LBL file. + Some examples on the mailing list use --code-page=1252. + TODO: explain what this does, and why one would or would not want + to do it. --lower-case Allow labels to contain lower case letters. Note that this @@ -58,14 +82,23 @@ Style options: --style=name - Specify a different style name, rather than the default. + Specify a different style name, rather than the default value + (which is the word default). --style-file=file Specify an external file to obtain the style from. "file" can - be a directory or a zip file containing the style. It can - also be a URL. If there is more than one style in the zip - file, then the --style argument can be used to select. + be a directory containing files such as info, lines, options + (see resources/styles/default for an example). The directory + path must be absolute or relative to the current working + directory when mkgmap is invoked. + The file can be a zip file instead of a directory. TODO-check + this: In this case, the zip file should contain directories + with styles, and the style 'default' will be used, unless the + --style option is also given to select a different one. + + The argument can also be a URL, in which case TODO. + For backward compatibility, you can also supply a map-features.csv file here. See the customisation help. @@ -84,55 +117,59 @@ will be used. eg. --name-tag-list=name:en,int_name,name --map-features=file - Outdated option, use the --style-file option now. + This option is obsolete; use the --style-file option instead. Product description options: --family-id This is an integer that identifies a family of products. +--family-name + TODO: describe this + --product-id This is an integer that identifies a product within a family. It is often just 1. --series-name ---family-name --area-name + --overview-mapname=name - If --tdbfile is enabled, this gives the name of the overview .img and .tdb files. + If --tdbfile is enabled, this gives the name of the overview + .img and .tdb files. The default map name is OSM_map. --overview-mapnumber=8 digit number - If --tdbfile is enabled, this gives the internal 8 digit number used in overview map and - tdb file. The default number is 63240000. + If --tdbfile is enabled, this gives the internal 8 digit + number used in the overview map and tdb file. The default + number is 63240000. -Misc options: +Miscellaneous options: + --max-jobs[=number] When number is specified, allow that number of maps to be processed concurrently. If number is not specified, the limit is set equal to the number of CPU cores. If this option is not - given at all, the limit is 1 (i.e. the maps are processed + given at all, the limit is 1 (i.e., the maps are processed sequentially). --keep-going Don't quit whole application if an exception occurs while processing a job - continue to process the other jobs. ---block-size=''number'' +--block-size=number Changes the block size that is used in the generated map. - There is no general reason why you would want to do this. + TODO: explain what this meant + Use of this option is not recommended. --net - Output file that supports "lock to road" option. + Create maps that supports the "lock to road" option. --route - Experimental: Output Routing Information (implies --net) + Experimental: Create maps that support routing. This implies --net + (so that --net need not be given if --route is given). ---gmapsupp - Write a gmapsupp.img file that can be uploaded to a garmin in - usb mode. - --ignore-maxspeeds When reading OSM files, ignore any "maxspeed" tags. @@ -156,7 +193,8 @@ --road-name-pois[=GarminCode] Generate a POI for each named road. By default, the POIs' Garmin type code is 0x640a. If desired, a different type code - can be specified with this option. + can be specified with this option. This is a workaround for not + being able to search for roads. --add-pois-to-areas Generate a POI for each area. The POIs are created after the @@ -230,7 +268,3 @@ 3 Enables debug output about suspicious relations that might cause wrong country region info - ---version - Output program version. -
pgp41anhnJ2bq.pgp
Description: PGP signature
_______________________________________________ mkgmap-dev mailing list mkgmap-dev@lists.mkgmap.org.uk http://www.mkgmap.org.uk/mailman/listinfo/mkgmap-dev
