[Serdev] Thoughts on Documentation -- Again

[Martin Hoffmann]

Andrei Pelinescu-Onciul wrote:
> On May 30, 2008 at 14:05, Martin Hoffmann <hn at nvnc.de> wrote:
> > 
> > So, unless anyone objects, I would like to start yet another attempt at
> > the SER User Manual. I would like to store the sources in the SER
> > repository, in doc/user_manual. For module documentation, I'd like to
> > keep a file reference.xml containing a single <refentry> for the module
> > in each module directory and ditch the old doc subdirectory.
> 
> So you want to move all the *.xml in modules/*/doc into this new
> directory doc/user_manual?

No. The reference.xml stays in the module directory. Since most people
want have all this XML and Docbook nonsense installed, we should
probably also put the man page in the tarball if not even CVS.

> Another point would be loosing history (if we move only the xml 
> files and not the whole doc dirs). OTOH I think that at least right now
> the history for docs has little value (is not like we need to see why
> some change happen in the docs very often :-)).

Before we start moving stuff around, we should move to a RCS that can do
these things. You will be able to keep you history, then ;)

> As far as I'm concerned I agree with anything that might bring us more
> documentation and it looks like your approach would :-) But my opinion
> doesn't really matter much when docs are involved (I haven't done any
> doc system testing like many of you have, I haven't written much docs
> and I'm more like the .txt or tex kind of guy anyway).

Hm, I haven't thought about texinfo so far. It is probably not a good
idea for the reference bits, since AFAIK it can't make man pages (which
I want).

But I started today to tinker with the user manual. While I am happy
with XML for the reference (it is an awful lot of markup and little
prose, so having something strict is quite good), it really sucks for
explanatory text. And since I believe that bad authoring tools lead to
bad text, I will have a look into using texinfo or even regular LaTeX
for the actual manual.

Regards,
Martin

PS: This is probably a bad time to suggest rtxt:

       http://binary.partim.de/mkweb/rtxt.html