283 lines
12 KiB
HTML
283 lines
12 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: Style Guide (was Re: I'm a sucker) -->
|
|
<!--X-From-R13: Rnivq Zyblq <yybl0076Nerory.arg.nh> -->
|
|
<!--X-Date: Tue, 10 Oct 2000 12:31:41 -0400 (EDT) -->
|
|
<!--X-Message-Id: 39E347AD.863C2A9B@rebel.net.au -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 025836EFF856D411A6660090272811E61D07F6@EMAIL -->
|
|
<!--X-Reference: 39E2A794.9935F5A5@rebel.net.au -->
|
|
<!--X-Reference: 10010100942.ZM13248@hoop.timonium.sgi.com -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: Style Guide (was Re: I'm a sucker)</title>
|
|
<link rev="made" href="mailto:lloy0076@rebel.net.au">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg03987.html">Date Prev</a>][<a href="msg03989.html">Date Next</a>][<a href="msg03986.html">Thread Prev</a>][<a href="msg03991.html">Thread Next</a>][<a href="maillist.html#03988">Date Index</a>][<a href="threads.html#03988">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: Style Guide (was Re: I'm a sucker)</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: Greg Ferguson <<A HREF="mailto:gferg@hoop.timonium.sgi.com">gferg@hoop.timonium.sgi.com</A>></li>
|
|
<li><em>Subject</em>: Re: Style Guide (was Re: I'm a sucker)</li>
|
|
<li><em>From</em>: David Lloyd <<A HREF="mailto:lloy0076@rebel.net.au">lloy0076@rebel.net.au</A>></li>
|
|
<li><em>Date</em>: Wed, 11 Oct 2000 02:15:33 +0930</li>
|
|
<li><em>Cc</em>: Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>>, <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>References</em>: <<a href="msg03977.html">025836EFF856D411A6660090272811E61D07F6@EMAIL</a>> <<a href="msg03981.html">39E2A794.9935F5A5@rebel.net.au</a>> <<a href="msg03986.html">10010100942.ZM13248@hoop.timonium.sgi.com</a>></li>
|
|
<li><em>Resent-date</em>: Tue, 10 Oct 2000 12:31:41 -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>: <wBnE2.A._ZH.rT045@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>Sender</em>: <A HREF="mailto:lloy0076@rebel.net.au">lloy0076@rebel.net.au</A></li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
|
|
Hmmm!
|
|
|
|
> Why is this nebulous? We have a defined mechanism - you have an
|
|
> idea, propose it to us. Use the LDP Author Guide to assist
|
|
> in the development of the document (and you can use us as
|
|
> resources). Submit it to ldp-submit. The document is published.
|
|
|
|
The howtos aren't something that most people look for on the net. They
|
|
do actually come with distributions (at least until RedHat stopped
|
|
distributing them on disk number 1). They looked like they were and are
|
|
run by the vendors, not the LDP. This is less than capable marketing.
|
|
Surely someone could convince RedHat or SuSe that it's less expensive to
|
|
have the LDP document something than write the docs by scratch...
|
|
|
|
Or are the vendors becoming more and more like the Evil Empire (aka
|
|
Microsoft)?
|
|
|
|
> I'd like to hear more of why this appears to be a problem, and I'd
|
|
> like to help fix it (if I can).
|
|
|
|
You require people to accept licences of varying degrees. Maybe
|
|
requiring people to state that feedback should at least be CC'ed to the
|
|
LDP would be too difficult...or maybe I'm being sarcastic...I meant
|
|
REALISTIC.
|
|
|
|
> > * the LDP doesn't "take ownership" of the documents hence its name is
|
|
> > hardly ever heard of (although it seems to be the most reasonable source
|
|
> > for many of the HOWTOs that go with distros)
|
|
>
|
|
> No doubt, but people still know of the LDP. We can do more in that
|
|
> area, certainly.
|
|
|
|
In what sense? Bad publicity is worse than no publicity.
|
|
|
|
> > * you're just as likely to receive SPAM on the mailing list as you are
|
|
> > other conversation
|
|
>
|
|
> That will be corrected soon. Once debian turns the existing
|
|
> mailing lists over to us, we will roll all into a closed list
|
|
> format (you must subscribe to post).
|
|
|
|
I will believe that when I see it. To be perfectly honest, I *always*
|
|
look at those who allow SPAM on mailing lists with suspicion and I only
|
|
subscribe to a mailing list that allows spam unless I'm really
|
|
interested. I am, believe me, interested in ensuring that the LDP
|
|
continues its work and contributes to the community. I'm not interested
|
|
in the spam and if you look at my history I've stated so...with voice
|
|
and opinion.
|
|
|
|
Why do you need debian's permission to turn the lists over to you? Have
|
|
I read things wrong - is this the Debin Documentation Project?
|
|
|
|
> One list will remain "open" for feedback from the web-site,
|
|
> and for the proposal of ideas for new content pieces, etc
|
|
|
|
Feedback about the web site goes to webmaster. New ideas and such...if
|
|
they're so interted they will join. People who are serious Linux users
|
|
will join mailing lists. Maybe you haven't experienced this and I have.
|
|
|
|
I will decline to propose new ideas on the "closed list"....this, IN MY
|
|
OPINION, is quite silly. There should be one list and one list only.
|
|
Let's not go multi-personality....
|
|
|
|
> Yes, and when it was proposed that the LDP define some sort of
|
|
> order, hierarchy or central contacts (such as a "core team") it
|
|
> was meant with much resistence. Like you state - it's a fine line.
|
|
> Perhaps it was in the way it was proposed, I don't know for sure.
|
|
|
|
So what we have is an unwritten, unheard of elite group who run the LDP.
|
|
Putting it bluntly - and you would know I don't spare feelings or words
|
|
- no wonder people distrust the LDP. If you are not capable of forming a
|
|
core group then it is natural, even right, that people may be suspicious
|
|
of your motives.
|
|
|
|
The time for the wonderful touchy-feely is gone. The vendors are here
|
|
and they will write their own documentation. There is no doubt about
|
|
that...and they can base it on LDP documents - the licence, remembmer,
|
|
is generally open content-ed....
|
|
|
|
> > I believe that we need to pull ourselves together and bring ourselves to
|
|
> > a more consistent touch and feel to the LDP; someone or a group of us
|
|
> > should attempt to convince the vendors not to include the "HOWTOs" but
|
|
> > to include the "HOWTOs by the [author] and the LDP"...a small change but
|
|
> > we're facing a marketing exercise. At some stage many of the HOWTOs have
|
|
> > been submitted to the LDP and we should make sure this is known.
|
|
>
|
|
> What is gained by all this, beyond some name recognition? Who benefits,
|
|
> the LDP or the consumer?
|
|
|
|
The LDP and the consumer. Name recognition is important. Most of the
|
|
HOWTOS and even man pages included with many distros are based on the
|
|
LDP's works or works under its auspices. We all gain if we gain more
|
|
recognition....just because we are open source and open content does not
|
|
mean we can be null marketing. We MUST market ourselves...people WILL
|
|
buy good documentation!
|
|
|
|
> There is no need to create one. This is generated from the
|
|
> structured content that is provided to us. *No one* needs to create
|
|
> a TOC. If you see a document within the LDP that *does not* contain
|
|
> a TOC, please let me know - it is an error.
|
|
|
|
I was using an example. I was saying for example, you should give us a
|
|
title for your work. Take yourself out of the specifics of my example
|
|
and rethink...
|
|
|
|
> Style (look) is controlled via the DSSSL. We can tweak that in whatever
|
|
> way makes sense. Jorge Godoy has been looking into CSS for an
|
|
> additional layer/way to provide a different look to the LDP documents.
|
|
> Again, this places no burden whatsoever on the author...they still
|
|
> provide SGML (or XML).
|
|
|
|
<sigh>
|
|
|
|
DSSL and XSL can't translate CDATA without a DTD. There is no DTD for
|
|
this e-mail. If I don't provide my name, email address and contact
|
|
details how can a DSSL or XSL translation sheet render these fields?
|
|
Assuming the LDP decides that it is a good thing to include an abstract
|
|
on the content page, how does the DSSL or XSL transaltion sheets render
|
|
these fields without the CDATA for the abstract?
|
|
|
|
You are missing my point entirely.
|
|
|
|
I'm not talking about style as in physical layout (html, tex, pdf, .doc
|
|
or wotever), I'm talking about the way a document is expressed an
|
|
formed.
|
|
|
|
> Please work with us on this. If anyone has ideas on what might
|
|
> constitute a nice style for the LDP docs, please provide
|
|
> input. The existing docbook SGML tranformations that were done
|
|
> can give you an idea of what we currently use for "style" (thru
|
|
> DSSL). Here are some examples: Bootdisk-HOWTO, DSL-HOWTO,
|
|
> Mail-User-HOWTO, Cable-Modem, Program-Library-HOWTO ...to name a few.
|
|
|
|
Again, you have totally missed my point. I could write you an XSL sheet
|
|
for DB 4.1 or 3.1 which rendered DocBook 3.1 in the most inappropriate
|
|
manner possible.
|
|
|
|
> There are some basic structured elements that need to be included.
|
|
> If they aren't there, then they are either added (in which case
|
|
> the corrected document is sent back to the author, with correction),
|
|
> or the doc is rejected.
|
|
>
|
|
> Some legacy docs currently part of the archive may not adhere to this.
|
|
> If they don't, then point them out to me/us.
|
|
|
|
I wasn't talking about legacy documents. You seem quite willing to talk
|
|
about things I hadn't even mentioned.
|
|
|
|
> SGML helps us to enforce a level of structure, our templates help
|
|
> to provide some *guidance* in the area of how the structure should
|
|
> be applied. So I believe it comes down to writing style, which I am
|
|
> (personally) opposed to dictating any sort of rules for.
|
|
|
|
So
|
|
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
|
<book>
|
|
<title>Using "ls"</title>
|
|
<chapter>
|
|
<para>
|
|
Unless you are a <emphasis>black man</emphasis> or <emphasis>jewish
|
|
woman</emphasis> you will already understand what the "ls" command does.
|
|
</para>
|
|
</chapter>
|
|
</book>
|
|
|
|
Is a valid LDP document. It does conform to DocBook V4.1. I would, of
|
|
course fill it out with more racist and sexist comments but ensure its
|
|
technical correctness...
|
|
|
|
> Understood. We all feel this way, and the problem will be corrected,
|
|
> as I stated earlier.
|
|
|
|
And Santa Claus can deliver all his presents in one evening...
|
|
|
|
DL
|
|
--
|
|
And so it was that later
|
|
As the miller told his tale
|
|
That a face that at first was ghostly
|
|
Turned a whiter shade of pale....
|
|
|
|
|
|
--
|
|
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>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="03977" href="msg03977.html">RE: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
<ul><li><em>From:</em> Gregory Leblanc <GLeblanc@cu-portland.edu></li></ul></li>
|
|
<li><strong><a name="03981" href="msg03981.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
<ul><li><em>From:</em> David Lloyd <lloy0076@rebel.net.au></li></ul></li>
|
|
<li><strong><a name="03986" href="msg03986.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
<ul><li><em>From:</em> "Greg Ferguson" <gferg@hoop.timonium.sgi.com></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg03987.html">USA kararlari ile ilgili</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg03989.html">RE: Style guide?</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg03986.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg03991.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#03988"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#03988"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|