[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Manifesto



As someone who recently joined this list because he was interested in
writing a HOWTO, I think it is important to make it easy for an author who
has a desire to contribute, and an idea for, documentation to create it
in a format that LDP will accept. No offense to anyone who has worked on
the guidelines in the past, but the first time I looked into the
procedure to create a document in the recommended format for submission to
LDP documentation my head started to spin. I understand the need to make
the documentation portable, but if a potential contributor needs to learn
a whole new program (to them), such as LinuxDoc or DocBook, or jump
through a number of hoops to submit their documentation, they might just
decide it is not worth the effort.

Edward Corrado

On Sun, 22 Oct 2000, David Lawyer wrote:

> 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 [email protected]
> with a subject of "unsubscribe". Trouble? Contact [email protected]
> 
> 


--  
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]