Difference between revisions of "Getting Started with XML and ConTeXt using TEXML"
(added links) |
(Changed introduction; added explanations; fixed wrong code) |
||
Line 2: | Line 2: | ||
This document is for XML authors who want to use open source | This document is for XML authors who want to use open source | ||
− | 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 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 | |
− | and | + | the unfamiliar cumbersome and unfamilar syntx 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 pagraphras 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 implements 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 want to convert their documents to | ||
+ | PDF via XSLT 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 the user already has ConTeXt installed | This document assumes that the user already has ConTeXt installed | ||
− | and knows how to use it. | + | and knows 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 conver the ConTeXt examles 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= | =Converting From XML= | ||
Line 45: | Line 69: | ||
TeXML document and immediately know what the author meant to | TeXML document and immediately know what the author meant to | ||
express in ConTeXt. In converting an XML document such as TEI to | express in ConTeXt. In converting an XML document such as TEI to | ||
− | TeXML, one is coming as close as possible to actually | + | TeXML, one is coming as close as possible to actually converting |
to ConTeXt itself, without having to worry about white space, and | to ConTeXt itself, without having to worry about white space, and | ||
while having the comfort of still working with an XML tree. If | while having the comfort of still working with an XML tree. If | ||
Line 52: | Line 76: | ||
you will still think in terms of ConTeXt. | you will still think in terms of ConTeXt. | ||
− | ==Simple Document in ConTeXt and in TeXML== | + | == Simple Document in ConTeXt and in TeXML == |
Here is the simplest ConTeXt document: | Here is the simplest ConTeXt document: | ||
Line 61: | Line 85: | ||
hello world | hello world | ||
\stoptext | \stoptext | ||
+ | |||
</texcode> | </texcode> | ||
− | In TeXML, this looks like: | + | On my system, I issue the command: |
+ | |||
+ | <texcode> | ||
+ | |||
+ | |||
+ | texexec [document_name] | ||
+ | |||
+ | </texcode> | ||
+ | |||
+ | 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: | ||
<pre> | <pre> | ||
Line 71: | Line 110: | ||
<TeXML> | <TeXML> | ||
<env name="text"> | <env name="text"> | ||
− | + | Hello World | |
</env> | </env> | ||
</TeXML> | </TeXML> | ||
Line 77: | Line 116: | ||
</pre> | </pre> | ||
− | + | 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: | |
− | |||
− | + | <pre> | |
− | |||
− | + | texml -e utf8 -c [infile.xml] [outfile.tex] | |
− | + | ||
+ | </pre> | ||
+ | |||
+ | 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 both the ConTeXt and XML document use different | ||
+ | structure, they do share the main text environment. Like all | ||
+ | environments 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 wihout a space. We end this | by the name of the environment wihout a space. We end this | ||
Line 107: | Line 154: | ||
command," which are placed in curly brackets. | command," which are placed in curly brackets. | ||
− | For example, | + | For example, to create a simple document with just one box, |
− | one box, inside of which were the lines "that's it," we write: | + | inside of which were the lines "that's it," we write: |
<texcode> | <texcode> | ||
Line 169: | Line 216: | ||
one in TeXML. | one in TeXML. | ||
+ | =To Do= | ||
− | + | * Include more documentation about TeXML. | |
− | |||
− |
Revision as of 07:44, 8 March 2005
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 unfamiliar cumbersome and unfamilar syntx 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 pagraphras 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 implements 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 want to convert their documents to PDF via XSLT 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 the user already has ConTeXt installed and knows 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 conver the ConTeXt examles 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 lend itself well to a conversion from an XML tree. If an innoncent 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 utlity to the dirty work of handling white space.
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 languge, 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 both the ConTeXt and XML document use different structure, they do share the main text environment. Like all environments 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 wihout 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 addtion, we want to disable as many of ConTeXt's automatic modes as possible, since we will generate things like titles and sections our self. ConTeXt automatically places a number on each page. To turn this feature off, place this line somewhere at the top of your document:
\setuppagenumbering[state=stop]
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.
To Do
- Include more documentation about TeXML.