[mkgmap-dev] documentation improvement patch

Tue Jan 14 12:05:13 GMT 2020

Hi Gerd,

It appears that mkgmap can only display ASCII characters, so although
non-ASCII characters are copied faithfully from options.txt to options,
mkgmap cannot display them. I have added an ASCII test to the code which
displays the line number and offending text, - it transpires there was a non
ASCII letter in the example usage of --mdr7-excl=name plus three special
hyphens.

For the long lines, I hadn't handled the case where adding two lines
together exceeded 160 characters and hence needed chopping twice. Now fixed.

I did wonder about taking out the example file. I have removed this from
options.txt and put it in a new file logging.txt and referenced it from
index.txt. I've also put it in a logging file for display from the command
line with help=logging. It may still look like a stack trace there, but
should at least be more expected. I have added a bit more information and a
reference to the Java documentation on logging at the end (primarily so you
can see something after the 'stacktrace').

How does that seem?
Mike

-----Original Message-----
From: Gerd Petermann [mailto:gpetermann_muenchen at hotmail.com] 
Sent: 14 January 2020 09:12
To: Mike Baggaley <mike at tvage.co.uk>; 'Development list for mkgmap'
<mkgmap-dev at lists.mkgmap.org.uk>
Subject: AW: [mkgmap-dev] documentation improvement patch

Hi Mike,

I see a few problems in the generated file options:
-  some scrambled characters around Xmx4g  . Seems this is a special hyphen
character?
I think the example file for the log configuration should be moved into
another file.
I used the command
java -jar dist\mkgmap.jar --help=options | more
to read the help and was tempted to think that the program crashed when I
saw those lines with
# The default level FINE, WARNING, INFO, SEVERE
.level=SEVERE
#handlers: java.util.logging.ConsoleHandler
handlers: java.util.logging.FileHandler java.util.logging.ConsoleHandler
# package or class name with .level appended and
...
It looks almost like a stacktrace ;)
We already have the file logging.properties in the resources folder, but it
is not copied to the dist\examples directory.
Maybe we should distribute both versions. e.g. as default.logging and
detailed.logging in examples?
- a few lines are much longer than the others, e.g.
"is somewhere between 1648 and 5520 for 1'' hgt input files (3312 is often
used), and 5520 to 9942 for 3'' hgt input files."
"    multipolygon, polygons and land-tag. The coastlinefile option is
ignored if precomp-sea is set."
Looks like a special case for buildoptions?

Gerd

________________________________________
Von: mkgmap-dev <mkgmap-dev-bounces at lists.mkgmap.org.uk> im Auftrag von Mike
Baggaley <mike at tvage.co.uk>
Gesendet: Montag, 13. Januar 2020 20:17
An: 'Development list for mkgmap'
Betreff: Re: [mkgmap-dev] documentation improvement patch

Hi Gerd, please find attached an updated patch that moves the section
mentioned below to index.txt.

Cheers,
Mike

-----Original Message-----
From: Mike Baggaley [mailto:mike at tvage.co.uk]
Sent: 04 January 2020 18:42
To: 'Gerd Petermann' <gpetermann_muenchen at hotmail.com>; 'Development list
for mkgmap' <mkgmap-dev at lists.mkgmap.org.uk>
Subject: RE: [mkgmap-dev] documentation improvement patch

Hi Gerd, it might be reasonable to move the following section to the
background section of index.txt, as it is not directly about the command
options:

A typical simple example using both splitter and mkgmap:

:       java.exe -Xmx2g -jar splitter.jar england-latest.o5m
:       java.exe -jar mkgmap.jar --gmapsupp -c template.args

The first command splits the Open Street Map data into smaller files
with each file containing the data for one tile of the map. It also
produces a file named template.args that contains the names of all
the generated files.

The second command takes as input all the individual files listed
in the template.args file generated by splitter, produces a .img
file for each tile, then merges all the tiles together into a
single gmapsupp.img file.

The rest of it is all about options and how to use them as far as I can see,
though some of the obsolete/ignored options could be removed, as presumably
they are now old enough to have no relevance.

Regards,
Mike
-----Original Message-----
From: Gerd Petermann [mailto:gpetermann_muenchen at hotmail.com]
Sent: 04 January 2020 08:12
To: Mike Baggaley <mike at tvage.co.uk>; 'Development list for mkgmap'
<mkgmap-dev at lists.mkgmap.org.uk>
Subject: Re: [mkgmap-dev] documentation improvement patch

Hi Mike,

thanks again. My 1st thought about the additions in options.txt was that it
produces a mix of FAQ /README and documentation about the options.
I think we should not do that.
I'll have a closer look again when the work on the is_in style function is
done.

Gerd

________________________________________
Von: mkgmap-dev <mkgmap-dev-bounces at lists.mkgmap.org.uk> im Auftrag von Mike
Baggaley <mike at tvage.co.uk>
Gesendet: Dienstag, 31. Dezember 2019 01:31
An: 'Development list for mkgmap'
Betreff: Re: [mkgmap-dev] documentation improvement patch

Hi Gerd, it looks like I inadvertently indented one section of the file
which caused the blanks. I have reworked the program so that it now has a
very basic understanding of paragraphs and can do the line length limiting
itself. It only has a very basic understanding of HTML (just ,<p>, <pre> and
</pre> and only when on a line by themselves). I have reverted my manual
chopping up of lines in options.txt, so there are now far fewer changes
(though I have fixed a few more typos) so it's much easier to see what is
going on (still lots of changes in the generated options file of course). I
have chopped out a number of <p> tags in options.txt for consistency - there
were some places where it was used before a new option and some where it was
not. Looking at the existing web page, you can see a small difference in
spacing between the two cases.  I just run the buildoptions program from
within my Eclipse Java environment. You can compile and run it by following
the following steps assuming you have a command prompt with its working
directory set to the mkgmap root directory:

cd options
javac buildoptions\main.java
java buildoptions.main

Note that so that the above works, I have changed the hard coded paths to
the input and output files to be relative to the options folder, so if
running from Eclipse, you need to set the working directory to
${workspace_loc:mkgmap/options} instead of using the default.

Cheers,
Mike

-----Original Message-----
From: Gerd Petermann [mailto:gpetermann_muenchen at hotmail.com]
Sent: 30 December 2019 09:40
To: Mike Baggaley <mike at tvage.co.uk>; 'Development list for mkgmap'
<mkgmap-dev at lists.mkgmap.org.uk>
Subject: AW: [mkgmap-dev] documentation improvement patch

Hi Mike,

thanks for the work. The patch applies fine now.
I don't understand some of the reformatting in options.txt.  I think they
were not intended.
See for example --split-name-index: Blanks at the beginning of the lines and
"See also option road-name-config." is no longer on a separate line.

It seems I am to stupid to run the java program on my machine :(
Please desribe the steps to compile and run it.

Looking at the source it seems you want to force max. 80 characters on one
line in the options.txt file so that the
buildoptions program doesn't have to reformat paragraphs?
This looks like a complicated work flow when I edit options.txt:
Edit, save, run buildoptions program, check if it complains about lines
longer than 80 characters, edit again ...
I think the java code should be able to detect a paragraph and split it into
pieces?

Gerd

-------------- next part --------------
A non-text attachment was scrubbed...
Name: doc-v7.patch
Type: application/octet-stream
Size: 187347 bytes
Desc: not available
URL: <http://www.mkgmap.org.uk/pipermail/mkgmap-dev/attachments/20200114/0a3d7605/attachment-0001.obj>