[mkgmap-dev] Short mkgmap HowTo

Sun Aug 14 19:46:25 BST 2011

 > heya. i think this is a wonderful idea - a beginner-friendly page
 > might be very useful, because it took me quite some time to figure
 > out several things - mkgmap wiki pages (and other resources) have
 > lots of contradicting, outdated or just missing information. a few
 > suggestions regarding newbie page.
 >
 > note that i don't claim that "somebody should do something about it",
 > i offer to do this ;)
 > didn't want to rush in and just start to mess up things. if there are
 > no objections, i could slowly change wiki pages in this direction.

That's great! By the way: this is a wiki, so anybody should do changes 
if one thinks they are good.

 > 1. i believe it should only list most important, simple steps - thus
 > i'd remove 'tile splitter' from main requirements list and only list
 > it when talking about splitting data;

Yes, it should contain the most important simple steps. And therefore 
splitter should remain there. Usually if you start with mkgmap you don't 
download data and split it yourself. And most downloads are bigger than 
one tile, so you have to split the data.

 > 2. i personally have been using osmosis to cut out regions,
 > especially if i'm just going to visit one city - no need to build
 > extra tiles, smaller dataset. if that is deemed to be useful, it
 > could be linked to from mkgmap beginner page;

I would call that advanced usage if you use osmosis to cut out such 
small areas that fit into one tile. You need to know the osmosis 
parameters (which is definetly complicated) and you must know that your 
area must be small enough to fit into one tile.

For the tile splitter you just have to download it and start it without 
any special parameters. Quite easy, isn't it?

 > 3. i'd move address search to a separate page and link to it from the
 > beginner's intro - have a section "further reading" or so (and as
 > such, nuke --nsis option from the default suggested ones);

I agree to move that to a separate page. I would not nuke the --nsis 
option from the address search parameters. Otherwise you have to explain 
in detail how the generated map can be installed in MapSource. With 
--nsis you just have to say: Use the .nsis script to create an 
executable map setup and run that.

 > 4. on the beginners page, all used options should be explained - what
 > they do and, especially, why would one use them. one of my biggest
 > sources of frustration with mkgmap was inability to figure out what
 > options do or what options to use for some functionality

I do not aggree. Don't explain the options on the beginners page. This 
is a short "How-To" and therefore I would leave it as short as possible.
But it would be great if you can add links to the pages with more 
detailed explanations for all options. Then you don't have to search for 
them.

 > 4.1. --tdbfile
 > ok, this is a quite wonderful one - especially if we look at the help
 > output of it :D
 >         Write a .tdb file.
 > i've used mkgmap to generate maps for various regions a few hundred
 > times by now. i have never used this option and i have no idea what
 > it does (help wasn't very... helpful). is it really useful for
 > newbies ?

I don't know too. I thought it would be necessary but don't know why it 
is needed or why not.

 > and, not directly related to newbie guide - it might be useful to add
 > some description on what that file is and why would one want it to
 > the help output ;)
 > (http://wiki.openstreetmap.org/wiki/Mkgmap didn't provide much more
 > information either)

 > 4.2. --route - is this still experimental, as --help suggests ?
 > side note : a newcomer might be put off by the fact that it's not
 > listed in http://wiki.openstreetmap.org/wiki/Mkgmap at all - maybe it
 > would be better to keep cli options on a separate page (would make
 > main page also readable). and also maybe just regenerate cli option
 > page from --help=options output every now and then so that two sets
 > of options won't have to be maintained ?

Fully agree! Throw away all option descriptions from the main mkgmap 
page and move them to one or more separate pages where we can do links 
to. If you improve some descriptions for options I will also be happy to 
commit them the mkgmap help file which is available with --help.

 > 4.3. --remove-short-arcs : again, not listed in the main page at all.
 > help output has something on that option, but for beginners, it might
 > be helpful to explain what short arcs are, what might be
 > consequences. on a more general note, what's a suggestion regarding
 > this option, should it be used with some non-zero value ?
 > also, what actually are "zero-length arcs" ? if i don't specify this
 > option at all, would they be kept ? if so, why not remove them by
 > default ?

Fully agree! Don't know about a good default value but I usually use the 
--remove-short-arcs without any special value set-

 > 4.4. --add-pois-to-areas : i suggested adding this one, so i could
 > try to document it as best as i could :)
 > 4.5. --gmapsupp - what happens if i don't specify this option ? i
 > seem to get img just fine anyway

Ok, as I wrote before: I vote for having the following structure:
http://wiki.openstreetmap.org/wiki/Mkgmap:
No option descriptions. Just an overall description what mkgmap does and 
some important links:
- Download
- How to
- Options
- Styles
- Contact (Mailing list etc.)

How to:
Just as it is. A short list of steps you have to perform to build your 
first routable map. Most steps should have links to further information.

How to address search:
Move the list of steps to create a address searchable map to the new 
page with links to further information.

Options:
Descriptions for all options. Maybe with a good grouping and maybe more 
than one page.

Styles:
Description how the style system works and what one can do with it.

Contact:
The common links to mkgmap relevant pages and the mailing list

Go ahead!!
Thanks!

WanMil