The DocBook Publishers Schema - OASIS be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications,
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
The DocBook Publishers SchemaEdited by Scott Hudson
Scott HudsonFlatironsFlatirons Solutions Corporation
This is a Committee Draft. It was approved by the OASIS DocBook Publishers subcommittee, butit does not necessarily represent the consensus of the OASIS DocBook Technical Committee.
Please send comments on this specification to the<[email protected]> list. To subscribe, please use theOASIS Subscription Manager.
The errata page for this specification is at http://docs.oasis-open.org/docbook/specs/publishers-er-rata.html.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intel-lectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at theOASIS website.
This document and translations of it may be copied and furnished to others, and derivative worksthat comment on or otherwise explain it or assist in its implementation may be prepared, copied,published, and distributed, in whole or in part, without restriction of any kind, provided that theabove copyright notice and this section are included on all such copies and derivative works. However,this document itself may not be modified in any way, including by removing the copyright noticeor references to OASIS, except as needed for the purpose of developing any document or deliverableproduced by an OASIS Technical Committee (in which case the rules applicable to copyrights, asset forth in the OASIS IPR Policy, must be followed) or as required to translate it into languagesother than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its suc-cessors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASISDISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITEDTO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT IN-FRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTAB-ILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that wouldnecessarily be infringed by implementations of this OASIS Committee Specification or OASISStandard, to notify OASIS TC Administrator and provide an indication of its willingness to grant
patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Tech-nical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownershipof any patent claims that would necessarily be infringed by implementations of this specification bya patent holder that is not willing to provide a license to such patent claims in a manner consistentwith the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS mayinclude such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rightsthat might be claimed to pertain to the implementation or use of the technology described in thisdocument or the extent to which any license under such rights might or might not be available; neitherdoes it represent that it has made any effort to identify any such rights. Information on OASIS' pro-cedures with respect to rights in any document or deliverable produced by an OASIS TechnicalCommittee can be found on the OASIS website. Copies of claims of rights made available for pub-lication and any assurances of licenses to be made available, or the result of an attempt made to obtaina general license or permission for the use of such proprietary rights by implementers or users ofthis OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Ad-ministrator. OASIS makes no representation that any information or list of intellectual property rightswill at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, andshould be used only to refer to the organization and its official outputs. OASIS welcomes referenceto, and implementation and use of, specifications, while reserving the right to enforce its marksagainst misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
Published 2008-06-05
Abstract
For more than a decade, DocBook has provided a structured markup vocabulary for hardware andsoftware documentation. DocBook is now widely used in both commercial and Open Source envir-onments. DocBook has a very broad element set, and applies to much more than just technical doc-umentation. The DocBook TC is engaged in evolving the suite of DocBook specifications. Thecommunity benefits from having a standard, open, interchangeable vocabulary in which to writestructured content. DocBook has been, and will continue to be, designed to satisfy this requirement.
The OASIS DocBook SubCommittee for Publishers is chartered to develop and maintain officialvariants of DocBook in support of the publishing industry. Specifically, the subcommittee will focuson schema and stylesheet customizations to support: periodicals as regularly published technicalnotes 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.
The DocBook Publishers Schema is based on DocBook 5.0, and delivered in the normative RelaxNGSchema format.
Table of ContentsIntroduction ........................................................................................................................ 3
Explicit support for Dublin Core metadata ................................................................................ 4New Element Definitions ...................................................................................................... 6Re-Defined DocBook Content Models ..................................................................................... 6Included DocBook Element Definitions ................................................................................... 8Excluded DocBook Element Definitions ................................................................................. 18Attribute Definitions ........................................................................................................... 25A. Acknowledgements ........................................................................................................ 25B. Revision History ............................................................................................................ 26
IntroductionFor more than a decade, DocBook has provided a structured markup vocabulary for hardware and softwaredocumentation. DocBook is now widely used in both commercial and Open Source environments. DocBookhas a very broad element set, and applies to much more than just technical documentation. The DocBookTC is engaged in evolving the suite of DocBook specifications. The community benefits from having astandard, open, interchangeable vocabulary in which to write structured content. DocBook has been, andwill continue to be, designed to satisfy this requirement.
The OASIS DocBook SubCommittee for Publishers is chartered to develop and maintain official variantsof DocBook in support of the publishing industry. Specifically, the subcommittee will focus on schemaand stylesheet customizations to support: periodicals as regularly published technical notes or journals,book publishing (such as business, legal, medical, and other non-technical domains), educational textbooksand other document types as appropriate for this industry.
The DocBook Publishers subcommittee maintains the DocBook Publishers schema. Based on DocBookV5.0, the DocBook Publishers schema is normatively available as a [RELAX NG] Schema (with someadditional Schematron assertions).
The DocBook Technical Committee welcomes bug reports and requests for enhancement (RFEs) from theuser community. The current list of outstanding requests is available through the SourceForge tracker in-terface. This is also the preferred mechanism for submitting new requests.
TerminologyThe key words must, must not, required, shall, shall not, should, should not, recommended, may, and op-tional in this Committee Draft are to be interpreted as described in [RFC 2119]. Note that for reasons ofstyle, these words are not capitalized in this document.
Normative References
[RELAX NG] James Clark, editor. RELAX NG Specification (Committee Specification). OASIS. 2001.
[XML] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, et. al., editors. Extensible Markup Language (XML) 1.0(Fourth Edition). World Wide Web Consortium, 16 August 2006.
[XLink11] Steven DeRose, Eve Maler, David Orchard, Norman Walsh, editors. XML Linking Language (XLink) Version1.1. World Wide Web Consortium, 2005.
[RFC 2119] IETF (Internet Engineering Task Force). RFC 2119: Key words for use in RFCs to Indicate RequirementLevels. S. Bradner. 1997.
[RFC 3023] IETF (Internet Engineering Task Force). RFC 3023: XML Media Types. M. Murata, S. St. Laurent, D.Kohn. 2001.
[DocBook: TDG5] Norman Walsh and Leonard Meullner. DocBook 5.0: The Definitive Guide.
Non-Normative References
[SGML] JTC 1, SC 34. ISO 8879:1986 Information processing -- Text and office systems -- Standard GeneralizedMarkup Language (SGML). 1986.
[W3C XML Schema] Henry S. Thompson, David Beech, Murray Maloney, et. al., editors. XML Schema Part 1:Structures. World Wide Web Consortium, 2000.
[W3C XML Datatypes] Paul V. Biron and Ashok Malhotra, editors. XML Schema Part 2: Datatypes. World WideWeb Consortium, 2000.
[Schematron] Rick Jelliffe, editor. The Schematron Assertion Language 1.5. Rick Jelliffe and Acedemia Sinica Com-puting Centre. 2001, 2001.
The DocBook Publshers RELAX NG SchemaThe DocBook Publishers RELAX NG Schema is distributed from the DocBook site at OASIS. DocBookis also available from the mirror on http://docbook.org/.
This subcommittee will submit additional enhancements back to the full DocBook standard as appropriate.The scope of this DocBook Publishers schema is publishing industry content. Broadly, this includes books,journals and other related publications. The DocBook Publishers schema has been written as a native RELAXNG grammar, based on DocBook V5.0. This effort delivers on the following goals:
1. Build official DocBook variant, based against the DocBook v5.0 schemas.
2. Address issues and enhancement requests that have arisen from experience with real-world DocBookimplementations.
3. Add support for features specific to the publishing industry.
Explicit support for Dublin Core metadataWhile DocBook already includes many of the elements that are defined by the Dublin Core, it is not inher-ently interoperable with DC metadata. The Publisher's SC has decided to formally adopt Dublin Coremetadata as a formal metadata model for info elements. The Publishers schema will continue to supportthe base DocBook info metadata, but will allow Dublin Core elements as an alternative for capturingmetadata in this widely adopted schema.
As the Dublin Core standard does not provide a RelaxNG or RelaxNG Compact version of their schema,the Publishers SC has endeavored to create Dublin Core in RNC format. The Publishers SC plans to con-tribute the dc.rnc, dcterms.rnc, and dcmitypes.rnc back to the Dublin Core standard.
The following Dublin Core elements have been defined and included in the Publishers schema:
While not appropriate in tech-nical documentation, severalpublishers requested this RFEto allow media objects (such asphotos) associated with a per-son.
db.info.elements | db.pub-l i sh ing . in l ines |db.citerefentry | db.citetitle| db.citebiblioid | db.person| db.personblurb | db.person-name | db.subtitle | db.title| db.titleabbrev
d b. b i b l i o -graphic.ele-ments
Modified to allow db.dialogueand db.poetry in all block levelpatterns.
db.dialogue | db.poetryd b . e x t e n -sion.blocks
7
The DocBook Publishers Schema
Included DocBook Element DefinitionsEach element in DocBook V5.0 is defined by its own pattern. To change the content model of an element,only that pattern need be redefined. To remove an element from DocBook, that pattern can be redefinedas “notAllowed”.
The following elements from full DocBook have been included:
8
The DocBook Publishers Schema
Table 3. Included DocBook elements
DescriptionModuleGroupDefinitionElement Name
An abbreviation, especially onefollowed by a period
pool.rncdb.publishing.in-lines
db.abbrevabbrev
A summarypool.rncdb.info.elementsdb.abstractabstract
Acknowledgements of a bookor other component
hier.rncdb.componentsdb.acknowledge-ments
acknowledge-ments
An often pronounceable wordmade from the initial (or selec-ted) letters of a name or phrase
pool.rncdb.publishing.in-lines
db.acronymacronym
A real-world address, generallya postal address
pool.rncd b . p u b l i s h -ing.blocks
db.addressaddress
The institutional affiliation ofan individual
pool.rncd b . p e r s o n . a u -thor.contentmodel
db.affiliationaffiliation
A text-only annotation, oftenused for accessibility
pool.rncdb.ubiq.inlinesdb.altalt
A spot in the documentpool.rncdb.link.inlinesdb.anchoranchor
An answer to a question posedin a QandASet
qandaset.rncdb.qandaentrydb.answeranswer
An appendix in a Book or Art-icle
hier.rncdb.componentsdb.appendixappendix
A region defined for a Calloutin a graphic or code example
callouts.rncdb.areaspecdb.areaarea
A region defined for a Calloutin a graphic or code example
callouts.rncdb.areasetdb.area.inareasetarea
A set of related areas in agraphic or code example
callouts.rncdb.areaspecdb.areasetareaset
A collection of regions in agraphic or code example
callouts.rncdb.programlist-ingco
db.areaspecareaspec
An articlehier.rncdb.componentsdb.articlearticle
The page numbers of an articleas published
pool.rncdb.info.elementsdb.artpagenumsartpagenums
The source of a block quote orepigraph
pool.rncdb.blockquotedb.attributionattribution
Pointer to external audio datapool.rncdb.audioobjectdb.audiodataaudiodata
A wrapper for audio data and itsassociated meta-information
pool.rncd b . m e d i a o b -ject.content
db.audioobjectaudioobject
The name of an individual au-thor
pool.rncdb.bibliography.in-lines
db.authorauthor
Wrapper for author informationwhen a document has multipleauthors or collabarators
pool.rncdb.info.elementsdb.authorgroupauthorgroup
The initials or other short identi-fier for an author
A titled division in a QandASetqandaset.rncdb.qandasetdb.qandadivqandadiv
A question/answer set within aQandASet
qandaset.rncdb.qandasetdb.qandaentryqandaentry
A question-and-answer setqandaset.rncdb.list.blocksdb.qandasetqandaset
A question in a QandASetqandaset.rncdb.qandaentrydb.questionquestion
15
The DocBook Publishers Schema
An inline quotationpool.rncdb.publishing.in-lines
db.quotequote
pool.rncdb.releaseinforeleaseinfo
A remark (or comment) inten-ded for presentation in a draftmanuscript
pool.rncremarkremark
pool.rncrevdescriptionrevdescription
pool.rncrevhistoryrevhistory
pool.rncrevisionrevision
pool.rncrevnumberrevnumber
pool.rncrevremarkrevremark
calstbl.rncrowrow
index.rncsecondarysecondary
index.rncsecondaryiesecondaryie
hier.rncdb.sectionsection
index.rncseesee
index.rncseealsoseealso
pool.rncseriesvolnumsseriesvolnums
hier.rncsetset
index.rncsetindexsetindex
pool.rncshortaffilshortaffil
A portion of a document that isisolated from the main narrativeflow
pool.rncsidebarsidebar
A paragraph that contains onlytext and inline markup, no blockelements
pool.rncsimparasimpara
An undecorated list of singlewords or short phrases
pool.rncsimplelistsimplelist
A section of a document withno subdivisions
hier.rncsimplesectsimplesect
calstbl.rncspanspecspanspec
statestate
A unit of action in a procedurepool.rncstepstep
Alternative steps in a procedurepool.rncstepalternativesstepalternatives
pool.rncstreetstreet
One of a group of terms describ-ing the subject matter of a docu-ment
pool.rncsubjectsubject
A set of terms describing thesubject matter of a document
pool.rncsubjectsetsubjectset
16
The DocBook Publishers Schema
A term in a group of terms de-scribing the subject matter of adocument
pool.rncsubjecttermsubjectterm
pool.rncsubscriptsubscript
A wrapper for steps that occurwithin steps in a procedure
pool.rncsubstepssubsteps
The subtitle of a documentpool.rncsubtitlesubtitle
pool.rncsuperscriptsuperscript
pool.rncsurnamesurname
calstbl.rnctabletable
A task to be completedtasks.rnctasktask
The prerequisites for a tasktasks.rnctaskprerequisitestaskprerequis-ites
Information related to a tasktasks.rnctaskrelatedtaskrelated
A summary of a tasktasks.rnctasksummarytasksummary
calstbl.rnctbodytbody
The word or phrase beingdefined or described in a vari-able list
pool.rnctermterm
An inline definition of a termglossary.rncdb.termdeftermdef
index.rnctertiarytertiary
Pointer to external text datapool.rnctextdatatextdata
A wrapper for a text descriptionof an object and its associatedmeta-information
pool.rnctextobjecttextobject
calstbl.rnctfoottfoot
A wrapper for the main contentof a table, or part of a table
calstbl.rnctgrouptgroup
calstbl.rnctheadthead
The text of the title of a sectionof a document or of a formalblock-level element
pool.rnctitletitle
The abbreviation of a titlepool.rnctitleabbrevtitleabbrev
A table of contentstoc.rnctoctoc
pool.rnctrademarktrademark
pool.rncuriuri
A list in which each entry iscomposed of a set of one ormore terms and an associateddescription
pool.rncvariablelistvariablelist
A wrapper for a set of terms andthe associated description in avariable list
pool.rncvarlistentryvarlistentry
Pointer to external video datapool.rncvideodatavideodata
17
The DocBook Publishers Schema
A wrapper for video data and itsassociated meta-information
pool.rncvideoobjectvideoobject
pool.rncvolumenumvolumenum
pool.rncdb.wordaswordwordasword
pool.rncxrefxref
pool.rncyearyear
Any element from almost anynamespace
pool.rncdb._anydb._any*.*
Excluded DocBook Element DefinitionsThe following elements from full DocBook have been excluded from the Publishers schema:
Note
Because the Publishers schema is written in RelaxNG Compact syntax, it is very easy to addelements back into a customization of the Publishers schema. For example, if the elements in theprogramming module were needed, it is very simple to use an include statement for the program-ming.rnc file from the source DocBook distribution.
18
The DocBook Publishers Schema
Table 4. Excluded DocBook elements
DescriptionModuleGroupDefinitionElement Name
A graphical user interface(GUI) keyboard shortcut
keyboard.rncdb.keyboard.inlinesdb.accelaccel
An annotationannotations.rncdb.ubiq.inlinesdb.annotationannotation
A unit of informationmarkup.rncdb.markup.inlinesdb.tokentoken
htmltbl.rncdb.html.informalt-able
tr
programming.rncdb.programming.in-lines
db.typetype
os.rncdb.os.inlinesdb.userinputuserinput
programming.rncvarargsvarargs
programming.rncdb.programming.in-lines
varnamevarname
programming.rncdb.voidvoid
admonitions.rncdb.warningwarning
Attribute DefinitionsEach attribute list in DocBook V5.0 is defined by its own pattern. To change the list of attributes availableon an element, only that pattern need be redefined. To remove all the attributes, that pattern can be redefinedas “empty”.
The following attribute definitions have been added to the Publishers schema:
Table 5. Publishers Attribute Pattern Definitions
Attribute pattern definitionAttribute pattern name
A. AcknowledgementsThe following individuals have participated in the creation of this specification and are gratefully acknow-ledged:
25
The DocBook Publishers Schema
Participants
• Jim Earley, Flatirons Solutions• Dick Hamilton, Individual• John Hanratty, Reed Elsevier• Gary Hoffman, Individual• Dave Pawson, Royal National Institute of the Blind (RNIB)• John Pederson, John Wiley & Sons, Inc.• Norm Walsh, Mark Logic Corporation• Keith Fahlgren, O'Reilly Media (Secretary)• Scott Hudson, Flatirons Solutions (Chair, Editor)