4. 2.000beta12

Enhancements | Fixes | Incompatibilities

4.1. Enhancements

Note: The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.

The major enhancements are:

Output format naming rationalisation

Automatic figure format conversion

Better HTML customisation and documentation

New output formats

Locales

Template processing

Paragraph text is now the default output

Post filtering

The minor enhancements are:

when include files and figures are searched for, the directory containing the document is now searched after the current directory
a Perl document catalog is now included (perl/catalog.sdf)
generation of non-MIF outputs is now slightly faster.

Further details on the major enhancements are provided below.

4.1.1. Output format naming rationalisation

As SDF occasionally provides several ways to generate an output:

a convention has been introduced for output format names (i.e. the parameter to the -2 option)
a mapping table has been added to sdf.ini so that sites can customise the mapping from logical format names to actual format names.

As a result, it is now easy to change sdf.ini so that PostScript generation (i.e. -2ps) is via POD format rather than via FrameMaker, say. Furthermore, regardless of the default setup for PostScript generation:

PostScript via FrameMaker can be explicitly requested via -2ps_fm, and
PostScript via POD can be explicitly requested via -2ps_pod.

Generally speaking, a name of xxx_yyy means format xxx via yyy. Likewise, a name of xxx_ means format xxx directly.

4.1.2. Automatic figure format conversion

As requested (many years ago, in fact), SDF will now automatically convert figure formats for you if it needs to. In particular, if you have a prn file on the search path, sdf will convert it to gif for HTML and eps for PostScript. Likewise, if you have an eps for PostScript, sdf will convert this to gif when you generate HTML.

Creating a prn file as a easy as printing to a PostScript file from most Windows apps including MS-Office and Rational Rose. As a result, figure management should no longer be the hassle its been in the past.

The conversion rules are stored in bin/sdf.ini. Feel free to have a look and/or forward me any additions/enhancements to the rules. One of the rules uses a new program supplied in SDF called prn2ps. This new command makes the output from a Windows 95/NT "print PostScript to a file" command acceptable to Ghostscript's ps2epsi.

4.1.3. Better HTML customisation and documentation

A large number of HTML customisation features already existed, but were poorly documented. The new customisation features in this release are:

HTML_PRE_HEADER/HTML_POST_FOOTER support
HTML_TEXT_* support
HTML_SECTION_LEVEL/HTML_PRE_SECTION support.

See the new tutorial titled Generating HTML Using SDF for details.

4.1.4. New output formats

SDF can now be converted to SGML like this:

  sdf -2sgml mydoc.sdf

By default, the linuxdoc DTD is used. Alternatively, the SGML_DTD variable can be used to change the DTD to qwertz, say, like this:

  !define SGML_DTD "qwertz"

If SGML-Tools 1.02 or later is installed, you can also generate the formats given below.

Command	Output format	Via
sdf -2latex_sgml	LaTeX	SGML-Tools
sdf -2dvi_sgml	DVI	SGML-Tools and LaTeX
sdf -2ps_sgml	PostScript	SGML-Tools and LaTeX
sdf -2rtf_sgml	RTF	SGML-Tools
sdf -2info_sgml	GNU info	SGML-Tools
sdf -2lyx_sgml	LyX	SGML-Tools

4.1.5. Locales

SDF now has better support for non-English languages via locales. The -L option of the sdf command can be used to specify a locale. The default locale name is specified in sdf.ini. Locale naming follows POSIX conventions (i.e. language_country), so the locale name for American english is en_us. The information for each locale is stored in the locale directory, so you'll need to have to look in there to see what locales are available. (As the default locale can be set in sdf.ini, this isn't as ugly as it first sounds.)

At the moment, a locale file simply contains a list of language specific strings, although it should ultimately be extended to support localisation of date and time formats. Feel free to send me new locales so I can include them in future versions of SDF.

4.1.6. Template processing

SDF can now also be used as a generic template processor, i.e. you can create C source, say, with ! macros and [[..]] expressions within it and use sdf to process it. For example, if you have a file called xx.sdt like this:

    !if DATE
        <P>
        The date is [[DATE:DOC_START]].
    !else
        <P>
        The time is [[TIME:DOC_START]].
    !endif

you can process it like this:

  sdf xx.sdt | less
  sdf -DDATE xx.sdt | less

If the file doesn't have a sdt extension, you need to specify template processing like this:

  sdf -ptemplate myskel.cpp | less

4.1.7. Paragraph text is now the default output

If you run the sdf program on a file without giving a target, the text of each paragraph is output. Therefore, you can now do things like:

sdf mydoc.sdf | spell -b

4.1.8. Post filtering

It is now possible to post filter the output of a format driver before the results are written to disk. The -y option of the sdf command can now be used to specify a post filter name. A post filter called xxx maps to a routine called xxx_PostFilter in the file perllib/sdf/post_xxx.pl.

Note: This feature is only useful for SDF developers who want to create a new output format which is very simliar to an existing one.

4.2. Fixes

Heading numbering in HTML and text outputs should be fixed now.

The file and line number in messages should generally be right now. Certain filters may still lead to incorrect line numbers being reported, but messages containing '$fullname', line number 0 or -1 should no longer appear.

Man page generation now works again. Previously, pod2man fell over unless a DOC_PROJECT and DOC_RELEASE was defined.

MIMS HTX and F6 Help formats should be working correctly now. The MIMS_CLIENT_CODE variable must now be specified on the command line when generating MIMS F6 help.

The APIs for SDF's Perl libraries are now present again in the SDF Guru Guide.

4.3. Incompatibilities

The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.

Given the rationalisation of output format naming, some of the previously used names (e.g. fmrtf, sgmllatex) have been changed. If the sdf command complains about an unknown alias, have a look in sdf.ini to see what the new name is.

The interface to FindFile, a subroutine which some users override to integrate SDF into their CM system, has changed. See the FindFile documentation for details.