Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


1. 2.001

Enhancements | Fixes | Incompatibilities

1.1. Enhancements

The enhancements are:

1.1.1. Level 0 headings

H0, A0 and P0 are now supported as paragraph styles. Level 0 headings are implicitly converted to:

 !define DOC_NAME "text of heading"
 !build_title

This feature makes it easier to structure large documents as topics each of which begins with H1. To format a particular topic as a document, sdf's -H option can be used to set the initial heading level to zero like this:

       sdf -2html -H0 mytopic.sdf

1.1.2. New command line options

The sdf program has some new command line options: -O, -g and -K.

The -O option specifies an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used. For example, to convert mydir1/mydir2/myfile to HTML and put the output in the same directory as the original file, the command is:

       sdf -2html -O mydir1/mydir2/myfile

Note: The -O option doesn't always work. In particular, HTML topics generation doesn't support it yet.

The -g option prefilters the input files by executing sdfget using the default report (default.sdg). To change the report used, specify the report name as the parameter. If the report name doesn't include an extension, sdg is assumed.

The -K option sets the look of headings. Sensible parameter values are H, A and P. For example, to get the embedded documentation out of a script, make the headings plain, generate a document (rather than a topic) and convert it to HTML, the command line is:

       sdf -g -KP -H0 -2html myscript

1.1.3. Table enhancements

The predefined table style names (columns, rows, grid, plain and shade) now have edit-case aliases (i.e. Columns, Rows, Grid, Plain and Shade). If the edit-case versions are used, quotes are not needed, e.g.

  !block table; style=Plain
  !endblock

The keepindents parameter has been introduced for the table filter. If set, leading whitespace in cells is kept, e.g.

!block table; keepindents
Directory     Description
sdf           top level directory
   bin        scripts
      bat     batch file wrappers around scripts
   perllib
      sdf     sdf libraries
      Pod     pod libraries
!endblock

The output is:

Directory Description
sdf top level directory
      bin scripts
            bat batch file wrappers around scripts
      perllib  
            sdf sdf libraries
            Pod pod libraries

1.1.4. HTMLDOC support

To convert a document to HTML ready for Michael Sweet's HTMLDOC program, the command is:

       sdf -2html -DHTMLDOC ...

Alternatively, sdf can call HTMLDOC itself in order to generate PostScript or PDF. The commands to do this are:

       sdf -2ps_html ...
       sdf -2pdf_html ...

Note: To maintain backwards compatibility, FrameMaker is still the default back-end for generating PostScript and PDF. If you wish to make HTMLDOC the default back-end, edit the FormatMappings sections of the sdf.ini file and change ps to mean ps_html and pdf to mean pdf_html. Once this is done, the following commands will use HTMLDOC rather than FrameMaker:

       sdf -2ps ...
       sdf -2pdf ...

When sdf invokes HTMLDOC, it sets the appropriate HTMLDOC options by using the following SDF variables: DOC_TITLE (build from DOC_NAME and DOC_TYPE), DOC_TOC, DOC_TWO_SIDES, OPT_PAGE_SIZE, OPT_MARGIN_INNER, OPT_MARGIN_OUTER, OPT_MARGIN_TOP and OPT_MARGIN_BOTTOM. In addition, a new variable called HTMLDOC_OPTS can be used to pass additional options through to the HTMLDOC command line, e.g.

       sdf -2pdf_html "-DHTMLDOC_OPTS:--gray --jpeg" ...

To do: add support for AUTHOR, COPYRIGHT and DOCNUMBER.

At the moment, SDF headers and footers are not converted to their HTMLDOC equivalents. To access HTMLDOC's header/footer support, it's currently necessary to use the HTMLDOC_OPTS variable.

1.1.5. Improved LaTeX support

Valerio Aimale's (mailto:valerio@publinet.it) LaTeX driver is now part of the standard distribution. Refer to the file doc/notes/latex.notes for usage details.

1.1.6. HTML formatting enhancements

The following phrase attributes are now supported when generating HTML: color, family, size, bold, italic, underline, bgcolor and changed. A changed phrase or paragraph is shown with the background color given by the HTML_CHANGED_COLOR variable. The default value is teal.

The following paragraph attributes are now supported when generating HTML: align, first, left, right.

See the SDF files within the examples/2001/stylesheets directory for examples of using these attributes.

1.1.7. HTML meta information and stylesheet support

The meta filter can now be used to add META tags to the HEAD of a HTML document. This filter expects a table with columns called Name and Content, e.g.

!block meta
Name|Content
description|Tools for building Java systems
keywords|Java,development tools
!endblock

Stylesheets can be linked or embedded using the links and stylesheet filters respectively. Here's a linked stylesheet:

       !block links
       Jump
       test.css
       !endblock

Here's how to embed the same stylesheet:

       !include "test.css"; stylesheet

Phrases and paragraphs now support the following attributes:

Here's an example of applying a custom style:

  [style='background-color: blue;; color: red']
  A styled paragraph.

Note: SDF uses a single semi-colon to separate attributes, so attributes values with embedded semi-colons need to use ';;' to mean ';'. (The general rule is to use N+1 consecutive semi-colons to get N semi-colons).

1.1.8. Stylesheet-friendly HTML generation

Generated HTML documents are now "stylesheet-friendly" in that:

Here are the document sections placed in DIVs:

Document part DIV name
title section title
table of contents contents
main body main
header section header
footer section footer
navigate section navigate

The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.)

Here's the list of classes placed on parts of the title:

Class Comments
doc-title title of document
doc-id id of document
doc-author author list
doc-status document status
doc-modified modification date

Tables are implicitly given a class named after the SDF table style. Heading and footing rows within tables are given classes of heading and footing respectively. Here's a set of Cascading Style Sheet (CSS) rules for a colorful table:

  TABLE.columns {background-color: yellow}
  TABLE.columns TR.heading {background-color: aqua}
  TABLE.columns STRONG {font-size: 20pt}
  TABLE.columns TD {color: purple}

See the SDF files within the examples/2001/stylesheets directory for more examples of using these features.

1.1.9. Embedded documentation enhancements

A new filter called get has been added.

Support for embedded documentation in IDL has been improved (the IDL now gets pretty-printed in the "Interface" section).

The getdoc and getcode macros now guess the get-rule using the formatting extension.

The sdfget program has been enhanced in several ways:

The default.sdg report has been enhanced to support new sections called Notes, See_also and Authors.

A new SDG report called all.sdg has been added. This report formats all embedded documentation sections (unlike default.sdg which only extracts selected sections).

The default.sdg and all.sdg reports have been enhanced to support the SDG_BEGIN and SDG_END macros. These macros are empty by default so authors can override these to customise the display of extracted documentation.

1.1.10. Miscellaneous stuff

A new module called homepage has been added to make it easier to build SDF-like home pages. For an example of usage, see the source for SDF's home page (doc/home.sdf).

A Russian locale (ru_ru) has been added thanks to Alexey L. Popov (alpopov@elkamail.ru).

New macros called div and enddiv can be used to put divisions in documents.

If sdf's -p option is specified without a parameter, table prefiltering is assumed.

1.2. Fixes

Indented tables now work as expected, i.e. leading whitespace at the beginning of the heading row is now accepted and remaining rows have that amount of whitespace trimmed.

When generating txt output, leading cell whitespace now works as expected. Previously, multiple spaces were converted to a single space.

Attribute values containing ;; no longer have the whitespace around the character sequence trimmed.

Internally, unhandled internal directives no longer produce a warning. (As a result, it's now easier to extend things without "breaking" existing drivers.)

When generating HTML, the HTML_PRE_SECTION is no longer prepended unless a table of contents is generated.

1.3. Incompatibilities

When HTML is generated, the default footer no longer contains a line. To get the old behaviour, set the HTML_OLD_FOOTERS variable, e.g.

       sdf -2html -DHTML_OLD_FOOTERS ...

The HTML driver no longer uses special embedded comments to work out where to put the table of contents.

The getcli macro no longer searches the include path: it just executes the command.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog