279 lines
12 KiB
HTML
279 lines
12 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: Manifesto -->
|
|
<!--X-From-R13: "Sqjneq [. Qbeenqb" <rpbeenqbNnguran.evqre.rqh> -->
|
|
<!--X-Date: Mon, 23 Oct 2000 08:36:05 -0400 (EDT) -->
|
|
<!--X-Message-Id: Pine.GSO.4.21.0010230824010.9454-100000@athena -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 20001022172424.A256@localhost -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: Manifesto</title>
|
|
<link rev="made" href="mailto:ecorrado@athena.rider.edu">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg04171.html">Date Prev</a>][<a href="msg04173.html">Date Next</a>][<a href="msg04204.html">Thread Prev</a>][<a href="msg04253.html">Thread Next</a>][<a href="maillist.html#04172">Date Index</a>][<a href="threads.html#04172">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: Manifesto</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>></li>
|
|
<li><em>Subject</em>: Re: Manifesto</li>
|
|
<li><em>From</em>: "Edward M. Corrado" <<A HREF="mailto:ecorrado@athena.rider.edu">ecorrado@athena.rider.edu</A>></li>
|
|
<li><em>Date</em>: Mon, 23 Oct 2000 08:36:33 -0400 (EDT)</li>
|
|
<li><em>Cc</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
<li><em>In-reply-to</em>: <<a href="msg04169.html">20001022172424.A256@localhost</a>></li>
|
|
<li><em>Resent-date</em>: Mon, 23 Oct 2000 08:36:05 -0400 (EDT)</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <yEAbhC.A.L1E.AFD95@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
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
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="04253" href="msg04253.html">Re: Manifesto</a></strong>
|
|
<ul><li><em>From:</em> Martin WHEELER <mwheeler@startext.co.uk></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="04169" href="msg04169.html">Manifesto</a></strong>
|
|
<ul><li><em>From:</em> David Lawyer <dave@lafn.org></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg04171.html">=?big5?B?QLrrrV6tcLVlQA==?=</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg04173.html">Feedback</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg04204.html">Re: Manifesto</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg04253.html">Re: Manifesto</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#04172"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#04172"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|