[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Outline for Author's Guide
>>>>> "Gary" == Gary Lawrence Murphy <[email protected]> writes:
>>>>> "K" == Kendall Clark <[email protected]> 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 [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]