Re: Outline for Author's Guide

[Kendall Clark <kclark@ntlug.org>]

>>>>> "Poet/Joshua" == Poet/Joshua D Drake <poet@linuxports.com> writes:

    Poet/Joshua> Hello, It seems to me that this a little more
    Poet/Joshua> complicated than it needs to be.  Yes DocBook is a
    Poet/Joshua> large beast but it is not uncontrollable. A quick FAQ
    Poet/Joshua> on what is good practice and not good practice should
    Poet/Joshua> suffice.

I don't agree. 

But in any event, the burden is on you to say precisely *which* things
in the outline don't need to be addressed. It's well and good to say
"the outline is too complicated," but unless that's accompanied by
*specific* recommendations for what doesn't need to be addressed, then
it's not very helpful.

I've done enough DocBook with teams of 10 to 20
authors/editors/content-personnel to know that a "quick FAQ" will not
suffice. Scale that to the number of LDP authors, and then scale it
again to account for the geographic/communication effects, and it's
not hard to see that w/out some pretty specific guidance, we're going
to get a mess.

Finally, many of the issues--heck, maybe *most* of the issues--in the
outline are *not* DB-specific but SGML-specific. That is, the whole
issue of entity management has to be faced no matter what SGML DTD we
might use, DB or otherwise.

    Poet/Joshua> I agree with Kendall in regards to the tools. No we
    Poet/Joshua> don't have the ability to just type sgmltools html
    Poet/Joshua> index.sgml and get what we want BUT we can type jade
    Poet/Joshua> <arguments> <stylesheet> index.sgml and get what we
    Poet/Joshua> want.  Heck, if we stick with specific style sheets
    Poet/Joshua> we should be fine. Just state in the FAQ that we
    Poet/Joshua> accept these version of the style sheets and these
    Poet/Joshua> "features".

That's confused, I'm afraid. LDP accepts SGML *source* and is
responsible for applying a transformation engine to that source to
produce output. 

That is to say, the AG doesn't need to address that part of the
transformation stage *at all*, as I said in my post. LDP authors
should think of the "backend" -- i.e., what happens to their source
once they submit it -- as a black box. What versions of stylesheets
are getting used are not important at all to *authors*. 

What is crucially important to them is that we address transformation
*expectations*, that is, what output looks like and what authors can
expect their source to get turned into. (But that's a separate issue
from the specific tools the backend uses to get that output. Think OOP
data-hiding and API boundaries for a fairly good analog.) 

This is important so that authors will know which precise DB
constructions they want to use *from among a range of options* to get
the desired effect. Yes, separating content from presentation is
essential to an SGML project; but individual authors are still going
to be asking questions like, 'how do I get this bold or italic?'. Even
if we want to help them think about their documents in more semantic,
and less presentational terms, we still have to handle the transition
cases.

Concrete example: I owe Tim an update of the User Group HOWTO. I have
a full DB kit installed here, but I've got pretty old version of
Norm's stylesheets, and I don't have the newest Jade either. But
that's ok, because I can get some HTML output to test that my document 
is coming out reasonably. Now, when I send the source file toTim, I
don't have to know, nor do I even care, what his SGML/DB setup is
like. I do need to know, however, if my expectations about
transformation are significantly different from what his kit is going
to produce. Do I need to know which version of Jade or the DSSSL
stylesheets or anything else he's using? No.

And that's a *good thing*. It's part of the magic of SGML. It's
document interchange and it's appropriate.

Now, I'm fairly SGML literate so if I don't care about the details of
the LDP backend, I think it's safe to say that most LDP authors won't
care either.

Best,

<Kendall/>


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