Manifesto

[David Lawyer <dave@lafn.org>]

Sorry for my delay in getting to this.  I somehow have an aversion to
dealing with it.  In this post I'll only comment on section 4: FILE
FORMAT RECOMMENDATIONS (new) or DOCUMENT CONVENTIONS (old):

Old manifesto:

4. DOCUMENTATION CONVENTIONS

   Here are the conventions that are currently used for LDP documents. If
   you are interested in writing another document using different
   conventions, please let us know of your plans first.
   
   All HOWTO documents must be in one of the two SGML formats: LinuxDoc
   or DocBook. LinuxDoc is the simplest while DocBook is more complex
   with more features.
   
   The guides -- full books produced by the LDP -- have historically been
   done in LaTeX, as their primary goal has been to be printed
   documentation. However, guide authors have been moving towards SGML
   with the DocBook DTD, because it allows them to create more different
   kinds of output, both printed and on-line. If you use LaTeX, we have a
   style file you can use to keep your printed look consistent with other
   LDP documents.
   
   The man pages -- the Unix standard for online manuals -- are created
   with the Unix standard nroff man (or BSD mdoc) macros.
               ______________________________________________

Proposed Manifesto:
   
4. FILE FORMAT RECOMMENDATIONS

   We are concerned that:
     * Documents will not be accessible to blind people or to people who
       depend on voice-reading applications
     * Free documentation will lose support and become less available
     * Free documentation will not be readily discovered, administered or
       searched
     * Free documentation will not be easily modifiable or extensible
     * Free documentation will not be available in a human readable
       format, as a "transparent" source
     * Documentation will not be freely distributable in a legally
       unrestricted way
       
   To overcome these concerns, we recommend:
     * source file formats that can be converted to the following output
       formats:
          + high resolution formats for typesetting such as DVI or
            Postscript, which support images
          + low resolution format (plain text) for low bandwidth or
            text-only devices
          + HTML for the current generation of Web browsers
          + Info (HTML and Info provide for both sighted and blind
            people)
     * support for comprehensive meta-data for discovery, collocation,
       evaluation, administration, authentication and search
     * transparent source (clear text editable by a generic editor,
       images in an open format)
               ______________________________________________
   
My comments:  The old manifesto clearly specifies what we require for
HOWOTOs.  Here it is:

   All HOWTO documents must be in one of the two SGML formats: LinuxDoc
   or DocBook. LinuxDoc is the simplest while DocBook is more complex
   with more features.

It's been stated that one may submit in plain text and then someone
will convert it.  But this will be difficult if there is no abstract
or sectionalization of the text document.

If the Manifesto is going to go into the reasons why we use certain
source formats, this needs to be kept very brief IMO.  We must not
only consider what is best for readers but what is easy for authors
including ones not familiar with a markup language.  What is proposed
only considers the needs of the readers.

4. FILE FORMAT RECOMMENDATIONS

   We are concerned that:
     * Documents will not be accessible to blind people or to people who
       depend on voice-reading applications
Wouldn't it be simpler to say that we would like our docs to be
accessible to a wide audience including people who use old hardware or
are vision impaired.  Many people erroneously think that blind people
can't see at all, but many of them are only partially blind.

     * Free documentation will lose support and become less available
What does this have to do with format?

     * Free documentation will not be readily discovered, administered or
       searched
Most of the solution to this doesn't depend on the format.

     * Free documentation will not be easily modifiable or extensible
This depends on the license and also on the format but people who read
the manifesto will not understand the implications.

     * Free documentation will not be available in a human readable
       format, as a "transparent" source
Again, many will not grasp the implications.

     * Documentation will not be freely distributable in a legally
       unrestricted way
What has this to do with format?       

   To overcome these concerns, we recommend:
     * source file formats that can be converted to the following output
       formats:
          + high resolution formats for typesetting such as DVI or
            Postscript, which support images
          + low resolution format (plain text) for low bandwidth or
            text-only devices
          + HTML for the current generation of Web browsers
          + Info (HTML and Info provide for both sighted and blind
            people)

The info system is complicated to use and I don't like it (but am
forced to use in sometimes).  I'm not sure we need to convert into it.

     * support for comprehensive meta-data for discovery, collocation,
       evaluation, administration, authentication and search

The problem here is that it's a lot of extra effort for the authors to
add metadata.  I think for most HOWTOs it would be much more
productive to improve their content and quality.  Since the sgmls 
we use allows one to create new tags, I don't think there is any need
to mention this.

     * transparent source (clear text editable by a generic editor,
       images in an open format)
               ______________________________________________
I really think we need to start over and redo this section from scratch.  The
"Old manifesto" was not written by me.  I only revised it and kept most of
the previous stuff.  Thus I think that it needs improvement.  In
addition, circumstances have changed.  So I'm not proposing that we
use the old one.

I think that the manifesto (or some other "official" document) should
mention what formats we accept.  This section  shouldn't be called
"recommendations" but "requirements" or "conventions".  Otherwise
people will think that we accept any format and not bother to read it.

Here's what I would say (in part):

We distribute LDP documentation in various formats such as HTML,
Postscript, and plain text.  Authors write in a format which can be
converted (by computer) to these formats (and more).  Formats which 
can be so converted include: DocBook or LinuxDoc (both are
SGML languages).  HOWTOs should be in one of these formats.  If you
use DocBook check first to see which versions we accept.

You may see what these sgml formats look like by downloading a HOWTO
(in sgml) from an LDP site.  We may accept a HOWTO in just plain text
if we can find someone to manually convert it to DocBook, etc.

[Add here whatever policy we want for the guides and FAQs.]


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org