Re: Manifesto

[Guylhem Aznar <guylhemlistes@ifrance.com>]

At 17:24 10-22-2000 -0700, David Lawyer wrote:
>My comments:  The old manifesto clearly specifies what we require for
>HOWOTOs.  Here it is:

Would you like the new manifesto to include a part about docbook and linuxdoc?

>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.

Please add a verbatim copy of the docbook and linuxdoc paragraph to the new 
manifesto

>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.

You're right (there are some of them in my LUG) - go ahead and fix the 
paragraph

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

Nothing. Just drop it.

>     * 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.

It also depends on the format - that's why a PDF only document is not 
acceptable

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

Maybe we should explain that?

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

Nothing. Just move it to the license part.

>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.

I don't really like it either, it is just an example of low res format 
suited for old hardware, even if lynx or w3m do support html on these machines

>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.

The metadata should be added by a separate person to help the authors.

>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.

Right

>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.

Please add some explainations about transparent format and low res/hi res, 
ie readable on a screen and readable on a printout.


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