Opened 21 years ago
Last modified 20 years ago
#381 closed defect (fixed)
Request: GDAL and OGR Utility Manpages
Reported by: | warmerdam | Owned by: | warmerdam |
---|---|---|---|
Priority: | high | Milestone: | |
Component: | default | Version: | unspecified |
Severity: | normal | Keywords: | |
Cc: | neteler@…, silke@… |
Description
Prepare man pages for the GDAL and OGR utility programs (using Doxygen likely).
Attachments (4)
Change History (8)
comment:2 by , 21 years ago
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.
comment:3 by , 21 years ago
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
comment:4 by , 20 years ago
I believe Silke is now building the man pages and committing them in gdal/man tree. Closing this bug report.
Note:
See TracTickets
for help on using tickets.