1This section describes the general format of a Yodl document.
2
3First of all, a Yodl document needs a em(preamble). This part
4of the document must be at the top, and must define the modifiers and the
5document type. Modifiers, when present, must appear first.
6
7Modifiers are often specific for a particular target document type
8(e.g., tt(latexoptions) or tt(mailto)), but may also have a general nature
9(e.g., tt(affiliation) or tt(abstract)). All modifiers are used to modify
10parameters of document types. Therefore, they must be specified before the
11document type is defined.
12
13All modifiers are listed in section ref(MODIFIERS). In general, you should use
14as many modifiers as appropriate. E.g., you should define a tt(mailto) even
15when you're not planning to convert your document to HTML. The reason is
16twofold: first, you might later decide that a HTML version isn't a bad idea
17after all. Second, later versions of the converters might use tt(mailto) even
18for non-HTML output formats.
19
20Following the modifiers, the em(document type) is defined. The document type
21is either tt(article), tt(report), tt(book), tt(plainhtml) or tt(manpage).
22Except for the tt(manpage) document type, which is a highly specialized
23document type, described in section ref(MANPAGE), the following rules apply:
24
25A decision about the document type to use should be based on its
26complexity. If the document's organization becomes too complex, it is probably
27a good idea to use a document type supporting a more complex
28organization. E.g., a complex em(article) might be written as an accessible
29em(report), combining related sections into chapters. Similarly, the structure
30of a report having 30 chapters might improve when it's re-organized as a
31em(book) having parts. To offer a rule of thumb: a document should have no
32more than approximately ten top-level sections, and each top-level sectioning
33should have no more than approximately ten subsections, etc..
34
35The document type influences the way Yodl formats the output. An tt(article)
36(or tt(plainhtml)) results in one output file. E.g., one final document when
37converting to HTML. If your article is way too long, then the loading of the
38HTML document will also take much time. When converting to HTML, Yodl splits
39tt(report)s and tt(books) into files each holding a chapter. These can be
40accessed through the table of contents. So, the document length can also be
41relevant when you contemplate switching to a tt(report) or tt(book).
42
43Documents using special macros, must have defined these macros em(before) they
44are used. An appropriate location for these macros is immediately beyond the
45preamble.  E.g., see the file tt(Documentation/manual/manual.yo) distributed
46with the Yodl package.  This is the main file of this manual, showing the
47preferred organization of Yodl files.
48
49To answer em(yes-but-what-if) oriented minds, here are two results of the
50wrong order of text, preamble and modifiers:
51    itemization(
52    it() If you put text before the preamble, i.e., before stating the
53document type, chances are that Yodl will happily translate the file, but
54subsequent states will probably fail. E.g., the tt(<html>) tag would come too
55late in a HTML conversion, causing the HTML browser to become confused.  Or,
56the tt(\documentstyle) definition would be seen too late by the LaTeX
57typesetter.
58    it() If you put modifiers, such as tt(latexoptions), em(beyond) the
59document type, then the modifiers will have no effect; though Yodl won't
60complain either. The reason for this is the definition of such modifiers will
61be seen bf(following) the stage where they are needed..
62    )
63
64