CreateDocumentWithCover
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available at: https://www.gnu.org/copyleft/fdl.html.
C O N T E N T S
3 Creating a Document with a Standard Cover Page
3.1 Creating the Document Manually
3.2 Creating the Document Programmatically
4 Creating a Document with a Custom Cover Page
5 Examples
5.1 Document With Cover Page and a Contents
5.2 A More Complicated Document With Cover Page
5.3 More Complicated Document With Cover Page and an Index
5.4 Generating a Document with Cover Pages Under Program Control
5.5 Document with no Cover or Contents
6 Sample Document
6.1 Cover
6.2 Body
6.2.1 Conditionals
6.2.2 Formatting
1 Introduction
In reading this document, Familiarity with the STF Syntax Summary is assumed. (Download document PDF)
This document shows how to create a document with a cover page manually and also using the python API.
It is assumed that Python has been installed, the STF Python API has been installed and STF has been installed. See the installation section of the STF Syntax Summary for details.
2 Document Structure
The structure of a document with a cover page is one or more unnumbered pages, termed cover pages, optionally followed by a table of contents, followed by the document body, optionally followed by an index:
[cover pages]
[Contents]
[document-body]
[index]
3 Creating a Document with a Standard Cover Page
Formatting and document structure commands are entered first. For example, if a list of figures is required in the contents, add .FG T to the preamble.
3.1 Creating the Document Manually
A standard cover page consists of a document title, a document description, and the document generation date. The easiest way to generate a standard cover page is to use the \Setup macro. The setup macro accepts the following arguments:
-
Name -- the document name
-
Document-title -- the top of page title.
-
Description -- a descriptive string. Multiple lines are separated with <TAB> characters.A typical setup macro is as follows:
\Setup{MyDoc,A Better Way to Grow Beets,~<tab><tab><Tab>By<tab><tab><tab>Mortimer Snerd}
The document name is "MyDoc". The top of page title is "A better Way to Grow Beets". The description is "~<tab><tab><Tab>By<tab><tab><tab>Mortimer Snerd". Notice that blank lines in the description are represented as consecutive tabs and that a string of blank lines at the start, starts with a tilde ("~"). That's because extra white space is automatically trimmed off the beginning of the line. The tilde is a forced space character and preserves the leading tabs.
3.2 Creating the Document Programmatically
Doc.setContents is used to control the contents. Doc.setStructure controls the document structure. Doc.createDocument sets the top of page title and Doc.describeDocument defines the document description. The document preamble is written when doc.beginDocument is called. Example:
from stflib import StfDoc |
This creates the same standard cover as the previous example, which looks similar to:
A Better Way to Grow Beets |
4 Creating a Document with a Custom Cover Page
The easiest way to create a document with cover pages is to use the cover macro, as follows:
optional preamble commands |
Where:
-
Optional preamble commands. These are commands that affect the document structure, such as .Chapter or .Class.
-
\Cover{...}. This is the cover macro. The TOC formatting commands are as follows: .CN, .FG, .IX, and .TB. The \Cover macro automatically turns these off, so if they are needed in the document, they must be explicitly turned back on, as in: .TB T, for example. This turns back on the list of tables in the contents, where:
* .CN -- controls generating a contents. For example .CN T enables the contents.
* .FG -- Controls the list of figures in the contents.
* .IX -- controls generating an index
* .TB -- controls generating a list of tables in the contents.
-
Cover pages. These are the desired cover pages. See some of the sample documents (including this one) for examples.
-
\EndCover is the macro that terminates the cover pages. The macro is preferred over the explicit command (.CV F) because it contains conditional horrizontal lines to make HTML and WIKI documents look better.
-
Document body. This the main part of the document containing paragraphs, tables, lists, and figures.
5 Examples
5.1 Document With Cover Page and a Contents
A document with a cover and a contents, but no tables or figures:
\Cover{.CN T} |
This generates a document with a cover page and a contents.
5.2 A More Complicated Document With Cover Page
A document with a cover and a contents, and tables and figures:
\Cover{.CN T, .TB t, .FG T} |
This generates a document with a cover page and a contents with a list of tables and a list of figures.
5.3 More Complicated Document With Cover Page and an Index
A document with a cover and a contents, and tables and figures:
\Cover{.CN T, .TB t, .FG T, .IX t} |
This generates a document with a cover page and a contents with a list of tables and a list of figures and an index.
5.4 Generating a Document with Cover Pages Under Program Control
This is similar to the above examples, only the \Cover and \EndCover macros are inserted into the document using the Verbatim command. doc.beginDocument() is not used when the \Cover macro is used.
from stflib import StfDoc |
5.5 Document with no Cover or Contents
Sometimes it is desired to create a "Headless" document. This is accomplished as follows:
\Cover{}
.CV F
Document-body
Since the \Cover macro turns off the contents, specifying \Cover with no TOC formatting options and using a null cover page, generates a headless document. Notice that .CV F was used rather than \EndCover{} to end the empty cover page. This is because \Endcover includes a horrizontal line separating the cover page from the contents when targeting to HTML or Wiki formats and there is no cover page when using a headless format.
6 Sample Document
Selections from this document are presented as a sample.
6.1 Cover
To begin, shown below is this document's complete cover page:
.setHtmlLocal T |
Notes:
-
.setHtmlLocal T -- declares that local files may be referenced as figures in HTML.
-
.db f,f -- disables all debugging information. The default is .db f,t, which causes the path to all referenced files to be included as comments in the generated file.
-
.sm Date -- makes the date environment variable a macro. Thus it can be referenced as \date{} as well as \Esc{Date}.
6.2 Body
Selections from the rest of this document are shown below:
6.2.1 Conditionals
.hl 1,Introduction |
Notes:
-
The first conditional (.ifc wiki) includes a reference to this document's PDF; this is omitted for all other versions, since it would be redundant.)
-
Notice the use of \href{} instead of \url{}. Href displays text as a hot link, while url displays the link.
6.2.2 Formatting
.hl 1,Document Structure |
Notes:
-
Notice the use of special page headings for LaTeX documents. This is because some of the paragraph titles are too long for the LaTeX formatting employed by this document, so short headings are substituted.
-
Notice how the \fixed{} inline format is used to cover several lines in the document.
The rest of the document is self explainatory (assuming a copy of the STF Syntax Summary is on hand.) Download the STF source to view all the documents and source code.
