Table of Contents

• 1 Synopsis
  • 1.1 Commands
  • 1.2 Options
  • 1.3 Creating a .doc file
  • 1.4 Creating an .inf file
  • 1.5 Creating loosely related .inf files
  • 1.6 Creating .inf files to be concatenated
• 2 Tags
  • 2.1 Words
  • 2.2 Tags which start in the first column
    • 2.2.1 Conditional Processing
    • 2.2.2 Character Formatting
    • 2.2.3 Paragraph Formatting
    • 2.2.4 Enumeration and Lists
    • 2.2.5 Table of Contents and Index
    • 2.2.6 Handbook Writing
    • 2.2.7 Miscellaneous
  • 2.3 Tags used in text
    • 2.3.1 Character Formatting
    • 2.3.2 Linking
    • 2.3.3 Miscellaneous

                        ***************************
                        **** PRELIMINARY DRAFT ****
                        **** SUBJECT TO CHANGE ****
                        ***************************

1 Synopsis

emxdoc -i [-acfgr] [-n start] [-o output] [-x xref] input
emxdoc -k [-o output] input...
emxdoc -l [-fr] [-o output] input
emxdoc -m [-o output] input...
emxdoc -t [-fr] [-o output] input
emxdoc -H [-o output] input

1.1 Commands

-i

Create .ipf file (for IPFC)

-k

Create .ndx file (for EPM)

-l

Create .tex file (for LaTeX) -- not yet implemented

-m

Merge directory files into cross reference file

-t

Create .doc file (plain text)

-H

Create .html file (for HTTP), the files extension .htm or .html has to be appended (perhaps a beta limitation)

1.2 Options

-a

Use concatenating instead of calling .inf files. Without -a, a reference to a label in another .inf file causes that .inf file to be called, that is, a new VIEW instance is created.  With -a, .inf files are assumed to be concatenated.  Use -n with -a

-b number

Select line breaking algorithm for -t.  Possible values are 0 (default) and 1 (slow):

0

greedy algorithm, filling lines as much as possible

1

minimize sum of (target_width - actual_width)^2

-c

Use color (light blue) instead of slanted font for highlighting with •pa, •sl, •em, •format slanted and •format emphasize

-e character

Set the escape character.  By default, emxdoc uses • (code 254) as the escape character.  This documentation always uses • as the escape character.  You can choose a different escape character with the -e option.  The character code is given in decimal, octal, or hexadecimal, using C notation.  If the argument of the -e option is a single non-digit character, that character is used as the escape character

-f

Enable French spacing.  With -f, one space is used after the end of a sentence, without -f, two spaces are used

-g

Gather global directory data

-h file

Use hyphenation table (for -t -b1)

-n start

Define first ID number, for use with -a.  The default is 1

-o output

Set name of output file (default: stdout)

-r

Make output file read-only

-w level

Set the warning level:

0

No warnings (default)

1

Text starting in first column

2

Text should be inserted here

-x xref

Use cross reference file, created by -m command

1.3 Creating a .doc file

emxdoc -t -o sample.doc sample.src

1.4 Creating an .inf file

emxdoc -i -o sample.ipf sample.src
ipfc sample.ipf /inf

1.5 Creating loosely related .inf files

emxdoc -ig -o sample1.dir sample1.src
emxdoc -ig -o sample2.dir sample2.src
emxdoc -m -o sample.dir sample1.dir sample2.dir
emxdoc -i -o sample1.ipf -x sample.dir sample1.src
emxdoc -i -o sample2.ipf -x sample.dir sample1.src
ipfc sample1.ipf /inf
ipfc sample2.ipf /inf

1.6 Creating .inf files to be concatenated

emxdoc -ig -n1 -o sample1.dir sample1.src
emxdoc -ig -n1000 -o sample2.dir sample2.src
emxdoc -m -o sample.dir sample1.dir sample2.dir
emxdoc -i -n1 -o sample1.ipf -x sample.dir sample1.src
emxdoc -i -n1000 -o sample2.ipf -x sample.dir sample1.src
ipfc sample1.ipf /inf
ipfc sample2.ipf /inf

Note that you'll get

151: No res for this reference [...]

warning messages from IPFC.  Use -n to avoid overlapping ranges of IDs.

2 Tags

Tags start by default with • (code 254).  You can use the -e option to choose a different character.  There are two types of tags:

• tags which start in the first column

• tags used in text

[...TODO...]

2.1 Words

To find a word, emxdoc skips ( * and ` characters, and then takes all characters until one of the characters , ; ! ? ' is found.  The characters . and : terminates a word if followed by a blank or by the end of the line.  The character ) terminates a word if properly nested.  The character [ terminates a word inside •prototype. After a word, terminating characters are skipped.

Example:

---

  If the -s[<blah>] option or example.dll (in LIBPATH) are missing,
  example() fails.

---

The above input consists of the following words:

---

    If
    the
    -s[<bla>]
    option
    or
    example.dll
    in
    LIBPATH
    are
    missing
    example()
    fails

---

2.2 Tags which start in the first column

2.2.1 Conditional Processing

•set name value

Set the variable name to value.  Variable names must start with a letter.  The remaining characters may be letters, digits or _.  Letter case is significant.  Possible values are false and true.  Variables can be used for •if.

•if condition
•else
•endif

Conditionally include or exclude sections of the input file. •if statements may be nested to up to 8 levels.

The condition consists of the operators &, | and !, the operands ipf, text, LaTeX or html (which are true if -i, -t, -l or -H, respectively, is in effect), false, true, variables (see •set) and parentheses.

Example:

---

        •if text
        •h1 Table of Contents
        •toc
        •endif

---

•ipf
•endipf

Insert lines of IPF commands between •ipf and •endipf as-is into the output file if -i is used.  Ignore lines otherwise

•text
•endtext

Insert lines between •text and •endtext as-is into the output file if -t is used.  Ignore lines otherwise

•latex
•endlatex

Insert lines between •latex and •endlatex as-is into the output file if -l is used.  Ignore lines otherwise

•html
•endhtml

Insert lines between •html and •endhtml as-is into the output file if -H is used.  Ignore lines otherwise

2.2.2 Character Formatting

•format style word...

Define words to be formatted in style style. Possible choices for style are:

abbrev

Abbreviation (must end with .)

bold

Boldface

emphasize

Emphasized (slanted, uppercase for -t)

param

Parameter (slanted lower case for -i)

slanted

Slanted (or colored if -c is used)

syntax

<...> slanted, [|] bold, rest tty

tty

Fixed-width typewriter font

underline

Underlined

Example:

---

        •format syntax <style> <word>
        •format tty .exe .com
        •format abbrev etc.

---

abbrev is orthogonal to the other styles.  It means that the period at the end of the word doesn't end a sentence (see the -f option).

•replace word replacement

Replace word with replacement, which is emxdoc input.

Example:

---

        •replace <table> •tt{<}•sl{table}•tt{>}

---

•replace takes precedence over formatting styles.

•special mode word replacement

Replace word with replacement on output in mode mode (text, ipf, LaTeX or html).

Example:

---

        •special LaTeX TeX \TeX{}

---

2.2.3 Paragraph Formatting

•verbatim
•endverbatim

Output lines between •verbatim and •endverbatim as-is, maintaining line breaks and leading spaces.  A fixed-width typewriter font is used.  The current indentation is used.

•example
•endexample

Like •verbatim, but indent by 4 characters.

•indent
•endindent

Use an additional indentation of 4 characters for paragraphs between •indent and •endindent.

•typewriter
•endtypewriter

Like •ident, but use •tt{} as default. Note that line breaks and leading spaces are not maintained in the output.

•samplecode
•endsamplecode

Sample code in library reference manual.

2.2.4 Enumeration and Lists

•description
•item term
  description
•enddescription

Describe terms.  Each description is started with •item.  The term to be described is given on the same line as •item.  Paragraphs between •description and •enddescription are indended. If term is short enough, its description starts on the same line.  Otherwise, it starts on the next line.

•list
•item term
  description
•endlist

Like •description, but the description is always put on a new line.

•enumerate
•item
  paragraph
•endenumerate

Numbered list of items.  •item starts a new item.  Each item is preceded by a number.  The paragraphs between •itemize and •enditemize are indended.

•itemize
•item
  paragraph
•enditemize

Unordered list of items.  •item starts a new item.  Each item is preceded by a mark.  The paragraphs between •itemize and •enditemize are indended.

2.2.5 Table of Contents and Index

•hlevel[flags] heading
•h- heading
•h= heading

Start new section of level level (1 through 3).  heading is the section heading.

Example:

---

        •h1 Getting started

---

If flags is u, the section is unnumbered and does not appear in the table of contents of the output file when creating a text file.

•h- and •h= create an underlined section heading which does not appear in the table of contents and does not start a new panel.

•label label

Define the label label to refer to the current section. The label can be used with •hpt{} and •ref{}.

Example:

---

        •label defining label

---

•toc

Insert table of contents.

Example:

---

        •if text
        •h1 Table of Contents
        •toc
        •endif

---

•ipfminitoc

In -i and -H mode, insert a table of hypertext links to the subsections of the current section.

•index term

Put term into the top level of the index.

Example:

---

        •index top level

---

•i1 term

Put term into the top level of the index (unless already done) and make this the first level entry for •i2.  If term is not present, disable •i2.

•i2 term

Put term into the second level of the index, under the term most recently used with •i1.

Example:

---

        •i1 indexing
        •i2 levels

---

2.2.6 Handbook Writing

•function name...

Used in a library reference.  With -i, •function starts a new panel.  With -t, •function inserts a dashed line.  All function and variable names described in this section should be listed in the •function line, separated by spaces.  If a name does contain (), it is automatically added to the list of words to be formatted specially, using tty style. The section heading is constructed by listing the names, separated by commas.  The last two names are separated by ` and '.  A level-two index entry is created for each name.  Therefore, an •i1 tag must have been used before •function.  With -k, •function defines a keyword.

•compat name...

Defines the compatibility of the function.  This tag, if used, must precede •headers if present.  If •headers is not present, it must precede •prototype. With -t, the compatibility is shown at the right end of the first line created by •headers.  If •headers is not used, a line is inserted by •prototype. The names are inclosed in square brackets.  With -i, •endprototype inserts the `Compatibility:' section, using the names defined with •compat.  The names are separated by spaces.

•headers
•endheaders

List include files.

•param name...

Format the names using •pa{}.  This definition is local to the current function or variable description, which ends at the next •function or •h1 tag.

•returnvalue

Starts a new section, titled `Return value:'.

•restrictions

Starts a new section, titled `Restrictions:'.

•implementation

Starts a new section, titled `Implementation-defined behavior:'.

•bugs

Starts a new section, titled `Bugs:'.

•errors

Starts a new section, titled `Errors:'.

•hints

Starts a new section, titled `Hints:'.

•seealso

Cross references in library reference manual.

•samplefile

Pointer to sample file in library reference manual.

•prototype
•endprototype

Function prototype in library reference manual.

2.2.7 Miscellaneous

•title title

Define title of .inf and .html document.

Example:

---

        •title Formatting documents with emxdoc

---

•language language

Define the language to be used for emxdoc-generated text. Valid languages are english (which is the default) and german.

•syntax style

Select the syntax style recognized by •sy{}.  Possible values for style are emx (which is the default) and dvidrv.

•keyword keyword...

Define keyword for EPM.  You can give multiple keywords, separated by spaces.

•table [indent] width...
  <column1> | <column2>...
  ----------+--------------
  <column1> | <column2>...
  <column1> | <column2>...
•endtable

Unfortunately, IPFC doesn't like font changes in tables.

2.3 Tags used in text

2.3.1 Character Formatting

•tt{text}

Use fixed-width typewriter font for text

•sl{text}

Use slanted font for text.  Use color instead if -c option is in effect

•bf{text}

Use bold font for text

•em{text}

Emphasize text.  This is done by using a slanted font for -i, using italics for -l and upcasing for -t

•sy{text}

Format text as grammer: •bf{} is used for the three characters [ | ], •sl{} is used for terms enclosed in angle brackets (<whatever> -- the angle brackets are removed if -i is used) and for * and # (and + for •syntax dvidrv) at the end of text, •tt{} is used for everything else

•pa{text}

Use •sl{} and convert to lower-case if the -i option is used.  Unmodified if -t is used

•ul{text}

Underline

2.3.2 Linking

•hpt{label}

Hypertext-reference to label, which is inserted into the output file

•ref{label}

Insert section number of label

2.3.3 Miscellaneous

•.

Insert a period which marks the end of a sentence.  Required after abbreviations.

•break

Force line break

---

--------------------------- END OF EMXDOC.DOC ------------------------------

---