GNOME.org
 

Re: Linux Documentation Infrastructure

Kim Lester wrote:

> We need to stop evolving doc systems and bring it all together.

Exceedingly well put!

> Convert (in some cases
> on the fly) all docs into one infrastructure, whilst maintaining the
> ability to handle frequently changing doc text.
> 
> >From what I've seen LDP and GDP are addressing an important part of
> getting a set of new docs up-to-date
> and mostly in some sort of format. What I see as the next step is
> unifying the strucutre.

I couldn't agree more, so far.
 
> Please bear with be while I explain, and if I've missed a key point

I think so. See below.

[snip]

> My recommendation which I want to help with, (time permitting :-) ) is
> to reduce the number of formats to 3 initially and 2 later. I think
> fewer is impractical,

One, now, is quite practical.

> however all formats would be presented though a similar front end
> so the formatting would not matter so much.

HTML with a browser as the front end and print formatter.

> My suggested minimal formats are:
>         *) sgml
>         *) man
>         *) plain-text

Most of the relevant SGML uses either Docbook or Linuxdoc DTDs and
there are tools to produce HTML from text encoded with those.

Browsers can display plain text if you add <html> and <pre> tages.

There are several man2html tools around. For links to examples of
the output of one, try:

http://www.freeswan.org/freeswan_trees/freeswan-1.2/doc/manpages.html

Those man pages are written and maintained by the programmers. The
tech writer (me) created the index page and wrote about 10 lines
of Makefile and shellscript calling man2html to produce the HTML
man pages. Since then, the project lead has altered the scripts to
improve the cross-referencing. It all works, our stuff is allGPL,
and I think the man2html tool is too.

There's an info2html tool available too. There is a lot of essential
information in info files. What do you do with it?

   Rewriting it just to get it into a format that fits into your
   integrated list would be a horrible waste of resources.

   Persuade FSF that info is obsolete and should be replaced? That may
   not be easy and if you did manage it, you'd still have some problems.
   What's the new format and what do we do with the old info docs?

   Writing any automated info2whatever conversion toll would likely
   involve considerable work. 

No. Just use info2html and deliver the HTML.

So I think we need a system that follows the old protocol builder's
maxim "Be liberal in what you accept, be carefully limited in what
you send out".

Input:
     man/troff
     SGML/Linuxdoc
     SGML/Docbook
     info
     HTML
     add more as required and when resources are available

Output:
     HTML

That leaves two main problems.

One is structuring the collection of HTML files. Your suggestions seem
like an excellent starting point for that, but I need to both think
more about it and hear what others have to say.

The other is implementing various tools that would make this work.

Quite a few pieces of it are out there. info2html. man2html, ...

Several groups -- at least LDP, OSWG, and the BSD doc project I think --
have scripts that build large chunks of web sites with sgml2html
tools. Those could likely be adapted to do another chunk of this.

The FreeS/WAN distribution includes a tool of mine that generates a
permuted index from <h?> headers in a group of HTML files. Quick and
dirty code, needing work, but a starting point.

FreeS/WAN also has a tool that post-processes html2man output and
inserts additional links.

The Amaya browser/editor from w3c.org has a handy "make book" feature.
Build an index file using href tags with "rel=subdoc" attribute, load
it in Amaya, hit "make book" on the menu and it replaces each such
tag with the referenced file, adjusting links as required and optionally
producing a table of contents for the whole thing.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]