[GRASS-dev] Manpage HTML markup consistency

[Helena Mitasova]

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


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.
>