14. 2.000beta7

Enhancements | Fixes | Incompatibilities

14.1. Enhancements

There are lots of new things in this version including:

Details are given below.

14.1.1. Topics mode for HTML

SDF can now generate a set of HTML topics, rather than a single HTML file. The command is:

   sdf -2topics myfile.sdf

If you want to manually control how a document is split into topics, simply include other sdf files which contain headings. These manual topics, if any, can be supplemented with automatically generated topics. By default, level 1 headings are used as topic breaks, in addition to the manual ones. The -n option can be used to change this:

  • -n0 disables autosplitting
  • -n2 uses level 1-2 headings to autosplit
  • -n3 uses level 1-3 headings to autosplit
  • etc.

To make it easy to navigate around the topics, SDF generates a default header and footer for a topic which supports jumping to the:

  • main topic (i.e. the contents)
  • parent topic
  • previous topic
  • next topic.

14.1.2. HTML headers and footers

These macros give you total control over the headers and footers used:

  • HTML_HEADER - header on a HTML document (or main topic)
  • HTML_FOOTER - footer on a HTML document (or main topic)
  • HTML_TOPIC_HEADER - header on a HTML topic
  • HTML_TOPIC_FOOTER - footer on a HTML topic.

The default implementation of these macros is in html.sdm in the kernel library. The default versions of these macros use the variables below, if they are set. On most occasions, useful headers and footers can be obtained by simply setting these variables:

  • HTML_URL_HOME - URL of the home page
  • HTML_URL_CATALOG - URL of the catalog
  • HTML_URL_SEARCH - URL of the search facilities.

14.1.3. HTML control variables

To fine tune HTML output, the following variables are useful:

  • HTML_BG_COLOR - the background colour of the page
  • HTML_BG_IMAGE - the background image of the page
  • HTML_TEXT_COLOR - the colour of normal text
  • HTML_LINK_COLOR - the colour of unvisited links
  • HTML_VLINK_COLOR - the colour of visited links.

To set a colour, use the RGB (red-green-blue) value as used by HTML. For example:

   !define HTML_BG_COLOR "ffffff"

For convenience, a number of variables are defined for common colours:


These are used as follows:


14.1.4. Macros inside tables

Macros can now be used inside tables. In particular:

  • rows can now be conditionally included or excluded
  • rows can be marked as changed.

For example:

!block table
Code    Description
BTW     By the way
!block changed
RTFM    Read the (fine) manual
SOS     Save our souls

14.1.5. Wide tables

The table filter now supports a new attribute called wide. When it is used, the table spans the side-head in addition to the text column.

14.1.6. Figure enhancements

The import macro now supports an align attribute, which is passed into the generated HTML. This can be used in combination with the clear macro to control how figures are aligned with text in HTML.

For example:

!import "mylogo"; align="right"
Some text.

HTML's alt attribute is now also supported by the import macro.

14.1.7. Special characters

Special characters can now be entered using {{CHAR:xxx}} where xxx is either:

  • a symbolic name
  • a character code (HTML only).

The symbolic names supported are given below.

Name Description
c copyright symbol
emdash a hyphen which is the width of the point size
endash a hyphen which is half the width of the point size
emspace a space which is the width of the point size
enspace a space which is half the width of the point size
nbdash a non-breaking hyphen
nbspace a non-breaking space
nl newline
r registered trademark
tab tab character
tm trademark

For convenience, variables with the same name are predefined. This makes it easy to include a special character. For example:

   Copyright [\[c]\] 1996, Us Pty Ltd.

Note: Some target formats do not yet support all of these characters. For example, HTML does not yet support Em or En spaces. In these cases, sdf will do the best it can (e.g. use a normal space for enpsace and emspace).

14.1.8. Cross-references

Cross-references are now supported via the xref phrase attribute. For example:

 Refer to page {{N[xref="pagenum"] Samples}} for more samples.

The value specifies the cross-reference style to use. The phrase text is used to find the target location. The predefined styles are given below.

Name Value
pagenum the page number
paratext the paragraph text
paratag the (FrameMaker) paragraph tag
paranum the paragraph number (e.g. Appendix A)
paranumonly the paragraph number only (e.g. A)
section section paranumonly, paratext, on page pagenum

New styles can be added by using the xrefs configuration filter. See mif.sdm in the kernel directory for examples.

Note: Other than PostScript, most targets ignore cross-references.

14.1.9. Other goodies

New macros include:

  • output - dynamically change the output file used

New filters include:

  • changed - mark a block as changed (shorthand for sdf; changed)
  • topics - include a set of sub-topics
  • sections - create section jumps for html and hlp outputs
  • note - format a note
  • quote - format a quotation
  • address - format an address
  • ascii_graphic - format an ASCII graphic.

The current directory is now searched first for the configuration library, i.e. if OPT_CONFIG is abc, sdf first looks for ./abc.sdm before searching for abc.sdm in a directory called abc on the search path.

14.2. Fixes

The copy number field on the mincom cover page has been fixed.

The Limitations & Future Directions heading in sdfget.sdm has been changed to Limitations and future directions.

14.3. Incompatibilities

The objects attribute of the table filter is now called tags.

The sections filter now generates SECT jumps for each paragraph within the block, provided the output is html or hlp. To include sub-topics (sub-sections), use the new topics filter.

When pretty-printing files using sdf, use the -N option to control line numbering. The -n option is now used to specify the level when autosplitting into HTML topics.

The message macro has been simplified - the message type is now an optional second parameter.

The obj* configuration filters have been renamed to phrase* to better reflect their purpose. (This shouldn't affect normal documents.)

The cfg_lang configuration filter has been renamed to langdefs.