RE: [htdig-dev] Status of defaults.xml

[Brian W. <bw...@st...>]

At 23:25 16/10/2002, Gabriele Bartolini wrote:
> >Well, it is close to ready  - I now have it successfully generating
>
>Well, first and foremost, it is the first time I express my opinion=
 regarding
>this solution and I think it is really efficient and intelligent. Good on
>ya, mate Brian! :-)
>
>Having said this, and also taking aknowledgement that I don't know how the
>XML file is structured, I want to raise the problem of 'translation' of
>the attributes' descriptions, uses, etc., in different languages.
>
>Any ideas?

Yes.

Let's start with the DTD as it stands:

<!ELEMENT HtdigAttributes ( attribute+ ) >

<!--  attribute:

           name     : Variable Name
           type     : Type of Variable
           programs : Whitespace separated list of programs/modules
                       using this attribute
           block    : Configuration block this can be used in ( optional )
           version  : Version that introduced the attribute
           category : Attribute category (to split documentation)

   -->

<!ELEMENT attribute( default, ( nodocs | (example+, description ) ) >
<!ATTLIST attribute name     CDATA #REQUIRED
                      type     string|integer|boolean) "string"
                      programs CDATA #REQUIRED
                      block    CDATA #IMPLIED
                      version  CDATA #REQUIRED
                      category CDATA #REQUIRED
                      >

<!-- Default value of attribute - configmacro=3D"true" would indicate the
      value is actually a macro ( eg BIN_DIR )
   -->
<!ELEMENT default (#PCDATA) >
<!ATTLIST default configmacro (true|false) "false" >

<!-- Basically a flag that suppresses documentation -->
<!ELEMENT nodocs EMPTY>

<!-- An example value that goes into the documentation -->
<!ELEMENT example (#PCDATA) >

<!ENTITY % paratext "#PCDATA|em|strong|a|ref" >
<!ENTITY % text "%paratext;|table|p|br|ol|ul|dl|codeblock" >

<!ELEMENT description (%paratext;) >

... + all the element for formatting the description

The first thing to do is then look at the items that might need
translation:

     * description
     * block
     * category
     * example

Analysis:
    * description is the one that will always need it
    * I think the values for "block" and "category" should be considered
      as 'keys' rather than the actual values - they should be translated
      by lookup table.
    * examples will *sometimes* require translation

To this end, I would suggest changing the following

    <!ELEMENT attribute ( default, ( nodocs | (example+, description ) ) >

to

    <!ELEMENT attribute ( default, ( nodocs | (example*, docset+ ) ) >

    <!-- lang would be the id of the language using a standard identifier,=
 or
         set to "default" for the default language -->

    <!ELEMENT docset  ( example*, description ) >
    <!ATTLIST docset  lang CDATA #REQUIRED >

As an example:

    <attribute name=3D"no_title_text"
               type=3D"string"
               programs=3D"htsearch"
               version=3D"3.1.0"
               category=3D"Presentation:Text" >
      <default>filename</default>
      <example>!!!!!?</example>
      <docset lang=3D"default" >
         <example>No Title Found</example>
         <description>This specifies the text to use in search results when=
 no
             title is found in the document itself. If it is set to
             filename, htsearch will use the name of the file itself,
             enclosed in square brackets (e.g. [index.html]).
         </description>
      </docset>
      <docset lang=3D"fr" >
         <example>Aucun titre retrouv=E9</example>
         <description>Ceci sp=E9cifie le texte =E0 utiliser dans les=
 r=E9sultats
              d'une recherche lorsque aucun titre se trouve dedans le=
 document.
              Si on le r=E8gle =E0  filename, htsearch se servira du nom du=
 fichier
              lui-m=EAme, inclus entre crochets (p.ex. [index.html]).
         </description>
      </docset>

    </attribute>

( And no - I don't speak french. I got a friend to do the translation
   for me )

This would then put the capability into the XML file. I would need to
figure out how to do characters like =E9 - possibly as &eacute; . As to

   * how this might then be used to generate documentation
   * how the translated versions will be maintained

are different issues altogether!

Note that it isn't a big change, but I think we should leave
it for version 2 defaults.xml.




>Ciao and thanks,
>-Gabriele

-------------------------
Brian White
Step Two Designs Pty Ltd
Knowledge Management Consultancy, SGML & XML
Phone: +612-93197901
Web:   http://www.steptwo.com.au/
Email: bw...@st...

Content Management Requirements Toolkit
112 CMS requirements, ready to cut-and-paste