298 lines
15 KiB
HTML
298 lines
15 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: Outline for Author's Guide -->
|
|
<!--X-From-R13: Unel Znjerapr [hecul <tnelzNpnanqn.pbz> -->
|
|
<!--X-Date: Mon, 6 Dec 1999 21:03:58 -0500 (EST) -->
|
|
<!--X-Message-Id: m3puwjcxt5.fsf@maya.linux.ca -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 14410.58586.289062.259723@cmpu.net -->
|
|
<!--X-Reference: Pine.LNX.4.10.9912051659410.12745-100000@wallybox.cei.net -->
|
|
<!--X-Reference: 14411.6824.457038.770755@cmpu.net -->
|
|
<!--X-Reference: m3k8mreqwp.fsf@maya.linux.ca -->
|
|
<!--X-Reference: 14412.9961.253473.998083@cmpu.net -->
|
|
<!--X-Reference: m33dtfeosr.fsf@maya.linux.ca -->
|
|
<!--X-Reference: 14412.13511.822051.573888@cmpu.net -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: Outline for Author's Guide</title>
|
|
<link rev="made" href="mailto:garym@canada.com">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg00025.html">Date Prev</a>][<a href="msg00027.html">Date Next</a>][<a href="msg00024.html">Thread Prev</a>][<a href="msg00027.html">Thread Next</a>][<a href="maillist.html#00026">Date Index</a>][<a href="threads.html#00026">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: Outline for Author's Guide</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: <A HREF="mailto:ldp-docbook@lists.debian.org">ldp-docbook@lists.debian.org</A></li>
|
|
<li><em>Subject</em>: Re: Outline for Author's Guide</li>
|
|
<li><em>From</em>: Gary Lawrence Murphy <<A HREF="mailto:garym@canada.com">garym@canada.com</A>></li>
|
|
<li><em>Date</em>: 06 Dec 1999 21:03:02 -0500</li>
|
|
<li><em>Organization</em>: TeleDynamics --- the Art of Being There</li>
|
|
<li><em>References</em>: <<a href="msg00008.html">14410.58586.289062.259723@cmpu.net</a>> <<a href="msg00009.html">Pine.LNX.4.10.9912051659410.12745-100000@wallybox.cei.net</a>> <<a href="msg00010.html">14411.6824.457038.770755@cmpu.net</a>> <<a href="msg00019.html">m3k8mreqwp.fsf@maya.linux.ca</a>> <<a href="msg00021.html">14412.9961.253473.998083@cmpu.net</a>> <<a href="msg00022.html">m33dtfeosr.fsf@maya.linux.ca</a>> <<a href="msg00024.html">14412.13511.822051.573888@cmpu.net</a>></li>
|
|
<li><em>Reply-to</em>: Gary Lawrence Murphy <<A HREF="mailto:garym@canada.com">garym@canada.com</A>></li>
|
|
<li><em>Resent-cc</em>: recipient list not shown: ;</li>
|
|
<li><em>Resent-date</em>: 7 Dec 1999 02:03:56 -0000</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-docbook@lists.debian.org">ldp-docbook@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <Tkz5gB.A.qQG.MsGT4@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-docbook-request@lists.debian.org">ldp-docbook-request@lists.debian.org</A></li>
|
|
<li><em>Sender</em>: <A HREF="mailto:garym@mail.wccweb.com">garym@mail.wccweb.com</A></li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
>>>>> "K" == Kendall Clark <kclark@ntlug.org> writes:
|
|
|
|
K> ... What I think we're suggesting is that since moving to DB
|
|
K> presents an opportunity to take advantage of SGML features
|
|
K> there needs to be some guidance as to how these features are
|
|
K> used.
|
|
|
|
Yes, exactly my point of blind leading the blind. There are some
|
|
gross things we can recommend, but I'd want to see someone's idea of a
|
|
"typical" DocBook output rendered into HTML, PDF, RTF and Postscript
|
|
before I said even "All sections must begin with titles followed by at
|
|
least one paragraph before proceeding to any subsection headers"
|
|
|
|
Prior to that, we have lots of Hello World things we can do: Take a simple
|
|
MiniHOW of just one section (or article or chapter or ...) and break it into
|
|
sections, then "Here is how to generate format X"
|
|
|
|
Gary> ... we don't have two dozen authors all working in
|
|
Gary> parallel putting these widgets into every new document.
|
|
|
|
K> I don't know what 'widgets' means in this context, sorry.
|
|
|
|
I'm showing my age ;) ... in the days before X made them popular as
|
|
real things, a "widget" was the typical example for a nondescript part
|
|
made by an imaginary factor in a textbook problem.
|
|
|
|
I'm open to alternate nomenclature, but calling them "TAGS" doesn't
|
|
distinguish the complex ones (eg tables or authorgroup with all the
|
|
proper attributes) from trivial tags like <emphasis>
|
|
|
|
K> This doesn't mean anything; as I said before, most of the stuff
|
|
K> in the AG is SGML usage stuff, not presentational. The AG isn't
|
|
K> meant to serve as an information design manifesto; rather, it's
|
|
K> meant to lay down a standard that LDP authors can follow so
|
|
K> they can know *how* to use SGML properly, that is, consistently
|
|
K> across a collection.
|
|
|
|
Oh, ok, but I still think we may be talking about the same thing. I'm
|
|
willing to concede we are not, though.
|
|
|
|
My view of the Author Guide is that it may contain a template for each
|
|
type of document giving an example structure of sections with some
|
|
sample 'widgets' like a table, an inline GIF/PNM example, a sidebar
|
|
and a few other fancy things. It would show how to do the document
|
|
info section, how to fill out the keyword and index tags and some
|
|
guidelines for where these are used, where and when we want secondary
|
|
index headers. The guide would also explain where we need to have
|
|
specific attributes
|
|
|
|
For example, the long-term advantage of DocBook is to allow managing
|
|
the document collection as one great database of items in a treelike
|
|
structure; branches can delimit sibling parts, or alternative parts.
|
|
|
|
Would we want to use the ARCH or REVISION attributes so we can have
|
|
one document cover many alternative versions?
|
|
|
|
Because DocBook is undiscovered territory, I'm not so certain the
|
|
answer is obvious. We may say "No, we don't care about those things"
|
|
or "No, they would be too much trouble", the same things people said
|
|
about HTML META tags back in 1996
|
|
|
|
What if, a year from now, we have the option to use some fancy new XML
|
|
database program? Do we want to go back over all docs and fix these
|
|
tags, and redo our CVS to accomodate them? What if it actually was not
|
|
very difficult to add them at the start? psgml-mode makes it
|
|
relatively easy to manage attributes. Perhaps the attributes and
|
|
entities should be addeed now even though we have no software which
|
|
will use them (remember it was years before search engines notice the
|
|
KEYWORD meta-tag).
|
|
|
|
Even today, we can make a dsssl that selects alternates, so one
|
|
document to handle multiple architectures or versions is not
|
|
impossible, but it is a manual process --- we'd probably do it the
|
|
old-fashioned way and just give the reader everything as one large
|
|
paper instead of several architecture-flavoured editions.
|
|
|
|
We may discover we can easily handle all this stuff *after* a document
|
|
is submitted and therefore need not bother the author with it at all
|
|
(we can invent an LDP Editorial Review Process :), but we still need
|
|
to know if this affects the author checking out a segment at some
|
|
future date to make an update. How do we manage revisions and CVS
|
|
tags? Do we mirror those in attribute values?
|
|
|
|
I think we will see editors with intrinsic entities and attributes
|
|
appear this spring, and by this time next year, they will be
|
|
relatively common. I'll be very surprised if StarOffice and WP do not
|
|
support DocBook in their next incarnations. If an author can manage
|
|
their own document attributes using a popup dialog box, they may not
|
|
mind doing so, but if we make them hunt through and insert these using
|
|
VI, we may not get many volunteers. We can debate all this, but until
|
|
we know what we want, how can we know what we should ask them to
|
|
produce?
|
|
|
|
K> Are you doubting the need for a Style/Author's Guide at all? Or
|
|
K> just that we're proposing going about creating it in a way you
|
|
K> don't agree with?
|
|
|
|
I don't doubt we need it, and I have no problems with the outline or
|
|
the means to create the Guide. I'm only thinking out loud about the
|
|
order of events. I'd build the car before I write the driver's guide.
|
|
|
|
I am proposing we create at least one 'reference' document for each
|
|
document type.
|
|
|
|
I'd like to see an old document transformed into what we want to see
|
|
as a DocBook edition, and run this through our whole process start to
|
|
finish (author to CVS, through revisions and finally signed off for
|
|
web/print display) before we release any Author Guide.
|
|
|
|
The AG is a very good idea, and there is lots that can be done on it,
|
|
but if we have just one sample document, we will discover things we
|
|
absolutely wish had been in the AG or had been stated differently.
|
|
|
|
K> Sorry, but I can't follow this; it's rather vague. What is the
|
|
K> 'them' that we might add in, perhaps by hand?
|
|
|
|
We've already decided the conversion won't be perfect because linuxdoc
|
|
was limited. If we load an auto-translated almost-DocBook HOWTO into
|
|
an editor and fix it up manually, we will have an example of what we
|
|
would have expected if someone had written it from scratch --- it may
|
|
turn out to be easier to write the doc from scratch --- and we can then
|
|
submit this document through our process to see if we can incorporate
|
|
it into the LDP operational processes of repeated revisions in CVS, a
|
|
sign-off on a "complete enough for public viewing" edition, create a
|
|
web, RTF and Postscript version, and then make a revision.
|
|
|
|
K> Example: what kind of user feedback do you suspect we'd get
|
|
K> from LDP authors with regard to, say, entity engineering?
|
|
|
|
"You've specified too many" or "Why don't you add XYZ because I am
|
|
tired of typing it" --- chances are, no, they won't care, but if we
|
|
have entities we wish to use (eg, every occurance of LDP is replaced with
|
|
the fully qualified ULINK to the website, ditto with MetaLab) then the
|
|
author need not repeat the same URLs throughout their text. This is
|
|
just one example.
|
|
|
|
In my own experience, I have modified the scope and structure of my
|
|
entities lists many times, and I am still not precisely happy with them.
|
|
Entities are much more than just a shorthand, even though, to an author,
|
|
they are only a shorthand notation.
|
|
|
|
K> Example: what about naming conventions? We need them, don't
|
|
K> have them, but as they are almost *purely* conventional
|
|
|
|
But are they purely conventional? Are there no technical constraints
|
|
or conveniencies? Perhaps, but do we know this, or are we just
|
|
"reasonably sure"
|
|
|
|
Also, authors are not the only stakeholders in a document. We need to
|
|
consider that the work done by the authors, where they probably do not
|
|
understand the meanings of certain conventions, will affect our own
|
|
operations (site management, revision control, collaborations &c) and
|
|
will affect the readers.
|
|
|
|
For example, suppose we decree that xref IDs in <sectN> tags are to be
|
|
"SEC:" + any string of 4 chars, will this be sufficient or would we
|
|
accept any arbitrary length tags? Would the people managing the
|
|
catalogs have wished the naming conventions were otherwise? (using the
|
|
"SEC" prefix makes the xref anchors easier to find using grep)
|
|
|
|
I'm not against an Authors' Guide, and many parts of the outline can
|
|
be started at once (we will probably learn more about the process just
|
|
doing that doc!).
|
|
|
|
I am only proposing we hold off on some parts. Specifically, sections
|
|
marked "LDP Style Guide", "LDP Extensions", "I18n Issues", "Mapping
|
|
DocBook Types to LDP Genres", "Document Reuse", "Marked Sections",
|
|
"Naming Conventions", and large parts of "Using Entities", "Common
|
|
Elements" and "MetaData", and even the last section on creating "A
|
|
Makefile". All these impinge on operations constraints and I'd want
|
|
to have a working prototype of our process before I handed this to
|
|
people to say "This is how you should be doing it".
|
|
|
|
--
|
|
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
|
|
TCI - Business Innovations through Open Source : <A HREF="http://www.teledyn.com">http://www.teledyn.com</A>
|
|
Canadian Co-ordinators for Bynari International : <A HREF="http://ca.bynari.net/">http://ca.bynari.net/</A>
|
|
Moderator, Linux Education Group: <A HREF="http://www.egroups.com/group/linux-ed">http://www.egroups.com/group/linux-ed</A>
|
|
|
|
|
|
--
|
|
To UNSUBSCRIBE, email to ldp-docbook-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="00027" href="msg00027.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Kendall Clark <kclark@ntlug.org></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="00008" href="msg00008.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Kendall Clark <kclark@ntlug.org></li></ul></li>
|
|
<li><strong><a name="00009" href="msg00009.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Tim <tjbynum@wallybox.cei.net></li></ul></li>
|
|
<li><strong><a name="00010" href="msg00010.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Kendall Clark <kclark@ntlug.org></li></ul></li>
|
|
<li><strong><a name="00019" href="msg00019.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Gary Lawrence Murphy <garym@canada.com></li></ul></li>
|
|
<li><strong><a name="00021" href="msg00021.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Kendall Clark <kclark@ntlug.org></li></ul></li>
|
|
<li><strong><a name="00022" href="msg00022.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Gary Lawrence Murphy <garym@canada.com></li></ul></li>
|
|
<li><strong><a name="00024" href="msg00024.html">Re: Outline for Author's Guide</a></strong>
|
|
<ul><li><em>From:</em> Kendall Clark <kclark@ntlug.org></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg00025.html">author's guide</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg00027.html">Re: Outline for Author's Guide</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg00024.html">Re: Outline for Author's Guide</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg00027.html">Re: Outline for Author's Guide</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#00026"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#00026"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|