Re: Outline for Author's Guide

[Kendall Clark <kclark@ntlug.org>]

>>>>> "Gary" == Gary Lawrence Murphy <garym@canada.com> writes:

>>>>> "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.

    Gary> Yes, exactly my point of blind leading the blind.  There are
    Gary> some gross things we can recommend, but I'd want to see
    Gary> someone's idea of a "typical" DocBook output rendered into
    Gary> HTML, PDF, RTF and Postscript before I said even "All
    Gary> sections must begin with titles followed by at least one
    Gary> paragraph before proceeding to any subsection headers"

There is *no* place on the AG outline where we will do what you talk
about above. It's simply not there. DB itself my place some similar
constraints, but <shrug/>.

    Gary> I'm showing my age ;) ... in the days before X made them
    Gary> popular as real things, a "widget" was the typical example
    Gary> for a nondescript part made by an imaginary factor in a
    Gary> textbook problem.

    Gary> I'm open to alternate nomenclature, but calling them "TAGS"
    Gary> doesn't distinguish the complex ones (eg tables or
    Gary> authorgroup with all the proper attributes) from trivial
    Gary> tags like <emphasis>

Well, the SGML nomenclature is what I use: elements, attributes,
entities, etc. <table> is an element no less than <emphasis>, it just
happens to be one that can contain others.

    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.

    Gary> Oh, ok, but I still think we may be talking about the same
    Gary> thing.  I'm willing to concede we are not, though.

    Gary> Because DocBook is undiscovered territory, I'm not so
    Gary> certain the answer is obvious.  We may say "No, we don't
    Gary> care about those things" or "No, they would be too much
    Gary> trouble", the same things people said about HTML META tags
    Gary> back in 1996

I don't understand this. It's undiscovered *for whom*?

[Lots of good questions snipped; many of which lie w/in the purview of 
this committee as I understand it.]

    Gary> The AG is a very good idea, and there is lots that can be
    Gary> done on it, but if we have just one sample document, we will
    Gary> discover things we absolutely wish had been in the AG or had
    Gary> been stated differently.

This seems like a strawman though. No one here afaik has said anyting
about zero, one, or many sample documents. 

    K> Example: what kind of user feedback do you suspect we'd get
    K> from LDP authors with regard to, say, entity engineering?

    Gary> "You've specified too many" or "Why don't you add XYZ
    Gary> because I am tired of typing it" --- chances are, no, they
    Gary> won't care, but if we have entities we wish to use (eg,
    Gary> every occurance of LDP is replaced with the fully qualified
    Gary> ULINK to the website, ditto with MetaLab) then the author
    Gary> need not repeat the same URLs throughout their text.  This
    Gary> is just one example.

To the first bit of feedback: if you don't need to use some of the
entities that have been specified, don't use them. To the second: you
have an entity namespace for your document, add it yourself, and
here's how.

    Gary> In my own experience, I have modified the scope and
    Gary> structure of my entities lists many times, and I am still
    Gary> not precisely happy with them.  Entities are much more than
    Gary> just a shorthand, even though, to an author, they are only a
    Gary> shorthand notation.

So? Every project redefines entities. That's kind of the point. I
don't see how that has anything to do with what we do first: tools or
an AG.

    K> Example: what about naming conventions? We need them, don't
    K> have them, but as they are almost *purely* conventional

    Gary> But are they purely conventional?  Are there no technical
    Gary> constraints or conveniencies?  Perhaps, but do we know this,
    Gary> or are we just "reasonably sure"

I said "almost purely conventional". No, there are some constraints,
but I think they are fairly minimalistic.

    Gary> Also, authors are not the only stakeholders in a document.
    Gary> We need to consider that the work done by the authors, where
    Gary> they probably do not understand the meanings of certain
    Gary> conventions, will affect our own operations (site
    Gary> management, revision control, collaborations &c) and will
    Gary> affect the readers.

Of course. Getting authors to provide what the backend mechanisms are
prepared to handle is a large part of the point of an AG.

    Gary> I am only proposing we hold off on some parts.
    Gary> Specifically, sections marked "LDP Style Guide", "LDP
    Gary> Extensions", "I18n Issues", "Mapping DocBook Types to LDP
    Gary> Genres", "Document Reuse", "Marked Sections", "Naming
    Gary> Conventions", and large parts of "Using Entities", "Common
    Gary> Elements" and "MetaData", and even the last section on
    Gary> creating "A Makefile".

The 2nd list I posted was a discussion list, and it is certainly a
valid discussion result to just say, 'we don't know the answer to this 
yet, so let's punt.' No one denies that, afaik. No one is saying that
there will only be 1 version of the AG. No one is saying that it will
not evolve in response to feedback. No one is saying there won't need
to be calibration between the backend and the AG.

But this thread has gotten far off track; the original referent of
'tools' in 'do we do tools first, second or simultaneous to the AG'
was 'conversion tools from linuxdoc -> DB', not the backend document
processing stuff. So, as far as that goes, all the points you make
about getting the backend and the AG into synch are totally valid, and 
I don't think anyone disagrees with them. My answer to the original
question is that we should get started on the AG asap. My answer to
this other question, now posed by the drift of the conversation, is
that we should work on the AG and the backend more or less at the same 
time.

Hope that clarifies a bit.

Kendall

PS--I don't know how decisions are going to be made on this committee, 
but I've just about exhausted my energy on the 'meta' discussion,
i.e., how we should proceed. I'm ready to either get started working
on the AG or wait until work on the AG does start; in the interim,
maybe I can finish chapter 4 of my dissertation. :>


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