[RFR] ddp://manuals.sgml/debiandoc-sgml-doc-pt-br/xml.sgml
Olá colegas,
Segue em anexo a tradução para revisão, juntamente com o original em inglês.
Antecipadamente grato,
--
Marcelo G. Santana(darkstar) GNU/Linux User number #208778
JID:marcelo.santana@jabber.org GNU Privacy Guard ID: 5BECD54C
Blog:Tempestade de Idéias - http://marcelosantana.wordpress.com
Projeto Debian Brasil - http://www.debianbrasil.org
<appendix id="xml">Conversion to XML
<p>
Now debiandoc-sgml package offers conversion to Docbook
XML format for its user to smoothly migrate to the newer
well maintained tool set called Docbook XML.
<p>
This appendix was written by Osamu Aoki (GPL2) in 2005.
<sect>Basic conversion method
<p>
No particular preparation of debiandoc-sgml SGML source is needed
to use the conversion tool <prgn>debiandoc2xml</prgn> .
See <manref section="1" name="debiandoc2xml">.
</p>
<p>
To make a single XML file from valid debiandoc-sgml source, issue
the following commands:
<example>
$ cd path/to/sgml-source-tree/
$ debiandoc2xml -1 foo.sgml
$ cd foo.xml/
$ mv index.xml foo.xml
</example></p>
<p>
The generated XML file is named as <file>index.xml</file> and let's
manually rename as <file>foo.xml</file> for this time.
</p>
<sect>Advanced conversion methods
<p>
In order to make generated file manageable, you may want to have them
split into separate files for each chapter and preserve external
<tt>ENTITY</tt> definitions as separate file. They are quite easy.
<sect1>Split XML file output
<p>
When issuing <prgn>debiandoc2xml</prgn> command, just issue it without
<tt>-1</tt> option in the above example. You get XML files with file
names matching <tt>id</tt> values of <tt>chapt</tt> tags.
The top page is <file>index.xml</file> and it will contain file
inclusion directions.
</p>
<sect1>Preserving external <tt>ENTITY</tt> definitions
<p>
Some SGML sources use external file to manage common information
across the documentation source and maintain good coherence.
Creating this <tt>ENTITY</tt> definitions in a separate file named
<file>default.ent</file> is common practice. It contains entries
such as:
<example>
<!ENTITY debianhome "http://www.debian.org/">
</example>
You probably want to preserve these remote definition after XML
conversion. Following describes how to do this.
<p>
In order to simplify this conversion, you need to simplify
<file>default.ent</file> by removing definition for conditional
switching such as:
<example>
<!ENTITY % q-ref "IGNORE">
</example>
and
<example>
<![%lang-fr;[
<!ENTITY full-title "Guide de référence pour Debian">
<!ENTITY p-debian-reference "debian-reference-fr">
]]>
</example>
<p>
Then, you tweak
<file>default.ent</file> file (assuming files are normally formatted)
as follows:
<example>
$ mv default.ent default.ent.orig
$ egrep "<\![[:space:]]*ENTITY[[:SPACE:]]+" <default.ent.orig | \
perl -p -e \
's/<\!\s*ENTITY\s+([-\w]+)\s.*$/<\!ENTITY $1 "@#@#@#$1#@#@#@">/' \
> default.ent
</example>
This will create alternative entries, which generate reference markers
such as:
<example>
<!ENTITY debianhome "@#@#@#debianhome#@#@#@">
</example>
<p>
Then use this alternative <file>default.ent</file> file for
XML conversion. (You may still modify this to include missing
required definitions such as lines containing "%" in the original
<file>default.ent</file> file.)
<p>
For each generated XML files with this alternative
<file>default.ent</file> file, you recover remote references by
converting markers with:
<example>
$ for i in *.xml ; do \
perl -p -i -e 's/@#@#@#$([\w]+)#@#@#@/\&$1;/g' $i ; \
done
</example>
You need to add specification of including original
<file>default.ent</file> in the header area of <file>foo.xml</file>
XML file at the top again as:
<example>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
<!ENTITY % default SYSTEM "default.ent"> %default;
<!-- more lines here -->
]>
</example>
<sect>Testing generated XML file(s)
<p>
You can test the generated XML file with Emacs and psgml, or nsgmls:
<example>
$ nsgmls -s /usr/share/sgml/declaration/xml.decl foo.xml
</example>
<appendix id="xml">Conversão para XML
<p>
Agora o pacote debiandoc-sgml oferece conversão para o
formato Docbook XML, para que seus usuários migrem sem
problemas para o novo conjunto de ferramentas melhor mantido
chamado Docbook XML.
<p>
Este anexo foi escrito por Osamu Aoki (GPL2) em 2005.
<sect>Método de conversão básico
<p>
Nenhuma preparação particular do fonte debiandoc-sgml SGML é
necessária para usar a ferramenta de conversão <prgn>debiandoc2xml</prgn> .
Veja <manref section="1" name="debiandoc2xml">.
</p>
<p>
Para fazer um único arquivo XML a partir do fonte debiandoc-sgml válido,
emita os seguintes comandos:
<example>
$ cd path/to/sgml-source-tree/
$ debiandoc2xml -1 foo.sgml
$ cd foo.xml/
$ mv index.xml foo.xml
</example></p>
<p>
O arquivo XML gerado é nomeado como <file>index.xml</file> e vamos
renomear manualmente como <file>foo.xml</file> neste momento.
</p>
<sect>Métodos de conversão avançados
<p>
Para tornar o arquivo gerado gerenciável, você pode querer tê-lo
dividido em arquivos separados por cada capítulo e preservar
definições externas <tt>ENTITY</tt> como arquivo separado.
Elas são bastante fáceis.
<sect1>Dividir o arquivo XML de saída
<p>
Quando o comando <prgn>debiandoc2xml</prgn> for emitido, apenas
emita-o sem a opção <tt>-1</tt> no exemplo acima. Você obtém
arquivos XML com nomes correspondentes aos valores <tt>id</tt>
das tags <tt>chapt</tt>.
A página inicial é <file>index.xml</file> e ela conterá direções
de inclusão de arquivo.
</p>
<sect1>Preservando definições externas <tt>ENTITY</tt>
<p>
Alguns fontes SGML usam arquivo externo para gerir a informação
comum em toda a documentação e manter uma boa coerência.
Criar essas definições <tt>ENTITY</tt> em um arquivo separado
chamado <file>default.ent</file> é uma prática comum. Ele contém
entradas tais como:
<example>
<!ENTITY debianhome "http://www.debian.org/">
</example>
Você provavelmente quer preservar essas definições remotas
após a conversão XML. A seguir descrevemos como fazer isso.
<p>
Para simplificar essa conversão, você precisa simplificar
o arquivo <file>default.ent</file> removendo definição para
desvio condicional tal como:
<example>
<!ENTITY % q-ref "IGNORE">
</example>
e
<example>
<![%lang-fr;[
<!ENTITY full-title "Guide de référence pour Debian">
<!ENTITY p-debian-reference "debian-reference-fr">
]]>
</example>
<p>
Então, você ajusta o arquivo <file>default.ent</file> (assumindo
que os arquivos estão normalmente formatados)
como a seguir:
<example>
$ mv default.ent default.ent.orig
$ egrep "<\![[:space:]]*ENTITY[[:SPACE:]]+" <default.ent.orig | \
perl -p -e \
's/<\!\s*ENTITY\s+([-\w]+)\s.*$/<\!ENTITY $1 "@#@#@#$1#@#@#@">/' \
> default.ent
</example>
Isso criará entradas alternativas, que geram marcadores de referência
tais como:
<example>
<!ENTITY debianhome "@#@#@#debianhome#@#@#@">
</example>
<p>
Então use esse arquivo alternativo <file>default.ent</file> para
conversão XML. (Você ainda pode modificá-lo para incluir definições
exigidas que estiverem faltando tais como linhas contendo "%" no
arquivo original <file>default.ent</file>.)
<p>
Para cada arquivo XML gerado com esse arquivo alternativo
<file>default.ent</file> , você recupera referências remotas
através da conversão de marcadores com:
<example>
$ for i in *.xml ; do \
perl -p -i -e 's/@#@#@#$([\w]+)#@#@#@/\&$1;/g' $i ; \
done
</example>
Você precisa adicionar a especificação da inclusão do <file>default.ent</file>
original na área de cabeçalho do arquivo XML <file>foo.xml</file>
no começo novamente como:
<example>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
<!ENTITY % default SYSTEM "default.ent"> %default;
<!-- more lines here -->
]>
</example>
<sect>Testando o(s) arquivo(s) XML gerado(s)
<p>
Você pode testar o arquivo XML gerado com Emacs e psgml, ou nsgmls:
<example>
$ nsgmls -s /usr/share/sgml/declaration/xml.decl foo.xml
</example>
Reply to: