STFLibraryDescription

bstanly

STF Library

  Author: Barry Stanly Copyright 2015 by Barry Stanly Printed on: June 25, 2017

C O N T E N T S

1 Introduction

2 Document Preamble
2.1 createDocument
2.2 describeDocument
2.3 endDocument
2.4 documentClass
2.5 setContents
2.6 setStructure
2.7 preambleComplete
2.8 endPreamble
2.9 beginDocument

3 Document Body
3.1 startCoverPage
3.2 endCoverPage
3.3 addToIndex
3.4 changeOutputFile
3.5 comment
3.6 copyFile
3.7 createTable
3.8 endList
3.9 endTable
3.10 footnote
3.11 includeFile
3.12 insertFigure
3.13 insertFile
3.14 InternalComment
3.15 listElement
3.16 paragraph
3.17 putLines
3.18 putVerbatim
3.19 setAutoWrap
3.20 setParagraphBias
3.21 startAppendicies
3.22 startList
3.23 tableRow
3.24 unnumberedParagraph
3.25 getLabel

4 Inline Formatting

T A B L E S

Table 2.4-I Document Classes
Table 4-I Inline Formatting Commands

1 Introduction

In reading this document, Familiarity with the STF Syntax Summary is assumed.

This document describes the Python library interface to the Simple Text Formatter (STF) automated documentation system.

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.
For more information, see the STF Syntax Summary


2 Document Preamble

The preamble is the first section of an input file, before the text of the document itself, where document customization takes place.


2.1 createDocument

Create an STF document, Arguments:

  1. Name -- Document name, used for documentation purposes

  2. Title -- Document title, appears at top. If omitted, a default is used.Example:
    from stflib import StfDoc
    self.doc = StfDoc("MyDoc")
    self.doc.createDocument("Mydoc","This is a good doc")


2.2 describeDocument

Set document description, Argument: Description

Multiple lines are separated with <tab> characters.
Example: self.doc.describeDocument("Title\t\t\tAuthor: Freddie")


2.3 endDocument

End the document, arguments: None
Closes the output file. Normally endDocument is optional, but it is required if the output file is to be processesd while the generating script is still active when STFXlate is invoked.


2.4 documentClass

Set document class, Argument: documentClass
Recognized classes are:

Table 2.4-I Document Classes

Class

Description

HTML

article

This is the default and most common document class

N

extarticle

Same as article but with extended font size support

N

report

This is similar to an article, except the first paragraph level is named "Chapter"

N

extreport

Same as report but with extended font size support

N

book

This is similar to a report, except books use double sided output

N

manual

This is a flag that indicates that the author will supply the LaTeX or HTML preamble

Y

HTML ignores all document classes, except for manual.
Example: self.doc.documentClass(article)


2.5 setContents

Define TOC, Arguments:

  1. Contents=True -- True means to create a TOC, default True, optional.

  2. Figures=True -- True means to include list of figures, default True, optional.

  3. Index=True -- True means to include an index at end of document, default True, optional.

  4. Tables=True -- True means to include list of tables, default True, optional.

  5. Appendix=False -- True means to include support for appendicies, default False, optional.Example: self.doc.setContents(Figures=False, Index=False)


2.6 setStructure

Adjust document defaults, Arguments:

  1. Chapters=False -- True overrides defaults. Normally Chapter is controlled by document class. Setting Chapters to True indicates a manual document class that uses a first paragraph of 'Chapter'. Optional, default=False.

  2. HTML_Local=True -- False specifies that, in expanding to HTML, referenced files are to be automatically prefaced with: "file://". Optional, default=True.

  3. DebugFiles=False -- True specifies to include file names as comments. Optional, default=False.

  4. FirstListAlphabetic=True -- False specifies lists expand as 1.a.A.a), True, the default, specifies lists expand as a.1.A.a). Optional.

  5. TableXref=True -- False disables cross references in tables. This is useful when targeting to RTF format. Optional, default=True.

  6. FrontMatter = True, the default supports a contents and an index. To use a cover page, set FrontMatter to false and enable the parts of the TOC desired (if any)explicitly. Optional, default=True.
    Example: self.doc.setStructure(FirstListAlphabetic=False)


2.7 preambleComplete

Specifies the end of the first half of the LaTeX preamble, Arguments: None
After preamble complete, LaTeX use package directives may be
inserted in the document command stream.

Preamble complete causes the first part of the document preamble
to be written.
This command is not used unless it is necessary to modify the
LaTeX packages in use or to add to the LaTeX configuration.
Example:
self.doc.preambleComplete()
self.doc.putVerbatim("\\usepackage{pdflscape}")


2.8 endPreamble

Specifies the end of the second half of the LaTeX preamble, Arguments: None.
After end preamble, LaTeX packages are configured.

EndPreamble causes the second part of the document preamble
to be written.
This command is not used unless it is necessary to modify the
LaTeX packages in use or to add to the LaTeX configuration.
Example:
self.doc.endPreamble()
self.doc.putVerbatim("\\pagenumbering{roman})"


2.9 beginDocument

Begin document -- ends preamble and starts the document, Arguments: None
Example: self.doc.beginDocument()


3 Document Body

The document body contains the text to be formatted.


3.1 startCoverPage

Begin cover page(s)
Cover pages are incompatible with describeDocument -- use one or the other.
If used, startCoverPage must be the first command after beginDocument. See 2.6.
Example: self.doc.startCoverPage()...


3.2 endCoverPage

End cover page(s). Cover pages are incompatible with describeDocument -- use one or the other.
Example: self.doc.endCoverPage()


3.3 addToIndex

Add item to index, Argument: item
Example: self.doc.addToIndex("item-of-interest")


3.4 changeOutputFile

Arguments:

  1. NewFile -- string containing path of the file to be opened.

  2. Append -- Boolean, True specifies to append to NewFile rather than to replace it, default: False.If NewFile equals "", then switch back to the previous output file; otherwise change to outputting to NewFile.
    Output files may be nested.


3.5 comment

Output comment block, multiple lines are separated with <tab> or <nl>, Argument: text string. Comments are ignored in noWrap mode, i.e. in NoWrap mode comments are not inserted into the document.
Example: self.doc.comment("\tWhoa look at that\t")


3.6 copyFile

Arguments: path -- path of filename
Copy file with minimal editing into document
Example: self.doc.copyFile("path")


3.7 createTable

All open lists are automatically closed:
Arguments:

  1. Caption -- Title of the table. Required.

  2. Header -- A one line column header. Columns are separated by tabs. Required.

  3. ColumnSpec='' -- Optional string that specifies column formatting. If omitted, column sizes are taken from the header, notes:

   * If ColumnSpec is omitted, it is inferred from the column lengths in the Header.

   * Spec: |Col|col|...

   * Col: l,r,c,p{}

   * p{}: p{length}

   * Sample ColumnSpec: |l|p{4.0in}|r| = 3 columns formatted as: justify left, size of 4 inches, justify right

  1. Long=True -- Specifies whether the table can span pages or not. False means short. Short tables may be repositioned to minimize white space. Optional, default True.

  2. Label='' -- Specifies an alphanumeric label with which to reference to the table. Specifying an asterisk ("*") causes a label to be generated and returned. Optional, default an empty string.Return: Label that can be used to refer to the table.
    Examples:

  3. self.doc.createTable("List of farbles", "Farble\tDescription            ") --Creates a table with the column lengths taken from the description. Both columns will wrap to stay within bounds.

  4. self.doc.createTable("List of farbles", "Farble\tDescription","|l|p{4in}|)" -- creates a table with two columns. The first column is left justified and will expand as necessary to hold the data, the second column wraps at four inches.

  5. MyLabel = self.doc.createTable("List of farbles", "Farble\tDescription            ", Long=False,Label="*") - Similar to the first example, but LaTeX may reposition the table in the document to reduce extra white space and "MyLabel" may be used to refer to the table in a reference later in the document; as in:
    self.Doc.Putlines("See table \\ref{" + MyLabel + ",Page}).


3.8 endList

Arguments: None
End a list (enumerated or bullet).
Example: self.doc.endList()


3.9 endTable

Arguments: None
End an active table.
Example: self.doc.endTable()


3.10 footnote

Output a footnote, arguments: String
Example:

self.doc.putLines("blah blah",Eol=False)
self.doc.footnote("notice that blah blah")
self.doc.putLines(" rest of line blah blah")


3.11 includeFile

Insert STF file in document stream with normal interpreting. Include files may be nested.
Arguments:

  1. File -- Path of file to be interpreted

  2. POD=False -- True - file is in Perl POD format; False, file is in STF format.

  3. Bias=0 -- Paragraph level bias.

  4. Labels='' -- List of labels to be activated for the fileExample: self.doc.includeFile(MyFile.stf)


3.12 insertFigure

Insert a Figure, Arguments:

  1. File -- path to figure.Typical extensions: jpg, jpeg, gif, png, bmp

  2. Caption -- the figure title.

  3. Label -- label - optional user specified label to refer to the table.Specifying "*" causes a label to be generated and returned.
    Return: Label that can be used to refer to the table.
    Esample:
    self.doc.includeFile(MyFile.stf)


3.13 insertFile

Insert file in document stream with no editing. File must be compatible with the final target (HTML, LaTeX, RTF, etc.)
Example:
.IFC HTML
self.doc.insertFile(MyFile.html)
.Endc
.ifc Latex | RTF
self.doc.insertFile(MyFile.tex)
.Endc


3.14 InternalComment

Output internal comment block, lines separated with <tab> or <nl>, Arguments: String
Example:
self.doc.InternalComment("Notice the blah format \t use this form for ...")


3.15 listElement

Add an item to a list, Argument: String
Example:
self.doc.listElement("Item")


3.16 paragraph

Start a paragraph, Arguments:

  1. Level -- Paragraph level, 1..9 for chaptered documents, 1..8 otherwise.

  2. Header -- Paragraph header (goes in contents)

  3. Label -- Optional label to refer to paragraph.Specifying "*" causes a label to be generated and returned.
    Return: Label to refer to paragraph
    Examples:
    self.doc.paragraph(1,"title")
    refer = self.doc.paragraph(1,"title","*")
    self.doc.putLines("See paragraph \\ref{" + refer + ",page}.")


3.17 putLines

Output a set of lines separated by <tab> or <nl>, Arguments:

  1. String -- a string containing one or more lines to be output.

  2. Tabs=True -- A boolean specifying whether tabs are to be interpreted as a new line or not. Optional, default=True.

  3. Eol -- A boolean specifying to end the line with a <NL>, default=True.A leading period is escaped.
    A blank line starts a new block paragraph.
    Inline commands are recognized, depending on the parse level.
    Examples:
    self.doc.putLines("Line1\tline2\t...")
    self.doc.putLines("Line", Eol=False, Tabs=False)


3.18 putVerbatim

Output literal line, Arguments:

  1. String - string to be output.

  2. Eol -- boolean specifying to terminate string with <NL>, default=True.Examples:
    self.doc.putVerbatim("Line")
    self.doc.putVerbatim("Line",Eol=False)


3.19 setAutoWrap

Enable/disable auto wrap, Argument Boolean
Example: self.doc.setAutoWrap(True)


3.20 setParagraphBias

Automatically bias the paragraph level. For example if Bias=1, specifying a level of one is interpreted as paragraph level 2. See the syntax summary for more information, arguments: integer
Example: self.doc.setParagraphBias(1)


3.21 startAppendicies

Assuming appendicies are enabled, start appendicies, Arguments: None
self.doc.startAppendicies()


3.22 startList

Begin an enumerated or a bullet list, Argument: Boolean
Bullet = True, begin a bullet list; Bullet = False, the default, begin an enumerated list.

Bullet lists have two nesting levels, enumerated lists have four.
Examples:
self.doc.startList() -- Start an alphabetic list.
self.doc.startList(Bullet=False) -- Start an alphabetic list.
self.doc.startList(True) -- Start a bullet list.
self.doc.startList(Bullet=True) -- Start a bullet list.


3.23 tableRow

Insert a row in an active table, Argument: String
Columns separated by <tab> characters, example:
self.doc.tableRow("Column1\tColumn2) -- inserts a row in a two column table.


3.24 unnumberedParagraph

Start an unnumbered paragraph, Arguments:

  1. Level -- Paragraph level, 1..9 for chaptered documents, 1..8 otherwise. Level sets the header font style to correspond to the numbered paragraph font style. Required.

  2. Header -- Paragraph header (does not go in contents.) Required.

  3. Label -- Optional label to refer to paragraph.Specifying "*" causes a label to be generated and returned.

Return label to refer to paragraph, example:
self.doc.unnumberedParagraph(2,"Notice that ...")


3.25 getLabel

Return a label. The label may be used to refer to structures with in the document, arguments: None
Example:

MyLabel = self.doc.getLabel()
self.doc.paragraph(1, "Now is the time", Label=MyLabel)
...
self.doc.paragraph("See paragraph \ref{" + MyLabel + ",Page}.")


4 Inline Formatting

The following formatting options are available as inline commands. See the Syntax Summary for more information. They may be embedded in an output line or specified separately.

Table 4-I Inline Formatting Commands

Command

Action

\bold{string}

specifies to bold the string. This construct may span lines.

\both{string}

specifies to bold and italicize the string. This construct may span lines.

\fixed{string}

specifies to use a fixed spaced font. This construct may span lines.

\href{url,text}

specifies an external link, except only the 'text' is displayed in the document.

\italics{string}

specifies to italicize the string. This construct may span lines

\norm{string}

specifies to use the default (proportional) font. This construct may span lines. Note: Closing the current \fixed{} inline command will also revert to the normal font.

\ref{label, [page]}

specifies a reference to an internal label. If "page" is specified, then the reference is of the form 'label on page', otherwise it is of the form 'label', where 'label' represents the paragraph, table, or figure number. RTF, PDF and HTML format files support internal links. This construct cannot span lines.

\und{string}

specifies to underline the string. This construct may span lines.

\url{url}

specifies an external link. RTF, PDF and HTML format files support external links. This construct cannot span lines.

The following examples will both output: Now is the time for all:

self.doc.putLines("Now is the \\bold{time} for all")

self.doc.putLines("Now is the",Eol=False)
self.doc.bold("time")
self.doc.putLines(" for all")

Related

Wiki: DocumationMagic