- From: Felix Sasaki <fsasaki@w3.org>
- Date: Wed, 02 May 2007 09:48:49 +0900
- To: Jirka Kosek <jirka@kosek.cz>
- CC: public-i18n-its@w3.org
Hi Jirka,
Many thank for this! Regarding your question: I think we should in the
BP and in general recommend not to use the ITS schemas "as is", but make
the adaptations which you proposed. That means that e.g. ITS+XHTML would
not include its:dir and its:ruby. Practically it means that as it comes
to local ITS markup, we would not just" add local attributes
http://www.w3.org/TR/its/#span.attributes to a schema, but a subset of
these. That is more efforts, but I think it's worth it to avoid confusion.
Felix
Jirka Kosek wrote:
> Hi all,
>
> please find attached the first draft of my DocBook section for BP. This
> is just very plain HTML rendering for your review. I will send xmlspec
> XML sources off-list to editors after I will incorporate your feedback.
>
> I modeled structure (and sometimes also wording, I hope it is OK) mainly
> after existing HTML and TEI sections.
>
> During the preparation of this text one question raised my attention. In
> DITA section there is the following note:
>
> Note: When you have the choice of using a DITA construct or a ITS
> construct to express the same thing, make sure to use the DITA construct
> to ensure DITA processors work properly. Use ITS local markup only if
> DITA does not provide an equivalent.
>
> My question is -- should the schemas provided in BP include ITS local
> markup which have equivalents in the host language?
>
> For example my current DocBook+ITS schema allows both
>
> <para dir="rtl">...</para>
>
> and
>
> <para its:dir="rtl">...</para>
>
> Wouldn't it be better to not add its:dir in this case into DocBook as
> DocBook already has support for this ITS category? (The same applies to
> many other existing schemas, including HTML.) This way authors will not
> be confused which markup to use.
>
> Jirka
>
>
>
> ------------------------------------------------------------------------
>
>
> Go to the table of contents. <#contents>1 ITS and DocBook
>
> DocBook 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
> <http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook>
> of OASIS <http://www.oasis-open.org/>.
>
>
> Go to the table of contents. <#contents>1.1 Integration of ITS
> into DocBook
>
> DocBook 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:
>
> 1.
>
> Adding the ITS local attributes
> <http://www.w3.org/TR/its/#span.attributes> to every existing
> DocBook element.
>
> 2.
>
> Allowing |rules <http://www.w3.org/TR/its/#rules>| element
> inside DocBook |info| element which is general metadata container.
>
> 3.
>
> Allowing |ruby <http://www.w3.org/TR/its/#ruby>| as inline
> element almost everywhere where plain text could be.
>
> Example 1:Â DocBook schema customization
> # 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
>
> db.its.attributes =
>
> its-att.translate.attributes?
>
> & its-att.locNote.attributes?
>
> & its-att.term.attributes?
>
> & its-att.dir.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
>
>
>
> [Example's source code <docbook/docbook-its.rnc>]
>
> For your convenience there is also available �flattened� schema
> stored inside one file and converted to other schema languages as well.
>
> *
>
> dbits.rnc <docbook/dbits.rnc> (RELAX NG compact syntax schema in
> one file)[Ed. note: Flattened version are broken at this time]
>
> *
>
> dbits.rng <docbook/dbits.rng> (RELAX NG schema in one file)[Ed.
> note: Flattened version are broken at this time]
>
> *
>
> dbits.dtd <docbook/dbits.dtd> (DTD in one file)[Ed. note:
> Flattened version are broken at this time]
>
> *
>
> dbits.xsd <docbook/dbits.xsd> (W3C XML Schema)[Ed. note: TODO]
>
> 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.
>
> Example 2:Â Sample DocBook document with 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>
>
> [Example's source code <docbook/ex-docbook-plus-its-1.xml>]
>
>
> Go to the table of contents. <#contents>1.2 Relating ITS to
> Existing DocBook Markup
>
> A 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
> <http://www.w3.org/TR/its/#selection-defaults-etc>. 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 <http://www.w3.org/TR/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.
>
> Example 3:Â ITS external rules for DocBook documents
> <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>
>
> [Example's source code <docbook/ex-relating-docbook-plus-its-1.xml>]
>
Received on Wednesday, 2 May 2007 00:49:01 UTC