MiniGML
A small GML formatter for your IBM PC or PS/2 Version 2.0

Document Number MINIGML.SCR

04/17/1987

Roman Koch
INS CC Zuerich
Operation
Mail: ICRKO01 at ZCHVM2

Preface

MiniGML is a small (less then 25 KB) and fast text formatting program. lt accepts a subset of the GML (Generalized Markup Language) starter set tags. MiniGML is a handy and simple way to process GML documents in environments where diskette space or memory is critical. MiniGML is not a replacement for other DCF/GML formatters like DWSCRIPT or SCRIPT/PC. For complex formatting tasks (indexing, cross-references, conditional processing and so on), and for perfect compatibility with your host GML, you will continue to use one of the big ones.

The idea to write MiniGML was born after a very interesting discussion about mini-editors in MINIEDIT FORUM on IBMPC: If you have a diskette-based system and want to be able to use an editor, a text formatter, a database and a spreadsheet without a lot of diskette swapping, you may have trouble to find appropriate products. In this case, MiniGML is for you.

This document assumes you are already familiar with DCF/GML. MiniGML's capabilities are limited both in the number of tags supported and in the amount of functions of each tag. This document presents which GML tags and DCF control words are supported and how they must be used.

MiniGML is written in Turbo Pascal 4.0 (tm Borland International). lt heavily uses Tim Slegel's TURBOSTR string functions (available from PCTOOLS) because of their small size and impressive speed. Thanks, Tim.

Summary of Changes

Program converted to Turbo Pascal Version 4.0. MiniGML is now an .EXE file. lt is about 20% faster then MiniGML 1.6.

New Functions

Support for the "tsize", "termhi" and "compact" parameters within definition lists. Support for the "termhi" and "compact" parameters within glossary lists. Limited Support for the GML table tags. Optional /w parameter to hold the screen output. Optional /g parameter to start output when a specified string appears in the input. Different default colors for monochrome and color screens. Limited support for the .rc control word. Support for the .cp control word. Support for the .ds and .ss control words (lets you create foils with MiniGML!). Menu-driven customiser program (you no longer need the definition file).

Bugs Fixed

Collecting of headings for the table of contents ends if there is not enough memory available. Highlighting tags are recognized and processed while in .fo off mode. The current formatting mode (off/on/left) is now saved before figures, examples and tables and restored correctly after the appropriate end tags. An example is always folowed by a blank line. Output redirection to a file now works with DOS 2.1. The bug which sometimes caused MiniGML 1.6 to wait for an enter has disappeared.

Some MiniGML Basics

MiniGML has been developed and tested on a IBM PC1, 320 KB, monochrome display, DOS 2.1, with a 5216 WheelPrinter. lt should run on every newer and larger PC and PS/2.

MiniGML is a DOS filter. lt uses the DOS facilities to redirect standard input and output. Therefore, it takes a file or the keyboard as input device, and the output may be redirected to the screen, the printer or to a file.

Obtaining MiniGML

MiniGML is distributed via PCTOOLS. The MiniGML package contains the following files:

MINIGML EXEBIN The program - download to the PC as a binary file 'MINIGML.EXE'.
MINIGML SCRIPT The documentation - this document.
MINIGMLC EXEBIN The customiser - download to the PC as a binary file 'MINIGMLC.EXE'.

Installing and Running MiniGML

To install MiniGML, download the program (MINIGML EXEBIN) as MINIGML.EXE and the documentation (MINIGML SCRIPT) as MINIGML.SCR to your diskette or hard disk.

To run MiniGML, enter (at the DOS prompt):

MINIGML [<input] [>output] [/?] [/W] [/S] [/N] [/Gsss]

where

<input
DOS filenme, including drive and path specifications, of your INPUT file.
Note: Don't forget the "<" character when using a file as input. Without the "<" character, DOS takes the keyboard to get input (in this case, you have to press Ctrl-Z to simulate an end-of-file).
/?
Display version number and syntax description.
/S
Colored Screen output (the output device or file specified with the >output parameter is not used). The default colors an be changed using the customiser.
/W
Wait if screen is full. The output is formatted as with the /s option. If the screen is full, MiniGML displays a "--- More --" message on the screen. You may then press any key to continue, or Ctrl-Break to cancel MiniGML. To get usable results with the /w option, the line length must be smaller or equal to the screen width -3.
Note: If you have a VGA or EGA, you may use the /wf option to force the screen into 50 (VGA) or 43 (EGA) lines.
>output
DOS device or filename, including drive and path specifications, of your OUTPUT.
Note: Don't forget the ">" character if you want to redirect the output to the printer or to a file. Use the /s or /w option if you want to see the output on the screen. If neither an output file nor the /s or /w option is specified, ">con:" is assumed.
/N
No printer control codes. /n has no meaning if /s or /w is used. /n is useful if you want to create a reference file without embedded printer control codes.
/Gsss
Goto sss, where sss is any string or character. MiniGML scans the file for the string sss (case- sensitive!) and starts the output when it is found. MiniGML processes the input in the background, so your output will start with the correct page numbers.
Note: The /g parameter must be the last parameter in the command line. Everything at the right of '/g' is taken as argument for the scan.

Usage examples:

While MiniGML is formatting your file, you may cancel MiniGML by pressing Ctrl-Break, and halt the screen output by pressing Ctrl-NumLock or PAUSE. To resume processing, you may press any other key.

Recommended Working Environment

If you are an experienced PC user, you will have no problems to integrate MiniGML in your working environment. For less experienced PC and/or GML users, the following hints may be useful:

With GML you describe what a thing is, not how it's supposed to look on the page. You use the GML language to describe the content of the document; for instance if you want to define a few technical terms in a glossary, you would start this glossary with the command ":gl.".

To learn more about "Document Composition Facility General Markup Language", known as "DCF/GML", look at the DCF/GML User's Guide (SH2O-9 186) and the DCF/GML Starter Set Reference (SH2O-9 187). This User's Guide only shows the differences to the official DCF/GML implementation!

To learn more about DOS filters, see "Standard Input and Standard Output" in your DOS manual.

If diskette space is critical, you may not only need a small text formatter, but also a small text editor. There are different small but powerful editors available on PCTOOLS (LED, T, E and much more), and they all work perfectly with MiniGML.

If you want to format your document while editing it, you need an editor with an integrated DOS shell (a function which allows you to enter DOS commands from within a program), or you may load one of the resident DOS pop-up utilities like XDOS or POPDOWN.

Limitations

MiniGML is designed to be small and simple. It has therefore some limitations and differences to other GML formatters. Some examples:

Normally, a document that formats okay with MiniGML will also be formatted correctly using SCRIPT/PC, SCRIPT/VS or DWSCRIPT.

Supported GML Tags

GML tags must start in column 1 of your text. Only the highlighting and the quote tags may appear in the middle of a line. Parameters (if any) are recognized only if they are on the same line with the tag.

Document Control

:gdoc.
Start general document. This tag is also used to define the security classification:
:gdoc sec='IBM Internal Use Only'
:egdoc.
End general document. This tag does nothing.

Front Matter of Document

:frontm.
Start front matter. Pages are not numbered. Headings do not appear in the table of contents.
:titlep.
Start title page. On the title page, only the title page tags should be used.
:title.
Define title of document. If you want multiple title lines, you may repeat this tag.
:docnum.
Define document number.
:date.
Define date. If there is no text immediately following this tag, the current date (as it is known to your personal computer) is inserted.
:author.
Author's name. If there are multiple authors, you may repeat this tag.
:address.
Start address.
:aline.
Address line. You may use more then one address line tag.
:eaddress.
End of address.
:etitlep.
End of title page. The security classification (defined with the :gdoc. tag) is printed as the last element of the title page. After the title page, the security classification will be centered on the top of the page.
:abstract.
Start abstract. You may use all other tags - but not the title page tags - in the abstract. Pages are not numbered.
:preface.
Start preface. You may use all other tags - but not the title page tags - in the preface. Pages are not numbered.
:toc.
Generate a table of contents. The table of contents will be printed at the end of the document. Collecting of titles starts after the :toc. tag. Titles in the front matter of a document are not collected.
:figlist.
List of figures. This tag does nothing. It will be discarded.

Body of Document

The body of a document is started with the :body. tag. Pages are numbered on the bottom of the page.

Headings

The heading text must irnmediatly follow the heading tag. It will not be recognized on the following lines. The ID and STITLE attributes are ignored.

:h0.
Start section. Page Eject. Title text will be printed bold, underscored and right-justified. Table of contents entry.
:hl.
Start chapter. Page Eject. Title text will be printed bold and underscored. Table of contents entry. The heading text is preceeded by the word "Appendix x." in the appendix of a document.
:h2.
Topic heading. Title text will be printed bold. Table of contents entry.
:h3.
Topic heading. Title text will be printed underscored. Table of contents entry.
:h4.-:h6.
Topic headings followed by a colon. If a paragraph tag follows, they are highlighted with highlight level 2 and imbedded in the text. If another tag follows, they are formatted as paragraphs without highlighting. No table of contents entry.

Paragraph Control

All paragraph control tags (:p., :pc. and :lp.) produce a new paragraph, separated from the previous paragraph with a blank line, and indented to the current indentation level within lists.

Lists

Up to 20 ordered, unordered and simple lists may be nested.

:ul.
Start unordered list. The 'compact' attribute is supported. Nested unordered lists use the same item prefix.
:sl.
Start simple list. The'compact' attribute is supported.
:ol.
Start ordered list. The 'compact' attribute is supported. Nested ordered lists use the same item numbering scheme.
:li.
List item. The ID attribute is not supported.
:eul.
End unordered list.
:esl.
End simple list.
:eol.
End ordered list.
:dl.
Start definition list. The term size may be specified with the "tsize=" parameter. The default is 10. The term highlighting may be specified with the "termhi=" parameter. The default is 2. The "compact" parameter is supported. Nesting of definition lists works only if all nested lists have the same tsize.
:dt.
Definition Term. Terms which are longer then 10 (or the specified tsize) are truncated. The term text must immediatly follow the definition term tag. It will not be recognized on the following lines.
:dd.
Definition Description.
:edl.
End definition list.
:gl.
Start glossary. The term highlighting may be specified with the "termhi=" parameter. The default is 2. The compact" parameter is supported.
:gt.
Glossary Term. The term text must immediatly follow the glossary term tag. It will not be recognized on the following lines. The glossary term is highlighted with highlight level 2.
:gd.
Glossary Description.
:egl.
End glossary list.

Highlighting

:hpl.
Start highlight level 1 (underscore).
:hp2.
Start highlight level 2 (bold).
:hp3.
Start highlight level 3 (bold and underscore).
:ehpl.
End highlight level 1.
:ehp2.
End highlight level 2.
:ehp3.
End highlight level 3.
:cit.
Start a citation. Citations are processed as :hpl. / :ehpl. tags.
:ecit.
End a citation.

Highlighting tags may be nested:

Zero:hpl.one:hp2.two:hp3.three:ehp3.two:ehp2.one:ehpl.zero

This line prints as follows:

Zeroonetwothreetwoonezero

Tables

MiniGML supports a very limited but easy-to-use subset of the table tags introduced with DCF/GML 3.1. Tables are a very powerfull tool to present structured data. When you were used to create tables with the box and tab control words, you will enjoy this new method because it is highly device-independent.

Compared to the host GML table tags, there are 3 major restrictions:

  1. Between the :table. and :etable. tags, you should only use the .c. and :row. tags. Otherwise, the results will be unpredictable.
  2. A cell can contain only one input line. The text of the cell must be entered on a single line immediatly following the :c. tag.
  3. The number and width of columns must be defined with the "widths=" parameter of the :rdef. tag.

In addition, there are some important design differences:

:rdef.
Row definition. The row definition always refers to the next table in the input file. If the :rdef. tag is omitted, the table tags are ignored. Only the "cwidths=" attribute is supported. If it is omitted, it defaults to cwidths='*'. Cell definitions must be set between apostrophes and separated with blanks. You may define up to 20 cells per row. Use an asterisk if you want MiniGML to calculate the cell widths. The "id=" attribute is ignored, but yoy should use it to stay compatible with the host GML. See the end of this chapter for an example how to use the :rdef. tag.
:table.
Start a table. All attributes are ignored, but you should use the "refid=" attribute to stay compatible with the host GML. The :table. tag must be followed by a :row. tag.
:c.
Cell. All attributes are ignored. The text of a cell must be entered on the same line as the :c. tag; only the line with the :c. tag is used to fill the cell. The text is normally left-justified. If it is a number, it is right-justified. Do not use highlighting tags within cells.
:row.
Start a row. All attributes are ignored. There must be at least one :row. tag in a table.
:etable.
End a table.

A Table Skeleton: This example shows the minimal requirements for a table. Use it as a skeleton for your own tables.

:rdef id=xxx [cwidths='x y z']
:table refid=xxx.
:row.
[:c.[cell text]]
.
[more :row. and :c. tags]
.
:etable.

A Simple Table:

:rdef id=simple cwidths='* * *'.
table refid=simple.
:row.
:c.CPU Type
:c.Storage (KB)
:c.User
:row.
:c.PC 1
:c.320
:c.Roman Koch
:row.
:c.PC XT
:c.640
:c.Operations (used as response time monitor)
:etable.

The above example produces the following results:

CPU Type Storage (KB) User
PC 1 320 Roman Koch
PC XT 640 Operations (used as
response time monitor)

A More Complex Table:

:rdef id=complex cwidths-'* 3 10 *'.
table refid=complex.
:row.
:c.Name
:c.Age
:c.Salary
:c.Comments
:row.
:c.Jack
:c.35
:c.28000
:c.Knows Jim
:c.Alice
:c.
:c.29000
:c.
:c.Jim
:c.37
:c.31100
:c.Has a black dog
:row.
:c.Averages
:c.36
:c.29366.67
:c.
:etable.

The above example produces the following results:

Name Age Salary Comments
Jack
Alice
Jim		 35

37		 28000
29000
31100		 Knows Jim

Has a black dog
Averages 36 29366.67  

Miscellaneous Tags

:note.
Start a note. A note is starting a new paragraph and begins with the highlighted word "Note:".
:q.
Start quote.
:eg.
End quote.
:fig.
Start figure. All attributes are ignored and processed as with the 'frame=rule place=inline' attribute. Figures are not indented. The :figcap. and :figdesc. tags are not supported.
:efig.
End figure.
:xmp.
Start example. The DEPTH attribute is not supported.
:exmp.
End example.
:i1.-:i3.
Index tags are discarded.
:lq.
Start a long quotation. Long quotations are indented four spaces from both the left and right margins.
:elq.
End a long quotation.

Appendix of Document

The appendix is started with the :appendix. tag. Level 1 headings start with the word "Appendix x.", with x going from A to Z. If you use more then 26 appendices, the appendix numbering gets funny.

Back Matter of Document

The back matter is started with the :backm. tag.

:index.
Index. This tag does nothing.

Supported DCF Control Words

Only one DCF control word per line is allowed. They must start in column 1. Be careful when using DCF control words in a GML document. For best document interchangeability, only GML tags should be used.

.br
Break. The next input line starts on a new output line.
.ce
Center text. The text immediatly following the .ce control word will be centered. Highlighting tags in this line are not recognized.
.cp [x]
Conditional page eject. If fewer then x lines remain on the current page, a page eject occurs. If x is omitted, a page eject occurs unless there is no text on the current page.
.ds
Double space mode. A blank line will be written after every output line. Double space mode allows you to produce foils with MiniGML.
.fo
Format mode. Valid modes are "on", "off" and "left".
.im
Imbed file. This control word must be followed by a DOS filename. If there is no extension in the filename, MiniGML adds the default extension ".SCR". If this .SCR file does not exist, MiniGML will try again without an extension. If the file does not exist, the statement is ignored. Only one level of imbed files is supported. If an imbed file contains a ".im" statement, it is ignored.
.ll xx
Define line length (number of characters).xx must be a number greater then 10. The default is 60. The default may be changed with the customiser.
.oc
Output comment. This line will be sent to the output device unchanged; it may be used for printer or Prancer control codes. This control word is ignored if the /s or In option is used.
Note: Be careful when you use output comments; MiniGML will not recognize any change in line spacing or paper positioning.
.pa
Page Eject. Parameters are ignored.
.pl xx
Define page length (number of lines). xx must be a number greater then 20. The default is 66. The default may be changed with the customiser.
Note: The page length should only be changed at the start of a document (otherwise, MiniGML will lose its page length control).
.pm xx
Define page margin (number of characters). xx must be a number. The default is 10. The default may be changed with the customiser. If the Is or /w option is used, the page margin is always 2 and can not be changed with the .pm control word. The page margins are the same on odd and even numbered pages.
.rc
Revision code. The revision code number is always interpreted as "1". Valid parameters are "on", "off" or any single character which then becomes the new revision marker. The default revision code character is the vertical bar. If neither "on" or "off" nor a character is specified, a blank is assigned to the revision code character. If the page margin is less then 2, no revision marks are printed. Revision codes are not printed on blank lines.
Note: Revision marking works best if applied to entire paragraphs. If single lines or words are marked, the revision mark may start too late or, in some situations, completly be omitted.
.sp [x]
Space x lines (x defaults to 1). If there are less then x lines left on the current page, a page eject will occur. The spacing is absolute: When double spacing is in effect, the "x" value is hot doubled.
Note: Blank lines in the input file are always translated to ".sp 1".
.ss
Single space mode. This cancels a previous .ds (double space mode).

In addition, the following DCF control words are suppressed:

.* / .cm
Comment
.se
Set variable
.bf
Begin font
.pf
Previous font
.df
Define font