5. 2.000beta11
Enhancements | Fixes | Incompatibilities
5.1. Enhancements
The enhancements are:
-
Documentation improvements
Better Perl documentation
Multi-line records in tables
Better man page support
Better PDF support
More flexible embedded documentation support
SDF expressions within inline blocks.
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
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 http://www.mincom.com/mtr/perl/pod/perl.html 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:
-
ftp://ftp.mincom.com/pub/mtr/sdf/perl/perlshtml-5.004_01.tar.gz
ftp://ftp.mincom.com/pub/mtr/sdf/perl/psh50041.zip
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
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
sdf -2book -zpdf mydoc.sdf sdf -2podps -zpdf mydoc.pdf
Note: The -2pdf option assumes that you have Adobe Acrobat's
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 <P> This HTML [[VERB]] expanded. !endblock
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 Pod:Sdf.pm.
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
None.