This section describes the general format of a Yodl document.

First of all, a document in the Yodl language needs a em(preamble). This part
of the document must be at the top, and must define the modifiers and the  
document type The modifiers, when present, must appear first.

The modifiers may be, e.g., tt(latexoptions), tt(mailto), tt(affiliation), 
etc.. A very useful modifier is tt(abstract). All modifiers  are listed in 
section ref(modifiers). In general, you should use as many modifiers as 
appropriate; e.g., you should define a tt(mailto) even when you're not 
planning to convert your document to HTML. The reason is twofold: first, you 
might later decide that a HTML version isn't a bad idea after all. Second, 
later versions of the converters might use tt(mailto) even for non-HTML output 
formats.

Following the modifiers, you need to define the document type. This type is
either tt(article), tt(report), tt(book), tt(plainhtml) or tt(manpage).
Except for the tt(manpage) document type, which is described in section 
ref(manpage), the following rules apply:

You should decide on the document type by counting the top-level sectioning 
commands that you need. E.g., if you write an tt(article) with 20 sections, it 
might be a good idea to switch to a tt(report) and group some of the sections 
into chapters. Similarly, a report with 30 chapters might be better off as a 
tt(book) with parts. As a rule of thumb, a document should have no more than 
10 top-level sectionings, and each top-level sectioning should have no more 
than 10 subsectionings, etc..

The document type also affects the way Yodl formats the output. An tt(article) 
(or tt(plainhtml)) leads to one output file; which means under HTML one final 
document. If your article is way too long, then the loading of the HTML 
document will be long too. In HTML output, Yodl splits tt(report)s and 
tt(books) into files that hold the separate chapters. These can then be 
reached via the table of contents. Ergo, the document length can also be 
relevant when you contemplate switching to a tt(report) or tt(book).

If your document uses special macros, then these must be defined bf(before)
they are used. I myself usually define such macros following the preamble.
E.g., see the file tt(doc/yodl.yo) that is distributed with the Yodl package.
This is the main file of this manual and follows the syntax described herein.

To answer em(yes-but-what-if) oriented minds, here are two results of the 
wrong order of text, preamble and modifiers:

itemize(

    it() If you put text before the preamble, i.e., before stating the 
    document type, chances are that Yodl will happily translate the file, but 
    that the following stages will fail. E.g., the tt(<html>) tag would come 
    too late in a HTML conversion, causing the HTML viewer to become confused. 
    Or, the tt(\documentstyle) definition would be seen too late by the LaTeX 
    typesetter.
    
    it() If you put modifiers, such as tt(latexoptions), bf(after) the 
    document type, then the modifiers will have no effect; though Yodl won't 
    complain either. The reason for this is the definition of such modifiers
    will be seen bf(following) the stage where they are needed..
    
)
