Re: [slrn-doc] slrnpull doc update suggestion

[Peter J R. <pea...@gm...>]

On Sunday 03 August 2008 22:52:52 andrew wrote:
> On Sun, Aug 03, 2008 at 04:48:36PM -0400, Rudy Taraschi wrote:
> > Option 2 - get rid of everything and create a single HOWTO type
> > document, which can sit in the main slrn doc directory.
>
> I agree completely with Option 2.

So do I. Much the same could be done with the slrn documentation: e.g., 
FIRST_STEPS could be integrated at the beginning of the reference manual, and 
score.txt at the end.

> Since this option is obviously for 
> the long term it raises the question again about which format should
> be used? If linuxdoc sgml is used for such a large rewrite it will
> perhaps create unnecessary work in the near future when conversion to a
> different format would be undertaken.

<rant>
Linuxdoc SGML outputs ugly text, ugly HTML and ugly PDF. I haven't tried the 
other output formats, but I'm willing to bet they're ugly too.

Here are two documents for slrn newbies:

1. <http://andrews-corner.org/slrn.html>
2. <http://slrn.org/docs/FIRST_STEPS.html>

I want to be able to generate documentation that looks like 1, not 2. The fact 
that Linuxdoc is easy to learn is no reason to continue with it. Our job is 
to make life easy for users, not for ourselves.
</rant>

I suggest DocBook XML for new documentation and for eventual conversion of old 
documentation: <http://www.docbook.org/>. Anything that isn't Linuxdoc will 
do, as long as it's reasonably well documented, reasonably full of useful 
features, and capable of generating professional-looking output files.

Any other ideas? Of course, we're limited to some extent by what JED is 
willing to include with slrn, but not everything we produce has to be 
official; we can release supplementary "slrn-doc" packages too.

-- 
PJR :-)