3. General Usage Instructions

This chapter covers the basics of starting a new document and using the ecromedos command line tool to convert documents to representational formats, also touching on the available output options that allow basic control over how documents are rendered.

3.1. Beginning a New Document

Starting a new document is easy and boils down to

choosing a document class and
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 abstract definitions of typical real-world document types, such as ‘letter’, ‘book’, or ‘newspaper article’.

The ecromedos Markup Language (ECML) provides the three document classes article, book and report. The primary difference between these is how many section levels 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 a glossary and keyword indexes. In print, documents are rendered double-sided with a separate title page. This class introduces the top-level sectioning element 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. In order to do so, open a terminal window and issue the following command:

#> ecromedos -n class > index.xml

Where class should be one of article, book, or report. When you open the file index.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

XHTML is the default output format, unless you modified the corresponding setting in the configuration file. In the default installation, to convert a document from ECML to XHTML, you simply have to issue the following command:

#> ecromedos document

where document is the name of an ECML input file. The output files will be placed into the working directory of the ecromedos command. 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 ../document

ecromedos will copy all resources required for viewing the document to the output folder and, in the case of HTML output, adjust the references inside the transformed document accordingly. This means that even though you can share images, such as logos, between source documents, each representational instance of a document will be completely self-contained.

After 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 L^aT_eX output first. Use the -f command line switch to tell ecromedos the desired target format:

#> ecromedos -f latex document

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 T_eX-file will carry the name of the document class you are using. To compile the L^aT_eX sources of your document, invoke the L^aT_eX compiler like this:

#> latex class.tex

You may have to call L^aT_eX 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 class.dvi
#> ps2pdf class.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 T_eX can produce PDF directly through the pdftex driver. So instead of taking the detour over an intermediate Postscript file, you can instruct ecromedos to produce output that can be compiled with the pdflatex command:

#> ecromedos -f pdflatex document
#> pdflatex class.tex

In addition, there is some preliminary support for generating output that can be processed with the Unicode-aware X_ƎT_eX using the xelatex command:

#> ecromedos -f xelatex document
#> xelatex class.tex

And again, remember that you may have to call L^aT_eX multiple times before the 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 L^aT_eX 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

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 ecromedos Document Processor will take care of linking the document together via a navigation menu that will appear at the top and bottom of each output file, providing for a seamless reading experience.

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.

Section Overviews

There is some preliminary support for per-section overviews. To generate a mini table of contents for a section, simply put a make-overview element right at the beginning of the section. There is one caveat however: L^aT_eX 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.5. Options Specific to Printable Output

The attributes papersize, bcor and div, which may be set on the document's root element, are passed through to L^aT_eX 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 L^aT_eX 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 last case, the first line of each paragraph will be indented.