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 _______________________________________________ grass-dev mailing list [email protected] http://lists.osgeo.org/mailman/listinfo/grass-dev
