[GRASS-dev] Manpage HTML markup consistency

[Dylan Beaudette]

On Tuesday 26 February 2008, Helena Mitasova wrote:
> DocBook has been considered for OSGeo edu material so there has been
> quite a bit of discussion on that - this is what Frank had to say:
>
> On the whole DocBook issue - we tried using DocBook for a while for
> MapServer
> docs and ended up abandoning it because installing and getting to
> understand DocBook tools was too hard for many potential contributors.  It
> also turned out to be a clumsy format to work in.  Perhaps things have
> improved, or we mapserverites were particularly dumb - but take that at
> least as a mild cautionary tale.  We ended up with documents written in
> html, and restructured text in plone though we aren't so thrilled with that
> either.  There is some consideration being given to just moving to a Trac
> wiki (though Trac wiki is particular weak as a wiki in my opinion).
>
> here is the discussion:
> http://lists.osgeo.org/pipermail/edu_discuss/2008-January/thread.html
>
> I tried DocBook and you just have to learn and get used to a new thing
> and it has its own complexities and I am not sure it is worth it.
>
> And BTW I am one those people who find having the old fashioned man pages
> on hand useful - I work a lot from home and it was much faster to view
> the simwe man pages that I was modifying using the old format than waiting
> for them to pop-up in remotely run web browser or move them around.
> I would also like to suggest keeping the man pages simple and easy to
> maintain, the more complex it gets, the fewer people will be able to
> maintain it and the more complex the task will become.
>
> Helena

This brings up a good question-- authoring. Are the manual pages going to be 
*mostly* generated on the fly from keywords and a template, as they are now, 
or do others envision some other approach. As it stands the boilerplate HTML 
document that accompanies each module isn't usually that complex, so 
authoring/editing these things wouldn't be too difficult (if a format like 
DocBook were to be used).

The complications would probably be primarily associated with writing new 
material, or longer how-to documents (like much of the material on the 
Mapserver page). 

I personally prefer LaTeX for documentation writing, but this may introduce 
too much overhead for users interested only in HTML documents. There are 
well-established tools to accomplish this, but not all users will have a TeX 
install. I noticed a tool called Latex2Man [1] which could simplify man page 
generation from a 'core' documentation set written in LaTeX.


1. http://ctan.tug.org/tex-archive/support/latex2man/latex2man.html


Dylan



> On Tue, 2008-02-26 at 09:31 -0800, Dylan Beaudette wrote:
> > On Monday 25 February 2008, Glynn Clements wrote:
> > > Dylan Beaudette wrote:
> > > > I wonder if now would be a good time to investgate the use of CSS in
> > > > the man pages. If we define a couple types of "container" objects
> > > > (<div>, <span>, etc) we can use a single style file to later
> > > > manipulate the look and feel of the manual pages.
> > >
> > > If you're going to overhaul the documentation, I suggest going all the
> > > way and using something which is intended to be used as a source for
> > > multiple formats (at least HTML and nroff, with one or more of TeX,
> > > PDF and PostScript as options), e.g. DocBook.
> >
> > Right-- this was the thought, although block-level CSS seemed like a
> > middle ground.
> >
> > I am not familiar with DocBook, but here is a good start:
> > http://en.wikipedia.org/wiki/DocBook
> >
> > There is a Debian package called 'docbook-defguide' which looks like it
> > contains much good information, saved (on my system) here:
> > /usr/share/doc/docbook-defguide/html/docbook.html
> >
> > It would be nice to have the option of converting the base manual into
> > one's favorite format: Man pages, HTML, LateX, PDF, etc.



-- 
Dylan Beaudette
Soil Resource Laboratory
http://casoilresource.lawr.ucdavis.edu/
University of California at Davis
530.754.7341