W3C home > Mailing lists > Public > public-i18n-its@w3.org > April to June 2007

Re: Draft of DocBook+ITS section

From: Felix Sasaki <fsasaki@w3.org>
Date: Wed, 02 May 2007 09:48:49 +0900
Message-ID: <4637DFF1.6050401@w3.org>
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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:12:49 GMT