[GRASS-dev] Manpage HTML markup consistency

[Helena Mitasova]

This was also discussed at OSGeo Edu and I am so far sticking with LaTeX
for the lecture notes and the GRASSbook is written in Latex too. 
I am not sure about its suitability for manpages -
many people are scared of its complexity although there is an easy 
to use text editor for it (see below) and I don't find it complex at
all, as long as Markus does the layout and formatting :)

Helena

http://lists.osgeo.org/pipermail/edu_discuss/2008-January/000682.html
http://www.lyx.org



On Tue, 2008-02-26 at 20:14 +0100, Jachym Cepicky wrote:
> Hi,
> 
> I do not know, if anybody already excluded LaTeX for better
> documentation output, but this format has it's potential as well...
> 
> 
> Jachym
> 
> Helena Mitasova píše v Út 26. 02. 2008 v 12:54 -0500:
> > 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.
> > > 
> > 
> > _______________________________________________
> > grass-dev mailing list
> > grass-dev at lists.osgeo.org
> > http://lists.osgeo.org/mailman/listinfo/grass-dev