Skip site navigation (1)Skip section navigation (2) 
Date:      Fri, 4 Jan 2002 21:50:18 -0200
From:      Mario Sergio Fujikawa Ferreira <lioux@FreeBSD.org>
To:        doc@FreeBSD.org
Cc:        Jose Porfirio <poool@terra.com.br>, Roberto Cantanhede <robertoc@yawl.com.br>
Subject:   Generating 2 file versions of the same info (xml+glossary related)
Message-ID:  <20020104235040.35646.qmail@exxodus.fedaykin.here>
index | next in thread | raw e-mail 

Hi,

	I wrote a short glossary I use for the translation effort
from English to Brazilian Portuguese of the FreeBSD documentation.
We (the translant are about to finish a couple chapters from the Handbook.
	I wanted to add this glossary to the translated documentation.
This glossary would be for the whole translated documentation not
only for a particular part (e.g., handbook).

	Therefore, I was thinking about adding it as
pt_BR.ISO8859-1/share/sgml/glossary.sgml with an appropriate entry
to pt_BR.ISO8859-1/share/sgml/bookinfo.ent.

	For instance,

<glossary id="glossary">
  <glossdiv><title>A</title>
    <glossentry id="authored">
      <glossterm>authored</glossterm>
  
      <glossdef>
        <para>escrito</para>
      </glossdef>
    </glossentry>
  </glossdiv>

  <glossdiv><title>B</title>
    <glossentry id="backward-compatible">
      <glossterm>backward-compatible</glossterm>
  
      <glossdef>
        <para>compat&iacute;vel de forma regressa</para>
      </glossdef>
    </glossentry>
  </glossdiv>

  <glossdiv><title>S</title>
    <glossentry id="set">
      <glossterm>set</glossterm>
  
      <glossdef>
        <para>ajustar; atribuir</para>
      </glossdef>
    </glossentry>
  </glossdiv>
</glossary>

gives entries for both authored, backward-compatible and set.

	All documents in the pt_BR.ISO8859-1 would have pointers to
the glossary.

	So, I have an English to Brazilian Portuguese which helps both
readers and translators since they can try to understand how things
were translated. This is important because many english words have a clear
context due to their open use in Computer related literature. However, no such
semantic background may exist for their translated counterparts.

	Nevertheless, what about users trying to understand
"compat&iacute;vel de forma regressa"? They may clearly understand
backward-compatible but completely miss "compat&iacute;vel de forma
regressa". Where the hell did that come from? :)
	That's where a Brazilian Portuguese to English glossary is
most helpful.

	The English to Brazilian Portuguese glossary above translated
to a Brazilian Portuguese to English one:

<glossary id="glossary">
  <glossdiv><title>A</title>
    <glossentry id="ajustar">
      <glossterm>ajustar</glossterm>
  
      <glossdef>
        <para>set</para>

        <glossseealso otherterm="atribuir">atribuir</glossseealso>
      </glossdef>
    </glossentry>

    <glossentry id="atribuir">
      <glossterm>atribuir</glossterm>
  
      <glossdef>
        <para>set</para>

        <glossseealso otherterm="ajustar">ajustar</glossseealso>
      </glossdef>
    </glossentry>
  </glossdiv>

  <glossdiv><title>C</title>
    <glossentry id="compativel--de--forma--regressa">
      <glossterm>compat&iacute;vel de forma regressa</glossterm>
  
      <glossdef>
        <para>backward-compatible</para>
      </glossdef>
    </glossentry>
  </glossdiv>

  <glossdiv><title>E</title>
    <glossentry id="escrito">
      <glossterm>escrito</glossterm>
  
      <glossdef>
        <para>authored</para>
      </glossdef>
    </glossentry>
  </glossdiv>
</glossary>

	As you can see, "set" became 2 entries ("ajustar" and
"atribuir") parsed by the ';' separator with appropriate <glossseealso
...></glossseealso> entries. Furthermore, the glossdef "compat&iacute;vel
de forma regressa" became id "compativel--de--forma--regressa", for
id only accepts alphanumeric and dash ("-") characters.
	As you can see, there are good reasons to have both files.
Moreover, we can have the words point to their glossary entries
which helps a lot. Furthermore, we could add "dictionary definitions"
(written by the users, not taken from actual dictinaries due to
Copyright issues) to some entries.

  <glossdiv><title>C</title>
    <glossentry id="compativel--de--forma--regressa">
      <glossterm>compat&iacute;vel de forma regressa</glossterm>
  
      <glossdef>
        <para>backward-compatible, compatible with previous versions</para>
      </glossdef>
    </glossentry>
  </glossdiv>

	These 2 files can be easily generated from a well delimited
file

authored|escrito
set|ajustar|atribuir
backward-compatible|compat&iacute;vel de forma regressa

using a perl script.

	Nonetheless, we have xml tools in the doc system. And, this is
a prime candidate for a xml parsing tool. It could automagically
generate both files from a xml file. I know this is possible and,
hopefully, not difficult but I lack the knowledge to do it.
	Anyone volunteers? Nik?

	This would be a huge improvement for the translating teams.
And, to the english documentation itself since we could begin using
glossary dictionary definitions to clarify some texts.

	Regards,

-- 
Mario S F Ferreira - DF - Brazil - "I guess this is a signature."
Computer Science Undergraduate | FreeBSD Committer | CS Developer
flames to beloved devnull@someotherworldbeloworabove.org
feature, n: a documented bug | bug, n: an undocumented feature

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
help

Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020104235040.35646.qmail>