1 ITS and DocBook1 ITS and DocBookDocBook is a general purpose XML schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). DocBook is maintained by the DocBook Technical Committee of OASIS.
1.1 Integration of ITS into DocBookDocBook V5.0 schema is maintained as a very modular and easy to customize schema written in RELAX NG [relaxng]. General techniques for schema customization are described in [docbook-howto].
The ITS additions involve the following changes to DocBook schema:
Adding the ITS local attributes to every existing DocBook element.
Not all ITS local attributes are added into schema as DocBook already provides its own means for specifying directionality of text.
Allowing rules element inside
DocBook info element which is a general metadata container.
Allowing ruby as inline element almost everywhere where plain text could be.
# This schema integrates ITS markup (http://www.w3.org/TR/its/)
# into DocBook schema (http://docbook.org)
#
# $Id: docbook-its.rnc,v 1.2 2007/05/01 20:01:13 jkj Exp $
#
# Copyright 2007 Jirka Kosek (jirka@kosek.cz)
#
# Permission to use, copy, modify and distribute this schema for any
# purpose and without fee is hereby granted in perpetuity, provided
# that the above copyright notice and this paragraph appear in all
# copies. The copyright holders make no representation about the
# suitability of the schema for any purpose. It is provided "as is"
# without expressed or implied warranty.
# Namespace declarations for DocBook, ITS and HTML (HTML is used internally in DocBook schema)
namespace db = "http://docbook.org/ns/docbook"
namespace its = "http://www.w3.org/2005/11/its"
namespace html = "http://www.w3.org/1999/xhtml"
# Include base DocBook schema
include "docbook.rnc"
{
# Exclude ITS markup from "wildcard" element
db._any =
element * - (db:* | html:* | its:*) {
(attribute * { text }
| text
| db._any)*
}
}
# Include base ITS schema
include "its.rnc"
# Define pattern for local ITS attributes
# (except its:dir attribute which already has an equivalent in DocBook)
db.its.attributes =
its-att.translate.attributes?
& its-att.locNote.attributes?
& its-att.term.attributes?
& its-att.version.attributes?
# Add local ITS attributes to all DocBook elements
db.common.attributes &= db.its.attributes
db.common.idreq.attributes &= db.its.attributes
# Allow its:rules inside info element
db.info.extension |= its-rules
# Allow Ruby markup almost everywhere
db.ubiq.inlines |= its-ruby
For your convenience there is also available “flattened” schema stored inside one file and converted to other schema languages as well.
dbits.rnc (RELAX NG compact syntax schema in one file)[Ed. note: Flattened version are broken at this time]
dbits.rng (RELAX NG schema in one file)[Ed. note: Flattened version are broken at this time]
dbits.dtd (DTD in one file)[Ed. note: Flattened version are broken at this time]
dbits.xsd (W3C XML Schema)[Ed. note: TODO]
There is no need for adding span element as
DocBook provides similar element called phrase which can be
used for attaching ITS local attributes to an arbitrary piece of
text.
The following example shows sample DocBook article conforming to
DocBook+ITS schema. The translateRule element is used to indicate that
function names (marked-up by function element) should not be
translated. The first paragraph is also marked as nontranslatable
using local ITS markup.
<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:db="http://docbook.org/ns/docbook"
version="5.0" xml:lang="en">
<info>
<title>Sample article</title>
<its:rules version="1.0">
<its:translateRule translate="no" selector="//db:function"/>
</its:rules>
</info>
<para its:translate="no">Nontranslatable content</para>
<section>
<title>Sample section</title>
<para>You can delete file using <function>unlink()</function> function.</para>
</section>
</article>1.2 Relating ITS to Existing DocBook MarkupA number of DocBook constructs implement the same semantic as some of the ITS data categories. In addition, some of the DocBook attributes are translatable, which is not the default for XML documents according to ITS defaults settings for translatability. These attributes need to be identified as translatable.
Note: When you have the choice of using a DocBook construct or a ITS construct to express the same thing, make sure to use the DocBook construct to ensure DocBook processing tools properly. Use ITS local markup only if DocBook does not provide an equivalent.
An external ITS rules element can
summarize these relations. Because DocBook use is widespread and
diverse the rules defined here are just example which may need further
tailoring for specific use.
<its:rules xmlns:its="http://www.w3.org/2005/11/its" xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0"> <!-- Translatable attributes --> <its:translateRule selector="//db:table/@summary" translate="yes"/> <its:translateRule selector="//db:*/@xlink:title" translate="yes"/> <its:translateRule selector="//db:*/@xreflabel" translate="yes"/> <its:translateRule selector="//db:*/@label" translate="yes"/> <!-- Non-translatable elements --> <its:translateRule translate="no" selector="//db:*[@revisionflag = 'deleted']"/> <its:translateRule translate="no" selector="//db:abbrev | //db:author | //db:classname | //db:command | //db:constant | //db:date | //db:editor | //db:email | //db:envar | //db:errorcode | //db:exceptionname | //db:filename | //db:function | //db:initializer | //db:interfacename | //db:markup | //db:methodname | //db:modifier | //db:ooclass | //db:ooexception | //db:oointerface | //db:option | //db:parameter | //db:person | //db:personname | //db:productnumber | //db:property | //db:returnvalue | //db:symbol | //db:tag | //db:type | //db:uri | //db:varname"/> <!-- Possible terms --> <its:termRule selector="//db:glossterm" term="yes"/> <its:termRule selector="//db:firstterm" term="yes"/> <!-- Bidirectional information --> <its:dirRule selector="//db:*[@dir='ltr']" dir="ltr"/> <its:dirRule selector="//db:*[@dir='rtl']" dir="rtl"/> <its:dirRule selector="//db:*[@dir='lro']" dir="lro"/> <its:dirRule selector="//db:*[@dir='rlo']" dir="rlo"/> <!-- Elements within text --> <its:withinTextRule withinText="yes" selector="//db:abbrev | //db:accel | //db:acronym | //db:application | //db:author | //db:citation | //db:citebiblioid | //db:citerefentry | //db:citetitle | //db:classname | //db:code | //db:command | //db:computeroutput | //db:constant | //db:database | //db:date | //db:editor | //db:email | //db:emphasis | //db:envar | //db:errorcode | //db:errorname | //db:errortext | //db:errortype | //db:exceptionname | //db:filename | //db:foreignphrase | //db:function | //db:guibutton | //db:guiicon | //db:guilabel | //db:guimenu | //db:guimenuitem | //db:guisubmenu | //db:hardware | //db:initializer | //db:interfacename | //db:jobtitle | //db:keycap | //db:keycode | //db:keycombo | //db:keysym | //db:link | //db:literal | //db:markup | //db:menuchoice | //db:methodname | //db:modifier | //db:mousebutton | //db:olink | //db:ooclass | //db:ooexception | //db:oointerface | //db:option | //db:optional | //db:org | //db:orgname | //db:package | //db:parameter | //db:person | //db:personname | //db:phrase | //db:productname | //db:productnumber | //db:prompt | //db:property | //db:quote | //db:replaceable | //db:returnvalue | //db:shortcut | //db:subscript | //db:superscript | //db:symbol | //db:systemitem | //db:tag | //db:token | //db:trademark | //db:type | //db:uri | //db:userinput | //db:varname | //db:wordasword"/> <its:withinTextRule withinText="nested" selector="//db:alt | //db:footnote | //db:remark | //db:indexterm | //db:primary | //db:secondary | //db:tertiary"/> </its:rules>