5. 2.000beta11

Enhancements | Fixes | Incompatibilities

5.1. Enhancements

The enhancements are:

Further details are provided below.

5.1.1. Documentation improvements

The documentation has been improved in the following ways:

  • it is now supplied in PDF format (in addition to PostScript and HTML)
  • the white paper, quick reference and tutorials are now single HTML documents, rather than sets of topics
  • the home page has been improved
  • the FAQ has been expanded and added to the catalog.

5.1.2. Better Perl documentation

The new mkpldocs program can be used to build the Perl documentation suite. Usage is:

  cd <perl_distribution_directory>
  mkpldocs all

The perl configuration library now generates better looking HTML with relative URLs. As such, the documentation can be easily moved after it is generated.

See for a publicly available version of the HTML generated by SDF for Perl 5.004_01. If you want a local copy, you can download it in either tar.gz or zip format. The URLs are:

5.1.3. Multi-line records in tables

Records in tables can now be continued onto the next line by terminating the line with a backslash. Like !-style macros:

  • exactly 2 terminating backslashes means a real backslash
  • N (N >= 3) terminating backslashes means N-1 real backslashes with continuation.

5.1.4. Better man page support

The -2man option nows sends output to standard output, rather than to a .man file. This improves compatibility with pod2man and makes it easier to do things like:

  sdf -2man faq.sdf | nroff -man | less

The following variables can now be used to change the headers and footers generated for man pages:

Variable Meaning
DOC_PRODUCT the center string in the header (e.g. Simple Document Format)
DOC_PROJECT the release name for the product (e.g. SDF 2.000beta11)
DOC_SECTION the section this man page is in

These variables are typically defined in a configuration library. You can also provide them on the command line using the -D and/or -f options like this:

  sdf -2man -DDOC_SECTION=3 ...
  sdf -2man -fsection=3 ...

5.1.5. Better PDF support

PDF support has been improved. To generate PostScript (via FrameMaker) and distill it to PDF, the new -2pdf option can be used like this:

  sdf -2pdf mydoc.sdf

If PostScript is being generated via a FrameMaker book or via pod2ps, the -zpdf option can be used like this:

  sdf -2book -zpdf mydoc.sdf
  sdf -2podps -zpdf mydoc.pdf

Note: The -2pdf option assumes that you have Adobe Acrobat's distill program on your path.

5.1.6. More flexible embedded documentation support

Mark Stavar's enhancements to SDF's embedded documentation support have now been integrated, but are not yet documented. These enhancements make it possible to put documentation into buffers which are formatted independently of the main one. Amongst other things, this makes it possible to have subtopics for each procedure/method/function in a library, each with its own set of Interface, Description, Examples, etc.

When time permits, I'll put together a tutorial explaining the different ways SDF can be used for embedded documentation. Until then, if you need further information on the multiple buffer approach, send me some email.

5.1.7. SDF expressions within inline blocks

SDF expressions are now supported within text processed by the inline filter thanks to a patch from Tim MacKenzie. For example,

!define VERB "is"
!block inline; expand
This HTML [[VERB]] expanded.

5.2. Fixes

Most of the links within the Perl documentation should now work correctly.

S phrases (i.e. phrases with non-breaking spaces) now work correctly for HTML and MIF formats. The nbsp variable has also been introduced as another way to insert non-breaking spaces.

HTML escapes (E phrases and CHAR phrases) are now supported by the mif and plain text drivers.

The default language used for pretty printing .h files is now C++, rather than C.

Non-last multi-line cells are now working correctly for delimited format (but aren't yet supported for fixed-width format).

Included some patches from Tim MacKenzie for:

  • handling filenames with non-alphanumeric characters like -
  • removing the need to have mif2rtf and sdfbatch on your path
  • improving compatibility with FrameMaker 4
  • better packaging of

To fix the formatting of MIMS specifications, the +ms option has been introduced.

When a FrameMaker book is generated:

  • the list of figures, list of tables and index, if any, should now appear in the table of contents
  • the last chapter now has a terminating line for infomap documents.

Missing libraries and modules now create a warning rather than an error.

The default footer for manuals has been changed to:

  • include the project name, if any
  • exclude the status if it's Final.

5.3. Incompatibilities