On Tue, 2005-08-23 at 18:48 -0500, Thomas Jones wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > On Tuesday 23 August 2005 17:09, Tommy Reynolds wrote: > > Uttered Thomas Jones <admin@xxxxxxxxxxxxxxx>, spake thus: > > > I have quickly built up a DTD Driver for the Docbook 4.2 release. This > > > driver contains declarations for Fedora Core specific documentation. > > > > I am not in favor of this subsetting (even if it's a proper subset) > > approach. What we have is already rigorously documented in several > > books at Borders, Barnes & Noble, Books-A-Million, Amazon, et. al., > > hope I didn't leave out your favorite; if I'd remembered it I would > > have plugged it. > > > Very good point. That definitely would be a disadvantage. > You got my favorite. ;) > > > An "approved subset" would be yet another learning level for newbies. > > I'd much rather see our current Documentation Guide fully-fleshed out > > with recommended (or at least tested) examples for the > > monkey-see-monkey-document crowd. No slur intended, but it's really > > much easier to bang out a DocBook document with minimal learning > > curve by just looking at an example of what you want to do; no > > "internalized learning" required. > > > > Actually, being a subset and not a superset; there is less that a end-user > would need to learn. > > Take for instance the following elements: > sidebar > synopsis > bridgehead > dedication > sect[1-5] > > Are any of these, needed? I hadn't realized it but somewhere in the wiki ---- > I don't remember where --- it is stated not to utilize the sect elements. It > just so happens that as a habit/preference I don't use these elements > anyways. However without a correct document model, all instances derived > thusly can and may be utilizing irrelevant, unneeded, or unwanted > content simply because they are a part of the original xml markup language. > > As one of the editors once stated offlist, I am one of the seemingly few > people who likes XML Markup. So I tend to see the project from another angle. > Whether that's good or bad I am not sure yet. Just because an element's not listed doesn't mean we don't use it. The <sectN> guidance was created to make docs more modular, and it has proven worthwhile several times for me personally. The ease of transmuting docs received with <sectN> just using some simple sed lines means no one has to break a sweat even if a writer uses that element. For any elements that need special guidance for FDP, that's what the Documentation Guide is for. I'm with Tommy on this one; defining this (a) takes energy away from docs and puts it toward unnecessary process, and (b) creates a need for additional documentation when DocBook is already covered. If we had hundreds of volunteer doc monkeys typing away, I would say go for it, but when we're still trying to put together the basis, it's probably not time for this. But it's worth keeping in mind for some future time when those armies of doc monkeys *do* show up... :-)
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
