OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-translation message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: FW: Foreign element in DITA for ITS


 Just an FYI about Yves' work on ITS


JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com
 

-----Original Message-----
From: Yves Savourel [mailto:ysavourel@translate.com] 
Sent: Friday, March 30, 2007 5:45 AM
To: 'Don Day'
Cc: 'Eric Sirois'; gershon@tech-tav.com; JoAnn Hackos
Subject: RE: Foreign element in DITA for ITS

Hi Don,

Thanks for the explanation.

I'm still puzzled though: why using two entities for "its"?

In itsDomain.ent: <!ENTITY % its-d-foreign "its"> In itsDomain.mod:
<!ENTITY % its "its">

Overall DITA's <foreign> mechanism seems quite handy. A great addition
to 1.1.

Cheers,
-yves

-----Original Message-----
From: Don Day [mailto:dond@us.ibm.com]
Sent: Thursday, March 29, 2007 11:18 PM
To: Yves Savourel
Cc: 'Eric Sirois'; gershon@tech-tav.com; JoAnn.Hackos@Comtech-Serv.com
Subject: RE: Foreign element in DITA for ITS

I'll take a stab at this, Yves. DITA specialization design patterns
declare new elements as parameter entities so that DTDs that embed the
specializations can "clone" the new element into existing content
models, ensuring that the new element is only used in the same contexts
where its archetype is already valid. In generalization, <its>
gracefully degrades to <foreign>, and all is well in context.

It looks like Eric defined its-d-foreign as a more semantic name for
this case, but you can see how this declaration basically adds <its>
into any content model where <foreign> is also already allowed. And
because both are declared as parameter entities, <its> is itself
extensible to further specialization (something your its associates
might find an intriguing future thought!).

In itsDomain.ent:
<!ENTITY % its-d-foreign      "its"                 >

and in your shell DTD:
<!ENTITY % foreign   "foreign | %its-d-foreign;"       >


Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 512-838-8550
T/L: 678-8550

"Where is the wisdom we have lost in knowledge?
 Where is the knowledge we have lost in information?"
   --T.S. Eliot


 

             "Yves Savourel"

             <ysavourel@transl

             ate.com>
To 
                                       "'Eric Sirois'"

             03/29/2007 10:36          <esirois@ca.ibm.com>

             PM
cc 
                                       Don Day/Austin/IBM@IBMUS,

                                       <gershon@tech-tav.com>,

                                       <JoAnn.Hackos@Comtech-Serv.com>

 
Subject 
                                       RE: Foreign element in DITA for
ITS 
 

 

 

 

 

 





Hi Eric,

I was looking closer to the files, and I have a question.

In itsDomain.mod there is:

<!-- declaration for the specialized wrapper and alternate element -->
<!ENTITY % its "its">

But it seems not to be used anywhere. Is it necessary to declare it?

Thanks
-ys



-----Original Message-----
From: Eric Sirois [mailto:esirois@ca.ibm.com]
Sent: Wednesday, March 28, 2007 1:34 PM
To: Yves Savourel
Cc: 'Don Day'; gershon@tech-tav.com; JoAnn.Hackos@Comtech-Serv.com
Subject: RE: Foreign element in DITA for ITS

Hi Yves,

There are couples of methods that can be used to include the ITS DTD via
<foreign>.
   Create a domain specialization based on <foreign>
   Create an element specialization such that the ITS elements are
children
   of <foreign> only in the prolog.

The first case is the easiest and quickest to implement and integrate
into existing DTDs, but it also allows the ITS elements to appear
wherever <foreign> is valid.  The two sample implementation (MathML and
SVG) have been done in this manner.

The second case is a bit more complicated.  Unfortunately, for DITA 1.0
and DITA 1.1 there is no simple way to simply specialize an element in a
specific context.  There are some discussion at the moment on the TC on
how best to solve address this for DITA 1.2.
In order for you to add <its:rules> specifically to <foreign> in a
<prolog> you would have to specialize <concept>, <prolog> and <foreign>.


I include a sample of a domain implementation.  I created a new shell
concept DTD that includes the ITS domain.  I could have included the
entries in the concept.dtd files.  I added the additional file so you
could compare it against the base concept.dtd.
For a domain you have to create two files:

itsDomain.ent
<?xml version="1.0" encoding="UTF-8"?>

<!ENTITY % its-d-foreign      "its"                 >

<!ENTITY   its-d-att     "(topic its-d)"                               >


itsDomain.mod
<?xml version="1.0" encoding="UTF-8"?>
<!-- declaration for the specialized wrapper and alternate element -->
<!ENTITY % its "its">


<!-- included ITS document type -->
<!ENTITY % its-def SYSTEM  "its/its.dtd" >
      %its-def;

      <!-- definition for the specialized wrapper and alternate element
-->
      <!ELEMENT its (%n.rules;)>
      <!ATTLIST its %global-atts;
class CDATA "+ topic/foreign its-d/its ">

Add/modify the following items to you favorite shell DTD.
<!ENTITY % its-d-dec     SYSTEM
"itsDomain.ent"                                                 >
%its-d-dec;

<!ENTITY % foreign   "foreign | %its-d-foreign;"       >

<!ENTITY included-domains
                        "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;
                         &ut-d-att; &indexing-d-att; &its-d-att;"
>

<!ENTITY % its-d-def     SYSTEM  "itsDomain.mod"
>
%its-d-def;


Sample 1:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"dtd/concept.dtd">
<concept id="xmlproc" xml:lang="en-us">
 <title>Processing XML with <tm tmtype="tm">Rainbow</tm></title>
<prolog>
   <its>  <--- domain specialization wrapper for foreign.
    <its:rules xmlns:its="http://www.w3.org/2005/11/its"; version="1.0">
     <its:translateRule selector="//uicontrols" translate="no"/>
     <its:translateRule selector="//wintitle" translate="no"/>
    </its:rules>
   </its>
 </prolog>
 <conbody>

 If you wanted to go the element specialization route.  You would have
to create a new shell DTD, for instance conceptIts.dtd, and an
accompanying module; conceptIts.mod.

In the mod file, you would redefine the three content models in question
to pull in <its:rules> from <foreignIts>.  If you want a sample
implementation for this type of specialization, please let me know, i
can create one for you.


Sample 2:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"dtd/concept.dtd">
<conceptIts id="xmlproc" xml:lang="en-us">  <title>Processing XML with
<tm tmtype="tm">Rainbow</tm></title>  <prologIts>
   <foreignIts>  <--- domain specialization wrapper for foreign.
    <its:rules xmlns:its="http://www.w3.org/2005/11/its"; version="1.0">
     <its:translateRule selector="//uicontrols" translate="no"/>
     <its:translateRule selector="//wintitle" translate="no"/>
    </its:rules>
   </foreignIts>
 </prolog>
 <conbody>

(See attached file: conceptIts.dtd)(See attached file:
itsDomain.ent)(See attached file: itsDomain.mod)

Eric A. Sirois
Staff Software Developer
DB2 Universal Database - Information Development DITA Migration and
Tools Development IBM Canada Ltd. - Toronto Software Lab
Email: esirois@ca.ibm.com
Blue Pages (Internal)

"Transparency and accessibility requirements dictate that public
information and government transactions avoid depending on technologies
that imply or impose a specific product or platform on businesses or
citizens" - EU on XML-based office document formats.



             "Yves Savourel"
             <ysavourel@transl
             ate.com>
To
                                       "'Don Day'" <dond@us.ibm.com>
             03/27/2007 02:36
cc
             PM                        <gershon@tech-tav.com>,
                                       <JoAnn.Hackos@Comtech-Serv.com>,
                                       Eric Sirois/Toronto/IBM@IBMCA
 
Subject
                                       RE: Foreign element in DITA for
ITS










Hi Don,

Thanks for your quick response.

> Where in the workflow is it best to insert the ITS rules into a topic 
> that is about to be translated?

I have a DITA file with some step by step instructions. It uses things
like <filepath>, <uicontrol>, <image>, <draft-comment>, etc.

I want to do various language-related actions on it. For example:
extraction to XLIFF, spell-checking, pseudo-translation, etc. The tool I
will use is an ITS processor and therefore assumes the default ITS
rules: all elements are translatable, no attribute is translatable.

To adapt these defaults to DITA I use an external ITS file to specify
that some elements are generally not translatable: for example
<draft-comments> and <filepath> (at least in my scenario). I also use
the ITS rule to specify that the alt attribute of <image> is
translatable. I also associate the DITA's translate attribute to ITS
rules so it behaves the same. [...so far no ITS inside the DITA file]

Then I want to show that I can override translatability only on specific
file. For example: Imagine that the UI references in my text (enclosed
in <uicontrol> and <wintitle>) are never going to be localized, but the
doc will be. So for this specific DITA file I want to define <uicontrol>
and <wintitle> has non-translatable.

The DITA way to do that would be to write <uicontrol
translate="no">...</uicontrol>. This would work and require no ITS in
the file.

But I'm lazy and want to do all the UI elements without having to go
through each occurences in this file. I cannot add a rule for them in
the external general set of rule I used so far because these rules are
for all DITA documents in general.

I could actually create a new external ITS rule file that links to the
genral one and set the UI element as non translatable [still no ITS
inside the DITA file]. But the point is to illustrate how ITS rules can
be used within a document instance. So I want to add an <its:rules>
element within the DITA document where I will set the UI elements as
non-translatable. Something like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"dtd/concept.dtd">
<concept id="xmlproc" xml:lang="en-us">
 <title>Processing XML with <tm tmtype="tm">Rainbow</tm></title>
<its:rules xmlns:its="http://www.w3.org/2005/11/its";
version="1.0">
  <its:translateRule selector="//uicontrols" translate="no"/>
  <its:translateRule selector="//wintitle" translate="no"/>
</its:rules> <conbody>
  <p><tm tmtype="tm">Rainbow</tm> (<image href="rainbowIcon.png"
alt="Icon for Rainbow"/>) is GUI program that allows you to execute any
existing <tm tmtype="tm">Okapi</tm> utility.<draft-comment>Maybe we also
need to talk about Tikal for commend-line mode?</draft-comment></p>
  <?Pub Caret?>
  <p>Here is an example of extracting XML documents to XLIFF<fn>XLIFF is
a standard format used by localization tools</fn> for translation, using
<tm tmtype="tm">Rainbow</tm>.</p>
  <ol>
   <li>Start <tm tmtype="tm">Rainbow</tm></li>
   <li>Drop the files to process in the <uicontrol>Input List
1</uicontrol> tab.</li>
   <li>Associate to each XML document with its relevant parameters
file.</li>
   <li>Select the <uicontrol>Text Extraction</uicontrol> command from
the <uicontrol>Utilities</uicontrol> menu. This opens the <wintitle>Text
Extraction Utility</wintitle> dialog box.</li>
   <li>Go to the <uicontrol>Format</uicontrol> tab and select
<tt>XLIFF</tt>.</li>
   <li>Go to the <uicontrol>Package</uicontrol> tab. Enter the name of
the directory where you want to create the translation package in the
<uicontrol>Output folder</uicontrol> field. The default is
<filepath>C:\Localization Projects</filepath>.</li>
   <li>Enter the name of the package to create in the <uicontrol>Package
name</uicontrol> field. For example: <filepath
translate="yes">Pack1</filepath>.</li>
   <li>Click <uicontrol>Execute</uicontrol> to start the process.</li>
  </ol>
 </conbody>
</concept>

I have changed the DTD to allow this, and it validates. But I wanted to
make sure this was how one would add non-DITA elements inside a DITA
file. I think it would probably be better in a <prolog>, so I've looked
up the references and found the <foreign> element... And hence my
question :)

By the way: I'm open to suggestions if the DITA structure I use for this
example is not quite right (not sure if <concept> is the right type of
DTD to use for this kind of concept + instructions). It's just an
example, but the more legit it looks the better.

I hope I'm not too confusing.
-yves









[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]