Difference between revisions of "Getting Started with XML and ConTeXt using TEXML"
m (replace missing links (I hope!)) |
m (Text replacement - "</cmd>" to "}}") |
||
(10 intermediate revisions by 8 users not shown) | |||
Line 4: | Line 4: | ||
software to produce high quality PDF documents--right now. | software to produce high quality PDF documents--right now. | ||
− | One and one half years ago I gave up using | + | One and one half years ago I gave up using LaTeX to format my XML |
documents. I had found--or so I thought--a much superior solution | documents. I had found--or so I thought--a much superior solution | ||
in the Formatting Object language, or FO. FO would allow me to | in the Formatting Object language, or FO. FO would allow me to | ||
create high quality PDF documents in XML and unicode instead of | create high quality PDF documents in XML and unicode instead of | ||
− | the | + | the cumbersome and unfamiliar syntax of TeX. It would |
allowed me to convert from an XML tree to an XML tree, exactly | allowed me to convert from an XML tree to an XML tree, exactly | ||
what an XML author wants. The FO language was established in the | what an XML author wants. The FO language was established in the | ||
Line 20: | Line 20: | ||
the development of FOP. While I could produce basic documents, I | the development of FOP. While I could produce basic documents, I | ||
still couldn't perform other basic formatting needs, such as | still couldn't perform other basic formatting needs, such as | ||
− | controlling widow | + | controlling widow paragraphs or centering a table. Since the |
developers of FOP have made no changes to their software in all | developers of FOP have made no changes to their software in all | ||
this time, I came to the conclusion that I would be stuck with | this time, I came to the conclusion that I would be stuck with | ||
Line 26: | Line 26: | ||
documents. | documents. | ||
− | Thus I turned back to | + | Thus I turned back to TeX, knowing I would face almost none of |
these limitations. I could produce beautiful documents right now, | these limitations. I could produce beautiful documents right now, | ||
without having to wait for an open source FO converter that | without having to wait for an open source FO converter that | ||
− | actually | + | actually implemented all the standards. ConTeXt seemed the most |
− | advanced form of | + | advanced form of TeX, allowing me to format in the most direct |
manner without having to rely on many different macros (or | manner without having to rely on many different macros (or | ||
outside libraries), so I choose it. | outside libraries), so I choose it. | ||
− | If you are an XML author who | + | If you are an XML author who wants to convert your documents to |
− | PDF via XSLT will find this document useful. I try to first | + | PDF via XSLT, you will find this document useful. I try to first |
describe how to do something in FO before explaining how I would | describe how to do something in FO before explaining how I would | ||
do it in ConTeXt, but even if you do not know any FO you should | do it in ConTeXt, but even if you do not know any FO you should | ||
Line 42: | Line 42: | ||
==What You Should Know== | ==What You Should Know== | ||
− | This document assumes that | + | This document assumes that you already have ConTeXt installed |
− | and | + | and know how to use it. If neither is true, take a little bit |
of time and visit the ConTeXt website to get familiar with how to | of time and visit the ConTeXt website to get familiar with how to | ||
run ConTeXt on your system. At the minimum, you should know the | run ConTeXt on your system. At the minimum, you should know the | ||
− | commands to issue to | + | commands to issue to convert the ConTeXt examples here to PDF. You |
don't need to know more than that to get started, though of | don't need to know more than that to get started, though of | ||
course the more you learn, the clearer this document will be. | course the more you learn, the clearer this document will be. | ||
Line 52: | Line 52: | ||
=Converting From XML= | =Converting From XML= | ||
− | Being text-based, ConTeXt does not lend itself well to a | + | Being text-based, ConTeXt does not always lend itself well to a direct |
− | conversion from an XML tree. If an | + | conversion from an XML tree. If an innocent blank line from an |
XML document finds its way into a ConTeXt document, we end up | XML document finds its way into a ConTeXt document, we end up | ||
with an extra paragraph division. One way around this problem is | with an extra paragraph division. One way around this problem is | ||
Line 62: | Line 62: | ||
python utility that converts its own special form of XML into | python utility that converts its own special form of XML into | ||
ConTeXt. That means you can use XSLT to convert from one XML tree | ConTeXt. That means you can use XSLT to convert from one XML tree | ||
− | to another and then let the python | + | to another and then let the python utility do the dirty work of |
− | handling | + | handling whitespace. |
TeXML uses a very simple XML language. Basically, it represents | TeXML uses a very simple XML language. Basically, it represents | ||
Line 73: | Line 73: | ||
while having the comfort of still working with an XML tree. If | while having the comfort of still working with an XML tree. If | ||
you use TeXML to convert, you really won't have to learn a new | you use TeXML to convert, you really won't have to learn a new | ||
− | XML | + | XML language, since TeXML consists of very few elements. Instead, |
you will still think in terms of ConTeXt. | you will still think in terms of ConTeXt. | ||
Line 81: | Line 81: | ||
<texcode> | <texcode> | ||
− | |||
\starttext | \starttext | ||
hello world | hello world | ||
\stoptext | \stoptext | ||
− | |||
− | |||
</texcode> | </texcode> | ||
Line 92: | Line 89: | ||
<texcode> | <texcode> | ||
− | |||
− | |||
texexec [document_name] | texexec [document_name] | ||
− | |||
</texcode> | </texcode> | ||
to produce a formatted document. Along with many other documents, | to produce a formatted document. Along with many other documents, | ||
− | this command prodices a document with the extension "dvi, | + | this command prodices a document with the extension ".dvi", which |
− | I can view with the xdvi software . Follow the instructions to | + | I can view with the xdvi software. Follow the instructions to |
produce other types of output. | produce other types of output. | ||
Line 106: | Line 100: | ||
<pre> | <pre> | ||
− | |||
<?xml version="1.0"?> | <?xml version="1.0"?> | ||
<TeXML> | <TeXML> | ||
Line 113: | Line 106: | ||
</env> | </env> | ||
</TeXML> | </TeXML> | ||
− | |||
</pre> | </pre> | ||
Line 121: | Line 113: | ||
<pre> | <pre> | ||
− | |||
− | |||
texml -e utf8 -c [infile.xml] [outfile.tex] | texml -e utf8 -c [infile.xml] [outfile.tex] | ||
− | |||
</pre> | </pre> | ||
The "-e" option along with its argument of "utf8" tells TeXML to | The "-e" option along with its argument of "utf8" tells TeXML to | ||
produce a document that is encoded in utf8. The "-c" option tells | produce a document that is encoded in utf8. The "-c" option tells | ||
− | TeXML to produce ConTeXt output rather than | + | TeXML to produce ConTeXt output rather than LaTeX. Make sure you |
include both options. | include both options. | ||
− | Although | + | Although ConTeXt and XML documents use different |
− | + | structures, they do share the main text environment. | |
− | + | Like all environments in ConTeXt, this one starts | |
with a backslash followed by the word "start", and then followed | with a backslash followed by the word "start", and then followed | ||
− | by the name of the environment | + | by the name of the environment without a space. We end this |
environment in the same way, replacing "start" with "stop." | environment in the same way, replacing "start" with "stop." | ||
− | In TeXML, we enclose environments with the | + | In TeXML, we enclose environments with the |
− | env</texcode> | + | <texcode> |
+ | env | ||
+ | </texcode> | ||
element. The mandatory "name" attribute defines the environment's | element. The mandatory "name" attribute defines the environment's | ||
Line 158: | Line 149: | ||
<texcode> | <texcode> | ||
− | |||
\starttext | \starttext | ||
\framed[width=2cm,height=1cm]{that's it} | \framed[width=2cm,height=1cm]{that's it} | ||
\stoptext | \stoptext | ||
− | |||
</texcode> | </texcode> | ||
Line 168: | Line 157: | ||
<pre> | <pre> | ||
− | |||
<?xml version="1.0"?> | <?xml version="1.0"?> | ||
<TeXML> | <TeXML> | ||
Line 176: | Line 164: | ||
<opt>width=2cm, height=1cm</opt> | <opt>width=2cm, height=1cm</opt> | ||
<parm>that's it</parm> | <parm>that's it</parm> | ||
+ | }} | ||
</TeXML> | </TeXML> | ||
</env> | </env> | ||
</TeXML> | </TeXML> | ||
− | |||
</pre> | </pre> | ||
Line 189: | Line 177: | ||
<texcode> | <texcode> | ||
− | |||
\enableregime[utf] | \enableregime[utf] | ||
− | |||
</texcode> | </texcode> | ||
Apparently, this allows ConTeXt to handle both utf8 and utf16. | Apparently, this allows ConTeXt to handle both utf8 and utf16. | ||
− | In | + | In addition, we want to disable as many of ConTeXt's automatic |
modes as possible, since we will generate things like titles and | modes as possible, since we will generate things like titles and | ||
− | sections | + | sections ourselves. ConTeXt automatically places a number on each |
− | page. To turn this feature off, place this line somewhere at the | + | page, and starts a new number with each part. To turn this |
− | top of your document: | + | feature off, place this line somewhere at the top of your |
+ | document: | ||
<texcode> | <texcode> | ||
− | + | \setuppagenumbering[state=stop, way=bytext] | |
− | |||
− | \setuppagenumbering[state=stop] | ||
− | |||
</texcode> | </texcode> | ||
Line 215: | Line 199: | ||
Here are two very simple documents, one in plain old ConTeXt, and | Here are two very simple documents, one in plain old ConTeXt, and | ||
one in TeXML. | one in TeXML. | ||
+ | |||
+ | |||
+ | <code>Simple_page.tex</code> | ||
+ | |||
+ | <texcode> | ||
+ | \enableregime[utf] | ||
+ | \setuppagenumbering[state=stop] | ||
+ | |||
+ | \starttext | ||
+ | Wie schön! | ||
+ | \stoptext | ||
+ | </texcode> | ||
+ | |||
+ | and <code>Simple_page.texml</code> | ||
+ | |||
+ | <pre> | ||
+ | <?xml version="1.0"?> | ||
+ | <TeXML> | ||
+ | <!-- | ||
+ | Attributes nl1 and nl2 can be used to force a new line before (nl1) or after (nl2) TeX command. | ||
+ | --> | ||
+ | <cmd name="setuppagenumbering"> | ||
+ | <opt>state=stop, way=bytext</opt> | ||
+ | }} | ||
+ | <cmd name="enableregime" nl1="1"> | ||
+ | <opt>utf</opt> | ||
+ | }} | ||
+ | <env name="text"> | ||
+ | Wie schön! | ||
+ | </env> | ||
+ | </TeXML> | ||
+ | </pre> | ||
=To Do= | =To Do= | ||
Line 220: | Line 236: | ||
* Include more documentation about TeXML. | * Include more documentation about TeXML. | ||
− | [[ | + | [[Category:XML]] |
− | |||
− |
Latest revision as of 13:21, 9 August 2020
Contents
Goal
This document is for XML authors who want to use open source software to produce high quality PDF documents--right now.
One and one half years ago I gave up using LaTeX to format my XML documents. I had found--or so I thought--a much superior solution in the Formatting Object language, or FO. FO would allow me to create high quality PDF documents in XML and unicode instead of the cumbersome and unfamiliar syntax of TeX. It would allowed me to convert from an XML tree to an XML tree, exactly what an XML author wants. The FO language was established in the same manner as HTML and therefore represented the power and acceptance of open source software. The open source tool called FOP, which did the actual conversion from the abstract language to PDF, could already do much of what I wanted for my small needs, such as create simple tables and format paragraphs.
One and one half years passed, however, and nothing changed with the development of FOP. While I could produce basic documents, I still couldn't perform other basic formatting needs, such as controlling widow paragraphs or centering a table. Since the developers of FOP have made no changes to their software in all this time, I came to the conclusion that I would be stuck with limitations if I continued to use FO and FOP to convert my documents.
Thus I turned back to TeX, knowing I would face almost none of these limitations. I could produce beautiful documents right now, without having to wait for an open source FO converter that actually implemented all the standards. ConTeXt seemed the most advanced form of TeX, allowing me to format in the most direct manner without having to rely on many different macros (or outside libraries), so I choose it.
If you are an XML author who wants to convert your documents to PDF via XSLT, you will find this document useful. I try to first describe how to do something in FO before explaining how I would do it in ConTeXt, but even if you do not know any FO you should find the hints about formatting useful.
What You Should Know
This document assumes that you already have ConTeXt installed and know how to use it. If neither is true, take a little bit of time and visit the ConTeXt website to get familiar with how to run ConTeXt on your system. At the minimum, you should know the commands to issue to convert the ConTeXt examples here to PDF. You don't need to know more than that to get started, though of course the more you learn, the clearer this document will be.
Converting From XML
Being text-based, ConTeXt does not always lend itself well to a direct conversion from an XML tree. If an innocent blank line from an XML document finds its way into a ConTeXt document, we end up with an extra paragraph division. One way around this problem is to use ConTeXt's native XML mapping, which you can read about on the ConTeXt home page. I find this mapping scheme too complicated, which is why I advocate using http://getfo.sourceforge.net/texml/index.html TeXML. TeXML is a python utility that converts its own special form of XML into ConTeXt. That means you can use XSLT to convert from one XML tree to another and then let the python utility do the dirty work of handling whitespace.
TeXML uses a very simple XML language. Basically, it represents ConTeXt commands in XML and does little more. One could look at a TeXML document and immediately know what the author meant to express in ConTeXt. In converting an XML document such as TEI to TeXML, one is coming as close as possible to actually converting to ConTeXt itself, without having to worry about white space, and while having the comfort of still working with an XML tree. If you use TeXML to convert, you really won't have to learn a new XML language, since TeXML consists of very few elements. Instead, you will still think in terms of ConTeXt.
Simple Document in ConTeXt and in TeXML
Here is the simplest ConTeXt document:
\starttext hello world \stoptext
On my system, I issue the command:
texexec [document_name]
to produce a formatted document. Along with many other documents, this command prodices a document with the extension ".dvi", which I can view with the xdvi software. Follow the instructions to produce other types of output.
In TeXML, this simple document looks like:
<?xml version="1.0"?> <TeXML> <env name="text"> Hello World </env> </TeXML>
I need to first convert this document to ConTeXt and then issue the same exact commands I used above. It is a two step process. In order to convert the XML to ConTeXt, I issue the command:
texml -e utf8 -c [infile.xml] [outfile.tex]
The "-e" option along with its argument of "utf8" tells TeXML to produce a document that is encoded in utf8. The "-c" option tells TeXML to produce ConTeXt output rather than LaTeX. Make sure you include both options.
Although ConTeXt and XML documents use different structures, they do share the main text environment. Like all environments in ConTeXt, this one starts with a backslash followed by the word "start", and then followed by the name of the environment without a space. We end this environment in the same way, replacing "start" with "stop."
In TeXML, we enclose environments with the
env
element. The mandatory "name" attribute defines the environment's name.
Commands
Aside from environments, we also have commands in ConTeXt. Through commands we control the text formatting in ConTeXt. Commands start with a backslash and can be followed by setups, which are placed in brackets, and by the "scope or range of the command," which are placed in curly brackets.
For example, to create a simple document with just one box, inside of which were the lines "that's it," we write:
\starttext \framed[width=2cm,height=1cm]{that's it} \stoptext
In TeXML, this looks like:
<?xml version="1.0"?> <TeXML> <env name="text"> <TeXML> <cmd name="framed"> <opt>width=2cm, height=1cm</opt> <parm>that's it</parm> }} </TeXML> </env> </TeXML>
Other Preliminaries
In order to makes sure that that our unicoded XML documents get converted properly, we want to put the following line at the top of all our documents:
\enableregime[utf]
Apparently, this allows ConTeXt to handle both utf8 and utf16.
In addition, we want to disable as many of ConTeXt's automatic modes as possible, since we will generate things like titles and sections ourselves. ConTeXt automatically places a number on each page, and starts a new number with each part. To turn this feature off, place this line somewhere at the top of your document:
\setuppagenumbering[state=stop, way=bytext]
We might alter this command in some ways later.
Example Documents
Here are two very simple documents, one in plain old ConTeXt, and one in TeXML.
Simple_page.tex
\enableregime[utf] \setuppagenumbering[state=stop] \starttext Wie schön! \stoptext
and Simple_page.texml
<?xml version="1.0"?> <TeXML> <!-- Attributes nl1 and nl2 can be used to force a new line before (nl1) or after (nl2) TeX command. --> <cmd name="setuppagenumbering"> <opt>state=stop, way=bytext</opt> }} <cmd name="enableregime" nl1="1"> <opt>utf</opt> }} <env name="text"> Wie schön! </env> </TeXML>
To Do
- Include more documentation about TeXML.