[mkgmap-dev] documentation improvement

Tue Apr 7 10:33:40 BST 2020

Hi Gerd & Mike

@gerd - as you say, it is better to just improve the documentation of
what is there. As far as I could see it was only the tiles and gmapsupp
that took the --description.

I'd suggest changing from:

;--description=text
:       Set the descriptive text for the map. This may be displayed in
QLandkarte, MapSource or on a GPS, where it is normally shown
below the family name. Example: --description="Germany, Denmark"
Please note: if you use splitter to build a template.args file
and pass it to mkgmap, then that file may contain a "description"
that will override this option. To prevent splitter from overriding
your description, place the --description option
after "-c template.args".

to:

;--description=text
:	Set the descriptive text of map components.
Map tiles take the most recent --description before the --input-file
that defines the tile.
gmapsupp.img takes the last --description.
Note that the splitter generated template.args includes
relevant --description values (see splitter --geonames-file).
The usage of the component descriptions is not consistent between
GPS devices, MapSource, Basecamp and QLandkarte.
Some use the --family-name to enable the complete map, others use the
gmapsupp.img description.
Some devices can enable individual tiles using the tile description.
Suggested usage:
  ... -c options.cfg -c template.args --family-name=Scandinavia
  --description=Scandinavia --gmapsupp typFile.txt

@mike - if you & Gerd are happy with something like this, do you want
to put it into your patch, otherwise I'll do it once your option
changes are out of the way.

Ticker

On Tue, 2020-04-07 at 07:57 +0000, Gerd Petermann wrote:
> Hi Ticker,
> 
> I think this was discussed before and that discussion lead to the
> chapter about template.args. My suggestion would be to add a hint
> that the last given description is used by the combiners. I found
> usage in OverviewBuilder, TdbBuilder, and GmapsuppBuilder, not sure
> what the other combiners use. NsisBuilder and GmapiBuilder should be
> checked.
> I don't like the idea to introduce just another "description" option
> with unclear meaning, we already have so many.
> I also don't like the idea that we might break backward
> compatibility.
> 
> Gerd
> 
> ________________________________________
> Von: mkgmap-dev <mkgmap-dev-bounces at lists.mkgmap.org.uk> im Auftrag
> von Ticker Berkin <rwb-mkgmap at jagit.co.uk>
> Gesendet: Montag, 6. April 2020 19:01
> An: Development list for mkgmap
> Betreff: Re: [mkgmap-dev] documentation improvement
> 
> Hi
> 
> This explains an annoyance I've had with my newer eTrex 30x.
> 
> On the eTrex HCx, the map selection function uses the --family-name
> value. The same map on the 30x just gave the name of one of the
> tiles,
> which, now I look, was always the last.
> 
> Putting a final --description after the tile definitions now gives me
> something that will work sensibly on both.
> 
> I'd like to request an enhancement that gmapSuppBuilder uses a new
> option instead of --description.
> 
> Ticker
> 
> On Mon, 2020-04-06 at 15:04 +0000, Gerd Petermann wrote:
> > Hi Mike,
> > 
> > will have a closer look tomorrow. Why do you think that  "putting -
> > -description after -c template.args " is incorrect?
> > When you use splitter with the --geonames-file option or with the -
> > -description option the template.args file will set
> > description.
> > If you use both the --description option is ignored.
> > The last given value for description is used for the combiners.
> > 
> > Gerd