[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Outline for Author's Guide

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

    Gary> I am going to vote for some of the tools first, especially
    Gary> the conversion tools, or else we risk having the blind lead
    Gary> the blind.

    Gary> Here is my rationale:

    Gary> None of us have heaps of experience with the ways users of
    Gary> diverse tech collections want to use information, or on how
    Gary> to catalog and manage that information, yet this is the
    Gary> basis of an authoring guide.

Well, speak for yourself! :>

>From what I've seen, there is significant experience doing just
that. Your other points may be write, but I don't think this one
stands up.

In addition, if you'll take a closer look, the outline of the AG that
I've posted here really isn't about "how to catalog and manage a
diverse collection of information" though that will need to be done as 

It is about what SGML features will be used, what features won't be
used, and how to use the ones that will be used.

I do think, however, that you have a point, and that this committee
should be wary of making the wrong kind of "policy" pronouncements.

    Gary> My guess is we will learn more
    Gary> by converting docs into an initial DocBook format, running
    Gary> it past some stakeholders, and folding their comments back
    Gary> into the auto-conversion process until people like it.

But the auto-conversion process can *never*, no matter how much
feedback, do a real job of converting Linuxdoc to DB
automagically. Why? Because there is a massive impedance mismatch
between Linuxdoc and DB, as others have pointed out repeatedly, most
recently Ed Bailey from Red Hat.

    Gary> If we go with a half-cocked Author Guide, we will be faced
    Gary> with having to re-format new documents to our eventual style
    Gary> guide, whereas if we use existing docs to auto-generate what
    Gary> we *think* people will want, if they don't like it, it is no
    Gary> big deal to re-generate a modified set and to continue the
    Gary> iterations until everyone is happy (well, at least content)

I think that this kind of up-translation from a semantically-sparse
DTD to a semantically-rich DTD isn't going to be automatically
possible. In fact, I'm pretty sure I've heard *real* SGML experts say
that very same thing. :>

There are just many, many issues in the AG outline that a conversion
script simply doesn't address. 


Kendall Clark

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