H1: 2.000beta11
!subsections "Enhancements,Fixes,Incompatibilities"
H2: Enhancements
The enhancements are:
!block sections
. 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.
!endblock
Further details are provided below.
H3: 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.
H3: Better Perl documentation
The new {{CMD: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 {{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}}
H3: 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.
H3: Better man page support
The -2man option nows sends output to standard output, rather than
to a .man file. This improves compatibility with {{CMD: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:
!block table
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
!endblock
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 ...
H3: 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
{{CMD: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]] {{PRD:Acrobat}}'s {{CMD:distill}} program on your path.
H3: 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.
H3: SDF expressions within inline blocks
SDF expressions are now supported within text processed by
the {{FILT:inline}} filter thanks to a patch from Tim MacKenzie.
For example,
!block example; lang='sdf'
!define VERB "is"
...
!block inline; expand
<P>
This HTML [[VERB]] expanded.
!endblock
!endblock
H2: 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 {{CMD:mif2rtf}} and {{CMD: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}}.
H2: Incompatibilities
None.