371 lines
15 KiB
HTML
371 lines
15 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: RE: Authorship -->
|
|
<!--X-From-R13: Uertbel Zroynap <UZroynapNph-cbegynaq.rqh> -->
|
|
<!--X-Date: Wed, 31 May 2000 00:41:14 -0400 (EDT) -->
|
|
<!--X-Message-Id: A5F46F4ED18FD211ABEE00105AC6CF077F8145@email.cu-portland.edu -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>RE: Authorship</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="msg02574.html">Date Prev</a>][<a href="msg02576.html">Date Next</a>][<a href="msg02574.html">Thread Prev</a>][<a href="msg02576.html">Thread Next</a>][<a href="maillist.html#02575">Date Index</a>][<a href="threads.html#02575">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>RE: Authorship</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: LDP <<A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A>></li>
|
|
<li><em>Subject</em>: RE: Authorship</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, 30 May 2000 21:40:53 -0700</li>
|
|
<li><em>Resent-date</em>: Wed, 31 May 2000 00:41: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>: <54AbPB.A.73.cfJN5@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>
|
|
First, let me say that about 85% of this makes ZERO sense to me, since I
|
|
don't know what ANY of the suggested changes were/are. See some more
|
|
comments below.
|
|
|
|
> -----Original Message-----
|
|
> From: Gary Preckshot [<A HREF="mailto:garrell@inreach.com">mailto:garrell@inreach.com</A>]
|
|
> Sent: Tuesday, May 30, 2000 4:37 PM
|
|
> To: LDP
|
|
> Subject: Authorship
|
|
>
|
|
[snip]
|
|
> I'm trying to move that into appendices with references to
|
|
> the appendix in the body.
|
|
> <Link> works fairly well.
|
|
|
|
That's way to vague for the LDP discuss list, might make sense to Mark.
|
|
|
|
[snip]
|
|
> 1) SGML tools are far and few between. We're lucky that any work.
|
|
>
|
|
> I agree with that. All the more reason for giving guidance to
|
|
> prospective authors
|
|
> for sorting out combinations that work in their situation.
|
|
> One of the things I
|
|
> discovered is that it was really difficult to figure out what
|
|
> was happening where.
|
|
> One of the things I tried to do is sort out combinations that
|
|
> worked. If we're going
|
|
> to ask authors to use SGML, we should not set them an
|
|
> impossible problem or give
|
|
> them incomplete guidance.
|
|
|
|
ARGH. :-) We REALLY need to get processing tools available to authors on
|
|
some machine that the LDP is in charge of, probably through a web form. It
|
|
would be REALLY nice to not have to have people worry about this.
|
|
|
|
> >2) Not many other platforms that support the tools we use.
|
|
>
|
|
> Well, a combination of Windows NT and Linux does - QED. Why else LILO?
|
|
>
|
|
> >3) The "original" (my) version listed that 1.0.9 was for LinuxDoc
|
|
> and was called sgmltools. The 2.x version works with DocBook
|
|
> and is called sgml-tools. Both are not being updated anymore and
|
|
> should be removed in favor of sgmltools-lite or doing it by hand.
|
|
>
|
|
> So why have in the HOWTO?
|
|
|
|
SGMLtools 1.0.x series is being maintained. I've got mixed feelings about
|
|
the sgmltools-lite (especially the name). There are also the Cygnus Docbook
|
|
tools. <A HREF="http://sourceware.cygnus.com/">http://sourceware.cygnus.com/</A> I think. There should/will be newer
|
|
versions before too long.
|
|
|
|
[whole series of incomprehensible stuff snipped]
|
|
|
|
> >"FAQs about the LDP"
|
|
|
|
More importantly, the LDP FAQ? I've been thinking about this for a while,
|
|
but I don't have a list of questions. Answers should be easy to come by.
|
|
So, anybody who's got a good feel for the recent questions feel free to post
|
|
them in another thread, and I'll take them and put them with answers in a
|
|
document.
|
|
|
|
> >1) Usually that's just a pointer to the ldp-discuss list.
|
|
>
|
|
> But there wasn't any pointer.
|
|
>
|
|
> >"Configuration Management"
|
|
>
|
|
> >Woah. I wouldn't call CVS this a configuration manager.
|
|
> It's not. It's source
|
|
> >code control.
|
|
>
|
|
> Which is configuration management for software or documents.
|
|
> I think probably
|
|
> there's confusion as to why LDP is using CVS. If we're not
|
|
> using it for
|
|
> configuration management, then why are we wasting time and resources.
|
|
|
|
Can you define "configuration management". That's like me saying to the VP
|
|
of our company, "we need RAID". He's going to ask about termites, or
|
|
cockroaches or something.
|
|
|
|
> >2) Not sure what you mean by this.
|
|
>
|
|
> The confusion over configuration management makes that
|
|
> obvious. Why is LDP using
|
|
> CVS? Because somebody said we should? Bad reason. If you
|
|
> can't state the policy,
|
|
> then there is no policy.
|
|
|
|
There is a policy. CVS is there to allow us to better track and maintain
|
|
our documents, and the scripts that we use, and other administrivia. Just
|
|
because one author isn't clear on the policy doesn't mean that the LDP as a
|
|
group doesn't have one. If you feel that things are relavent to the list,
|
|
send them here please.
|
|
|
|
> >3) LDP doesn't write the software. It's not to our
|
|
> advantage to maintain older
|
|
> tools on the CVS site.
|
|
>
|
|
> After calling SGML "code" numerous times, you say this?
|
|
|
|
I think this is just not being quite clear enough. The LDP does not write
|
|
Software Applications. The LDP does write software documentation. This is
|
|
code because of the markup we use to give those words added meaning.
|
|
Assuming that you're talking about the SGML Tools projects, we DO NOT
|
|
maintain those, although we are the primary target users. The SGML tools
|
|
1.0.x has a site on SourceForge (I believe). The DocBook specific SGMLTools
|
|
v2 and v3 have a site on SourceForge. No need for us to host software when
|
|
there are FAR superior alternatives for that sort of thing than our time on
|
|
Metalab and Serek's PLD server.
|
|
|
|
> What's really obvious is
|
|
> that LDP is asking authors to produce writing to certain
|
|
> format standards, and it
|
|
> has no control over the tools it recommends in its own HOWTO
|
|
> about writing HOWTOs.
|
|
|
|
That's only partly true. We have as much control over those tools as
|
|
anybody else who doesn't write their own tools. The LDP is not a project
|
|
with the size and power of the Linux Kernel, or the GNOME project. We've
|
|
got volunteers to write docs, we don't have dozens of people coding for us
|
|
(although that would be nice). We can only ask for what we want, until we
|
|
come up with some programmers. I'm going back to school in a few weeks
|
|
(along with working full time) so that I can get back into programming, and
|
|
maybe helping out a bit.
|
|
|
|
> Not only that, you've just told me that the version currently
|
|
> on the LDP web site is
|
|
> way out of date, and was when it was written. If ever there
|
|
> was a case for
|
|
> configuration management, this is it.
|
|
|
|
The current version of what? Elaborate please.
|
|
|
|
> >4) I list the reasons really along with the reasons why CVS
|
|
> is good. The
|
|
> biggest advantage is the goal of having LDP documentation
|
|
> automatically updated
|
|
> and distributed after a CVS update. Alas, it's not in place (yet)
|
|
>
|
|
> It isn't why CVS is good. CVS is just a tool. It's the LDP
|
|
> policy that counts here.
|
|
> Otherwise you end up having your horizons defined by a tool.
|
|
> Dare I say it? This is
|
|
> a prime example of geekthink. You have a problem, find a tool
|
|
> that sort of does some
|
|
> useful stuff, lose sight of the problem, and wander among the
|
|
> trees of CVS. The
|
|
> logic should be:
|
|
>
|
|
> LDP wants to accomplish a), b), .... z). It has decided to
|
|
> use CVS to accomplish the
|
|
> d), h)....and r) goals. Here's what LDP gets out of it:....
|
|
> Here's what you get out
|
|
> of it:... Here are the steps to use the LDP CVS server:...
|
|
> Here's what you need to
|
|
> accomplish those steps:.....
|
|
|
|
We've got the goals, and some ideas on how to use CVS to accomplish those
|
|
goals. Most of these ideas are stored in the heads of some of the people
|
|
who have been here for a while, and we're a bit lax on communicating with
|
|
Mark, and the LDP list in general, about what we're doing. We'll get there,
|
|
and maybe we can write some more on that. However, I think it should
|
|
probably go on the CVS list, so that the people who are really interested in
|
|
that can keep track, and we don't clutter up this list. I think Mark has
|
|
some info about that in the HOWTO-HOWTO, so subscribe and take this part of
|
|
it there please.
|
|
|
|
[snip more comments that are totally out of context]
|
|
|
|
> >6) Logging into the CVS server so you are authenticated and
|
|
> can update files.
|
|
>
|
|
> Assume I know nothing. Break it down into steps, do each
|
|
> step, and explain what
|
|
> you're doing.
|
|
|
|
Yes, the docs with regard to CVS are, uhm, not good. We can do better,
|
|
certainly. I've already volunteered for one thing this email, not sure that
|
|
it would be good to volunteer for another. Any takers?
|
|
|
|
> >7) The $ is the shell prompt. I guess I could use
|
|
> [markk@wayga ~]$, but $
|
|
> is a bit simpler. This is getting maybe to my biggest issue
|
|
> with this. We
|
|
> have to assume that LDP authors know *something* about Linux,
|
|
> or else they
|
|
> wouldn't be writing.
|
|
>
|
|
> You use different prompts in different examples. Be
|
|
> consistent. Use the same prompt
|
|
> everywhere. Somewhere in your doc, explain what you are
|
|
> doing. Books do this
|
|
> consistently, and usually use a different font for what the
|
|
> computer types and what
|
|
> you type. They also explain their conventions up front.
|
|
|
|
I'd like to see us adopt some more formal conventions, and have them better
|
|
stated. We could even provide a short section that people could just block
|
|
include into their HOWTOs that shows the general conventions. For a good
|
|
online, current, DocBook example of that, check out the GNOME Documentation
|
|
Project's Guide to writing software documentation. It's someplace on
|
|
<A HREF="http://www.gnome.org/GDP/">http://www.gnome.org/GDP/</A> I haven't looked since the re-design, so I can't
|
|
say where it is.
|
|
|
|
> >8) Serek (the CVS admin) asked that I include it.
|
|
>
|
|
> He may have asked that you include it, but your duty is to
|
|
> the reader. If you
|
|
> include it, you should explain it.
|
|
|
|
Assuming this is more about the CVS instructions, yeah, they need work.
|
|
|
|
> >9) In case you don't have an account, or forget your
|
|
> password, or have
|
|
> a guest user who likes CVS, I don't know.
|
|
>
|
|
> Think about a prospective HOWTO author. Why would he/she want
|
|
> anonymous access?
|
|
|
|
EASY. CVS is the way to get the most current version of the documents by
|
|
some authors, they may want to tell their readers how to find the latest
|
|
version. I could come up with more, but that's the most compelling one
|
|
offhand. BTW Mark, I think it's Kosher to commit your HOWTO and it will get
|
|
processed and put on the LinuxDoc.org site.
|
|
|
|
[snip] Must have context. Tired of me saying that yet?
|
|
|
|
> Last, I thought I'd repeat some discussion group messages and
|
|
> remark on their
|
|
> relevance to the HOWTO-HOWTO
|
|
>
|
|
> >I've read that the LDP uses a custom stylsheet for DocBook that
|
|
> generates a
|
|
> Table of Contents. Where can I get it?
|
|
>
|
|
> This would be an appropriate thing for LDP to have under CVS
|
|
> control and the HOWTO
|
|
> should have a pointer for getting it.
|
|
|
|
It's in CVS now. If you're not on the CVS commits list, it's under
|
|
'builder/dsssl/ldp.dsl'.
|
|
|
|
> >I've read the HOWTO-HOWTO and the section on style is very brief.
|
|
> Is there
|
|
> more guidance on how a HOWTO should be structured?
|
|
>
|
|
> That's a valid question and one of the things I was trying to
|
|
> address, particularly
|
|
> in the appendix on DocBook and in Step 4.
|
|
|
|
Was the question about Markup style, or about writing style? They're
|
|
completely different, and both completely undefined.
|
|
|
|
> >Does the LDP accept HOWTOs and mini-HOWTOs using the DocBook DTD?
|
|
>
|
|
> A question that should be definitively answered.
|
|
>
|
|
> Stein Gjoen <sgjoen@mail.nyx.net> says:
|
|
> >Style and structure are two different things but if structure
|
|
> is what you are loking for then I have a template under
|
|
> development
|
|
> here:
|
|
>
|
|
> In Appendix A I was trying to give a usable template (by cut
|
|
> and paste). Maybe we
|
|
> can get Stein to contribute his.
|
|
|
|
I think it would be nice to use Stein's template as THE template. There are
|
|
now DocBook and Linuxdoc versions (as of earlier today I created a DocBook
|
|
version). I disagree with some of the markup, and more of the content, but
|
|
I'll get to those soon.
|
|
|
|
Anyway, that's enough out of me for a while, all the European guys should
|
|
get to read this in the morning (well in a few hours for them), so I'll have
|
|
something to do when I get up tomorrow.
|
|
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="02576" href="msg02576.html">RE: Authorship</a></strong>
|
|
<ul><li><em>From:</em> "Anthony E. Greene" <agreene@pobox.com></li></ul></li>
|
|
<li><strong><a name="02577" href="msg02577.html">Re: Authorship</a></strong>
|
|
<ul><li><em>From:</em> Mark Komarinski <markk@cgipc.com></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="msg02574.html">printing on Slackware Linux 7.0</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02576.html">RE: Authorship</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02574.html">printing on Slackware Linux 7.0</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02576.html">RE: Authorship</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02575"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02575"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|