[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 ldp-discuss-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
>
>
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org