Re: Outline for Author's Guide

[Gary Lawrence Murphy <garym@canada.com>]

>>>>> "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 : http://www.teledyn.com
Canadian Co-ordinators for Bynari International : http://ca.bynari.net/
Moderator, Linux Education Group: http://www.egroups.com/group/linux-ed


--  
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org