2. 2.001beta1

Enhancements | Fixes | Incompatibilities


2.1. Enhancements

The enhancements are:

2.1.1. Better documentation

The SDF Quick Reference has been greatly improved. It now documents 95% of SDF's features rather than the 10% of features most frequently used.

2.1.2. build_title enhancements

If DOC_CODE is set and DOC_NAME is not set, build_title will now lookup DOC_NAME via references data if it can.

The separator between DOC_CODE and DOC_VERSION in DOC_ID can now be controlled by setting DOC_ID_SEP. The default value is '.'.

2.1.3. Library search path

Previously, libraries had to be placed in the perllib/sdf/home directory. Now, sdf's new -Y option can be used to specify a comma-separated list of directories to search for libraries. For example, if you want sdf to search c:\mysdflib and c:\ for libraries on a MS-DOS/Windows system, the command is:

  sdf -Yc:\mysdflib,c:\ ...

If your search path for libraries is always the same, the SDFOPTS environment variable can be used, e.g. the following sequence of commands will have the same effect as above:

  set SDFOPTS=-Yc:\mysdflib,c:\
  sdf ...

2.1.4. Improved searching rules

Previously, libraries had to be placed in a fixed location but modules used the same search rules as normal files. Now that sdf supports a library search path, libraries, modules and normal files have different search rules. The new rules are:

File type Directories searched
libraries current directory, document's directory, directories on the library path, perllib/sdf/home
modules current directory, document's directory, directories on the module path, perllib/sdf/home, perllib/sdf/home/stdlib
normal files current directory, document's directory, directories on the include path, perllib/sdf/home

The library path and the module path are initialised by sdf's -Y option. The include path is initialised by sdf's -I option. Inheriting a library (via a configuration library or the inherit macro) appends the library's directory to the module path and the include path.

2.1.5. Pretty printing enhancements

Language names are now case insensitive. The keywords for Perl, Java and IDL have also been improved. Python support has been added.

2.1.6. Localisation improvements

Strings within dates and times can now be localised using the datestrings filter. See en_au.sdl for an example.

A Czech locale (cz_cz) is now provided (although it doesn't have localised date strings yet).

2.1.7. New verbose levels and debug tracing

sdf's -v option now supports additional verbose levels:

As before, level 1 shows the post-processing actions and leaves intermediate files around.

In addition, sdf's new -T option can be used to switch on debug tracing. The parameter is a comma-separated list of name-value pairs where each name is a tracing group and each value is the level of tracing for that group. To get the trace output provided by the -v option, one can use the user group like this:

  sdf -Tuser=2 ...

This is slightly different from the -v option in that intermediate files are not implicitly kept. Additional tracing groups will be added over time (probably one per output driver).

2.1.8. Miscellaneous stuff

Class filters now support a variables parameter which implicitly defines a variable for each object. The variable name is the same as the object name with non-alphanumeric characters replaced with '_'. (This feature should simplify configuration libraries for projects.)

The jumps macro has been introduced as a more convenient form of the subsections macro. (This feature should simplify web pages for projects.)

KP and KN have been added as paragraph styles. These are shorthands for N[keep_prev] and N[keep_next] respectively.

SUB and SUP have been introduced as phrase styles for subscripts and superscripts respectively. (Consider these experimental features for now, as I haven't had a chance to test them.)


2.2. Fixes

The SDF Templates link on the home page included in the distribution now points to the SDF web site as it should.

Mac filename handling should finally be ok now. (However, installation instructions for the Mac are yet to be added.)

Minor corrections have been made to the SDF User Guide.

The conversion of PRN files to GIF files has been improved: a margin is no longer added as ps2gif is prone to incorrectly make it black.

Books generated with the fancy look now have a correctly formatted table of contents.

Java pretty printing has been fixed.


2.3. Incompatibilities

The Improved search rules may introduce some unexpected incompatibilities, particularly if custom file searching was implemented. Previously, advanced users could customise the search rules (to integrate a configuration management system, say) by overriding the FindFile subroutine. The default FindFile subroutine no longer searches perllib/sdf/home/stdlib, but otherwise, the search rule for normal files has not changed so custom FindFile routines should still hopefully work. The new routine called FileModule will need to be overriden if your custom FindFile is also needed for finding modules (or similar things like sdg, sdr and sdp files).