Mkgmap/dev/option-review
Jump to navigation
Jump to search
Option review
There is a perception (which I agree with) that there are too many options to mkgmap and/or that they are confusing.
One solution to this is to divide clearly the options in the documentation into ones that you are likely to need straight away and those that are only useful for published maps or in rare cases. This is an important part of the solution but it is not discussed further here.
The other part of the solution is to have more generally useful defaults, remove options that are not really useful and to rename or combine options to better describe their use.
This page lists all the current options, and my thoughts on what should be done for each one.
I don't expect anyone to agree with all these.
There is not going to be any massive overnight changes, but I want to approach one option at a time and start removing obsolete options and adding a few defaults, rather than waiting for a big plan.
Option classification
The options are classified according to why they exist. Don't worry too much if you disagree with any of the classifications as is just an aid to thinking about what to do and many could be said to be in more than one category.
- 1 non-optional
- shouldn't even be an option because there is only one setting that works. Perhaps had some genuine use in the past. Basically these should be removed.
- 2 workaround
- automatic algorithm fails and needs human help depending on the map. Might be a quick fix to something that could be done better in the future. If there already is a better solution, then such an option could be considered for removal.
- 3 style
- This is meant to cover anything that affects the look or performance of the map which is not a matter of broken or working. Should have reasonable default values, so that they only need changing in rare cases.
- 4 information
- add information to the map (eg --family-id). Mostly these should stay, although combining them could be considered.
- 5 output
- select what is created. Mostly should be kept, although could be combined, defaulted or renamed.
- 6 performance
- control operations with a large performance impact (time or memory) that is likely to make it impossible for some people to use the program. This is not meant to include anything that produces a broken map if omitted.
- 7 warnings
- control warnings about the input osm files. Will probably combine all these into a --warnings option.
- 8 generate
- generate extra elements based on the input data. Consider each one separately.
- 9 obsolete
- Just not needed any more, or doesn't work. Remove.
- 10 random
- supports some random thing that someone wanted to do once. See if it is still needed or just do it and remove the option.
- 11 input
- selecting input files. Mostly can't avoid this but could consider combining options perhaps.
- 12 informational
- produces some informational output, eg --help etc
The options
| Option | Class | Notes | Action |
|---|---|---|---|
| --help=topic | 12 informational | keep | |
| --version | 12 informational | keep | |
| --input-file=filename | 11 input | keep | |
| --gmapsupp | 5 output | Create map for GPS device. Not an obvious name to anyone new to Garmin devices. | Possibly rename to --gps (and --desktop) or --output=[gps,desktop] |
| -c filename, --read-config=filename | 11 input | keep | |
| --output-dir=filename | 5 output | keep | |
| -n name, --mapname=name | 4 information | keep | |
| --description=text | 4 information | keep | |
| --country-name=name | 4 information | perhaps all these country/region parameters could be combined
somehow? |
keep |
| --country-abbr=abbreviation | 4 information | keep | |
| --region-name=name | 4 information | keep, perhaps combine | |
| --region-abbr=abbreviation | 4 information | keep, perhaps combine | |
| --latin1, --unicode, --code-page=number | 4 information | defaults to ascii only, should default to 1252, I know that is
western european centric, but the current default is less useful. |
default to 1252 |
| --charset=name | 9 obsolete | this was from before I understood the character set options. | remove+code |
| --lower-case | 1 non-optional | I only put this in to show that it doesn't work (for all devices).
Now all that happens is that people write to me complaining that it doesn't work. |
remove+code |
| --index | 5 output | requires a significant amount of memory for large maps. | keep or default on? |
| --x-split-name-index | 5 output | still experimental? | keep or default on? |
| replaced by separate program (r2426) | |||
| --bounds=directory/zipfile | 11 input | keep | |
| --location-autofill=[option1,[option2]] | 2 workaround | investigate how useful this still is. Basically obsoleted by bounds? | |
| --housenumbers | 5 output | default on | |
| --style=name | 11 input | keep | |
| --style-file=file | 11 input | keep | |
| --list-styles | 12 informational | keep | |
| --check-styles | 12 informational | keep | |
| --levels=levels code, --overview-levels=levels code | 3 style | this really lives inside the style. Changing it without modifying the style leads to unbalanced results. | remove?, style-option |
| --name-tag-list | 3 style | a style option, that can be overriden from the command line. | keep |
| --map-features=file | 9 obsolete | This was the first style file format, not useful today. | remove+code |
| --family-id | 4 information | keep | |
| --family-name | 4 information | keep | |
| --product-id | 4 information | keep | |
| --product-version | 4 information | keep | |
| --series-name | 4 information | keep | |
| --area-name | 4 information | keep | |
| --overview-mapname=name | 4 information | keep | |
| --overview-mapnumber=8 digit number | 4 information | keep | |
| --remove-ovm-work-files | 6 performance | keep | |
| --copyright-message=note | 4 information | keep | |
| --copyright-file=file | 4 information | keep | |
| --license-file=file | 4 information | keep | |
| --reduce-point-density=NUM | 3 style | default to a reasonable value | |
| --reduce-point-density-polygon=NUM | 3 style | default to a reasonable value | |
| --merge-lines | 3 style | investigate if this works safely, enable always if so. Else fix or
remove if we can't do that (may need a different approach). |
default on, or remove |
| --min-size-polygon=NUM | 3 style | default to a reasonable value. | |
| --polygon-size-limits=limits code | 3 style | default to a reasonable value. | |
| --max-jobs[=number] | 6 performance | keep | |
| --keep-going | 12 informational | Would be clearer if it was called --ignore-errors | rename? |
| --block-size=number | 11 output, 9 obsolete | Now automatic calculation works. | remove |
| --net | 5 output | default to on | |
| --route | 5 output | default to on | |
| --drive-on=left/right/detect/detect,left/detect,right | 3 style | keep | |
| --check-roundabouts | 7 warnings, and modifies the data | undecided. I think perhaps it should become just a warning. | |
| --check-roundabout-flares | 7 warnings | combine into --warnings | |
| --max-flare-length-ratio=NUM | 10 random, 7 warnings | do we really need this? | remove |
| --ignore-maxspeeds | 3 style | belongs in the style , see include roadspeed | already ignored |
| --ignore-builtin-relations | 10 random, 1 non-optional | claims performance benefit, but only if you want a broken map. | remove |
| --ignore-turn-restrictions | 1 non-optional or 2 workaround | don't know why you would want to do this | remove |
| --ignore-osm-bounds | 1 non-optional, 2 workaround | breaks routing across tiles, was a quick fix for files that have multiple bounds. The correct solution is for mkgmap to just deal with multiple bounds. | remove (and fix properly) |
| --preserve-element-order | 10 random | added for a particular application. Perhaps should just be made default, it only uses a small amount of extra memory (if any) and is quite useful when tracking down problems. | default on, and remove |
| --remove-short-arcs[=MinLength] | 1 non-optional | obsolete | already ignored |
| --adjust-turn-headings[=BITMASK] | 2 workaround or 1 non-optional | makes turn directions better. Investigate if it works well, if so default on and improve as necessary.
Otherwise remove. |
default on, or remove |
| --report-similar-arcs | 7 warnings | not a particularly useful warning? | combine in --warnings |
| --report-dead-ends=LEVEL | 7 warnings | combine in --warnings | |
| --road-name-pois[=GarminCode] | 9 obsolete, | a work around from before we had address index, now more trouble than it is worth. | ignored since r3605 |
| --add-pois-to-lines | 8 generate | should be handled with care, is likely to produce a large number
of POI, style should check mkgmap:line2poitype tag in points file. |
limit number of generated POI? |
| --add-pois-to-areas | 8 generate | always need to do this, controlled by style? or should be. | default on |
| --pois-to-areas-placement[=taglist] | 3 style | seems like it should be controlled in the style | move to style |
| --precomp-sea=directory/zipfile | 11 input | keep | |
| --coastlinefile=filename[,filename] | 11 input | is this obsolete with --precomp-sea? anyway only need one way to get
sea polygons. Or have one option that works out what kind of file it is given and acts accordingly. |
? |
| --generate-sea[=ValueList] | 8 generate | this itself has a whole slew of sub-options. Is this obsolete with --precom-sea? Only need one way to create the sea. | |
| --make-poi-index | 5 output, 1 non-optional | Doesn't work? If it works enable and remove the option, else remove the code. | remove |
| --nsis | 5 output | default on, not really much point in not creating this file. Could combine as --desktop or --output=desktop | default on |
| --make-all-cycleways | 8 generate | depreacated, treated like --make-opposite-cycleways | keep with warning |
| --make-opposite-cycleways | 8 generate | better solutions using the style file, but not simple | keep |
| --make-cycleways | 8 generate | already ignored | |
| --link-pois-to-ways | 1 non-optional | implements access restrictions | default on and remove |
| --process-destination, --process-exits | 3 style | seems like it should always be done. Or controlled by style. | default on and remove |
| --delete-tags-file=FILENAME | 11 input | keep? | |
| --tdbfile | 5 output | annoyingly it defaults to on but only if there is more than one file.
may as well always produce these files. remove or perhaps control with --desktop |
default to on. |
| --show-profiles=1 | 5 output | perhaps could be a style option | keep |
| --draw-priority=25 | 5 output | keep | |
| --transparent | 5 output | keep | |
| --poi-address | 1 non-optional or 3 style | not even sure why this is a thing, default is on now | remove? |
| --verbose | 12 informational | keep |