search

mantlik / osm2garmin

Convert OpenStreetMap data to Garmin-compatible format.
http://osm2garmin.mantlik.org/
GNU General Public License v2.0
8 stars 1 forks source link

Update documentation for Release 1.2 #95

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago 
Pitney wrote:

Hello 

I would like to volunteer to update the User's Guide to help support this 
project.

I propose to:

- document all features/options
- expand the descriptions of various options, with examples where appropriate
- provide install/uninstall instructions for all 3 os's, listed separately

To accomplish this I need help in 3 areas:

- a contact who can explain features/options currently not documented
- installation help for Mac/Win environments (I can do the Linux)
- someone to review my changes, for what is clear to me may not be clear to 
others

A posting this past summer referenced a location for an editable User Guide but 
this is no longer valid.  I need this also.

Finally an understanding of the time line for making 1.2 a stable release.

Thanks, pitney

Original issue reported on code.google.com by mantl...@gmail.com on 9 Jan 2013 at 9:23

GoogleCodeExporter commented 9 years ago 
Dear user,

thank you for your willingness to help with the documentation.

Current state of the user's guide corresponds to the stable 1.1 version. Please 
note, that the 1.2 release is currently under development and present state of 
the user interface can change anytime in the future. Similarly, new features 
can appear later. Development of the 1.2 version is not frozen yet. Under 
normal development cycle, manual updates are made in the final stage of the new 
release preparation.

Regardless of this, you are welcome to contribute to the documentation, of 
course, and your initiative is highly appreciated!

The documentation was created in Docbook 5 format and it's source is a part of 
the source code of the project. Corresponding clones of the documentation 
(HTML, PDF and Javahelp) are generated automatically in corresponding build 
steps as a part of the project build process. Development environment used is 
Netbeans with Maven. Source Git repository is located here: 
http://code.google.com/p/osm2garmin/source/browse/

If you are familiar with Netbeans, Docbook, Maven and Git, you can clone the 
source repository and directly update Docbook sources in the docbook 
subdirectory of the sources tree of the Osm2garminGUI subproject and submit the 
patch here. Please note that all figures are located in the javahelp source 
subtree, any figures in the docbook directory will be ignored.

If you are not familiar with the development tools, it is not worth to learn 
them, I guess. It would be helpful enough for me if you can upload proposed 
documentation extensions in the raw text format here together with figures (png 
format) and I can add appropriate Docbook tags where needed and update the 
corresponding sources.

Please refer to the ReleaseNotes wiki to find out new features currently 
implemented in the Release 1.2. More detailed information can be found in the 
discussion in corresponding Issues. In addition, please refer to open issues 
marked with Milestone Release 1.2 tag to find out changes planned to be 
included in the development version in the future.

Release 1.2 will be stabilized as soon as all opened issues for this release 
will be resolved (fixed, ignored or postponed to the next release) and the 
development release will proof itself stable, i.e. no new defect issues will 
appear for a while.

Thank you once more for your initiative.

Original comment by mantl...@gmail.com on 9 Jan 2013 at 10:14

GoogleCodeExporter commented 9 years ago 
Hello -

Working on the updated User's Guide and I have the following questions.  Short 
answers please.

Main Window, Icons – what is the function of:

Save all
undo/redo arrows

Main Window, create contours “box”  - shows a value of “null” - 
possible reasons?

If the program runs out of memory, what message is shown in the “output” 
window/tab?

Programs settings – what is the function of the Export/Import buttons?

Processing Parameters -

Contour Interval – what happens if a value of 0 (zero) is used?

Maximum # of contours... - is this the # in a cell or in a tile?  Also, valid 
for minor, medium, major?

Are contours generated for tiles or files?

Delete old maps... - what maps and what directory?  Just those in the region 
directory?

.img files – 4xxx.img are contour files, 7xxx.img files are osm data files 
–  is this correct?

Are startup options really listed by passing -h or –help as an option?

What is the default value of Java -J-Xms?

Windows and Mac installation instructions.

Original comment by mappit...@gmail.com on 29 Jan 2013 at 11:47

GoogleCodeExporter commented 9 years ago 
Sorry for delay, I was out last week. Here are quick answers to your questions:

Save all, Undo, Redo are (or should be) in effect when editing settings files 
only. They provide basic text editor functions.

Out of memory in the output:
Unspecific, depends on the situation when OOM situation occurred. Output window 
and logs need to be examined to find out the source problem. Under some 
circumstances the program does not launch at all.

Export/import buttons in Program settings:
They are general purpose Netbeans buttons. they do not have special meaning in 
Osm2garmin. They are intended to be used e.g. for exporting/importing user 
settings between instances of the program but this does not have practical 
applications for Osm2garmin. I did not test whether it works at all. On the 
other hand, there is no simple way how to remove them, so the best is to simply 
ignore both of them.

Contour interval:

0 value will (most probably) confuse processing and cause wrong results or 
program crash. You can try, if you want.

Maximum # of contours is meant in a single SRTM cell, i.e. approx. 90x90 
meters. The value is valid for minor contours. Medium and major contours are 
always plotted.

Are contours generated for tiles or files?
The process is a little more complicated. First of all, contours are generated 
for the whole tile (default 5x5 degrees). As a next step, tile splitter splits 
the tile depending on density of generated contours to smaller chunks. Finally, 
each chunk is converted from OSM to Garmin format and the whole tile is packed 
and stored in Contours directory. Next time, when a particular tile already 
exists, the whole tile is unpacked to the corresponding region's directory. 
Thus, under normal circumstances contours overlap the region up to the contours 
tile boundary.

Delete old maps...
The entire region directory for each region selected for processing is deleted 
at the beginning of processing if Delete old maps is checked.

.img files numbering
Contour files start with 3,4,5 and 6 depending on position on the globe. 
Numbering is selected so as any single tile has an unique number even if each 
tile has 1x1 degree extent only. OSM maps are numbered sequentionaly starting 
from 70000001 for each region. (This is not important information for a regular 
user, I guess).

Startup options:
These are startup options for application launcher, not for the program itself. 
The launcher is in fact Netbeans RCP launcher. You can get help passing -h or 
--help (notice double hyphen) to the launcher.

Default values for Java Virtual machine
Default values for -J-something options (Java virtual machine parameters) 
depend on the Java virtual machine installed on the user's computer. They are 
different depending on platform, version of the OS, Java version and many other 
factors. One important thing for Osm2garmin is that you can not get more than 
about 1400 Mbytes of memory on 32-bit Java installations, but even this 
threshold depends on other factors. Plese note that even parameters themselves 
can differ for different Java installations and try not to confuse users too 
much, please.

Installation instructions:
I can't provide much more than you can find in the current version of the 
manual. In general, the installation wizard should be platform independent. As 
such it should look similarly for each platform. The only platform dependent 
thing should be launching of the installer/uninstaller only, but such a thing 
should be supposed to be trivial and as such not included in the manual, I 
guess. It should be made standard way in the manner which is common to any 
application installed on the user's computer.

Original comment by mantl...@gmail.com on 4 Feb 2013 at 1:12

GoogleCodeExporter commented 9 years ago 
Hello -

Attached (as .txt and .odt) is my first pass at the 1.2 Users Guide.  I have 
added a Reference section describing the program's controls and settings as I 
have struggled over the past few months trying to use other undocumented 
programs.  This effort has helped me to use o2g and hopefully others as well.

Feedback is needed and appreciated.  One concern I have is that my English is 
too complicated... ;)  Thanks, pitney

Original comment by mappit...@gmail.com on 10 Feb 2013 at 5:13

Attachments:

GoogleCodeExporter commented 9 years ago 
This issue was updated by revision r254.

Updated documentation taking into account mappitney's suggestions.

Original comment by mantl...@gmail.com on 21 Feb 2013 at 3:57

GoogleCodeExporter commented 9 years ago 
This issue was updated by revision r255.

Admonition graphics for PDF replaced with vector graphics (svg).

Original comment by mantl...@gmail.com on 12 Mar 2013 at 1:59