Re: [docbook-tc] DocBook Publishers documentation

["Hudson, Scott" <Scott.Hudson@schneider-electric.com>]

Title: Re: [docbook-tc] DocBook Publishers documentation

My answers inline [SH:]

On 6/7/11 1:59 PM, "Norman Walsh" <ndw@nwalsh.com> wrote:

> Scott Hudson <scott.hudson@schneider-electric.com> writes:
>> I'd like to include some of the verbiage from the specification in the
>> Introduction that explains the purpose behind the schema, and a summary of
>> what has been added / removed. I can work with you on this if you'd like.
>
> Yeah, that's the sort of thing I meant when I said
SH: Do you want to just paste from the spec, or do you have source somewhere
I should edit, or just send you the text?

Introduction

For more than a decade, DocBook has provided a structured markup vocabulary
for hardware and software documentation. DocBook is now widely used in both
commercial and Open Source environments. DocBook has a very broad element
set, and applies to much more than just technical documentation. The DocBook
TC is engaged in evolving the suite of DocBook specifications. The community
benefits from having a standard, open, interchangeable vocabulary in which
to write structured content. DocBook has been, and will continue to be,
designed to satisfy this requirement.

The OASIS DocBook Schema for Publishers is an official variant of DocBook
v5.x, specifically designed to support the publishing industry. Publications
that the schema is designed to support includes (but is not limited to):
periodicals as regularly published technical notes or journals, book
publishing (such as business, legal, medical, and other non-technical
domains), educational textbooks and other document types as appropriate for
this industry.

Based on DocBook V5.0, the DocBook Publishers schema is normatively
available as a RELAX NG Schema (with some additional Schematron assertions).
Of the 361 total elements in the full DocBook standard, the Publishers
schema has been simplified to exclude 149 elements from full DocBook.
Modifications have been made to 11 patterns from the DocBook schema.
Additions to the schema include: the Dublin Core metadata elements (54) and
6 new elements.

>
>>> I'm not sure what the chapters should be for this book. Probably just
>>> an introduction and maybe "what's different".
>
>> I did notice the dcterms:* entry, and agree that we need to figure out how
>> to display/reference these better.
>
> Right. We could make a refentry page for each one, but that seemed
> like overkill. I should probably just format that list as a table with
> the one line description and a link or something.
SH: there's a description of each in the spec. We could just use that?
>
> It appears that the content model for info is "bag of DocBook stuff"
> OR "bag of dcterms stuff". No mixing. Is that the intent? (Not that I
> think it's successfully articulated because the DocBook stuff allows
> *:*.)
SH: Yes, that is correct. either or, no mixing.
>
>> HTML tables were explicitly removed from Publishers, though there is a
>> request to add them back in, it is not part of the approved schema.
>
> Ah. Just fumble fingered on my part, I think. Fixed now :-)
>
> Publishers removes informaltable but leaves informalfigure and
> informalexample? That's intentional, is it?
SH: hm. informaltable should still be in, according to the spec...
>
>                                         Be seeing you,
>                                           norm

Thanks and best regards,

--Scott

Scott Hudson |  Pelco by Schneider Electric | United States | API and
Integration - Strategy
Ph: +1-970-282-1952  | M: +1-720-663-7268 |
scott.hudson@schneider-electric.com

______________________________________________________________________
This email has been scanned by the MessageLabs Email Security System.
For more information please visit http://www.messagelabs.com/email 
______________________________________________________________________