[GRASS-dev] Manpage HTML markup consistency

[Jachym Cepicky]

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
-- 
Jachym Cepicky
e-mail: jachym.cepicky gmail com
URL: http://les-ejk.cz
GPG: http://www.les-ejk.cz/pgp/jachym_cepicky-gpg.pub
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Toto je =?UTF-8?Q?digit=C3=A1ln=C4=9B?=
	=?ISO-8859-1?Q?_podepsan=E1?= =?UTF-8?Q?_=C4=8D=C3=A1st?=
	=?ISO-8859-1?Q?_zpr=E1vy?=
Url : http://lists.osgeo.org/pipermail/grass-dev/attachments/20080226/5b6ff56c/attachment.bin