334 lines
14 KiB
HTML
334 lines
14 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: RE: Style Guide (was Re: I'm a sucker) -->
|
|
<!--X-From-R13: Uertbel Zroynap <UZroynapNph-cbegynaq.rqh> -->
|
|
<!--X-Date: Tue, 10 Oct 2000 13:20:14 -0400 (EDT) -->
|
|
<!--X-Message-Id: 025836EFF856D411A6660090272811E61D0801@EMAIL -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--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:GLeblanc@cu-portland.edu">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg03989.html">Date Prev</a>][<a href="msg03991.html">Date Next</a>][<a href="msg04002.html">Thread Prev</a>][<a href="msg04012.html">Thread Next</a>][<a href="maillist.html#03990">Date Index</a>][<a href="threads.html#03990">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>: "'David Lloyd'" <<A HREF="mailto:lloy0076@rebel.net.au">lloy0076@rebel.net.au</A>>, 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>: Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>></li>
|
|
<li><em>Date</em>: Tue, 10 Oct 2000 10:22:13 -0700</li>
|
|
<li><em>Cc</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-date</em>: Tue, 10 Oct 2000 13:20:14 -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>: <eGQ3iD.A.PQG.MB145@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>
|
|
> -----Original Message-----
|
|
> From: David Lloyd [<A HREF="mailto:lloy0076@rebel.net.au">mailto:lloy0076@rebel.net.au</A>]
|
|
>
|
|
> Hmmm!
|
|
>
|
|
> > 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.
|
|
|
|
I don't follow you here. What's wrong with the licensing policy? Why
|
|
should feedback on a document HAVE to go to the mailing list? Sending it to
|
|
the author has yielded good results for me.
|
|
|
|
> > > * 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.
|
|
|
|
Yeah, but it certainly sounds like you're complaining that we're getting NO
|
|
publicity, and not complaining about the bad publicity that we're getting.
|
|
|
|
> > > * 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?
|
|
|
|
It's got nothing to do with permission. Debian was kind enough to host
|
|
these mailing lists for us, since we did not have the resources to host them
|
|
ourselves. Now that we have those resources available, we're in the
|
|
processor transferring to lists to a new server.
|
|
|
|
> > 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.
|
|
|
|
For the GNOME website, feedback sent to "webmaster@gnome.org" IS sent to a
|
|
mailing list. Many different people read this, so that they can address
|
|
different issues that arise from people emailing webmaster. The concept for
|
|
the LDP is the same. People will not necessarily join the mailing list if
|
|
they have suggestions or comments, they may simply wish to send them off. A
|
|
new author to the LDP should NOT have to be on the LDP-Discuss list, as this
|
|
list has quite a bit of traffic, much of which they won't care about while
|
|
they're busy drafting their document.
|
|
|
|
> 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....
|
|
|
|
Can you rephrase that, it doesn't make sense to me.
|
|
|
|
> > 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 mailing list runs the LDP. The people who make policy decisions are the
|
|
people who show up here and contribute.
|
|
|
|
> > > 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!
|
|
|
|
We don't care if they buy it, so long as it's available to them. I'd like
|
|
to see us get better name recognition so that people know where the
|
|
documents can be found. If people choose not to contribute back to the LDP,
|
|
that's their decision, we cannot force them to contribute.
|
|
|
|
> > 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...
|
|
|
|
Your arguments are NOT clear, and you made no mention of that being an
|
|
example (that I could see, at least) in your mail. Have you read the LAG?
|
|
|
|
> > 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.
|
|
|
|
Maybe you aren't making yourself clear...
|
|
|
|
> 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.
|
|
|
|
The LAG has some guidelines for this, and there are a couple of sample
|
|
templates, and TONS of sample HOWTOs to go from. What EXACTLY are you
|
|
asking for?
|
|
|
|
> > 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.
|
|
|
|
Yeah, so what? We have stylesheets that are designed to do a good job
|
|
creating output from the documents that we receive. The LAG outlines the
|
|
things that you should do before you decide to submit your document to us.
|
|
|
|
> > 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...
|
|
|
|
No, it's not, for a whole slew of reasons. Let me quote the LAG for you.
|
|
|
|
Before you distribute your code to millions of potential readers there are a
|
|
few things you should do.
|
|
|
|
First, be sure to spell-check your document. Most utilities that you would
|
|
use to write SGML have plug-ins to perform a spell check. If not, there's
|
|
always the aspell program.
|
|
|
|
Second, get someone to review your documentation for comments and factual
|
|
correctness. The documentation that is published by the LDP needs to be as
|
|
factually correct as possible, as there
|
|
are millions of Linux users that may be reading it. If you're part of a
|
|
larger mailing list talking about the subject, ask others from the list to
|
|
help you out.
|
|
|
|
|
|
Go read the LAG again, and see if it addresses any of your concerns.
|
|
|
|
> > 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...
|
|
|
|
This WILL be fixed, as soon as it can be. As of right now, administrative
|
|
control for these lists is out of our hands. Once it IS within our power,
|
|
it will be fixed. Patience is a virtue.
|
|
Greg
|
|
|
|
|
|
--
|
|
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="04012" href="msg04012.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>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg03989.html">RE: Style guide?</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg03991.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg04002.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg04012.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#03990"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#03990"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|