STFXLateSummary

 
 
 
 

STF Syntax Summary

 
 
 

How to use Simple Text Format for Automated Documentation

 
 
 
 
 

by

 
 

Barry Stanly Printed on August 28, 2022 Copyright 2015 by Barry Stanly

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 Nuances In Computing Hosted at https://sourceforge.net/p/simpletextformatter Download document PDF

---

C O N T E N T S

1 Introduction
1.1 Basic Use
1.2 Case Study
1.2.1 Inputs
1.2.2 Outputs
1.3 Documentation

2 Command Summary

3 Command Aliases

4 Inline Commands

5 Generating Output
5.1 Label Hierarchy
5.2 Generating PDF Output
5.3 Generating HTML Output
5.4 Generating Wiki Output
5.5 Generating RTF Output
5.6 Generating Text Output
5.7 Working with DocBook
5.8 Processing POD Files
5.9 Generating Epub Format Files
5.10 STFXlate Switches
5.11 Convenience Commands

6 Special Characters
6.1 Notes
6.2 Parse Level
6.3 Working With Foreign Text Files

7 Syntax Description
7.1 AI -- Auto Image Size
7.2 AP -- Include support for appendices
7.3 AR -- Add to following row
7.4 AX -- Enable appendices
7.5 AW -- Set auto wrap
7.6 BD -- Begin Document
7.7 BI -- Set paragraph Bias
7.8 BK -- Set Line Break
7.9 CH -- Use Chapters
7.10 CN -- Table of Contents Required
7.11 CO -- Comment
7.12 CM -- Command
7.13 CP -- Copy File
7.14 CV -- Start and End Cover Page(s)
7.15 DB -- Enable debug
7.16 DC -- Create Document
7.17 DE -- Describe Document
7.18 DL -- Debug Line
7.19 DS -- Dump State
7.20 DT -- Document-class
7.21 EF -- Soft End of File
7.22 EL -- End List
7.23 EP -- End Preamble
7.24 FG -- Use Figures
7.25 FQ -- Filter Quotes
7.26 FM -- Front Matter
7.27 FS -- Set Font Size
7.28 HF -- SetHTMLLocalFigures
7.29 HL -- Header Level
7.30 IE -- Insert Figure
7.31 IF -- Include File
7.32 IN -- Insert File
7.33 ... -- Internal Comment
7.34 IX -- Generate an index
7.35 LE -- List Element
7.36 LL -- Labeled List Element
7.37 LS -- List Start
7.38 NP -- No Operation
7.39 OF -- Change output file
7.40 PC -- Preamble Complete
7.41 PD -- POD Format
7.42 Working with Perl POD Format Files
7.42.1 POD Inline Formatting Codes
7.42.2 POD Character Escapes
7.42.3 POD Commands
7.42.4 STF POD Support
7.43 PE -- End paragraph commands
7.44 PL -- Put Line
7.45 PP -- Start Paragraph
7.46 PS -- Start paragraph commands
7.47 PT -- Put Table of Contents
7.48 PU -- Push command
7.49 RP -- Replace String in Symbol
7.50 SC -- Set Contents Starting Number
7.51 SD -- SetLandscape
7.52 SE -- Set Escape
7.53 SF -- Set Figure size
7.53.1 Scale Factor Operands
7.53.2 Scale Factor Codes
7.53.3 Scale Factor Specifications
7.54 SN -- Set No RTF References
7.55 SL -- Set List Order
7.56 SM -- Set Macro
7.57 SP -- Set Parse Level
7.58 SQ -- Set Paragraph Level
7.59 SU -- Substitute
7.60 SV -- Save Variables
7.61 SX -- Set Expression
7.62 TB -- Include List of Tables in TOC
7.63 TC -- Table Caption
7.64 TE -- Table End
7.65 TH -- Longtable header
7.66 TP -- Table separator character
7.67 TR -- Table Row
7.68 TS -- Table Start
7.69 TX -- Set Text Tag
7.70 UF -- Set Unwrapped Font Size
7.71 UP -- Define Unnumbered Paragraph
7.72 VB -- Verbatim String
7.73 WK -- Control Wiki Output Format
7.74 WR -- Control line wrapping
7.75 XE -- Execute Command
7.76 XX -- Add to Index
7.77 YA -- Activate Conditional(s)
7.78 YE -- End Conditional
7.79 YF -- Final Condition
7.80 YL -- Alternate Conditional
7.81 YS -- Start Condition

8 Including Foreign Files

9 STF Internals
9.1 Creating Documents
9.1.1 Alternatives to .BeginDocument
9.1.1.1 The Cover macro
9.1.1.2 The EndCover Macro
9.1.1.3 The Setup Macro
9.2 Internal Stacks
9.3 STF Macros
9.3.1 Types of Macros
9.3.2 Macro Syntax
9.3.3 Defining Replacement Macros
9.3.4 Defining Inline Macros
9.3.5 Defining Keyword Macros
9.3.6 Macro Examples
9.3.7 Macro Usage
9.3.8 Adding commands to Include Files
9.3.9 Landscape Support
9.4 Predefined Symbols
9.5 Lists
9.5.10 List Example
9.6 Working With Symbols
9.7 Generating an Index

10 References
10.1 Internal References

A P P E N D I C E S

A Debugging
A.1 Pitfalls and Hints
A.2 Spell Checking
A.3 Debugging Macros

B Installation
B.1 Installing Python
B.2 Installing the Rest of the Software
B.3 Updating the Registry
B.3.1 Updating the Path
B.3.2 Convenience Associations
B.3.3 Typical Use
B.3.4 Included Files
B.4 Installing Under UNIX/Linux

C Standard Macros

Index

T A B L E S

Table 2-I Command Summary
Table 3-I Alias Summary
Table 5.1-I Command Line Switches and Their Corresponding Labels
Table 5.10-II STFXlate Command Line Switches
Table 5.11-III Convenience Commands
Table 6-I Special Characters
Table 6.2-II Parse Level
Table 7.12-II Command Examples
Table 7.3-I AddRow Example
Table 7.65-III Sample Table
Table 7.70-IV Unwrapped Font Sizes
Table 7.73-V Wiki Format Codes
Table 9.4-I Predefined Symbols
Table 9.6-II Kinds of Symbols
Table B-I Typical STFXlate Installation
Table B.3.2-II STF File Associations
Table B.3.4-III Included Files
Table C-I Standard STF Macros

F I G U R E S

Figure 1-1 Document Generation Process
Figure B.3.2-2 File Associations Menu

---

1 Introduction

STF is a system of automatically generating documentation under control of a program or a script. It is frequently used to automatically generate test reports. STF is also used to clean up the output of a process and turn it into a nice looking report.

The method described herein consists of several steps (see figure 1-1):

1. Generate -- A program or script writes a meta file containing the desired content of the report including the formatting desired. This is done by passing the content to be written to library routines that save the content in the meta file. The programmer concentrates on the data to be incorporated in the report and lets the library handle the details.

2. Translate -- The meta file is processed by a translator that translates the data to either an HTML file, a Wiki file, or a LaTeX file.

3. Format -- The LaTeX file is processed by a member of LaTeX's program suite and converted to one of the following document formats:

   a. PDF -- pdflatex is used to produce a PDF report.

   b. HTML -- this is directly produced by the translator and requires no further processing.

   c. RTF -- latex2rt is used to produce an RTF format file suitable for inclusion in a word processor.

   d. Wiki -- this is directly produced by the translator and requires no further processing other than uploading to a Wiki site.

   e. Text -- the STF translator can produce a text file suitable for parsing by a script or program. For example, Acronym⁽¹⁾ may be used to extract a candidate list of acronyms. LyX may be used to operate on the LaTeX file if a formatted text file is desired.

   f. Document Translators -- LyX can be used to export LaTeX to DocBook; also LibreOffice and OpenOffice may be used to export HTML to DocBook. There is also a generalized document converter, Pandoc, that can be used to convert between LaTeX, HTML, Wiki format, and Docbook. Details may be found at: http://pandoc.org.

   g. E-Book -- Calibre can be used to convert the HTML output to various e-book formats. See http://www.calibre-ebook.com for more information. It is interesting to note that modern e-book PDF readers implement text reflow and scaling, so that there is little advantage to an e-book format for reports. Particularly since reports at times depend on text alignment which the PDF format maintains and the e-book format does not.

Figure 1-1 Document Generation Process

The library outputs text in Simple Text Format (STF) and STFXlate is then used to translate the STF formatted text to either LaTeX, HTML, or Wiki. The meta file format is described first. Normally this is not needed by a programmer writing reports. Instead a library API document is provided for each language used to generate STF format files.

STF documents may also be written by hand. For example this document is written in STF. The document source is included with the STF distribution, see Appendix B for installation instructions.

1.1 Basic Use

The typical way a document is generated is for a program (or script) to call the STF library and pass it the name of a new document and any global formatting options. typically this would look like Doc = new Document("MyDoc", "Test Results","Integration Test of Farble System"). This creates a new document with the file name "MyDoc.stf", a title of "Test Results", and a document description of "Integration Test of Farble System". The corresponding STF commands (described later) inserted into the document are:

.CreateDocument MyDoc,Test Results
.DescribeDocument Integration Test of Farble System
.BeginDocument

Frequently a boilerplate description is used to make the generated document read better. One way is to prepare the boilerplate as a separate file and include it into the text, as in:

.includefile Boilerplate.sti

The the test results are usually written in tabular form as they are generated. So a table is setup to hold the entries:

Doc.CreateTable("Test Results", "Test suite       ", "Test Case", "Result")

A lot depends on how the library is defined. For this example, the table caption is "Test Results", and there are three columns named "Test suite", "Test Case", and "Result". One convention is to use the length of the column headings as the column width. This makes the table easy to define. Trailing blanks in the column names are used to define the column width, but are not otherwise displayed. Using that length convention, the STF commands inserted for the example would be:

.Caption Test Results
.TH Test suite<TAB>Test Case<TAB>Result
.Table |p{1.5in}|p{.9in}|p{.6in}|, ,long

Of course any real library would support many options for setting the table column widths.

A typical library call to insert a row would look similar to:
Doc.Row(A,B,C), which inserts one row in the table. An alternate way to add a row could be: Doc.Row("aaaaaaaaaaaaa<tab>bbbbbbbbbbbbbbbbbbbb<tab>cccccccccccccccc") which inserts three columns, delineated by a tab separator.

The table may be explicitly ended by using Doc.Endtable() or by inserting a numbered paragraph. Numbered paragraphs automatically close open tables and also close open lists.

For more information consult the library user manual for the corresponding language of interest.

1.2 Case Study

A test report generator was written using the Python application program library as a case study. The Test Report Generator (TRG) required 749 lines of Python code and generates a full featured test report.

1.2.1 Inputs

The inputs to TRG are:

1. A description of the project structure (11 lines for the study), specifying the desired output, and the names of the test levels (Such as System, Suite, Test).

2. A description of the test suites and tests (40 lines for the study).

3. A requirements map, mapping requirements to tests. When this file is included, the test status of the requirements is also produced.

4. And a file of test results (36 lines for the study).

5. Also included is a template used to create a formal test report.

   
   

1.2.2 Outputs

The output from TRG consists of a set of tables giving the test status. In this case the structure consists of three levels: Subsystem, Suite, and Test. The structure names and number of test levels are arbitrary. What is significant is that the study chose three levels. The outputs consist of the following tables:

1. System Description. This summarizes test suites and test cases.

2. Subsystem Test Status. This is a summary of the test results by subsystem.

3. Suite Test Status. This is a summary of test results by test suite.

4. Test Status. This a full listing of the test results.

5. Requirements Test Status. This lists the requirements and their test status.

6. Requirements to Tests Cross Reference. This is a cross reference between the requirements and tests and is useful for determining what tests remain to be executed to close out the requirements testing.

7. Tests to Requirements Cross Reference. This shows what tests, test each requirement.

8. A quick look report consisting of the above tables in a formatted document (HTML and PDF).

9. A formal test report consisting of selected tables and other verbiage, as appropriate. The included template is customizable for the problem at hand.TRG is designed to scale based on the project needs. A small project might have only two, or even, one test level. A large project might have five levels (Subsystem, Function, Suite, Test, and Case). TRG sorts it all out and generates the tabular summaries based on its inputs.

The requirements map is optional, but recommended.

1.3 Documentation

All of the following documents are written in STF format and processed by STFXlate and pdflatex. The source and finished documents are included in this distribution. The available documentation consists of the following documents:

1. STFXLate Summary -- This document. The summary describes the STF commands used to generate a document and is useful when extending the application program interface or in coding templates, etc.

2. STF Library Description -- This describes the Python application interface.

3. Test Report Description -- This describes how to use the TRG.

4. Sample Quick Look Test Report -- This is the quick look output from the TRG test case.

5. Sample Formal Test Report -- This the formal test report from the TRG test case.

   
   

2 Command Summary

STF commands are two characters long, start in column two, and are preceded by a period in column one.

STFxlate has an alias facility for use when STF is coded by hand. This consists of human readable names instead of the two letter STF commands. Aliases are more than two characters long, start in column two, and are also preceded by a period in column one. However it is only required to use enough characters to make the alias unique. Thus both .Inc and .IncludeFile are equivalent aliases for .IF. STF commands and aliases are case insensitive. For a complete discussion, see Nuances in Computing.

In the following table, column 'H' indicates whether the corresponding command is supported by HTML and Wiki formats ('Y'), or whether it is ignored ('-') when --html or --wiki is specified.

Table 2-I Command Summary

Com	Function	Syntax Summary	H
%	Comment	String 7.11	Y
... .AI .AP .AR .AW .AX .BD .BI	Internal Comment Auto Image Size Include support for appendices Add row to following row Set auto wrap Define Appendix Begin Document Set paragraph bias	String 7.33 Path,[Size] 7.1 T/F 7.2 row-spec 7.3 T/F 7.5 Level, [label], Title 7.4 [Cover] 7.6 Number 7.7	Y Y Y Y Y Y Y Y
.BK	Set Line Break	7.8	Y
.CH .CN .CM .CO .CP .CV	Use Chapters Output a table of contents Explicitly execute a macro or inline command Comment Copy File Cover page	T/F 7.9 T/F 7.10 7.12 String 7.11 File-name 7.13 T/F 7.14	- Y Y Y Y Y
.DB .DC .DE .DL .DS .DT	Enable debug Create Doc. Describe Doc. Debug Line Dump State Doc. Class	T/F 7.15 Name, Title 7.16 Fields separated by (<TAB>) 7.17 Line 7.18 Line 7.19 article, report, book, manual, other 7.20	Y Y Y Y Y -
.EF .EL .EP	Soft end of file End List End Preamble	None 7.21 None 7.22 None 7.23	Y Y -
.FG .FM .FQ .FS	Include list of figures in contents Set Front Matter on or off Filter ASCII quotation marks Set document font size	T/F 7.24 T/F 7.26 T/F 7.25 Number 7.27	Y Y Y -
.HF .HL .IE .IF .IN .IX	SetHTMLLocalFigures Header Level Include Figure Include File Insert File Use an index	T/F 7.28 Level, Title 7.29 File-name 7.30 File-name, [POD],[Bias],[label-list] 7.31 File-name 7.32 T/F 7.34	Y Y Y Y Y Y
.LE .LL .LS .NP	List Element Labeled List Element List Start No Operation	String 7.35 Label,String 7.36 [Bullet] 7.37 None 7.38	Y Y Y Y
.OF .PC .PD .PE .PL .PP .PS .PT .PU	Change output Preamble Complete POD Format End paragraph command Put Line Define Paragraph Start paragraph commands Put Table Of Contents record Push commands on the format stack	File-Name, [Append] 7.39 None 7.40 Used internally in processing POD format files. 7.41 Flag, Level, [=;]Cmds 7.43 String 7.44 Level, [label], Title 7.45 Level,[=/]Cmds 7.46 tag, Title 7.47 single line command 7.48	Y - Y Y Y Y Y Y Y
.RP .SC .SD .SE .SF .SL .SM .SN .SP .SQ .SU .SV .SX	Replace string in symbol Set contents starting number Set Landscape Set Escape Set Figure size Set List Order Set Macro Set No Table Xref Set Parse Level Set Paragraph Level Substitute Save Escape Variables to a file Set Expression	Symbol,String,Value 7.49 Number 7.50 T/F 9.3.9 Key Value 7.52 Code, Spec 7.53 "1, 2, 3, 4" 7.55 macro-name 7.56 T/F 7.54 'level' 7.57 'level' 7.58 'char' /phrase/ 7.59 path 7.60 label,expression 7.61	Y - - Y Y Y Y - Y Y Y Y Y
.TB .TC .TE .TH .TP .TR .TS	Use Tables Table Caption Table End Longtable header Longtable sep. char. Table Row Table Start	T/F 7.62 String 7.63 None 7.64 col 1 & col 2, ... col n 7.65 Table separation character 7.66 String 7.67 Column-Spec, [Label], [Long], [Headless], [Splitlines] 7.68	Y Y Y Y Y Y Y
.TX	Set Text Tag	TX 'tag':option 7.69	Y
.UF .UP .VB	Set unwrapped font size Define Unnumbered PP Verbatim String	Size 7.70 Level, [label], Title 7.71 String 7.72	- Y Y
.WK .WR .XX .YA .YE .YF .YL .YS .XE	Wiki Format code Start/Stop wrapping Add to Index Activate Conditional(s) End Conditional Final Condition Alternate Conditional Start Conditional Execute	String 7.73 On|Off 7.74 Keyword 7.76 Label [, label, ..., label] 7.77 [Label] 7.78 [Comment] 7.79 Label [, label, ..., label] 7.80 [-]Label [&,|] [-]Label ... 7.81 Line 7.75	Y Y Y Y Y Y Y Y Y

3 Command Aliases

STF command mnemonics are difficult to remember when coding by hand, so most commands have an associated alias. Aliases are preceded by a period in column 1, start in column 2, and must be 3 characters long or longer. Abbreviations are supported. Thus .Verbatim and .verb refer to the same command. Enough characters must be specified to make the alias unique or the results are unspecified. Aliases that begin with an equals sign ('=') are Perl POD format commands that are recognized by STFXlate so that Perl POD format files may also be processed. For more information see Nuances In Computing. The aliases are as follows:

Table 3-I Alias Summary

Alias	Cmd	Description
.AddRow .Activate .Appendix .AutoImageSize .BeginDocument	.AR .YA .AX .AI .BD	Add to top of next row 7.3 Activate label 7.77 Defines an appendix 7.4 Specifies the image size file 7.1 Finishes document preamble 7.6
.Bias .Break .Caption .Chapters .Class .Command .Comment	.BI .BK .TC .CH .DT .CM .CO	Sets paragraph bias 7.7 Sets break line for Python debugger 7.8 Sets table caption 7.63 Sets first para. level to 'chapter' 7.9 Specifies the document class 7.20 Explicitly execute a macro or inline command 7.12 Insert a comment 7.11, 7.33
.CopyFile .CreateDocument .Cover .Debug	.CP .DC .CV .DB	Copies file into document 7.13 Starts Document 7.16 Starts and ends cover page 7.14 Turn debug trace on and off 7.15
.DescribeDocument .DebugLine .DumpState .EndCond	.DE .DL .DS .YE	Multi-line string for cover page 7.17 Comment line 7.18 Comment line 7.19 End conditional block 7.78
.EndIf .EndList .EndPreamble .ELIF .Else .EndTable .Escape .Execute .Figure	.YE .EL .EP .YL .YF .TE .SE .XE .IE	End conditional block 7.78 Ends enumerated or bullet list 7.22 Outputs usepackage commands 7.23 Alternate If Condition 7.80 Final Action 7.79 Ends a table 7.64 Define an escape key-value pair 7.52 Executes line after macro replacement 7.75 Inserts a figure 7.30
.FilterQuotes .HeaderLevel .IfCond	.FQ .HL .YS	Automatically translates ASCII quotes 7.25 Same as .PP with no label 7.29 If Condition 7.81
.IncludeFile .Index .InsertFile .ListElement .ListLabel .LongTableHeader .NOOP	.IF .XX .IN .LE .LL .TH .NP	Reads an external file as input 7.31 Adds key to index 7.76 Inserts a file 7.32 Specifies a list element 7.35 Specifies a labeled list element 7.36 Specifies a long table header 7.65 No operation, used with \Esc{...} 7.38
.Output .PPStart .PPEnd .PreambleComplete .Push .PutLine .PutTOC .Replace	.OF .PS .PE .PC .PU .PL .PT .RP	Switches output to a new file 7.39 Sets cmds at start of paragraph 7.46 Sets cmds at end of paragraph 7.43 Outputs config. commands 7.40 Pushes commands on the format stack 7.48 Outputs a line 7.44 Adds a record to Table Of Contents 7.47 Replaces string in symbol 7.49
.Row	.TR	Specifies a table row 7.67
.SaveVariables .SetAutoWrap .SetContentsPageNum .SetEscape .SetPPLevel .SetExpression .SetFontSize .SetFrontMatter .SetHTMLLocalFigures .SetList .SetLandscape .SetMacro .SetParseLevel .Size .StartList .SetNoRTFRef .SetTableSepChar .SetUnWrappedFontSize .SetWrap .Substitute	.SV .AW .SC .SE .SQ .SX .FS .FM .HF .SL .SD .SM .SP .SF .LS .SN .TP .UF .WR .SU	Save escape variables to a file 7.60 Sets Auto Wrap font size 7.5 Sets Contents initial number 7.50 Set Escape 7.52 Set next PP level 7.58 Define escape after macro replacement 7.61 Sets document default font size 7.27 Controls front matter 7.26 Set HTML Figures 7.28 Sets list order 7.55 Disables support for landscape 7.51 Names an existing macro 7.56 defines the parse level. 7.57 Set figure size 7.53 Begins a list 7.37 Turns off cross references in tables when using RTF format 7.54 Sets table separation char. 7.66 Sets unwrapped font size. 7.70, 7.5 Controls line wrap 7.74 Substitute phrase for a character 7.59
.TableEnd .TableStart .SetTextTag .TOC .UnnumberedPP .UseAppendices .UseContents .UseFigures .UseIndex .UseTables .Verbatim .Wiki	.TE .TS .TX .CN .UP .AP .CN .FG .IX .TB .VB .WK	Ends a Table 7.64 Begins a Table 7.68 Begins a Table 7.69 Creates a Table of Contents 7.10 Unnumbered paragraph 7.71 Specifies to include support for appendices 7.2 Creates a Table of Contents 7.10 Adds figures to contents 7.24 Creates an index 7.34 Adds tables to contents 7.62 Inserts string 7.72 Controls Wiki output format 7.73
=back =begin [:]identifier =cut =encoding =end [:]identifier =for [:]identifier =head =item =over =pod =qv	.LE .YA .YS   .YE   .PP .LE .LS .YE --	Ends list 7.42.3 Included if [:]identifier is active 7.42.3 Skip until a POD cmd is detected 7.42.3 Ignored 7.42.3 End block 7.42.3 Same as 1 line begin block 7.42.3 Convert from POD to STF 7.42.3 Convert from POD to STF 7.42.3 Sets up list 7.42.3 End block 7.42.3 Returns rest of line as an STF cmd 7.42.3

4 Inline Commands

Several formatting commands are directly recognized in the input text. They are case insensitive and have the form of: '\key-word{operand}'. There cannot be a space between the key word and the opening brace. Ending braces that are not part of an inline command must be escaped with a backslash. Thus to print '\url{}' in boldface in an operand, use '\bold{\\url{\}}' This would print as '\url{}'. The recognized commands are:

1. \bold{string}, which specifies to bold the string. This construct may span lines.

2. \dlink{label}, Insert a link anchor in the document. The link may be referenced via \dref and \dpage. This construct cannot span lines.

3. \dref{label,display-text}, Position to link anchor when display-text is double clicked. See dlink. This construct cannot span lines.

4. \dpage{label,display-text}, Position to the page associated with the anchor when display-text is double clicked. See dlink. Displays "display-text nn", where "nn" is the page number. This construct cannot span lines. \dpage does not display when targeting to HTML or Wiki formats. Examples:

\dlink{label} -- define an anchor. \dref{label,see blah} -- create a hot link to label with the text "see blah".   \dref{label,see blah}\dpage{label, ~on page~} -- create a hot link to label with the text "see blah on page nn", where clicking "see blah" takes you to the anchor and clicking "nn" takes you to the top of the corresponding page.

1. \esc{key}, which specifies to insert the value specified in a previous set escape statement. If 'key' begins with a dollar sign, the value is taken from the environment. If the value is not defined in the environment or in a set escape statement, the key is left in the document and preceded and followed by a question mark. An error message is also written to the log file. This construct cannot span lines.

2. \fig{file[,label],caption} Title, inserts a figure inside of a table. This construct cannot span lines. The caption and the title (use one or the other) appear at the bottom of the graphic. The difference is the title is not included in the table of figures in the contents and the caption is included therein. The label is used to create an anchor that may be referenced by \dref and/or \dpage. When a caption is used, the label is used to create an escape variable that holds the figure number. The Label can be referenced by \ref, which will display the figure number.
   To reference an inline figure number before the figure is defined, use the .SaveVariables command at the end of the document and include the resulting file at the beginning. This technique makes the figure number available after the document has been formatted at least once.

To reference the location of the inline figure, use the \dref{} inline formatting code. To reference the page on which the figure is located, use \dpage{}. An example is:

See figure \dref{label,\esc{label\}}\dpage{label, ~on page~}. This would generate "See figure Fig-num on page nn." The inner brace is escaped to delay the expansion until after the string is inside of the \dref{} routine.

1. \fixed{string}, which specifies to use a fixed spaced font. This construct may span lines.

2. \fn{string}, define a footnote. This construct cannot span lines. For HTML and Wiki output, inline formatting codes cannot be included in normal footnotes, see \fnx, below.

3. \fnx{string}\#19, define an extended footnote⁽²⁾. This construct cannot span lines, however it can contain embedded inline formatting codes.

4. \href{url,text}, which specifies an external link, except only the 'text' is displayed in the document. RTF, PDF, HTML, and Wiki format files support external links. This construct cannot span lines. (Commas in URLs should be specified as '%2C', for example, see http://www.w3schools.com/tags/ref_urlencode.asp

5. \italics{string}, which specifies to italicize the string. This construct may span lines, i.e. the ending "}" may be on a following line. So specifying: \Italics{ ... several lines ... }, the entire enclosed paragraph would be italicized.

6. \nl{}, which specifies a line break. This construct cannot span lines.

7. \norm{string}, which 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.

8. \ref{label, [page]}, which 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, Wiki, and HTML format files support internal links. This construct cannot span lines.

9. \und{string}, which specifies to underline the string. This construct may span lines.

10. \url{url}, which specifies an external link. RTF, PDF, Wiki, and HTML format files support external links. This construct cannot span lines, i.e. the starting "\url{" and the ending "}" must be on the same line.

11. \#nh specifies to insert the corresponding hexadecimal character, where 'n' and 'h' are any two hexadecimal digits.

    
    

5 Generating Output

Python script STFxlate.py reads the STF input file and writes either an equivalent LaTeX file, which is then processed by LaTeX or by one of its associated programs, such as pdflatex; or it writes an equivalent HTML file, which is suitable for browsing by any one of a half dozen browsers; or it writes a Wiki version in markdown format; or it writes a plain unformatted ASCII text file.

The following paragraphs include examples of creating various output formats. The syntax shown is for Windows command files. For UNIX, the leading 'python' used in invoking STFxlate may be omitted. The various programs Python, LaTeX, etc. must be located on the current search path (or defined in the Windows registry.)

It is helpful to encapsulate invoking STFxlate in a command file. The command file contains all the path references and simplifies the syntax. A sample command file named STFxlate.bat is:

@echo off if EXIST C:\Users\Public\Cmds\StfMacros.stf set $STF_CONFIG=C:\Users\Public\Cmds\StfMacros.stf C:\Python36\pythonw.exe C:\Users\Public\Cmds\STFxlate.py %*

Using this bat file simplifies running STFxlate. STFxlate.bat should be located in a directory that is in the search path. The following examples use STFxlate.bat.

It is, perhaps, even more helpful to use the GUI that comes with STF (Executor). Executor will automatically invoke the correct command sequence to generate documents, see paragraph B.3.2 for more information; also see illustration B.3.2-2.

5.1 Label Hierarchy

Choosing an output format implicitly defines a label of the same name. Thus specifying --html automatically defines label html. Because the output for the Wiki format leverages the HTML output class, defining --wiki defines two labels: html and wiki. So if conditional behavior is specified, the order of conditionals using labels can be important. For example if a conditional section of code is for HTML, but not Wiki, there are two choices:

1. Specify Wiki first and then HTML as in:
   

.ifc Wiki stuff... .elif html stuff... .endc

1. or specify a compound test as in: .ifc html & -Wiki.

2. a similar situation occurs when specifying --rtf. --rtf implicitly defines --latex, so reference label RTF before label Latex.Either approach will work, see paragraph 7.81 for more information on conditionals.
   Table 5.1-I shows the command line switches and their corresponding labels.
   

   Table 5.1-I Command Line Switches and Their Corresponding Labels

Switch	Defines labels	generates	Required Actions
latex rtf html wiki text	latex latex, rtf html html, wiki html, text	tex file tex file HTML file Wiki file txt file	Requires pdflatex to generate a PDF file Requires latex2rt to generate an RTF file   The Wiki file must be uploaded by hand

5.2 Generating PDF Output

To generate a PDF document. First make sure Python and LaTeX distributions are installed. Then use:

STFxlate -i masterdoc

The rest of the sequence is:
pdflatex masterdoc.tex
makeindex masterdoc
pdflatex masterdoc.tex
This will create masterdoc.pdf⁽³⁾ (notice that LaTeX requires at least two passes if a contents or an index is required.) See paragraph 9.7 for more information on index generation.

5.3 Generating HTML Output

To generate HTML use: STFxlate -i masterdoc --html

This will create masterdoc.html.

5.4 Generating Wiki Output

To generate Wiki (markdown format) use: STFxlate -i masterdoc --wiki

This will create masterdoc.wiki. Wiki's use Markdown format, which is not standardized, i.e. it varies across Wiki sites. So STF uses the most likely expansion to be recognized by all sites. The following features are typical:

1. Markdown format was never intended to use to write reports so not all of the STF semantics are implemented. However reasonable defaults are provided so that document semantics are preserved. For example the Wiki expansion at SourceForge does not generate vertical lines in tables. However column alignment is still preserved so that the resulting tables are still legible. For situations where maximum clarity is required, PDF or HTML expansions are preferred. The Wiki output was qualified against the following Wiki sites:

   a. The SourceForge Markdown formatter:
https://sourceforge.net/p/simpletextformatter/wiki/markdown_syntax/.

   b. A GitHub Markdown formatter: http://tmpvar.com/markdown.html.

   c. Another GitHub Markdown formatter: https://jbt.github.io/markdown-editor/. The third Markdown site displays much better if the .Wiki command is used to alter the output format slightly:
.Wiki L,T
.Wiki G,T
are recommended for this site. See paragraph 7.73 for more information.

1. Illustrations must be uploaded to the Wiki site by hand. Not all Wiki sites support embedding images inside of Wiki pages. Support for the differing syntax across Wiki sites is provided by macro \WikiFigure{format}. \WikiFigure{} receives the following parameters:

   a. The link (referenced as $@@@01)

   b. The figure number (referenced as $@@@02)

   c. The Caption (referenced as $@@@03)The default definition for \WikiFigure{} is contained in file StfMacros.stf and is as follows:

.SetEscape WikiFigure,[*,$@@@02=]=!$@@@01
An alternate format for sites that do support figures is:
.SetEscape WikiFigure,[*,$@@@02=]=

Modify the definition to match the Wiki site.

   d. The STF macro facility may be used to advantage in dealing with differing syntax across sites (see 9.3.)

   e. Comments are not supported in Markdown, so STF comments are automatically removed from the translation.

   f. Footnote expansion supports using macro \WikiNum{format} to specify how footnote numbers are embedded in the document. \WikiNum{} receives two parameters: the link ID and the footnote number. The default definition for \WikiNum{} is contained in file StfMacros.stf and is as follows:
.SetEscape WikiNum,[*,]=!<a href=$@@@01>^($@@@02)</a>

5.5 Generating RTF Output

Generating RTF output is similar to generating PDF only use latex2rt instead of pdflatex. An example is:

STFxlate -i masterdoc --rtf
latex2rt masterdoc.tex

1. A copy of latex2rt may be found at: http://sourceforge.net/projects/latex2rtf/files. Not all LaTeX semantics are supported, but it does produce an RTF file suitable for inclusion and editing in a Word document. The '--rtf' flag causes STFxlate to generate lists and tables in the format that latex2rt expects. Because latex2rt does not support all of STF semantics, STFXlate automatically converts STF to the nearest latex2rt equivalent. For example latex2rt limits the paragraph number to five (5) levels, so STFXlate automatically limits the number of paragraph levels to 5.

2. An alternate way to generate RTF output is to use STFxlate to produce a LaTeX output file and then use LaTeX2RTF to convert the LaTeX output to RTF. A copy of LaTeX2RTF may be found at http://latex2rtf.sourceforge.net/.

3. A third way is to use LyX. Import the resulting LaTeX file into LyX and then export it as RTF. LyX may be downloaded from http://wiki.lyx.org/Windows/Windows.

4. Latex2rt will occasionally lose count of braces ("{,}") when translating TeX to RTF. When this happens the message: "(Not set):2505 Mismatched '{' in RTF file, Conversion may cause problems." is displayed in the console window. The work-around is to reissue the latex2rt command and include "-Z1" on the command line. The "Z" option indicates the number of extra "}" characters to append to the end of the TeX file.All three approaches produce an RTF file suitable for inclusion in a word processor. However, the resulting RTF file usually requires hand editing.

Note: Not all word processors recognize index records embedded in RTF format files. If you can't generate an index when one is specified in the source (STF) document, change word processors. For example, MS Word does recognize RTF index records.

5.6 Generating Text Output

There are times when it is desirable to have a text image of the output. For example, This can be useful if it is desired to parse the output using a regular expressions parser. The text file may be output directly by STFxlate. Tables are left in raw format, usually with a tab separator between columns. Lines are not wrapped. An example is:

STFxlate -i masterdoc --text

This would generate masterdoc.txt in a format suitable for searching but not nicely formatted. To obtain a nicely formatted text document, create the LaTeX output. The output from STFxlate is a TeX file. (masterdoc.tex). Load it into LyX using the import menu. Then use the export menu and specify text. This formats tables, wraps lines, etc. Alternately there are several web sites that address how to obtain text output from a LaTeX source. LyX can be obtained from: http://www.lyx.org/Download

5.7 Working with DocBook

In addition to exporting text, LyX can also export to DocBook The process is similar to that noted in 5.6. Namely import the LaTeX formatted document, and export the DocBook equivalent. Because this feature of LyX is currently being updated, use a web search to locate the latest information.

An additional method of exporting STF to DocBook is to use LibreOffice or OpenOffice. Edit the STF HTML output using, say LibreOffice, and then export it to DocBook.

5.8 Processing POD Files

POD files are included from a master document. A sample master document is as follows:

.CreateDocument PODDoc, Sample POD File
.DescribeDocument This is a sample POD document
.BeginDoc
.Include \esc{$PODDOC}.txt, POD

The master document is setup to reference environment variable 'PODDOC'. The next example shows how to define PODDOC under windows. (When STFxlate is executed under UNIX, use: export PODDOC='file-name'.)

set PODDOC=mypodfile

Use one of the preceding methods to specify the output format, i.e. --latex, --html, etc.

5.9 Generating Epub Format Files

It turns out that epub format files are Zip files containing XML and HTML. The XML contains the metadata and the HTML contains the text. So the HTML output of STF may be used, with the appropriate metadata, to create a simple e-book. Calibre, available from http://www.calibre-ebook.com may be used create an e-book from STF's generated HTML. To view the meta data, rename an epub file to a zip file and examine its contents.

5.10 STFXlate Switches

STFXlate uses the UNIX/Linux convention for command line switches. Single letter switches are preceded with a single minus sign ('-') and multiple letter commands are preceded with two minus signs ('--'). Single letter switch operands are separated from the command letter by a space; multiple letter switches are separated from their operands by an equals sign ('=') with no intervening spaces. The following switches are supported when invoking STFXlate:

Table 5.10-II STFXlate Command Line Switches

Short	Long	Purpose
-i -o -d -a -g -y -s -c -t -r -l -x -b -p -w -u -h	--input=file --output=file --root=dir --activate=list --target=string --Log=file --start=file --config=file --html --rtf --latex --text --debug --pod --wiki --update --help	Specifies master input file Specifies LaTeX or HTML output file Contains configuration files, default: [home]\.nic\STFxlate List of labels to be activated Identifier for configuration files. Normally taken from output type. Name of log file. Default STFXlate'input'.log Define macros. Default from environment, as: $STF_STARTUP Initial commands. Default from environment, as: $STF_CONFIG Specifies target of HTML Specifies target of RTF Specifies target of LaTeX Specifies target of Text Turns on debug flag Specifies input is a POD file Specifies target of Wiki in markdown format. Specifies to check the current STFXlate version against the website version, see 9.4 Display help

5.11 Convenience Commands

The following convenience commands are included. These are implemented as batch commands (bat) in Windows or in bash in UNIX/Linux. The following table assumes that STF has been installed.

Table 5.11-III Convenience Commands

Command	Action	Requires
makeDoc	Creates PDF and HTML for documents without a contents or index	pdflatex
makeDocWithIndex	Creates PDF and HTML for documents with a contents or index	pdflatex, makeindex
makeRTFDoc	Creates RTF document	latex2rt
makeWiki	Creates a wiki document in markdown format
ViewSubDoc	Creates PDF and HTML for documents without a document header	pdflatex
SuperCleanSTF	Cleans up after pdflatex. Deletes temporary files AND *.tex files.
SuperCleanLatex	Cleans up after pdflatex. Deletes temporary files but leaves *.tex files.
NewSTF	Creates a dummy STF document. Rename it and customize into a new document.

6 Special Characters

STF uses the standard ASCII character set. The following special characters are recognized and have the specified function:

Table 6-I Special Characters

HEX	Decimal	Description
01	1	used internally to encode quotation marks.
02	2	used internally to encode tildes.
03	3	used internally to encode backslashes.
04	4	used internally to mark table columns.
05	5	used internally as a format designator.
06	6	used internally as a format designator.
09	9	recognized as in fixed format as a tab separator; also recognized in tables as a column separator.
0A	10	a single <LF> is recognized as a new line separator in UNIX formatted files.
0B	11	used internally to encode non breaking spaces.
0C	12	used internally to encode end of line in macros
0D	13	a <CR><LF> sequence is a new line separator in Windows formatted files; a single <CR> is a new line separator in Macintosh formatted files.
0E	14	used to mark a null line in macros.
14	20	used to encode '\'.
15	21	used to encode '<'.
16	22	used to encode '>'.
19	25	used to mark extended footnotes.

6.1 Notes

1. Usually the backslash must be doubled when using a program interface as in: putline("The following word is \\bold{bolded}.") This would print as: The following word is bolded.

2. Ending an input line with a backslash concatenates the following line on the end, as in:

Input line 1\ Input line 2

would concatenate "Input line 1" and "Input Line 2", in effect creating one long line. The ending backslash must be the last character on the line. To end a line with a backslash, use a double backslash. Concatenation is useful when using inline constructs that do not support spanning lines, such as footnotes and inline escapes.

1. A single minus is output as a minus sign; a double minus sign is output as an en dash; a triple minus sign is output as an em dash.

2. Quotation marks are processed as follows: backtick "(')" is used for the start of a quoted string and the apostrophe "(')" is used for the end. For double quotes, use two marks: (''This is a string''). This would print as ("This is a string").

3. A non breaking space is represented as a tilde ('~'). To represent an actual tilde, precede it with a backslash ('\').

4. A backslash in an operand escapes the character that follows it. Thus '\\' in an operand prints as '\'. However a backslash as the last character on a line concatenates the next line.

5. When the parsing level is 5, the ASCII quotation mark (") indicates a string literal. Thus, in parse level 5, "\bold{abcd}" is equivalent to \\bold{abcd\}. Both print as \bold{abcd}. To embed a literal quotation mark in a literal, use two quotation marks, as in "This is""Quoted""".
   That would print as: This is "Quoted".
   
   

   
   

6.2 Parse Level

There are 5 parse levels.

Table 6.2-II Parse Level

Level	Meaning
5	Processes key words, macros, composite characters and literals.
4	The default, removes processing of literals. This makes the ASCII quotation mark an ordinary character.
3	In addition to level 4, level 3 removes recognizing composite characters. These are quotation marks, double and triple minus signs. The ASCII left and right single quotation marks ("','") are displayed unprocessed(4); and double and triple minus signs are not combined into dashes. The tilde is still recognized as a forced space character.
2	In addition to level 3, level 2 removes key words. Macros are still processed. Tildes are unprocessed.
1	In addition to level 2, level 1 removes inline commands and macros.

6.3 Working With Foreign Text Files

On occasion, it is useful to process pure text files with STF. When processing non STF text files, following techniques may be used to advantage:

1. It may be useful to setup a master file that includes the text file. That way it is not necessary to make changes to it. The master file should include the STF header. Typically this looks similar to:

.dc Document-name, Document title ... turn off front matter .fm F .BeginDocument .IncludeFile ForeignFile.txt

If a title page and contents are desired, then, instead of .fm F, use .FG F, .tb f, and .ix F. These produce a table of contents without a list of tables, figures, or an index. It is also a good idea to add a DescribeDocument command as in: .DescribeDocument title <TAB> <TAB> Author(s)

1. If the text file has extended ASCII characters, add the \EXTASCII{} macro to the preamble. This will cause STF to recognize the extended ASCII characters. Alternately use a filter program, such as sed or tr⁽⁵⁾, to sanitize the file prior to processing. Either that, or use the STF substitute command to provide the STF equivalents.

2. If the file contains ASCII quotation marks, the .FilterQuotes command may be used to convert quotation marks to formatted quotation marks. The algorithm is based on the assumption that beginning quotes are preceded by a space. See 7.25.

3. If a contents is desired, then it is necessary to insert paragraph titles into the text. One technique is to use a text editor and insert .hl 1,Title as appropriate into the text file, where "Title" is the desired paragraph title. Sometimes a macro editor, such as XEmacs may be used to simplify this process.

   
   

7 Syntax Description

The description of the STF formatting layer follows.

7.1 AI -- Auto Image Size

.AI file-path, Size -- alias: .AutoImageSize

Operands:

1. File-path -- location of file containing image size information.

2. Size -- specifies desired image size.This command takes two optional arguments, a file path and the desired image size.

If no operands are specified, then AutoImageSize is set to not active. Specifying an existing file sets it to active.

If the file path is not blank, then that file is loaded. If the image size has not been specified, a default of 512 x 384 is used. The image size file should contain one line for each image being used in a .Figure command. The file format is:

Image-name image-tag WxH ...

One image name per line. The image tag is usually the same as the image file extension and is ignored. "WxH" is the image width and height of the figure in pixels. When a .Figure command is evaluated, the auto-image-size file will be searched for the image name. If found, the image will be adjusted to fit within the default window size.

Examples:

.AI

AutoImageSize.txt will be turned off.

.AutoImageSize MyImageSize.txt, 640x480

MyImageSize.txt will be loaded and the default window size set to 640x480.

.AI , 640x480

The default window size will be set to 640x480.

Notes:

The magick identify⁽⁶⁾ command may be used to automatically generate autoimagesize.txt. Identify is native to UNIX and downloadable for Windows. Under Windows identify is a command recognized by ImageMagick.
ImageMagick may be downloaded from: http://www.imagemagick.org/script/binary-releases.php.

There are multiple distributions on this site, so scroll down to the Windows Binary Release. ImageMagick recommends installing
GhostScript first, this may be found at: http://sourceforge.net/projects/ghostscript/?source=dlp.

Examples:

1. From the Windows/Dos shell:
   magick identify *.jp*>autoImageSize.txt will generate the file for JPEG images.

2. From the Windows/Power Shell(PS) window:
   magick identify *.jp* | Out-File -encoding ASCII -filepath autoImageSize.txt will generate the same file. The reason why the applet "Out-File" is required for PS is the default output for PS is Unicode and STFXlate expects ASCII.

Multiple image size files are merged with the precedence order being that of the last file loaded takes precedence over previous files, etc.

7.2 AP -- Include support for appendices

.AP T/F -- Alias: .UseAppendices
Operands: Boolean -- Includes support or omits support. The default is to omit support. This command must be used before .BeginDocument.

7.3 AR -- Add to following row

.AR -- Alias: .AddRow
Operands: Row-spec, see 7.67 -- Adds current row to following row, in effect a vertical merge of table cells.
For example the following table uses .AddRow:

.Caption AddRow Example .Row .Table |c|c| .row Header1<tab>Header2 .row Stuff11<tab>Stuff12 .AddRow Stuff21<Tab>Stuff22 .row Stuff31<tab>Stuff32 .row Stuff41<tab>Stuff42 .EndTable

This displays as shown in table 7.3-I.

Table 7.3-I AddRow Example

Header1	Header2
Stuff11	Stuff12
Stuff21 Stuff31	Stuff22 Stuff32
Stuff41	Stuff42

7.4 AX -- Enable appendices

.AX -- Alias: .Appendices
Operands: None -- changes first level paragraph to become an appendix. After the .Appendices command .PP 1 and .HL 1 generate new appendices instead of first level paragraphs.

7.5 AW -- Set auto wrap

.AW T/F -- Alias: .SetAutoWrap
Operands: Boolean -- turns auto wrap on and off.

When Auto Wrap is enabled (Flag = True), STF2latex manages the font and line wrapping. The algorithm is as follows:

1. If a line starts with one or more spaces, it is output unwrapped in fixed font.

2. Otherwise the line is wrapped in proportional font.

3. Inline formatting is not supported in unwrapped format.

4. SetWrap is ignored if Auto Wrap is in effect.

5. The Font Size of unwrapped font is controlled by the .UF command, see 7.70.
   

   
   

7.6 BD -- Begin Document

.BD -- alias: .BeginDocument
Operands: Optional Cover -- indicates that a cover page is being used. Required for HTML and Wiki documents, optional for PDF documents. Example:
.BeginDocument Cover
When 'Cover' is specified on the BeginDocument command, the next command must be .Cover T, see 7.14.

This causes the document preamble to written to the STF output file. Customization of the preamble is discussed in 9.1.

7.7 BI -- Set paragraph Bias

.BI Number -- Alias: .Bias
Operands: Bias

This command takes one argument.

The Bias is a numeric offset applied to all paragraph levels defined in the file. So if the bias equals 2, then a paragraph defined as level 1 gets biased to level 3, etc. Bias is inherited downward, i.e. if a file is included, the parent file's bias is inherited. If the bias is changed inside of an included file, it reverts back to the parent file's bias when the include file exits. The default is zero.

7.8 BK -- Set Line Break

.BK -- Alias: .Break
Operands: None

The Break command does nothing, however it provides a convenient place to set a break point in the Python debugger. ".BK" is inserted at convenient places in the document and a break point set at the interpretation of the .Break command in stf2Latex. When the .Break command is encountered the script halts as per the debugger break setting. This allows the interpretation of particular commands in the document to be stepped through in the debugger. See Appendix A.

7.9 CH -- Use Chapters

.CH T/F -- Alias: .Chapter
Operands: Boolean

This command is ignored when HTML is specified. True specifies that the document is divided into chapters. It should only be used when the first paragraph level is "Chapter" and the document class is not article, extarticle, extreport, report, or book. Classes report and book automatically use chapters. See 7.20.

7.10 CN -- Table of Contents Required

.CN T/F -- Alias: .TOC
Operands: Boolean

True specifies a Table of Contents is required, False specifies to omit the Table of Contents. The default is True. This command may only be used before .BeginDocument.

7.11 CO -- Comment

.CO String -- Alias: %
Operands: Ignored

Inserts a comment into the output file.

7.12 CM -- Command

.CM String -- Alias: Command
Operands: As specified by the macro

This command explicitly executes a macro. It is used when recognition of inline commands is disabled. See paragraph 6.2. Here are some examples:

Table 7.12-II Command Examples

Inline Format	Explicit Format	Result
\Landscape{begin}	.cm landscape,begin	Enables landscape
\ProgramListingOff{}	.cm ProgramListingOff	Turns off listing mode

7.13 CP -- Copy File

.CP File-Name -- Alias: .CopyFile
Operands: File-Name

This command copies an existing file into the document with minimal formatting. Commands in the file are not recognized nor are inline formatting commands. This command is typically used to copy program listings.

7.14 CV -- Start and End Cover Page(s)

.CV T/F -- Alias: .Cover
Operands: Boolean

This command inserts text ahead of the table of contents. It must be used as the first command after .BeginDocument. It is incompatible with the .DescribeDocument command -- use one or the other. Do not use paragraph commands in the cover page(s). However references are supported. Usually the STF macro facility is used to create commands that are compatible between HTML and LaTeX. Sample LaTeX cover pages are shown at: http://tex.stackexchange.com/questions/59460/custom-title-page-in-report-or-book-class

.CV T -- starts inserting cover page(s)
.CV F -- ends the cover page sequence and starts the contents.

Notes:

1. The Cover option must be added to the .BeginDocument command when cover pages are used, see 7.6.

2. The \Cover and \EndCover macros are usually used to begin and end cover pages rather than specifying .CV T/F directly. See 9.1.1.1.
   

   
   

7.15 DB -- Enable debug

.DB Command-Trace, [File-Trace] -- Alias: .Debug
Operands:

1. Command-Trace -- Boolean, True turns on the command trace, False turns it off.

2. File-Trace -- Boolean, Optional -- True turns on the file trace, False turns it off.
   This command takes two Boolean arguments. The first enables a trace of commands inserted as comments into the generated file; the second is optional and enables a trace of referenced files, also inserted as comments. The defaults are Debug(False, True).

While it is useful for debugging purposes, the command-trace should be turned off prior to generating any final copy.

7.16 DC -- Create Document

.DC Name, Title -- Alias: .CreateDocument
Operands:

1. Document-Name -- inserted as a comment at the top of the output file.

2. Document-Title, optional -- Displayed at the top of the document. Default: "Document".This command creates the document and is always the first STF command.
   
   

   
   

7.17 DE -- Describe Document

.DE <TAB> separated fields -- Alias: .DescribeDocument
Operands: Tab separated string.

Describe Document is an optional command that specifies the cover page of the report. It can consist of multiple lines separated by tabs (<TAB>). (The first line frequently lists the author(s).) This command may only be used before .BeginDocument. To omit the date stamp, set date to an empty symbol, as in
.se date, see paragraph 9.4. Describe Document is ignored if an explicit cover page is also specified, see 7.14

7.18 DL -- Debug Line

.DL -- Alias: DebugLine
Operands: Comment line written to log

Example:
.DL Creating table. "Creating Table" will be written to the log.

7.19 DS -- Dump State

.DS -- Alias: DumpState
Operands: Comment line written to log

STFXlate internal state is written to the log. This includes the currently defined labels, symbols, and macros. "DS" can be useful in debugging.

Example:
.DS State midway through document. "State midway through document" will be written to the log followed by the values of all internal variables.

7.20 DT -- Document-class

.DT Class -- Alias: .Class
Operands: Document-class -- the name of a LaTeX class.

The Document Class is an optional string that indicates the type of LaTeX document being constructed. Specifying --html or --text on invocation causes the document class to be ignored, except if "manual" is specified. Recognized values are:

1. "article" -- this is the default and most common document class.

2. "extarticle" -- same as article but with extended font size support

3. "report" -- this is similar to an article, except the first paragraph level is named "Chapter"

4. "extreport" -- same as report but with extended font size support

5. "book" -- this is similar to a report, except books use double sided output.

6. "manual" -- this is a flag that indicates that the author will supply the LaTeX or HTML preamble.
   This command may only be used before .BeginDocument.

There are many options that are available to a LaTeX formatted document that are not supported when using HTML output format. See http://tex.stackexchange.com/questions/36988/regarding-the-book-report-and-article-document-classes-what-are-the-mai for a discussion.

7.21 EF -- Soft End of File

.EF -- Alias: None
Operands: None

On encountering .EF in column 1, STFXlate ignores the rest of the current input file and continues processing as if an end of file has been reached.

7.22 EL -- End List

.EL -- Alias: .EndList
Operands: None

End List ends an enumerated or bullet list.

7.23 EP -- End Preamble

.EP -- Alias: .EndPreamble
Operands: None

Preamble Complete is triggered if it was not explicitly stated; the preamble configuration commands are written. After EndPreamble is called, InsertFile and Verbatim may be used to insert LaTeX commands to override standard directives. See 9.1.

7.24 FG -- Use Figures

.FG T/F -- Alias: .UseFigures
Operands: Boolean

True specifies to include a list of figures in the table of contents, False specifies to omit the list of figures. The default is true, a list of figures is included in the contents. This command may only be used before .BeginDocument.

7.25 FQ -- Filter Quotes

.FQ T/F -- Alias: .FilterQuotes
Operands: Boolean

True specifies to convert ASCII quotes ("...") to formatted quotes ("..."). Parse level 5 is implicitly turned on, if it is not already specified. However literals are disabled. Instead the following logic is employed:

If a quotation mark is preceded by a space, it is assumed to be a leading quote and changed to (''). If a quotation mark is followed by or preceded by a period, it is assumed to be an ending quote, ("). Otherwise the opposite sense is employed, i.e. if the previous mark was a leading quote, a following quote is used, etc.

7.26 FM -- Front Matter

.FM T/F -- Alias: .SetFrontMatter
Operands: Boolean

True specifies to enable the document front matter, False specifies to disable the document front matter. Front matter includes the contents, Index, and title page. This command may only be used before .BeginDocument.

7.27 FS -- Set Font Size

.FS Size -- Alias: .SetFontSize
Operands: Size

Sets the LaTeX font size: 10, or 12. If class extreport or class extarticle is specified, then other sizes may be specified. This command may only be used before .BeginDocument.

7.28 HF -- SetHTMLLocalFigures

.HF T/F -- Alias: .SetHTMLLocalFigures
Operands: Boolean

Some HTML browsers restrict the type of files that can be referenced locally. This is usually due to security concerns. So for example, <img src="c:\mypic.jpg"> will not display. However, <img src="file://c:/mypic.jpg"> will display just fine. Setting SetHTMLLocalFigures to true, informs STFxlate to automatically promote figure references for local files to use the "File://" prefix in front of file names. The default is True, i.e. the default is to fix local figure file names.

7.29 HL -- Header Level

.HL Level, Title -- Alias: .HeaderLevel
Operands:

1. Number -- paragraph level. Specifies the paragraph level.

2. Title -- paragraph title.This command is the same as specifying the ".pp"
   command with the label omitted, see 7.45.
   
   

   
   

7.30 IE -- Insert Figure

.IE Filepath, [label], Caption -- Alias: .Figure
Operands:

1. Filename -- path of a file containing a figure in a format recognized by pdflatex and/or HTML. Typically supported formats are: .JPEG, JPG, PNG, and GIF.

2. Label -- optional label that can be used to refer to the figure in a "\ref{}" statement.

3. Caption -- the title of the figure.Inserts the file as a figure into the document. The caption is used to label the figure and is also copied into the table of contents. Omitting the caption makes the figure anonymous, i.e. it not not added to the table of figures in the contents. Differences in graphic formats are discussed in Nuances In Computing. Image scaling is discussed in 7.53 and also in 7.1

Note: If Wiki attachments are being used, only the file name and extension are required. The full path is ignored. see 7.73.

7.31 IF -- Include File

.IF Filename, [POD],[Bias],[label-list] -- Alias: .IncludeFile
Operands:

1. Filename -- path of a file containing STF commands and text. Processing continues using the included file until the file ends. Include files may be nested. ".EF" starting in column one is recognized as a soft end of file.

2. POD -- Optional flag that specifies the file is in Perl POD format⁽⁷⁾.

3. Bias -- Optional number that specifies paragraph bias for the include file, see 7.7. Bias propagates downwards through included files. Thus an included file inherits its parent's file bias. Changing the bias inside of an included file does not affect the parent file, as the bias reverts to the parent's file original bias when the included file ends.

4. Label-list -- comma separated list of labels. Labels are used in conditional statements. See 7.81. Labels propagate downward through included files. Thus an include file inherits its parent's file labels. However labels defined in an included file disappear when the file ends.
   

   
   

7.32 IN -- Insert File

.IN Filename -- Alias: .InsertFile
Operands: Filename -- path of a file to insert.

This copies an existing LaTeX (or HTML) format file into the document. The text is not interpreted by STFxlate. Binary file format is not supported, i.e. only ASCII format files may be inserted.

7.33 ... -- Internal Comment

... String -- Alias: None
Operands: Comment string

The comment is not included in the generated document.

7.34 IX -- Generate an index

.IX T/F -- Alias: .UseIndex
Operands:
A Boolean flag that turns index generation on and off. Default: True.

Specifies whether or not to generate an index. This command may only be used before .BeginDocument.

7.35 LE -- List Element

.LE Paragraph -- Alias: .ListElement
Operands: Paragraph

Specifies a paragraph that is part of a list expansion, see 9.5

7.36 LL -- Labeled List Element

.LL Label, Paragraph -- Alias: .ListLabel
Operands:

1. Label -- An STF label that holds the current list number and that can be used to refer to the list element in a reference statement.

2. Paragraph -- Specifies a paragraph that is part of a list expansion, see 9.5
   

   
   

7.37 LS -- List Start

.LS [Bullet] -- Alias: .StartList
Operands: Bullet -- optional flag indicating that a bullet list is required.

Starts a list, see 9.5 Up to four alphabetic lists may be nested and up to two bullet lists may be nested.

7.38 NP -- No Operation

.NP -- Alias: .NOOP
Operands: None

This specifies a no operation command. It is useful in defining macros, see 9.3

7.39 OF -- Change output file

.OF Filename [,Append] -- Alias: .Output
Operands:

1. Filename -- path of a file to be written.

2. Append -- optional. Indicates to append to an existing file rather than replace itSpecifies to start writing to a new file. Append is a flag indicating the file is to be appended to rather than replaced. This is useful in creating document fragments to be included in another document. Specifying a blank file name reverts to the previous output file.
   
   

   
   

7.40 PC -- Preamble Complete

.PC -- Alias: .PreambleComplete
Operands: None

Preamble complete causes STFXlate to write LaTeX use-package directives. At this point, InsertFile may be used to add additional use-package directives. This command is ignored if the target is HTML or Text, see 9.1. This command may only be used before .BeginDocument.

7.41 PD -- POD Format

.PD -- Alias: None
Used internally in processing POD format files.

7.42 Working with Perl POD Format Files

The Perl POD format is implemented in STF. The POD format of linking within a document and of linking to Linux man-pages differ from the LaTeX equivalents, so these are not supported. The details of the supported semantics are discussed in the following paragraphs. Information on POD files may be found at:
http://search.cpan.org/~flora/perl-5.14.2/pod/perlpod.pod

POD files are processed by including them from a master STF file, see paragraph 5.8.

Notes:

1. Automatic wrap is turned on for POD include files. This wraps lines not starting with white space.

2. On opening, POD files are skipped until the first POD command is encountered, i.e. they are skipped until an equal sign is detected in column one.

3. POD begin blocks may be nested, however some POD begin labels have a leading colon (':'). STF considers the colon to be part of the label. This means when activating labels for processing, the leading colon must be included with the label. See paragraph 7.81

4. POD files are not rigorously syntax checked, i.e. they are presumed to be error free.

   
   

7.42.1 POD Inline Formatting Codes

POD inline formatting codes, see http://en.wikipedia.org/wiki/Plain_Old_Documentation for more information. are indicated by a capital letter immediately followed by one or more less than signs ('<') and are terminated by the same number of greater than signs ('>'). For example 'B< text >' would bold the text as in: text. Spaces between significant greater than or less than signs are not supported. For example B<< text >> is supported, but B< <text >> is not. Formatting codes may be nested, as in: B<<< A>I<< B >> >>>. This would expand to: A > B, where I<>, italicizes its operand. Notice that significant brackets must be set off by spaces. The supported codes are:

1. I<text> -- italic text.

2. B<text> -- bold text.

3. C<code> -- code text. This is expanded in a fixed font.

4. F<file-name> -- style for file names. Italics are used.

5. X<topic name> -- an index entry.

6. U<text> -- underline text.

7. Z<> -- a null (zero-effect) formatting code.

8. L<name> -- a hyperlink. POD has many different formats for this construct. Implied links to man pages are not supported. See http://en.wikipedia.org/wiki/Plain_Old_Documentation for more information. The following forms of POD syntax are supported:

   a. L<url> -- this is displayed and hot linked to the URL.

   b. L<text|url>. The text is displayed and hot linked to the URL. The separator character is the vertical bar ('|').

   c. L<name> -- this references the Perl documentation site.

   d. L<name::name2> -- this references a sub paragraph on the Perl documentation site.

   e. L<name/"phrase"> -- this references a lower level sub paragraph on the Perl documentation site.

1. E<escape> -- a character escape. The character is inserted in the text. See 7.42.2.

2. S<text> -- text contains non-breaking spaces. Spaces are replaced with non breaking spaces.
   

   
   

7.42.2 POD Character Escapes

The following character escapes are supported:

1. E<lt> -- a literal < (less than)

2. E<gt> -- a literal > (greater than)

3. E<verbar> -- a literal | (vertical bar)

4. E<sol> -- a literal / (solidus, aka forward slash)

5. E<number> -- the byte code is inserted in the document. This type of construct is usually not portable to multiple document formats, e.g. LaTeX and HTML will interpret non standard codes differently.
   

   
   

7.42.3 POD Commands

POD defines the following commands. Commands start with an equals sign ('=') in column 1. Inline formatting commands are not supported in headings. The supported commands are:

1. =pod -- Identifies start of text to be formatted. Text lines starting with a non blank character are wrapped. Lines starting with one or more blanks are not wrapped. Unwrapped lines are expanded in a fixed font. Wrapped lines are expanded in a proportional font.

2. =head1 title -- Identifies a heading level 1. Converted to .pp 1, , title

3. =head2 title -- Identifies a heading level 2. Converted to .pp 2, , title

4. =head3 title -- Identifies a heading level 3. Converted to .pp 3, , title

5. =head4 title -- Identifies a heading level 4. Converted to .pp 4, , title

6. =over indent-level -- Identifies the start of an itemized list. Only '=Item' and '=back' may follow an '=over' command. The indent-level is ignored.

7. =item stuff -- Identifies a list element. Converted to: .le stuff. Blank lines generate block paragraphs. Inline formatting commands are supported. If the first non blank character of the first item is an asterisk, a bullet list is generated. An item with no text is an error. A leading asterisk is blanked.

8. =back -- Ends a list.

9. =begin label -- Interpreted as a conditional block. If the label is active the block is included; otherwise it is skipped. A POD block is active if it is included in an Activate command. If the label has a leading colon (':') in the POD document, include the colon in the activate statement.

10. =end label -- Identifies the end of a conditional block.

11. =for label text... -- Identifies a single paragraph conditional block.

12. =encoding type -- Ignored.

13. =cut -- Skips text until = is encountered. POD format Implementations seem to vary according to the available documentation on POD format. For this implementation, an '=cut' is terminated by any POD command.

14. =qv -- Returns rest of line as an STF command. This is an extension to POD and is useful in debugging. For example =qv .ef returns '.EF', which is a soft end of file.

    
    

7.42.4 STF POD Support

1. The set auto wrap command is automatically enabled when processing POD documents. See paragraph 7.5. Auto wrap automatically switches the document format between a line wrapped mode, used for normal document processing, and an unwrapped or literal mode. If a line starts with a space, the line is output in unwrapped mode, otherwise it is output in wrapped mode. Inline formatting commands are not recognized in unwrapped mode.

2. All of POD syntax is supported, except for internal document references and implied Linux man-page references which are different from the LaTeX implementation and so are not supported. (STF does support internal and external links for STF format files, see paragraph 4.) Also STF does not recognize text encoding other than that supported by the Python standard read functions, which includes standard ASCII.

3. A paragraph bias can be specified for include files. This supports including a large number of POD files in a document by increasing the paragraph levels so that the POD files can be included in document sections. For example, setting the Bias to 2, biases the range of paragraph level numbers by two. So the effective range of POD header levels becomes [3..6] instead of [1..4].
   Note:

STF has the ability to integrate document fragments into a coherent document. There are probably situations that could benefit from being able to integrate local POD documentation into a larger document.

7.43 PE -- End paragraph commands

.PE Flag, Level, [=;]Cmds -- Alias: .PPEnd
Operands:

1. Flag -- Boolean flag that specifies to not include the current paragraph. True means that the end paragraph commands will be processed for the current paragraph.

2. Level -- specifies the paragraph level to be processed.

3. [=;]Cmds -- specifies STF commands to be executed at the end of every paragraph of the specified paragraph level. An equal sign ('=') as a first non blank character before the commands specifies that multiple commands are to be entered and the character following the equal sign is the command line delimiter.Specifies commands to be executed at the end of a paragraph specified by an ".hl", ".le", ".pp", or ".up" statement.
   
   

   
   

7.44 PL -- Put Line

.PL Paragraph -- Alias: .PutLine
Operands: Paragraph -- a line of text to be output.

"PL" is required if an ordinary line begins with a period; otherwise it is optional.

7.45 PP -- Start Paragraph

.PP Level, [Label], Title -- Alias: None
Operands:

1. Number -- paragraph level. Specifies the paragraph level.

2. Label -- optional label that can be referred to in a \ref{} statement.

3. Title -- paragraph title.
   

   
   

7.46 PS -- Start paragraph commands

.PS Level, [=;]Cmds -- Alias: .PPStart
Operands:

1. Level -- specifies the paragraph level to be processed.

2. [=;]Cmds -- specifies STF commands to be executed at the start of every paragraph of the specified paragraph level. An equal sign ('=') as a first non blank character before the commands specifies that multiple commands are to be entered and the character following the equal sign is the command line delimiter.Specifies commands to be executed at the start of a paragraph specified by an ".hl", ".le", ".pp", or ".up" statement.
   
   

   
   

7.47 PT -- Put Table of Contents

.PT Record -- Alias: .PutTOC
Operands: Tag, Title -- a line to be added to the Table of Contents. The tags are:

1. toc -- Add to Table of Contents

2. lof -- add to Table of Figures

3. lot -- add to Table of TablesExample: .PutToc lof, Title
   This will add an entry to the list of figures. This command is of use in dealing with the different syntaxes in use across Wiki sites, but is also supported for the other output formats.

Note:
.pt toc supports a two level contents, i.e. the second and subsequent paragraph levels are indented, while the first level is not. The level is taken from the last paragraph level. Normally this is correct. However, when a different level is required, the .SetPPLevel command may be used to set the level prior to using PutTOC, see 7.58.

Note:
The \Paragraph macro is usually used to add unnumbered paragraphs to the contents. A typical use is to add a Forward or a Preface to a document.

7.48 PU -- Push command

.PU String -- Alias: .Push
Operands: Single line to be pushed onto the format stack.

Pushes a single line on the format stack. See 9.2.

7.49 RP -- Replace String in Symbol

.RP Symbol, String, Value -- alias: .Replace

Operands:

1. Symbol -- identifies an existing symbol

2. String -- specifies string to be replaced

3. Value -- replacement string.This command takes three arguments, a symbol name, a string, and a value.

The symbol is searched for all occurrences of the string and the string is replaced with the value.

This command is useful in dealing with Windows' file paths that use the backslash character as a directory separator. Since STF uses the backslash as an escape character, backslashes tend to be lost when doing symbol manipulation on Windows' paths. For example, assume a symbol, say MyPath, with a value of C:\Users\Me. Then when combining MyPath with another file name, the backslash separators get lost. So
.xe .SetEsc MyPath,\esc{MyPath}\\MyFile.txt becomes
C:UsersMe\MyFile.txt and the directory information is lost. One solution is to double the backslashes inside of MyPath before doing the the symbol manipulation, so it becomes:
.RP MyPath,\\,\\\\ This doubles the backslashes so that
.xe .SetEsc MyPath,\esc{MyPath}\\MyFile.txt becomes C:\Users\me\MyFile.txt as intended. See 7.75 and 7.52 for more information.

7.50 SC -- Set Contents Starting Number

.SC Initial-Number -- Alias: .SetContentsPageNum
Operands: Integer -- Contents initial page number.

Example:
.SC 2 -- the Table of Contents will begin page numbering at Roman numeral ii. This is useful if the front matter contains numbered pages.

7.51 SD -- SetLandscape

.SD T/F -- Alias: .SetLandscape
Operands: Boolean -- specifies to include support for landscape.

SetLandscape must be called before the preamble is written, typically after CreateDocument. The startup default is SetLandscape(True), which enables landscape for pdflatex, see 9.3.9. This command may only be used before .BeginDocument.

7.52 SE -- Set Escape

.SE Key, Value -- Alias: .SetEscape
Operands:

1. Key -- a lookup key to reference the escape.

2. Value -- a value to be referenced.This command specifies an inline escape. When encountered "\esc{key}" is replaced with its "value". Preceding a key with a dollar sign, causes the environment to be searched for the key. If found the environment value is used. This is useful in dealing with special characters and short standardized paragraphs. Escapes may also be used as part of a filename in insert, copy, or include file. SetEscape may also be used to define macros, see 9.3.
   
   

   
   

7.53 SF -- Set Figure size

.SF Code, Size-spec -- Alias: .SetFigureSize
.SF scale, WxH -- Alias: .SetFigureSize (deprecated)
.SF is used to set the figure size inside of documents and also to set the figure size inside of tables. The purpose is to define a box in which to place the figure inside. The box has a width and a height.

The behavior of figures differs slightly between LaTeX and HTML⁽⁸⁾. LaTeX will scale the figure to maximally fill the box without distorting the figure. HTML will stretch the image so that the box is filled. This stretching usually distorts the image. The distortion can be avoided if the box is presized for each image or if AutoImageSize is used.

7.53.1 Scale Factor Operands

1. Code -- specifies applicability of specification, see below.

2. Scale (deprecated) -- scale factor for LaTeX. This form is now ignored.

3. WxH -- Scale for HTML, "W" is the width in pixels, "H" is the height.

4. Specification -- specifies the scaling for documents and tables, see below.

   
   

7.53.2 Scale Factor Codes

The following codes are supported:

1. D -- Document. Specification applies to LaTeX document figures, i.e. those not inside of a table.

2. T -- Table. Specification applies to figures inside of a table.

3. C -- Table. Specification applies to LaTeX figures inside of a table, however STF will calculate the appropriate scaling.

4. H -- HTML. Specification applies to HTML figures.

   
   

7.53.3 Scale Factor Specifications

Code "D" -- The specification is a LaTeX graphics option string. The default is
width=\linewidth/2,height=\textheight/2,keepaspectratio=true,scale=5
The effect of this specification is for figures to occupy half a page and scale to fill the half page without distortion. Currently STF does not support flowing text around a figure, so specifying, say a third of a page, (height=\textheight/3) will usually leave extra white space on each side of the figure. See the supported options for the LaTeX Graphicx package at https://en.wikibooks.org/wiki/LaTeX/Importing_Graphics#The_graphicx_package for a complete description of all the options. Example:
.sf D,width=\linewidth/2,height=\textheight/2,keepaspectratio=true,scale=5

Code "T" -- The specification is for the dimensions of a box: WxH, where "W" is the box width in pixels and "H" is the box height in pixels. All cells containing figures in the table will be scaled to these dimensions. Example:
.SF T,150x200

Notes:

• In LaTeX there are 72 pixels per inch.

• A typical page is 6.5 inches wide and 9 inches long.

• Figures are inserted in tables using the \fig inline command.
  Code "C" -- The specification is for the dimensions of the table: Rows,Columns[,Pad], where "Rows" is number of rows to size the table for, "Cols" is number of columns, and "Pad" is an optional amount of extra space in pixels to reserve for titles. STF will calculate the appropriate cell size to maximally fill the table. Long tables may be used, however the "Rows" specification is then for the number of rows on the first page. Example:
  .SF C,3,3,20

Code "H" -- The specification sets the box size for HTML: WxH, where "W" is the box width in pixels and "H" is the box height in pixels. Example:
.SF H,400x600. Default: .SF H,500x600.

See reference LL-6 for examples.

7.54 SN -- Set No RTF References

.SN T/F -- Alias: .SetNoRTFRef
Operands: Boolean -- specifies to omit cross references when outputting RTF format files. True disables labels and the \ref{} inline command when outputting RTF.

7.55 SL -- Set List Order

.SL n1, n2, n3, n4 -- Alias: .SetLists
Operands: A four element list specifying the list expansion order for LaTeX.

This command should be used before BeginDocument. It changes the order of list symbols. The default order for STF format documents targeting to LaTeX is: a., 1., A., a); the default order for HTML is: a., 1., A., i.. The string is a list of four numbers specifying the new order. The default is "1, 2, 3, 4". For example, specifying "2, 1, 3, 4" permutes the order to: 1., a., A., a), etc.

7.56 SM -- Set Macro

.SM Macro-Name -- Alias: .SetMacro
Operands:

1. Name -- The name of an existing macro to be added to the keyword name table.

2. Flag -- Optional boolean flag (T/F) that specifies whether or not the macro can span lines. Default False. (Inline macros can span lines, see 9.3.)
   The SetMacro command adds a macro that is already defined in an SetEscape statement to the keyword name table. After that the macro may be invoked by name. For example, the following sequence names InsertPdf as a keyword:

.SetMacro InsertPDF. Once that is done, InsertPdf may be invoked two ways:
\Esc{InsertPdf,myfile.pdf}, or as \InsertPDF{MyFile.pdf}

The second form is more intuitive, but equivalent to the first. See Using for PDF examples.

7.57 SP -- Set Parse Level

.SP level -- Alias: .SetParseLevel
Operands: Level -- sets the parse level. See 6.2

7.58 SQ -- Set Paragraph Level

.SQ level -- Alias: .SetPPLevel
Operands: Level -- sets the paragraph level.
Normally the paragraph level is set as part of the paragraph command ("PP" and "UP"), see 7.45. However when manually adding table of contents entries, it is necessary to set the paragraph level manually first. The \Paragraph macro takes of this for you. Normally this command is only used when defining special purpose macros.

7.59 SU -- Substitute

.SU trigger /phrase/ -- Alias: .Substitute
Operands:

1. Trigger -- a single character or a string. The trigger will be replaced everywhere in the document.

2. /phrase/ -- a string to replace the trigger in the document.Example defining character decimal 129, (81₁₆) as a copyright symbol:

.ifc latex | RTF .sub #81 /\textcopyright{}/ .endc .ifc html & -Text .sub #81 /©/ .endc .ifc Text .sub #81 /Copyright(c)/ .endc

7.60 SV -- Save Variables

.SV file path -- Alias: .SaveVariables
Operands: File Path -- the path to the file to contain the current variable's state.

The variables are saved in loadable format. To restore the state, include the file. Here's an example of how to make the escape variables known through out the document, i.e. those generated at the end of the document are available at the beginning:

%Restore state at document beginning .Include myvar.sti   % Save Variable state at document end .SaveVariables myvar.sti

7.61 SX -- Set Expression

.SX Key, Expression -- Alias: .SetExpression
Operands:

1. Key -- a Storage key to reference the expression.

2. Expression -- a symbol expression to be evaluated.This command specifies an inline escape. When encountered "\esc{key}" is replaced with the evaluated expression. This command is similar to .SetEscape, except any symbols referenced in the expression are replaced with their values prior to storing. See paragraph 7.77.
   
   

   
   

7.62 TB -- Include List of Tables in TOC

.TB T/F -- Alias: .UseTables
Operands: Boolean

True specifies a list of tables in the contents is required, False specifies to omit the list of tables. The default is True. This command may only be used before .BeginDocument

7.63 TC -- Table Caption

.TC String -- Alias: .Caption
Operands: Caption string
Defines the caption for the next table. If the caption is set to blank, then the table is generated without internal horizontal lines and there is no entry in the table of contents. A single column table without a caption is a text box.

7.64 TE -- Table End

.TE -- Alias: .EndTable
None
Ends a table.

7.65 TH -- Longtable header

.TH Header -- Alias: .LongTableHeader
Operands: the table header for the next longtable.

Normally columns are separated by tab characters <TAB>. Example:
.TH col 1 <TAB> col 2, ... col n
This sets the table column header for the next longtable. It must be called before the table is created.
Example:

.Caption Sample table .SetTableSepChar | .LongTableHeader No.|Description .Table |c|p{5in}|,, Long -- this identifies a two column table. The first column will be centered, the second column will be wrapped so that the table fits on the page. .row 1 | Hercules was the Roman name for the greatest hero of Greek mythology. Hercules had a god as one of his parents, being the son of the Zeus and a mortal woman. .EndTable

This expands to:

Table 7.65-III Sample Table

No.	Description
1	Hercules was the Roman name for the greatest hero of Greek mythology. Hercules had a god as one of his parents, being the son of the Zeus and a mortal woman.

7.66 TP -- Table separator character

.TP 'Char' -- Alias: .SetTableSepChar
Sets the string used to separate table columns. An empty string returns to the default of <TAB>.

7.67 TR -- Table Row

.TR Row -- Alias: .Row
Operands: columns separated by the column separation character (usually <TAB>.)

7.68 TS -- Table Start

.TS Column-Spec, [Label], [Long], [Headless], [SplitTableLines] -- Alias: .TableStart
Operands:

1. Column-Spec -- string identifying the number and alignment of each column.

2. Label -- an optional label identifier. The table number may be referenced using the label. Example: \ref{label}.

3. Long -- an optional flag indicating that the long form of the table expansion is to be used. Longtables may span pages, but no single row may be longer than a page.

4. Headless -- an optional flag indicating that the author is to provide the opening table expansion and closing table expansion. This only applies to LaTeX documents.

5. SplitTableLines -- an optional flag indicating that the table entries are to have additional line wrapping.
   Only simple tables are directly supported. These consist of one or more columns with a heading at the top of the table. The table entries are automatically enclosed in boxes.

Tables require a caption to be specified before the table start command. The Column-Spec and Label operands are positional; the flags may appear in any order after the label. The operands are interpreted as follows:

1. Column-Spec is string that specifies how many columns the table has and what their alignment is. Column-Spec has the following format: "|y | y | y| ...", where each "y" identifies a column and "y" is one of the following:

   * l -- case "L", signifies to left justify the column.

   * c -- Lower case "C", signifies to center the column.

   * r -- Lower case "R", signifies to right justify the column.

   * p{w} -- Lower case "P", specifies to wrap the column, i.e. if the lines are longer than will fit, they will be wrapped to the column width, "w". LaTeX recognizes many different units for width. Examples are: 3in, 3cm, 3pc, 144pt, for three inches, three centimeters, three pica, and 144 points. (One pc = 12 pt and there are 72 pt per inch.) an example is p{5cm} for a 5 centimeter wide column.

1. Each vertical bar indicates a vertical line in the table.

2. Label is an optional string that labels the table so it can be referred to in the document.

3. Long specifies, for LaTeX, to do the table expansion using the longtable package. This allows tables to be more than one page long. No single row can exceed the page size though. When long is used, LongTableHeader must be used previous to defining the table to set the table header. Normally when creating tables automatically, only the longtable format is used. That is because it is the more general format. Normal tables may be repositioned by LaTeX to minimize white space in the document; long tables are not repositioned.

4. Headless is a flag indicating that the author will supply the table formatting. Only the table body is output by STFxlate. The table header and other formatting information is supplied using the Verbatim command. Another use for the headless option is when using the ChangeOutput library call. This supports creating a headless LaTeX table in a separate file, which can then be inserted in multiple files. The headless table can also be used to experiment with various LaTeX formatting options to see what looks best.

5. SplitTableLines specifies, for LaTeX, to enclose table items with \seqsplit{Item} Very long sequences of chracters do not always wrap properly inside of a table column. This option fixes that. This only applies to LaTeX documents, and only has an effect with the "p{w}" column spec.

6. For normal (i.e. not long) tables, the first row specifies the table column headers.
   

   
   

7.69 TX -- Set Text Tag

.TX 'Code':'Tag' -- Alias: SetTextTag

This command only affects text generation when the "--text" output option is used.

Operands: 'Code' -- specify what is being tagged:
PN:'tag' -- prepends paragraph titles with 'tag'
For example:
.TX PN:@
would tag paragraph numbers with '@', making it easier for a parsing script to identify the start of a paragraph. An example would be:
3.2.5 title would be replaced with @3.2.5 title, etc.

7.70 UF -- Set Unwrapped Font Size

.UF size -- Alias: SetUnwrappedFontSize
Operands: Size -- An index into a size table. Only applies to LaTeX Autowrap mode. Table 7.70-IV shows the font sizes for each setting.LaTeX terminology is used to describe the font size.

Table 7.70-IV Unwrapped Font Sizes

Size	Description
-4 -3 -2 -1 0 1 2 3 4 5	tiny scriptsize footnotesize small normalsize large Large LARGE huge Huge

7.71 UP -- Define Unnumbered Paragraph

.UP Level, [Label], Title -- Alias: None
Operands:

1. Level -- the paragraph level. Even though the paragraph is unnumbered, the level affects the font.

2. Label -- optional label to receive a reference to the paragraph. It can be used to refer to the table in a \ref{} statement.If it is desired to add unnumbered paragraphs to the contents, use the \paragraph macro. For example a preface may be added as follows:
   

\cover{} cover pages ... ... insert unumbered paragraphs \ExtendFm{} \Paragraph{1,Preface} preface ... \endcover{} rest of document

7.72 VB -- Verbatim String

.VB String -- Alias: .Verbatim
Operands: A single line to be inserted in the output file with minimum processing.

7.73 WK -- Control Wiki Output Format

.WK Code,Value -- Alias: .Wiki
Operands: Format Code, the code may be abbreviated by its leading capital letter.

Table 7.73-V Wiki Format Codes

Code	Settings	Uses
Attachments	T/F	Causes figures to expand using attachments rather than as a URL or file name.
EOL	T/F	SourceForge end of lines do not require an explicit EOL mark. However many Wiki sites do. Setting EOL to True causes STFXlate to append a line break (<br>) on certain lines.
ForceAddRow	T/F	Causes Wiki row expansions in tables to use an implicit AddRow format instead of Row. The AddRow format omits horizontal lines in tables. The reason is some Wiki sites do not display horizontal table lines, but leave the corresponding white space. this causes Wiki tables to appear bloated. Setting .Wiki ForceAddRow to T inhibits the extra space making tables with short entries appear better. Tables with long entries will sometimes lose internal sync and appear shifted. So the resulting table must be examined after using ForceAddRow to see if it looks as desired or not.
Graphics	T/F	Causes graphics size to be omitted from figures. Some Wiki sites will refuse to display graphics if the size is included.
HTML	T/F	Causes href to expand using HTML syntax rather than Markdown syntax. This is normally preferred for Wiki sites that support HTML.
Line	T/F	Separates paragraph declarations with a blank line from the table of contents reference label. Some Wiki sites get confused if a contents label immediately precedes a paragraph declaration.

It is only necessary to specify enough characters to recognize the format code. Thus "ForceAddRow" may be abbreviated as "F", etc.
Example:
.Wiki EOL,T
.Wiki Line,T
.Wiki Graphics,T
.Wiki Attachments,T

7.74 WR -- Control line wrapping

.WR T/F -- Alias: .Wrap
Operands: Boolean
True, the default, causes spaces and lines to be compressed into block paragraphs and uses a proportional font. False leaves spacing alone and expands in a fixed font. Unwrapped mode is normally used for program listings.

7.75 XE -- Execute Command

.XE String -- Alias: .Execute
Operands: STF command(s).

Symbols are replaced with their values and the resulting line is pushed onto the command stack to be reread as the next command. This provides a way to parametrize commands.

Each input line gets one pass by the symbol parser, which replaces the symbols in the line. However, the parser cannot resolve nested symbols. So to process nested symbols, escape the outer symbols with backslashes and operate with .xe to replace the inner symbols and push the line on to the command stack so that it gets reread and processed normally. This second pass then replaces the outer symbols and processes the line. For example, suppose a figure has multiple definitions, depending on some external condition. Also suppose it is desired to place the figure inside of a table. The command to place a figure inside of a table is \fig{}. Because the location of the figure is variable, it must be represented as shown below:

... Define figure. Label "Alarm" was previously defined .ifc Alarm .SetEscape MyFig,C:\myfigs\Alarm.jpg .else .SetEscape MyFig,C:\myfigs\Normal.jpg .endc .caption My Table .table |c|c| .row Column 1 title<tab>Column 2 title .xe .row \\fig{\esc{MyFig},This fig does something\}<tab>\\fig{another figure\} \endtable{}

The inline figure commands \fig{}, are escaped with backslashes so that the .xe command will not process them. After the .xe command resolves the inner reference \esc{MyFig}, the line is pushed on to the command stack to be reread as:
.row \fig{C:\myfigs\Normal.jpg,This fig does something}<tab>\fig{another figure}, assuming that label Alarm was not defined.

7.76 XX -- Add to Index

.XX String -- Alias: .Index
Operands: Index string.

7.77 YA -- Activate Conditional(s)

.YA Label [, label, ..., label] -- Alias: .Activate
Operands: Label-list
Activates Conditional Labels [, label, ..., label]. 'YA' may be included inside of a conditional block, but blocks may not be nested.

A label can be a string or a label function. The label functions are as follows:

1. %Exist defines a label if the referenced path exists and removes the label from the active set if the path does not exist, syntax:
   %Exist(Label:path)

   * Starting path with a dollar sign causes 'path' to be interpreted as a symbol, see 7.52. The symbol value is used as the path.

   * If the path starts with a dollar sign or a backslash, then precede the path with a backslash ("\")

1. %Compare compares escape variables. The syntax is:
   %Compare(Label:Symbol:Op:String), where

   a. Label is a label to be activated or deactivated

   b. Symbol is an escape variable. If it is not defined, '?' is used.

   c. Op is one of the following: <, <=, =, ==, >=, >, != ('=' and '==' are synonyms for equality and '!=' indicates the test for inequality.)

   d. String is a string to be compared with the variable. To compare another symbol, reference it as \esc{Symbol-name} and prefix the '.Activate' statement with '.xe'.Labels and label functions may be intermixed in an .Activate statement.

Examples

Include file if it exists

.Activate %Exist(GetFile:myfile.sti) .ifc GetFile .include myfile.sti .endc

Analysis:
Label GetFile is activated if file myfile.sti exists. If the file does not exist, the label is deactivated. The .ifc GetFile statement conditionally includes text until .endc is encountered. So if myfile.sti does not exist, it is skipped without error.

Include File with Variable Name

.se Project,MyProject .xe .Activate %Exist(GetFile:\Esc{$Project}MyFile.sti) .ifc Getfile .include \Esc{$Project}MyFile.sti .endc

Analysis:
Escape variable Project is set to "MyProject" (see 7.52).
.xe replaces escape variables on its line and pushes the line onto the command stack to be re-input as the next line.
The dollar sign ("$") in the reference means to check the environment to see if environment variable PROJECT is defined. If PROJECT is defined in the environment, the environment overrides the value set in the SetEscape (".SE") statement; otherwise the value in the SetEscape is used.
Assuming PROJECT is not defined in the environment, the line now looks like:
.Activate %Exist(GetFile:MyProjectMyFile.sti)
If MyProjectMyFile.sti exists, label GetFile is activated.
If label GetFile is active, then MyProjectMyFile.sti is included in the document.

Conditionally Include File Defined in Environment

.xe .Activate %Exist(GetFile:$MyFile) .ifc Getfile .include \Esc{$MyFile} .endc

Analysis:
Escape variable $MyFile is defined in the environment. MyFile can also have a default value defined via SetEscape. (see 7.52.)
The dollar sign ("$") in the reference means to check the environment to see if environment variable MYFILE is defined. If MYFILE is defined in the environment or via SetEscape and the file exists, the file is included.

Notes:

1. Environment variables are defined in the environment in all uppercase. Environment variables inside the document are case insensitive, but computer environment references are not.

2. Preferencing an escape reference \esc{Name} with a dollar sign causes the program to check the environment to see if NAME is defined. If it is defined in the environment, the environment value is used; otherwise the document value is used.

3. .Include statements automatically evaluate escape references and so do not require an .xe, however the .Activate statemente does require the leading .xe to evaluate the escape reference.

Test a Variable

Check for non blank

.SE Test,Any .Activate %Compare(Lab:Test:==:) .ifc -Lab do something if Test is not blank .endc

Check for a Specific Value

.SE Section,Good Stuff .Activate %Compare(Lab:Section:==:Good Stuff) .ifc Lab do something if Section equals "Good Stuff" .endc

Compare Two Variables

.SE Section,Good Stuff .SE Test,Good Stuff .xe .Activate %Compare(Lab:Section:==:\Esc{Test}) .ifc Lab do something if Test Equals Section .endc

7.78 YE -- End Conditional

.YE [Label] -- Alias: .EndCond
Operands: Optional label to be matched with the start of block label.

7.79 YF -- Final Condition

.YF [Comment] -- Alias: .Else
Operands: Optional comment.

7.80 YL -- Alternate Conditional

.YL [-]Label [&,|] [-]Label -- Alias: .Elif
The syntax is the same as for .YS, start conditional. However .YL must be enclosed between a .YS and a .YE construct. .YL provides an alternate condition to be executed if the starting .YS is false. There may be multiple .YL statements. The first condition to evaluate as true causes all subsequent .YL statements to be skipped. See below.

Alias Expansion   .IFC label expression ... .ELIF label expression ... .ELIF another label expression ... .ELSE ... .Endif

STF Command Expansion   .YS label expression ... .YL label expression ... .YL another label expression ... .YF ... .YE

7.81 YS -- Start Condition

.YS [-]Label [&,|] [-]Label -- Alias: .IfCond
Operands: Label expression. Label expressions consist of labels and the relational logical operators:

1. '&' -- both the left and right labels must be active for the expression to be True.

2. '-' -- the next label is inverted. There must be no space between the minus sign and the following label.

3. '|' -- either the left or right label must be active for the expression to be True.
   If the expression evaluates to False, the entire block is taken to be not active. The expression is evaluated left to right without precedence. '&' and '|' must be separated by spaces. Active blocks are included in the generated document; inactive blocks are not. In the following examples, 'LABn' is a label:

LAB1 | LAB2 -- active if either label is active. LAB1 & LAB2 -- active if both labels are active. LAB1 | LAB2 & LAB3 -- active if (LAB1 or LAB2) is active and LAB3 is active. LAB1 & LAB2 | LAB3 -- active if (LAB1 and LAB2) or LAB3 is active. LAB1 & -LAB2 -- active if LAB1 is active and LAB2 is not active.

8 Including Foreign Files

STFXlate can insert the following file formats into an STF document:

1. Perl POD format files. These are processed natively in STF using the .Includefile command. See 7.31 and 5.8.

2. PDF files. PDF file may be inserted into STF documents via the \InsertPDF{...} macro. InsertPDF also requires that the \setupPDF{} macro be used in the STF file preamble to prepare the document to insert PDF⁽⁹⁾ files in the STF output. specifying LaTeX output directly inserts the PDF file with the standard document headers and footers; specifying HTML output inserts references to the PDF file.

3. Word Documents. Word documents may be converted to PDF and processed via the \InsertPDF macro. Word documents may also be converted to TeX via docx2tex and the resulting .tex file inserted in the LaTeX output. TeX format files are inserted using the .InsertFile command. Direct inclusion of Word documents into HTML is not supported, use the PDF format.

4. ASCII Text. ASCII text files sometimes use extended ASCII, (codes > 128) to represent special characters. For this case, the \EXTASCII{} macro inserted in the preamble will cause STF to recognize the extended ASCII characters. There is also a case where the ASCII quotation mark is used for both right and left quotes. For this case insert .FilterQuotes T in the preamble. .FilterQuotes attempts to match right and left quotation marks and format them appropriately.
   

Using the \insertPDF Macro

InsertPDF has four parameters:

• file -- path of PDF file, Required.

• scale -- Scale factor, i.e. the percentage to shrink the PDF document so that it will fit on a page. Optional, default=0.85.

• page-spec -- specifies which pages to insert; Optional; default all. See the documentation on the web for the pdfpages package. Typical examples are: 1, for for the first page; 2-3, for pages two and three; 1,4-5, for the first page and pages 4 and 5, etc.

• Angle -- rotation angle, Optional, default = 0. Positive values specify a clockwise (left) rotation; negative values specify a counterclockwise (Right) rotation.An example is:

Create MyDoc,PDF example ... preamble commands go here \setupPDF{} .Begin blah blah \insertPDF{Myfile.pdf}

This inserts a PDF file with the standard document headers and footers. Another example of merging PDF files is:

... Merge PDF files ... include PDF header \setupPDF{} ... use Cover macro with no front matter \Cover{} ... end cover \EndCover{} ... make InsertPDF a key word .SetMacro InsertPDF ... insert a PDF file scaling=1, entire document \insertPDF{Myfile.pdf;1} ... insert a PDF file scaling=1, pages 1, 3-5, and 10 \InsertPDF{NotherPDF.pdf;1;1,4-5,10} ... insert a PDF file default scaling, entire document, rotated 90 degrees \InsertPDF{MorePDF.pdf;;;-90}

Because there are no front matter commands, the document is produced without page numbers or titles. In effect the specified PDF documents (and pages) are merged into a single PDF document.

9 STF Internals

9.1 Creating Documents

There are two commands that are required to create a document:

1. .dc -- CreateDocument.The CreateDocument command has two operands: the document name and the document title. The CreateDocument command is the first command in any STF document.
   

2. .bd -- BeginDocument.
   The BeginDocument command has an optional operand: Cover. Cover signals HTML and Wiki formats to allow for a cover page.

The information between these two commands defines the document preamble. Additional commands may be used to indicate how the document is to be expanded. See the \Cover macro, below.

9.1.1 Alternatives to .BeginDocument

There are two macros designed to simplify the document start up process: Cover and Setup.

9.1.1.1 The Cover macro

The cover macro is used to setup a custom cover page. It is used instead of both .BeginDocument and .CreateDocument. The cover macro supports the following operands:

1. .UseContents T -- means to include a Table of Contents after the cover page(s), .CN T or .TOC T may also be used.

2. .UseTables T -- means to include a list of tables in the contents, .TB T may also be used.

3. .UseFigures T -- means to include a list of figures in the contents, .FG T may also be used.

4. .UseIndex T -- means to include an index at the end of the document, .IX T may also be used.Notes:

5. Other preamble commands may be used before \Cover, i.e. it is not necessary to use CreateDocument when using a cover page.

6. Cover page(s) are terminated by \EndCover{}. See \Endcover below.
   Example:
   \Cover{.CN T, .TB T} -- Specifies to use a cover page and include a Table of Contents with a list of tables.
   

   
   

9.1.1.2 The EndCover Macro

The end cover macro is used to close cover pages. It is the same as the .CV F command except it includes a horizontal line separator for the HTML and WIKI formats. This improves readability. See 7.14.

Example:
\EndCover{}

9.1.1.3 The Setup Macro

The setup macro is used to define a standard cover page. It is used instead of both .CreateDocument and .BeginDocument. The setup macro has the following format: \Setup{Doc-Name,Doc-Title,[Description],[Cover]}.

1. Doc-Name, this is the first parameter and is a short name that can be used to refer to the document.

2. Doc-Title, This is the top of page title.

3. Description, this is an optional description. Multiple lines are separated by <TAB> characters.

4. Cover, this is an optional flag and is used to indicate that a custom cover page is to be used. This is deprecated, use the \Cover macro instead.
   \Setup provides a simple way to define a standard cover page. Examples:
   \Setup{Mydoc,A better Way to Grow Beets,~<tab><tab><tab>By<tab><tab><tab>Mortimer Snerd}
   This creates document "MyDoc" with a title of "A better Way to Grow Beets" and a description of "By Mortimer Snerd." A similar example with an explicit cover page is:

\Cover{.UseFigures T,.CN T,.UseTables T} \Center{\Largest{A better Way to Grow Beets}} \Vskip{} blah blah blah \Vskip{} \Center{By} \VSkip{} \Center{Mortimer Snerd} \Vskip{} Printed on \esc{date} \EndCover{}

9.2 Internal Stacks

There are two stacks that are used to control the operation of STFXlate: The format Stack and the command stack. The format stack holds commands that are inserted into the command stream when a right brace ("}") is encountered. The command stack holds pending input lines. Various commands push data onto these stacks.

A right brace ("}") causes the Format Stack to be popped and the extracted line inserted into the output file.

The command stack substitutes for the current input file as long as it is not empty.

9.3 STF Macros

9.3.1 Types of Macros

There are several types of macros:
Replacement Macro -- the macro is defined to be a block of text. When the macro is encountered, it is replaced by the text block.

Inline Macro -- the macro acts like a new inline command. This type of macro operates on a block of text. When encountered the macro pushes the commands to close the macro on to the format stack and inserts commands to open the macro into the text stream. All text between the macro and the closing brace are affected by the macro's commands.

Keyword Macro -- This form of macro accepts parameters and inserts commands into the text stream based on its parameters.

9.3.2 Macro Syntax

.SetEscape and \Esc{} form a simple macro facility.
SetEscape defines a macro template and \Esc references it.
The template may contain replaceable parameters and is defined as follows:
.SE Name, {Cmds}[header]=/body
where defaults and directives for the replaceable parameters precede the equals sign and are enclosed in square brackets, ("[...]"); an equals sign separates the defaults from the body. The first character after the equals sign is the line separator. The line separator separates multiple lines in the body. Syntax:

1. .SetEscape defines the macro Name. SetEscape may also be abbreviated as .SE.

2. "Name" is the name of the macro and is case insensitive.

3. "{Cmds}" specifies commands to close the macro when the associated ending brace ("}")is encountered. "Cmds" are optional. If they are omitted, the curly braces ("{}") are also omitted. Unpaired braces and backslash characters must be escaped.

4. "[header]" specifies default values for parameters, and is optional. The default parameter separation character is the comma.

5. "=/" specifies that the macro has multiple lines, and may have replaceable parameters. The "/" is the line separation character. Any ASCII character may be used in place of "/".

6. If the equals sign is missing, the unedited body replaces the macro when the macro is invoked.

7. The body specifies the parametric lines to replace the macro in the document.

8. Parameters are indicated by an alphanumeric string starting with a dollar sign ('$'). An example is $Name. The names of replaceable parameters are case sensitive, so frequently they are indicated as numeric only. An example is "$1".

9. The header consists of leading flags followed by default values for parameters. There aretwo possible flags. If the first character following the left bracket is an asterisk ("*"), then
   parameter names are defaulted to "$@@@nn" and the second character defines the
   parameter separation character. If the first character following the left bracket is not
   an asterisk, then it is the parameter separation character. If the parameter separation
   character is omitted, then the entire body is the first (and only) parameter. For example
   [*], or [ ], omits the parameter separation character.

Defaults are specified as $parm=value. Multiple defaults are separated by the parameter separation character.

The macro body consists of one or more logical lines, separated with the line separation character.
Macros are invoked using the \Esc{...} inline statement. The format is:
\esc{Name,$1=value1/$2=Value2...}. Each line has the parameters replaced with their corresponding values and then the first line of the macro body replaces the "\Esc{...}" statement itself and the rest of the lines in the macro body (the second and subsequent) are pushed on to the command stack. New input lines are read from the command stack until it is exhausted and then input returns to the input file.

9.3.3 Defining Replacement Macros

Replacement macros are defined by SetEsc as follows:
.SE Name, text

Name is the macro name and "text" is a block of text. Escape a leading bracket ("["), a leading curly brace ("{"), or equals sign ("=") with a backslash ("\").

9.3.4 Defining Inline Macros

Inline macros are defined using SetEscape as follows:
.SE Name, {CloseCmds}=OpenCmds
Name is the macro name, "CloseCmds are the commands necessary to close the macro and "OpenCmds" are the commands that open the macro. STFXlate inserts the open commands into the text stream. When the closing curly brace ("}") is encountered, the closing commands are inserted into the text stream. Inline macros must be followed by a .SetMacro command specifying the macro as being an inline macro, see paragraph 7.56.

9.3.5 Defining Keyword Macros

Keyword macros are defined using SetEscape as follows:
.SE Name, [flagsDefaults]=/template. The fields are defined above.

9.3.6 Macro Examples

Superscript macro

Example:
blah\sup{superscript} blah, this would print as: blah^superscript blah

... Superscripts ... Usage: \Sup{xxx} .ifc latex | rtf .SetEsc Sup,{\}}=\textsuperscript{ .endc .ifc html & -Text .SetEsc Sup,{</sup>}=<sup> .endc .ifc text .SetEsc Sup, {>}=^< .endc .sm Sup,True

Landscape Macro

Example of using landscape:

\Landscape{begin} lots of text \Landscape{end}

The landscape macro:

... ...Mac Landscape ... Define Landscape Mode ... Usage: ... \Landscape{begin} ... \Landscape{end} ... .ifc Text | RTF .SetEsc Landscape, [*]=//$@@@01 Landscape/ .endc .ifc Html .SetEsc Landscape, [*]<!-- $@@@01 Landscape--> .endc .ifc LaTex & -RTF .SetEsc Landscape, [*]$@@@01{landscape} .endc .sm Landscape

Include POD File with Bias

...Mac GetPOD ... Import POD file with Bias ... bias and list of labels are optional ... Usage:   \GetPOD{'Filename',bias;,Label-list} ... Sample1: \GetPOD{PerlDoc.pl;2;,label,lab2} ... Sample2: \Esc{GetPOD,PerlDoc.txt;2} ... Sample3: \Esc{GetPOD,PerlDoc.txt} .SetEscape GetPOD, [*;$@@@02=0;$@@@03=]=//.Include $@@@01,POD$@@@03/=qv .Bias $@@@02/ .sm GetPOD

Center Macro

Example:
\center{blah} would print as:

blah

... ...Mac Center ... Usage: ... \center{paragraphs to be centered} ... .ifc Text | RTF .SetEsc Center, {</Center>}=<Center> .endc .ifc Html .SetEsc Center, {</center>}=<center> .endc .ifc Latex & -RTF .SE Center, {\end{center\}}=\begin{center} .endc .sm Center, True

9.3.7 Macro Usage

The syntax of referencing macros via \esc{Macro-Name,Parameters} is a bit awkward. It can be improved by using the .SetMacro command. SetMacro adds the macro name to the Keyword table. After that the macro may be referenced as
\Macro{parameters}. See 7.56.

9.3.8 Adding commands to Include Files

As shown above in the POD macro example, including files via macros permits commands to be added at the top of the included file. The method is to define a macro and use the macro feature of pushing macro lines after the first macro line onto the command stack. The command stack is read after the first macro line is interpreted, which in this case is .IncludeFile. However, .Bias defined inside of an include file reverts to the original (parent file) value and labels defined in an include file disappear when the include file exits.

9.3.9 Landscape Support

Landscape mode is supported when targeting to LaTeX. STFxlate includes partial support for landscape mode. The rest of Landscape mode is implemented as a macro.

Header command SetLandscape controls whether landscape support is included or not. The reason why this is conditional is because the support package for pdflatex is different from that of latex. For pdflatex, use \usepackage{pdflscape}; for latex, use \usepackage{lscape}. The default is to include support for pdflatex.

When targeting to RTF, SetLandscape is automatically set to False -- latex2rt generates an error and stops on encountering a landscape usepackage directive.

The Landscape Macro

Assuming SetLandscape is true, or support for pdflatex has been inserted into the header manually, then the Landscape macro controls the landscape mode as follows:

\landscape{begin} turns landscape mode on, and \landscape{end} turns it off. The landscape macro is part of the sample macros included with STFxlate, see paragraph 7.52.

9.4 Predefined Symbols

The following symbols are predefined and may be referenced using \Esc{symbol-name}.
They may also be explicitly overridden in the document. Thus setting "DATE" to a fixed value effectively sets the printed document date. Predefined symbols may also be specified in a Set macro (.SM) statement, after which they may be referenced as \Symbol-name{} instead of \Esc{symbol-name}, see Esc and also 7.52.

Table 9.4-I Predefined Symbols

Symbol	Usage
CDIR	Directory path to current input file
DATE FEXT FNAME INPUTROOT	Current date Extension of the input file Basename of the input file Directory path of input file
LASTPARSE	Last parse level. May be used to return to the parse level prior to the the last .SetParse command
OS	Name of operating system. For example, "NT" implies Windows like, and "posix" implies UNIX like.
STFHOME TARGET	Directory path of STFXlate configuration files. Name of current output file type. For example, specifying --latex on input would implicitly set TARGET to LATEX.
TIME UPDATE_PENDING	Current time Set to "T" or "F", corresponding to True or False. UPDATE_PENDING is set when the --update switch is specified. See 5.10.
USERNAME $SYSTEMMACROS	Registered name of current user Optional environment variable containing the path of installation dependent macros file. This file is used by companies to append standard company macros. Such as a company boilerplate, for example.
$USERMACROS $STF_STARTUP $STF_CONFIG	Optional environment variable containing the path of user macro file. Optional environment variable containing path of start up file. Optional environment variable containing path of configuration file.

Notes:

1. $STF_CONFIG specifies the name of an initialization STF file. The file is interpreted prior to the input file. The initialization file may contain a Create Document and/or a Begin Document command, in which case the input file may not contain these commands. The configuration file may be also specified as switch --config and may be used to add standard attributes to a set of documents, such as always specifying an index and a list of tables and figures in the contents. It may also be used to always specify a local preamble. If both are specified, --config overrides $STF_CONFIG.

2. $STF_STARTUP specifies the name of a start up STF file. The file is interpreted immediately after the Begin Document command. The start up file may not contain document preamble commands, such as Begin Document. A typical use would be to establish local document defaults. The file may also be specified as switch --start. If both are specified, --start overrides $STF_START.
   

   
   

9.5 Lists

Up to four nested list levels are supported: "a.", "1.", "A.", "a)". The reason why the first list level is alphabetic is to be able to refer to paragraphs by number. If the first list level were numeric, then it would not be possible to distinguish between paragraph 1.2.3, where "3" is the last number of the paragraph and paragraph 1.2.3 where the last paragraph number is "2" and the "3" refers to the third list element. The latter case becomes, if the first list level is alphabetic: paragraph 1.2.c. See paragraph 7.55 for information on how to permute the list labeling order.

Notes:

The max size of an alphabetic list is 676 elements; after which the list letters repeat.

For how to refer to a list element, see: 7.36; for how to start a list, see 7.37.

Lists do not continue past paragraph boundaries; a paragraph command automatically closes all open lists.

Example:

.pp 3,xmpl,List Example .ls .le first paragraph .ll blah, second paragraph .ls bullet .le first bulleted paragraph .le etc. .el .el   see paragraph \ref{xmpl}-\ref{blah,page}.

This would expand as follows:

9.5.10 List Example

1. first paragraph

2. second paragraph

   * first bulleted paragraph

   * etc.
see paragraph 9.5.10-LL-1.

9.6 Working With Symbols

STF supports several kinds of symbols. They serve different purposes and exist in their own space. The different kinds and their purpose is shown in Table 9.6-II.

Table 9.6-II Kinds of Symbols

Kind	Purpose	How Ref.	Set By
STF Label Esc Variable Doc Label Anchors	conditional processing replacable parameters document information document locations	.IfCond \esc{} \ref{} \dref{}, \dpage{}	.Activate, .YA .SetEscape, .SE, \fig{} .Table, .Figure, .ListLabel, PP \dlink{},\fig{}

It should be noted that the .Figure command defines a document Label, while the inline Figure command, \fig{}, defines both an escape variable and an anchor. The reason is that LaTeX figures are designed to reposition themselves so as to fit well on a page. Thus LaTeX won't allow defining a label inside of a figure inside of a table. So to compensate, the inline figure number is stored in an escape variable and the page location is stored in an anchor.

The HTML/Wiki formats don't have a concept of a figure so it is not a problem for HTML/Wiki⁽¹⁰⁾. When targeting to LaTeX or RTF, it is necessary to use \dref{} when referring to an inline figure location⁽¹¹⁾. Examples:

Referencing an Inline Figure

Assume "\fig{file.jpg,MyFig,This is an inline Figure}" was used to put a figure inside of a table. \Fig{} will assign the generated figure number to escape variable MyFig, it will also define an anchor of the same name. A typical reference looks like this:
Blah blah see figure \dref{MyFig, \esc{MyFig\}}\dpage{MyFig,~On Page~}. This would display as:
Blah blah see figure 'Figure-num' on page 'page-num', where the hot links will move to the indicated locations. The reason why the inner brace ('}') in \dref is escaped is to delay expanding the reference until it is inside of the \dref{} expansion. HTML and Wiki formats also support this syntax (although page references are ignored because HTML and Wiki documents have no pages).

Referencing an Ordinary Figure

Assume the command ".Figure MyFig2.jpg,MyFig2,This is a figure" was used to place a figure inside of a document. This defines a document label, myfig2, and associates the figure number and location of the figure inside of the document with it. So to reference the figure, use:
Blah blah see figure \ref{MyFig2,Page}. This would display as:
Blah blah see figure 'Figure-num' on page 'page-num', where the hot links behave as before.

9.7 Generating an Index

STFXlate automatically generates an index for HTML, and Wiki formats. LaTeX generates the index for LaTeX files. Normally RTF files are generated with the index and contents turned off. Although the index references are embedded in the RTF output file, it is up to the operator to decide where to put the index and contents and to manually generate them.

LaTeX uses a two step process to generate indices. The first step is to write index references to 'doc-name'.idx. The "idx" file consists of a list of index references and their coresponding page number. The second step is to create an "ind" file from the "idx" file. This is done by using anyone of several "make" index programs. The default, for MikTex, is makeindex.exe. Makeindex supports subcategories and many other options. However the current index generated for HTML and Wiki outputs does not support subcategories. Also, apparently makeindex gets confused if the entries contain LaTeX formatting commands. So, for example, the "ind" entry: "\indexentry{\textbackslash{}Smaller|hyperpage}{C1}", which specifies a reference to "\smaller" on page C1 gets omitted because of the embedded braces. So to make the indices consistent between the various output formats, a short Python script, MOIP⁽¹²⁾ is included that supports LaTeX embedded formatting commands. However, MIOP does not at this juncture support subcategories.

The default command file to generate documents makeDoc.bat, is setup to use MOIP.py. The commands to use makeindex.exe are included as comments. If you want to use makeindex, just switch the comments, i.e. comment out MOIP and uncomment makeindex. See paragraph 7.34 for more information.

10 References

10.1 Internal References

1. Syntax Summary (This document), in PDF format and in Wiki format.

2. Create Document with Cover, in PDF format and in Wiki format.

3. Test Report Generator (TRG) Description, in PDF format and in Wiki format. This is a working example -- use the TRG to generate test reports.

4. Creating a document under program control, in PDF format and in Wiki format. This document shows how to use the Python API to create reports.

5. Working With Images in PDF format and in Wiki format. This a more detailed description of how to use Figures.

6. Working With the GUI in PDF format and in Wiki format. This a description of the GUI that comes with STF. The GUI is used to execute commands by clicking on files. This makes it easier to implement a process, such as developing an STF document.

7. STF Library Description in PDF format and in Wiki format. This is a description of the Python API. #

   A P P E N D I C I E S

Appendix A - Debugging

It can be vexing dealing with a process with multiple layers, such as the one described herein. In this case the layers consist of the following programs:

• Generating program -- typically written in a high level language, such as C, C++, Python, etc. This produces the STF file.

• STFxlate.py -- the translator from STF format to LaTeX or HTML formats:

   - Input to STFxlate can be in STF format or in Perl's POD format.

   - STFXlate is launched using the Python interpreter.

   - STFXlate is usually launched via command file STFXlate.bat. STFXlate.bat creates a temporary file named: "000STF_Working." When "000STF_Working" disappears, it is safe to examine the PDF or HTML output files.

• Pdflatex -- the program that converts STF output (*.tex) to PDF format:

   - Pdflatex -- requires at least two passes if a contents or an index is required.

   - Makeindex is the program that generates an index for pdflatex.

• LaTex2rt (or LaTeX2rtf) -- the program that converts STF output, .i.e the resulting *.tex file, to RTF format.Here some suggestions on how to debug the process when something goes wrong:

a. Review the log files. The STF log file is named using the input file name as: "File-name'_STFxlate.log". So if the input is "Test.stf", the log would be named "Test_STFxlate.log". The STF log file is the first file to check for errors. Error messages refer to the line number in the input file that caused the error. If the STF log file has no errors, then a clean representation of the document may be obtained by specifying HTML output. This can be an assist in determining what the LaTeX error is.

b. LaTeX errors are recorded in "File-name'.log". This is the LaTeX log file and is the second place to check for errors. Search for "error" to identify errors. Next view the STF output file, "File-name'.tex", and look at the line indicated in the LaTeX log file. If XEmacs is used to view the file, <Alt-G> may be used to locate the line number in a text file. The surounding context may be used to determine the problem line in the STF input file.

c. Catastrophic LaTeX errors cause pdflatex to halt and usually leave file texput.log in the execution directory. If it remains after execution, examine it for error messages.

d. Turn on the debug trace by specifying --debug when invoking STFxlate. Then examine the LaTeX input file ("'File-name'.tex"). The file will contain the original STF input lines as comments.

e. After fixing an error delete all the left over auxillary files before retrying. These include files with the following extensions: "*.aux", "*.log", "*.out", "*.toc", "*.idx", "*.ilg", "*.ind", "*.lof", "*.lot", and "*Con.html". This will prevent stale information from confusing your results. SuperCleanSTF.bat is a convenience command file included with STF that deletes the leftover files.

f. Because POD files are converted to STF format as they are read, --debug may not identify the problem.

   * The first thing to do if a problem is suspected with a POD file, is to run the Perl POD file checker, see http://perldoc.perl.org/Pod/Checker.html.

   * If there are still unidentified problems use the Half-Interval method to isolate them. The way this works is to first estimate the mid point of the input POD file and insert "=qv .ef". The '=qv' command is not really a POD command, but is included to make debugging easier. In this case, it inserts the STF ".ef" command into the file at that point. ".ef" represents a soft end of file. Delete the auxiliary files mentioned previously and rerun the file. If the error persists, delete the "=qv .ef" and move it up half way and reinsert it. Process again. Continue to move the end of file upwards or downwards by halves until the bad section is isolated. Putting "=qv ... " on the start of a line changes it into an internal comment, which removes it from processing. This technique may be used to further diagnose the problem.

g. The half interval method may also be used to advantage with any STF input file. Simply position the soft end of file command .ef up and down the file, until the output error disappears. The syntax error must be located after that point in the file.

h. A further technique exists when debugging STFXlate.py itself. This is to insert ".Break" at strategic points inside the input file being used for testing. The .Break command has no effect on the resulting outputfile, but it does provide a convient place to set a break point inside STFXlate.py. .Break may be abbreviated as .BK.

i. Unrecognized keywords usually result in question marks being inserted in the output file. So searching the PDF or HTML output for "?" may be used to identify the context of the invalid keyword.

A.1 Pitfalls and Hints

a. There are two places where unexpected text causes strange results. These are inserting text between the list start command (".ls") and the first list element (".le"), and inserting text between the table start (".ts") and the first row (".row"). If the document looks strange, check for those errors.

b. The first character after the .row command in a table is a space, not a <TAB> or comma.

c. .hl and .pp are separated from the paragraph title with a comma.

d. When the STFXlate log is empty, it is usually safe to run SuperCleanSTF.bat to remove all the extraneous files produced by the document generation process.

A.2 Spell Checking

There are several techniques that can be used to spell check an STF document:

a. Edit the PDF version in a PDF editor that supports spell checking. For example, Libre Office and Open Office both support spell checking PDF documents.

b. Use the UNIX grep⁽¹³⁾ command to locate the sub-document with the error.

c. Another technique when importing sub-documents from various sources is to define a macro that includes the sub-documents. The macro should expand normally when debug is False, but it should list the path in the document when debug is True. So to spell check complicated documents, first turn on Debug, next generate a PDF representation, then edit the PDF using, say, LibreOffice⁽¹⁴⁾.

d. Another technique is to target to RTF and then use a word processor to spell check the document.

e. Direct spell checking of an STF source may be done using Aspell, available from: http://aspell.net/.

A.3 Debugging Macros

The best way to debug macros is to turn debug on. This is accomplished by putting .db T or .db T,T (see 7.15 near the top of the document source file. This inserts debugging information as comments into the specified output file. Since WIKI (Markdown) format does not support comments, the commentary is inserted into the log.

Appendix B - Installation

STFXlate requires the Python interpreter to run. If PDF output is desired, then a LaTeX formatter is also required. Also the standard installation includes many convenience command files and scripts that make the process of processing STF much easier. The recommended installation is as follows. The last column in the following table indicates whether the program is required (R), Optional (O), or included with the distribution (I).

Table B-I Typical STFXlate Installation

Program	Purpose	Location	ROI
DocBook Converter	Create DocBooks	http://pandoc.org	O
Docx2tex Converter	Convert docx to tex	http://docx2tex.codeplex.com/	O
E-Book Creator	Calibre	http://www.calibre-ebook.com	O
ExecutorDrvr.bat	Convience-Cmd	C:\Users\Public\Cmds	I
Executor.py	Displays Command Menu	C:\Users\Public\Cmds	I
GhostScript	Convience-Cmd	http://sourceforge.net/projects/ghostscript/?source=dlp	O
Gnuplot	Plotting and Charting Software	https://sourceforge.net/projects/gnuplot/files/	O
Imagemagic.exe	Convience-Cmd	http://www.imagemagick.org/script/binary-releases.php	O
Install.bat	Install STF for Windows	C:\Users\Public\Cmds	I
LyX	Convert LaTeX	http://www.lyx.org/Download	O
makeDoc.bat makeDocWithIndex.bat	Convience-Cmd Convience-Cmd	C:\Users\Public\Cmds C:\Users\Public\Cmds	I I
makeImageBooklet.bat makeImageBooklet.py makeRTFDoc.bat NewSTF.bat	Convience-Cmd Convience-Cmd Convience-Cmd Convience-Cmd	C:\Users\Public\Cmds C:\Users\Public\Cmds C:\Users\Public\Cmds C:\Users\Public\Cmds	I I I I
MikTeX(15)	LaTeX processor	http://www.miktex.org, https://www.tug.org/texlive/	R
POD	Perl Pod Format	http://en.wikipedia.org/wiki/Plain_Old_Documentation	O
Python	Execute STFXlate	http://www.python.org/download	R
LaTeX2RT	Create RTF Output	http://latex2rtf.sourceforge.net	O
stflib.py	Python API	C:\Users\Public\Cmds	I
STFxlate.bat STFXlate.py	Convience-Cmd STFXlate	C:\Users\Public\Cmds C:\Users\Public\Cmds	I I
STFASCII.stf	Define Extended ASCII	C:\Users\Public\Cmds	I
StfMacros.stf	Define Standard STF Macros	C:\Users\Public\Cmds	I
SuperCleanLatex.bat SuperCleanSTF.bat ViewSubDoc.bat	Convience-Cmd Convience-Cmd Convience-Cmd	C:\Users\Public\Cmds C:\Users\Public\Cmds C:\Users\Public\Cmds	I I I

B.1 Installing Python

The first step is to install the latest version of Python (from either the python 2 or 3 series.) The Python installer may be downloaded from
https://www.python.org/downloads. Download the Python installer and double click it. It is strongly rcommended that you read the How To Geek Article on installing Python at https://www.howtogeek.com/197947/how-to-install-python-on-windows/ prior to doing the installation. STFXlate will operate correctly using either Python 2.7+ or Python 3.6+.

B.2 Installing the Rest of the Software

STF is part of the Nuances In Computing (NIC) utilities. NIC utilities refer to sub directory %USERPROFILE%\.nic^(16),(17) for configuration information. NIC utilities are stored in subdirectory C:\Users\Public\Cmds⁽¹⁸⁾.

The second step is to execute the install script: Install.bat. The install script is designed to be executed from a disk -- either DVD or hard drive. If you are installing from a web site, download the utilities to a hard drive or DVD ROM first. Then double click Install.bat (located in directory STF.) All the included software will be installed.

B.3 Updating the Registry

Windows stores configuration information in a database called the Registry. It is possible to write scripts or programs to update the Registry, but it is difficult to avoid privilege problems when automating Registry updates. Windows is designed to block unauthorized programs and scripts from making changes to critical areas in the Registry. So the easiest way to finish the installation is by manually making a few changes to the Registry. Fortunately Microsoft has included ways of making Registry changes without having to directly edit the Registry.

B.3.1 Updating the Path

The first change is to add the NIC utilities to the path. For Windows 7 and 8, click on Start and enter 'system' (but don't press enter.)
Click on System
Enter Advanced System Settings in the find a setting search box.
Click on Environment Variables.

For Windows 10, press <Win><X> (hold down the windows key and press X)
Click system
Enter Advanced System Settings in the find a setting search box and click the find action.
Click on Environment Variables.

Edit the system environment variables, not the user environment variables.
Scroll down until the Path variable is highlighted and click on 'Edit'. Add C:\Users\Public\Cmds;C:\Pythonxx; to the beginning of the path; or add ;C:\Users\Public\Cmds;C:\Pythonxx to the end of the path and save. Where 'Pythonxx' refers to the directory where python is stored. For example 'python27' refers to the directory for python 2.7.

B.3.2 Convenience Associations

Windows (and UNIX) provide the option of associating file extensions with a program designed to process the file. For example, double clicking somefile.doc will open a word processor to edit the file. Similarly double clicking somefile.html will open a browser to display the file.

Windowing systems present a graphical, mouse controlled, interface. So to maintain the feel of windows as much as possible, convenience commands should be invokable via the mouse. Convenience commands provide easy ways to command a PC to do useful things.

STF includes another python script that associates actions with files. This is Executor.py. Executor presents a menu of actions when invoked based on the file's extension. To complete the file associations, right-click on a file with an extension of 'stf'. and select properties. Under opens with, click Change. Click more apps and scroll down to the bottom of the list. Click look for another app on this PC. Enter C:\Users\Public\Cmds\ExecutorDrvr.bat in the file name field. Click OK. This adds the extended menu to STF files. Executor stores its default configuration in C:\Users\'you'\.nic\Executor the first time it is executed. You may edit the configuration as desired. See figure B.3.2-2 to see what the default menu looks like.

Figure B.3.2-2 File Associations Menu

Table B.3.2-II STF File Associations

Utility

Function

Wordpad makeDoc makeDocWithIndex makeRTFDoc ViewSubDoc SuperCleanSTF SuperCleanLatex NewSTF.bat xemacs

Editor Generate PDF and HTML with no index or contents Generate PDF and HTML with an index and/or contents Generate RTF format output Generate a doc for viewing from an STF include file Remove *.aux, *.lof, *.out, *.toc, *.idx, *.con, *.lot, *.log, *.ilg, *.ind, *.*~, and *.tex files Remove *.aux, *.lof, *.out, *.toc, *.idx, *.con, *.lot, *.log, *.ilg, *.ind, *.*~ files Generate a model STF document Edit files using XEmacs (must be installed separately)

Double clicking on an STF file will display the menu. Select the desired option.

B.3.3 Typical Use

Developing a document is an iterative process. Typically you double click on a STF file. Choose makeDocWithIndex from the menu. Examine the size of the STFXlate log file. If it is zero, double click on the STF file again and choose SuperCleanSTF. This removes all of the LaTeX temporary files. If the log is non zero or if file texput.log is present. Examine the log files for errors first.

B.3.4 Included Files

The following files are included with the distribution:

Table B.3.4-III Included Files

File	Function
STF stflib Summary CaseStudy_TestReport	Directory containing the STF Source and command files. Directory containing stflib.py the Python API interface library. Directory containing the STFXLate Syntax Summary and document source. Directory containing a sample Test Report Generator written using stflib

B.4 Installing Under UNIX/Linux

The following directories are used to implement STF on Linux/UNIX:

a. $HOME/.nic -- NIC is short for Nuances in Computing, a book written by this author and languishing to be published. Most of the ideas used to design and implement STF were taken from NIC.

b. $HOME/.nic/Executor -- holds Executor.py. The Executor intiialization file, Executor.ini, is automatically created at first use. It may be edited as desired.

c. $HOME/.nic/STFxlate -- Holds STFXlate.py and associated configuration files. During installation, copy in the following files:

   * MOIP.py -- My Own Index Program. See paragraph 9.7 for details.

   * STFASCII.stf -- A macro to define the extended ASCII character set.

   * StfMacros.stf -- the standard STF macros.

   * STFxlate.py -- the program to implement STF. STFXlate will add the standard configuration files on first use. They may be edited as desired, but be sure and save a backup as STFXlate will overwrite them whenever it is updated.

d. $HOME/.local/share/nautilus/scripts -- Holds Nautilus scripts. Copy 1Menu here.

e. $HOME/.local/share/nautilus/scripts/STF -- Holds the following STF implementation scripts:

   * makeDoc -- Creates PDF and HTML documents from STF sources.

   * makeDocWithIndex -- same as makeDoc only adds a contents and, optionally, an index.

   * makeRTFDoc -- Creates RTF documents using latex2rtf.

   * makeWiki -- Creates wiki documents from STF sources.

   * newSTF -- Creates a sample STF template.

   * superCleanLatex -- removes trash files from the directory, but leaves *.tex files.

   * superCleanSTF -- removes trash files from the directory.

   * viewSubDoc -- Creates a temporary STF source used to display yhe chosen file as an STF document.

f. $HOME/.profile -- profile establishes session defaults. a sample .profile file is included in the STF distribution.The Nautilus shell scripts use python3, a link to python 3. Feel free to edit the scripts or to adjust the links as necessary.

Appendix C - Standard Macros

The following macros are defined in file StfMacros.stf. Usage notes are contained in the file.

Table C-I Standard STF Macros

Macro	Purpose	Usage
Box	define box table. 7.63	\box{}
Center CIncludeFile Copyright Copyright CheckForUpdates	Center lines Conditionally include file if it exists define copyright symbol define copyright symbol Compare current STFXlate version against cloud version and create UpdateMe.txt if there is a new version available for download.	\center{lines} \CIncludeFile{file-path} \#81 \Copyright{} \CheckForUpdates{}. --update and --latex(19) must also be specified.
Cover EndBox EndCover	Setup for cover page see 9.1.1.1 Ends a text box, synonymous with \EndTable{}. 7.63 Close cover pages see 9.1.1.1	\Cover{options} \EndBox{} \EndCover{}
EndTable	End table so that LaTeX and HTML look the same. 7.64	\EndTable{}
EXTASCII ExtendFM GetPOD	Define extended ASCII character set Extend Front Matter Include Perl POD File	\ExtASCII{} \ExtendFM{} \GetPOD{file;bias;,labels}
Hline IfLab	Insert horizontal line Insert multiple lines if Label expression is true see 7.77	\hline{} \IfLab{label^Line^...^Line9}
InsertPDF	insert PDF file	\InsertPDF{file;scale;page-spec} See Using
Landscape Large Larger Largest LaTeX Newpage Paragraph	Turn landscape mode on/off Large Font Larger Font Largest Font define LaTeX print symbol Insert page break Add unnumbered paragraph to contents	\landscape{begin | end} \Large{text} \Larger{text} \Largest{text} \Latex{} \newpage{} \Paragraph{level,Title}
ProgramListing	Turn Program Listing on/off	\ProgramListingOn{}, .cm ProgramListingOff(20)
Setup	Setup document preamble. Cannot be used with .EndPreamble, or PreambleComplete, or Begin. or .Create	\setup{Doc-name, Doc-Title, Doc-Description,[Cover]}
SetupPDF Smallest Smaller Small Sub Subtitle	setup insert PDF in header Smallest Font Smaller Font Small Font define Subscript Insert a subtitle in a table	\SetupPDF{} See Using \Smallest{text} \Smaller{text} \Small{text} \sub{text} \Subtitle{n;text}, 'n'=Number of columns in table
Sup TeX VSkip WikiNum WikiFigure	define superscript define TeX print symbol insert blank lines in header page format footnotes in Wiki's format Illustrations in Wiki's	\sup{text} \Tex{} \Vskip{} \WikiNum{format} \WikiFigure{format}
WikiRow	Expand to ".Row" for non wiki documents, expand to "AddRow" for Wiki documents. Preceed with execute command, Example: .Xe \WikiRow{\} ... rest of table row; escape inline references with a backslash.	\WikiRow{format}

F O O T N O T E S

(1) 
Described in Nuances in Computing

(2) 
When generating a document automatically, the footnotes expansion should use the extended form as it supports embedded format codes for HTML, Wiki, and LaTeX.

(3) 
The default STFxlate output format is --latex and does not have to be stated explicitly

(4) 
The LaTeX default is to display normal single quotes, the HTML default is to display the backtick and apostrophe.

(5) 
Sed and tr are UNIX filter utilities that are also available for Windows.

(6) 
The Imagemagick directory must be in the windows path -- see B.3.1. A typical path for Imagemagick is: C:\Program Files\ImageMagick.

(7) 
POD is defined in the Perl documentation as "Plain Old Document format".

(8) 
RTF is similar to LaTeX; Wiki is similar to HTML; Text does not support figures

(9) 
The \SetupPDF macro must be used in before the \Setup macro if the \Setup macro is also used.

(10) 
In the case of HTML/Wiki, it is STF that provides the concept of a figure.

(11) 
\fig is used to place figures inside of tables.

(12) 
Short for My Own Index Program

(13) 
Grep for Windows may be downloaded from: http://unxutils.sourceforge.net

(14) 
LibreOffice may be downloaded from http://www.libreoffice.org/

(15) 
This one is my preference for Windows, TexLive is my preference under Linux. Both are correspondingly included along with installing LyX

(16) 
This is also referred to as: C:\Users\'you'\.nic

(17) 
This is ~/.nic under UNIX/Linux

(18) 
This is ~/bin under UNIX/Linux

(19) 
More precisely latex, html, text, rtf, or wiki must be specified.

(20) 
It is necessary to use the .CM command to turn program listings off, since inline commands are disabled in program listing mode

I N D E X

$STF_CONFIG - X.001 X.002 X.003	\Paragraph - X.001 X.002
$STF_STARTUP - X.001 X.002 X.003	\ProgramListing
$SYSTEMMACROS	\ref
$USERMACROS	\Setup - X.001 X.002
%	\SetupPDF - X.001 X.002
%Compare	\Small
%Exist	\Smaller
--config	\Smallest
--start	\Sub
--text	\Subtitle
... - X.001 X.002	\sup
.AI - X.001 X.002 X.003	\TeX
.AP - X.001 X.002 X.003	\und
.AR - X.001 X.002 X.003	\url
.AW - X.001 X.002 X.003	\VSkip
.AX - X.001 X.002 X.003	\WikiFigure{}
.BD - X.001 X.002 X.003	\WikiNum{} - X.001 X.002
.bd	Add unnumbered paragraphs to TOC
.BeginDocument	Adding a preface
.BI - X.001 X.002 X.003	ASCII
.BK - X.001 X.002 X.003	Bias
.Bk	Calibre
.Break	CDIR
.CH - X.001 X.002 X.003	Checking for updates
.CM - X.001 X.002 X.003	Checking STFXlate version for updates
.CN - X.001 X.002 X.003 X.004	Column-spec
.CO - X.001 X.002 X.003	Combining path symbols
.CP - X.001 X.002 X.003	Conditionaly include file
.CreateDocument	DATE
.CV - X.001 X.002 X.003	Debugging texput.log
.DB - X.001 X.002 X.003	DocBook - X.001 X.002 X.003
.DC - X.001 X.002 X.003	docx
.dc	docx2tex
.DE - X.001 X.002 X.003	Dos shell
.DL - X.001 X.002 X.003	e-book - X.001 X.002
.DS - X.001 X.002 X.003	ebooks
.DT - X.001 X.002 X.003	Environment
.EF - X.001 X.002 X.003	epub format
.EL - X.001 X.002 X.003	Executor
.EP - X.001 X.002 X.003	Extend Front Matter
.FG - X.001 X.002 X.003	Extended ASCII
.FilterQuotes	FEXT
.FM - X.001 X.002 X.003	FilterQuotes - filter quotes
.FQ - X.001 X.002 X.003	FNAME
.FS - X.001 X.002 X.003	Foreign text files
.HF - X.001 X.002 X.003	Formatting POD files
.HL - X.001 X.002 X.003	fq - filter quotes
.IE - X.001 X.002 X.003	generating DocBook
.IF - X.001 X.002 X.003	Ghostscript - X.001 X.002
.IN - X.001 X.002 X.003	Gnuplot
.IX - X.001 X.002 X.003	Headless table
.LE - X.001 X.002 X.003 X.004 X.005	HTML
.LL - X.001 X.002 X.003	html output
.LS - X.001 X.002 X.003 X.004	Identify
.NP - X.001 X.002 X.003	ImageMagick - X.001 X.002
.OF - X.001 X.002 X.003	including Word format
.PC - X.001 X.002 X.003	INPUTROOT
.PD - X.001 X.002	Install
.PE - X.001 X.002 X.003	Label Functions
.PL - X.001 X.002 X.003	Label hierarchy
.PP - X.001 X.002 X.003	LASTPARSE
.PS - X.001 X.002 X.003	LaTeX
.PT - X.001 X.002 X.003	Latex2rt
.PU - X.001 X.002 X.003	Long table
.RP - X.001 X.002 X.003	LyX - X.001 X.002
.SC - X.001 X.002 X.003	makeDoc - X.001 X.002
.SD - X.001 X.002 X.003	makeDocWithIndex - X.001 X.002
.SE - X.001 X.002 X.003 X.004	makeImageBooklet
.SetLandscape	makeindex
.Setmacro	makeRTF
.SF - X.001 X.002 X.003	makeRTFDoc
.SL - X.001 X.002 X.003	makeWiki
.SM - X.001 X.002 X.003	Markdown
.SN - X.001 X.002 X.003	Markdown format - X.001 X.002
.SP - X.001 X.002 X.003	Merging PDF files
.SQ - X.001 X.002 X.003	MikTec
.SU - X.001 X.002 X.003	MOIP
.SV - X.001 X.002 X.003	newSTF
.SX - X.001 X.002 X.003	NewSTF
.TB - X.001 X.002 X.003	OS
.TC - X.001 X.002 X.003	Out-file
.TE - X.001 X.002 X.003 X.004	Pandoc
.TH - X.001 X.002 X.003	PDF
.TP - X.001 X.002 X.003	pdf output
.TR - X.001 X.002 X.003	pdfpages
.TS - X.001 X.002 X.003	Perl
.TX - X.001 X.002 X.003	Perl POD format - X.001 X.002 X.003
.UF - X.001 X.002	POD - X.001 X.002
.UP - X.001 X.002 X.003	POD file format
.VB - X.001 X.002 X.003	Power shell
.WK - X.001 X.002 X.003	Preface
.WR - X.001 X.002 X.003	Python
.XE - X.001 X.002 X.003	Referencing the environment - X.001 X.002
.XX - X.001 X.002 X.003	RTF - X.001 X.002 X.003
.YA - X.001 X.002 X.003 X.004	rtf output
.YE - X.001 X.002 X.003 X.004 X.005 X.006	sample Macros
.YF - X.001 X.002	sed
.YL - X.001 X.002 X.003 X.004	Setescape
.YS - X.001 X.002 X.003 X.004	Setting the date
000STF_Working	SplitTableLines
=back - X.001 X.002	STF
=Begin	STFASCII - X.001 X.002
=begin	STFHOME
=cut - X.001 X.002	STFLatex
=encoding	Stflib
=end - X.001 X.002	StfMacros - X.001 X.002
=for - X.001 X.002	Stfmacros.stf
=head - X.001 X.002	STFXlate
=item - X.001 X.002	STFxlate
=over - X.001 X.002	STFXlate updates - X.001 X.002 X.003
=pod	SuperCleanLatex - X.001 X.002
=qv - X.001 X.002	SuperCleanSTF - X.001 X.002
\#nh	Symbol manipulation
\bold	Table - Headless
\center	Table - Label
\CheckForUpdates	Table - Long
\CIncludeFile	Table - SplitTableLines
\Copyright	TARGET
\Cover - X.001 X.002 X.003	Test Report Generator
\dlink	Text box
\dpage - X.001 X.002	text output
\dref - X.001 X.002	Textput.log
\EndBox	TIME
\EndCover - X.001 X.002 X.003	tr
\EndTable	TRG
\esc - X.001 X.002	UF
\EXTASCII - X.001 X.002 X.003	Unicode
\ExtendFM - X.001 X.002	UPDATE_PENDING
\fig	Username
\fixed	viewSubDoc - X.001 X.002
\fn	Wiki - X.001 X.002
\fnx	Wiki Attachments
\GetPOD	Wiki End of line (EOL)
\hline	Wiki footnotes
\href	Wiki ForceAddRow
\IfLab	Wiki Graphics
\InsertPDF - X.001 X.002 X.003	Wiki HTML
\italics	Wiki illustrations
\landscape	Wiki Line
\Large	Wiki output
\Larger	Wiki table alignment
\Largest	WikiFigure - X.001 X.002
\LaTeX	WikiNum
\newpage	WikiRow
\nl	XEmacs
\norm