3. General Usage Instructions

This chapter explains how to start a new document by generating an empty document template and how to convert documents to representational formats from the command line.

3.1. Beginning a New Document

Starting a new document is easy and boils down to (a) choosing a document class and (b) generating a template from which to continue editing.

3.1.1. Choosing a Document Class

When starting a new document, you first have to choose a document class fitting the type of document you intend to write. Document classes are abstractions of typical real-world document types, such as letter, book, newspaper article, etc.

The ecromedos Markup Language provides three document classes: article, book and report. The primary difference between these is how many levels of sections they provide and how they are rendered when generating printable output.

article: The article class is intended for short documents without the need for a glossary or keyword index. On paper, articles are rendered single-sided with an in-page title. Articles offer three section levels through the sectioning elements section, subsection and subsubsection.
book: The book class is for large documents that may contain glossary and keyword indexes. In print, documents are rendered double-sided with a separate title page. This class' top-level sectioning element is the chapter. Chapters start on odd-numbered pages and may be further grouped into parts.
report: A report is essentially the same as a book, but documents are rendered single-sided when generating printable output.

3.1.2. Starting from a Template

When you have decided on which document class you want to use, the recommended way of starting your document is to generate a bare document template. For example, in order to start a new document of type report, open a terminal window and issue the following command:

ecromedos -n report > main.xml

When you open the file main.xml in your editor, you should see something similar to the following listing:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE report SYSTEM
    "http://www.ecromedos.net/dtd/2.0/ecromedos.dtd">
<report lang="en_US" secnumdepth="3" secsplitdepth="1">
        <head>
                <subject>Subject</subject>
                <title>Title</title>
                <author>Author</author>
                <date>Date</date>
                <publisher>Publisher</publisher>
        </head>
        <make-toc depth="3" lof="no" lot="no" lol="no"/>

        ...

        <chapter>
                <title>Chapter Title</title>
                <p>
                First paragraph in first chapter...
                </p>
        </chapter>

        ...

</report>

Even if you are not yet familiar with the ecromedos Markup Language, you should be able to interpret the general structure of the markup. For now, you don't need to know the details. You will dive deeper into document writing in chapter 4.

3.2. Transforming Documents

In order to convert your documents from ecromedos Markup Language to one of the supported output formats, you have to call the ecromedos Document Processor from the command line. The exact procedures are explained in the following subsections.

3.2.1. Producing XHTML Output

The default output format is XHTML. You can change this by modifying the target_format setting in ecmds.conf. In the default installation, to convert a document from ECML to XHTML, you simply have to issue the following command:

ecromedos main.xml

Mind that the output files will be placed into the current working directory. If you don't want the output in the same directory as the source files, simply create an empty folder, change into it and call ecromedos from there:

mkdir spool
cd spool
ecromedos ../main.xml

ecromedos will automatically copy all resources required for viewing the document to the output folder and (when the target format is HTML) adjust the references inside the document accordingly. This means, for example, that even though you can share images between source documents, each instance of a document will be completely self-contained.

After the transformation, load the file index.html into your Web browser to view the results.

3.2.2. Producing PostScript and PDF

If you want to produce a PostScript or PDF version of your document, you will have to generate LaTeX output first. But don't worry, you don't need to know anything about LaTeX. Think of it as an intermediate output format. Use the -f command line switch to tell ecromedos the desired target format:

ecromedos -f latex main.xml

Depending on your setting of secsplitdepth (see section 3.3.2), you will obtain one or more output files with the extension tex. The main TeX-file will be called main.tex In order to compile the LaTeX sources of your document, invoke the LaTeX compiler like this:

latex main.tex

You may have to call LaTeX two or three times until all cross-references are resolved and the table of contents is completely built. The result will be a file with the extension dvi. You can use the following commands to convert the DVI file to PostScript and PDF:

dvips -Ppdf main.dvi
ps2pdf main.ps

The first command will generate PostScript output from the DVI file and the second command will turn the PostScript into PDF. Starting with ecromedos 2.0, you can take advantage of the fact that TeX can produce PDF directly through the pdftex driver. So instead of taking a detour via an intermediate PostScript file, you can instruct ecromedos to produce output that can be compiled with the pdflatex command:

ecromedos -f pdflatex main.xml
pdflatex main.tex

In addition, you can generate output which can be processed with the Unicode-aware XƎTeX using the xelatex command:

ecromedos -f xelatex main.xml
xelatex main.tex

And again, remember that you may have to call LaTeX multiple times before your document is rendered complete.

3.3. Output Options

Even though we are dealing with semantic markup, there are some decisions about the presentation of a document that are left to the author, such as whether the document should have a table of contents or not, whether sections are to be numbered and if so, down to which section level, and so on. The language elements and element attributes that are described below, give you some limited control over these presentational aspects.

3.3.1. Specifying the Document's Language

By setting the lang attribute on the document's root element you can select the language to be used for automatic titles, i.e. section titles that are generated by the document processor automatically, such as “table of contents” or “bibliography”. When generating LaTeX output, this also activates the hyphenation patterns for the specified language.

In ecromedos version 1 you could simply supply the English name of the desired language such as german or english. Starting with version 2, you have to supply an ISO locale identifier such as en_US. This is to better take into consideration regional differences. For example, there are countries that speak the same language but use different scripts.

Currently, ecromedos supports the following language/territory combinations:

Language	Territory	Identifier
English	Canada	en_CA
	Great Britain	en_GB
	New Zealand	en_NZ
	USA	en_US
German	Austria	de_AU
	Germany	de_DE
	Switzerland	de_CH

If you would like to add a new language/terrritory combination, please contact the developers through the mailing list and provide translations for the strings in the English localization catalog located at xslt/i18n/english.xml below the installation folder.

3.3.2. Chunking Into Multiple Files

Set the secsplitdepth attribute on the root element of your document to an integer value between 0 and 5, in order to control down to which section level the document will be chunked into individual files. This is especially useful when generating HTML output. Splitting up large HTML documents into multiple files will improve the user experience, because the document will be easier to navigate, individual parts will load more quickly, and the user's browser doesn't have to keep the entire document in memory, at once.

Here is an example on how it works. When you write a book or report (without making use of the part element), setting secsplitdepth to 1 will result in each chapter being written to a separate file. The level count always starts at zero. So if, one day, you decide to group the chapters into parts, leaving secsplitdepth at 1 means that the document is now split at the parts' level. If you still want each chapter to go to a separate file, you have to increment secsplitdepth to two. If you set secsplitdepth to zero, the entire document will be rendered into a single file.

When generating HTML, the document processor will take care of linking the individual parts together via a navigation bar that will appear at the top and bottom of each output file.

3.3.3. Chapter and Section Numbering

Set the secnumdepth attribute on the document's root element to an integer value between 0 and 5, in order to control down to which section level sections are to be numbered. Setting it to zero will turn section numbers off completely.

3.3.4. Generating a Table of Contents

In previous versions of ecromedos, the generation of the table of contents (TOC) was controlled by setting the root element's tocdepth attribute appropriately. Starting with version 2.0, there is a new language element make-toc for that purpose, which should be inserted right after the document header.

By setting the element's depth attribute to an integer value between 0 and 5, you determine the deepest section level that will be included in the TOC. In addition, you may set either of the attributes lof, lot, lol to yes or no, to toggle whether the TOC should contain a “List of Figures”, “List of Tables” or “List of Listings”, respectively.

3.3.5. Per-Section Overviews

ecromedos has experimental support for per-section overviews. This feature is not extensively tested and has some limitations. In order to generate a mini table of contents for a section, put a make-overview element right at the beginning of the section.

There is one caveat however: LaTeX only supports section overviews for the base sections, i.e. in the book and report classes you can have section overviews for parts and chapters but not for sections and subsections. For HTML this limitation does not exist.

3.3.6. Options Specific to Printable Output

The attributes papersize, bcor and div on the root element are passed through to LaTeX and influence how your document is rendered when producing PostScript and PDF.

The purpose of the papersize attribute should be pretty obvious. Supported values are legalpaper, letterpaper, executivepaper, aXpaper, bXpaper, cXpaper, dXpaper. The default is a4paper which is the standard office paper format used in Germany. You can activate landscreen mode by adding the keyword landscape separated with a comma.

The bcor attribute lets you specify a binding correction. That is the amount in centimeters (cm) or points (pt) by which the text body should be indented to make up for margin space lost when binding the document. For example write bcor="1.5cm" to get a binding correction of 1.5 centimeters.

The div attribute indirectly controls the dimensions of the text body. Its argument is passed through to the LaTeX macro package KOMA-Script which is responsible for layouting the document. KOMA-Script tries to automatically determine the optimal dimensions for the text body by applying a set of typographic rules. To this end, the page is divided into $\text{[math]}$ rectangles of equal size, which serve as the basic units for splitting the page into margins and text body. The greater you choose div, the larger the text area will be. Try values between eight and 16.

Use the parskip attribute to specify the amount of horizontal space to insert in between paragraphs of text. You have the choice between full for a full line, half for half a line (default) or off to have no skip in between paragraphs. In the latter case, the first line of each paragraph will be indented.