Request: GDAL and OGR Utility Manpages

[warmerdam]

Prepare man pages for the GDAL and OGR utility programs (using Doxygen likely).

[warmerdam]

I made a first attempt at this with Doxygen and was unable to produce any
respectible results.  It is unlikely this will be completed in the near future
at this rate. 

[warmerdam]

Silke writes:

If this is just a problem of reformating the descriptions I would
volunteer to do this manually. Therefor I need 
a) a declaration that these descriptions are under a free licence
b) your OK that the text is suitable for man pages. Of course I
would add some sections like "SEE ALSO", "OPTIONS" but I feel not
able to rewrite the description or even to recognize errors.

Please let me know if you think that this is a possible solution.
Then I could begin to reformat the pages. You would then be informed
about the progress by the bugtracker.

	Silke

---

Silke, 

I can declare that the existing utility descriptions are under the MIT/X
license I normally use for the rest of GDAL.  

But I don't want to manually create and maintain man pages for the GDAL
utilities, I would like them to be auto-generated from the Doxygen inputs. 
However, can't see how to get decent "man" output that looks right for man
from Doxygen.  Also, it isn't clear how to group them.  In the HTML output
I like the utilities all being on one page but in man I would like a seperate
man page for each utility.  

Also, I don't want to install all the API man pages generated by Doxygen, as
it produces lots of surplus crap.  I wouldn't mind installing the API
docs, but ideally I would be able to easily know the difference between 
command man pages and API man pages.  This does not appear to be easy.

Now, if you have an excellent understanding of Doxygen (or time to spend on it)
and can wrestle it into what I want, then you could be a big help.  But if you
just manually produce a set of man pages that will quickly fall out of sync
with reality then that is much less useful. 

[silke@…]

patch for doxygen version 1.3.3

[silke@…]

config for html-pages

[silke@…]

config file for man pages

[silke@…]

example documentation file

[silke@…]

Hallo Frank!
I played a little bit with doxygen and I think I found solutions for
(almost) all of your problems:

* to group the documentation of man-pages and HTML in different kind of
ways we should use different doxygen conf files. Then we can play with
ENABLED_SECTIONS.  Please look at the attachments gdal_man.dox and
gdal_html.dox and as an exemple gdal_utilites.dox to see how this works. I
had to patch doxygen so that beginning new pages were ignored when the man
sections is not enabled. Of course a manonly flag would be nicer. I first
tried this but also in this case beginning new pages were created even for
html. Fixing this would have been much more complicated.

* The man output was indeed not very nice looking. I first adapted
gdal_utilities.dox to use description lists (only for gdalinfo). This makes
the description of the flags much nicer. Than I patched doxygen to have
nicer output for simple lists.

* Concerning the API man pages I decided to do nothing in the first case.
How exactly do you want to have reflected the difference between API and
bin man pages?

Please let me know whether you find the proposed solution suitable. I then
would adapte gdal_utilities.dox and ogr_utilities.dox to produce decent man
pages for all binaries.

Greetings,

Silke
  

[warmerdam]

I believe Silke is now building the man pages and committing them in 
gdal/man tree.  Closing this bug report.