Re: Debdoc

[Dmitry Borodaenko <d.borodaenko@belcaf.com>]

On Sun, Jul 23, 2000 at 07:40:32AM -0700, erik wrote:
> On Sun, 23 Jul 2000, Pavel M. Penev wrote:
> 
> > 
> > I think we could make the "index" page contain the introduction and make a
> > separate page on installlig, huh?
> 
>  Yep, I agree -had already made a note of it....

Just my 5 cents:

I think that you guys are missing one small point: you should not think
in terms of HTML ("index" page &c.) as a primary (source) documentation
format. Look at this quote from LWN:

   Along those lines, the Open Documentation Summit was a pre-conference
   meeting to the Open Source Convention. Eight hours long, it focused
   on improving the documentation that accompanies open source software,
   reports O'Reilly. Participants included representatives from the
   Linux Documentation Project, GNOME, KDE, FreeBSD, BSDI, SourceForge,
   Samba, OASIS, Los Alamos National Labs, Python, and Open Content.

   "The major conclusion reached by attendees was to standardize on
   DocBook/XML as the canonical format for open source documentation.
   The role of DocBook, however, is to be the storage and exchange
   format.  Different projects will use it in different ways, but all
   will provide some form of their documents in a standard DocBook
   format".

I agree that XML is not as common and well-understood as HTML, but still
it is simpler than TeX or SGML (I think this is the only justification
of it's mere existence). And the reason XML suits better for writing
docs is that it separates content from representation. Simply put, one
XML document may be translated with stylesheets into different
representatons suitable for graphic or text-only on-screen reading,
printout or speech synthesis program or whatever. Well, ask James Clark
if you want to know more.

The package you plan to work on is a Good Thing, and I wish it not be
spoiled by use of HTML. Why HTML, when everyone and his mother uses or
moves to DocBook over SGML at least? Anyone who can write HTML will not
need to learn much before starting to write XML docs.

Best regards,

Dmitry