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