Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog
Enhancements | Fixes | Incompatibilities
The primary objectives of this release are:
I still need to fix up some bugs and loose ends with respect to the POD stuff, but there's enough working to be useful (in my opinion, at least). In particular, the core POD documentation provided with Perl 5.004 can be:
If you're an existing POD user, please read the SDF for POD Users tutorial. If you find a bug not listed in the PODNOTES file, email the details to sdf-bugs@mincom.com.
If you're an existing SDF user, please note that most of the documentation doesn't yet reflect the changes outlined below. You will also need to take care with the Incompatibilities outlined below.
The enhancements are:
Further details are provided below.
POD users can now use SDF or migrate to SDF when POD isn't powerful enough. In particular:
A
Any SDF macro can now be called via POD's = syntax, i.e. if a macro call starts with an = character, the call is terminated by the next blank line.
As a consequence of its new meaning, = is no longer available as a shorthand for the E paragraph tag. However, the > character can now be used as a shorthand for the V (verbatim) paragraph tag. See Verbatim paragraphs below.
Any phrase style which is a single capital letter can now be specified using POD's [A-Z]<..> syntax. So, the following lines are equivalent:
Hello {{B:world}} Hello B<world>
Paragraph and phrase styles must now start with a capital letter, digit or underscore. As a result, the following SDF will now come out as expected.
The following documents should be reviewed:
Previously, SDF would warn about reviewed being an unknown paragraph style. As a special case, phrases which look like URLs are still assumed to be so.
Outside of blocks and multi-line macros calls, a \ at the start of a line now escapes a special character or pattern, including itself. A \ can also be used to escape a ] character within a set of attributes.
At the end of a !-style macro call line:
For fixed-width verbatim paragraphs, the > special tag or V paragraph style can now be used. For example:
> {{Hello world}}
or
V: {{Hello world}}
The result is:
{{Hello world}}
The new verbatim filter can be used to mark a block of text as verbatim.
In fact, the interpolation of embedded characters within the text of any paragraph can be disabled by setting the verbatim paragraph attribute. For example:
N[verbatim] {{Hello world}}
The result is:
{{Hello world}}
SDF uses a number of special symbols inside paragraphs:
If you need to include one of these symbols in a paragraph, use the appropriate escape as shown below.
Symbol Escape < E<lt> > E<gt> {{ E<2{> }} E<2}> [[ E<2[> ]] E<2]>
Note the following rules:
In addition to bulleted, ordered and plain lists, SDF now supports enumerated lists, i.e. lists where each item is a label. Each enumerated list item is tagged with either:
For example:
& BTW . by the way & FYI . for your information & RTFM . read the flamin' manual
The result is:
BTW
FYI
RTFM
All of POD's commands are now available as SDF macros. The new macros are:
Macro | Meaning |
headn | level n heading (n = 1 .. 6) |
over [N] | begins a list (N is the suggested indentation which is ignored) |
item string | label for item in a list |
back | ends a list |
pod | does nothing |
cut | ignore text until an = is found at the start of a line |
for X Y | Y is target-specific output for X |
begin X | begin target-specific output for X |
end X | end target-specific output for X |
See the perlpod manpage for further details.
All of POD's interior sequences are now available as SDF phrase styles. The new phrase styles are:
Style | Meaning |
B | bold |
C | code |
E | special symbol or HTML escape |
F | file |
I | italics |
L | POD-style link |
S | text contains non-breaking spaces |
X | an index entry |
Z | does nothing |
See the perlpod manpage for further details on the meanings of these tags.
The sdf -2man ... command now generates a .out file in POD format and runs
The sdf -2latex ... command now generates a .out file in POD format and runs
The sdf -2text ... command now generates a .out file in POD format and runs
Hopefully, someone will provide fully functional manpage and LaTeX drivers (complete with table support) eventually.
SDF can now generate PostScript without needing a commercial tool. This can be done by:
In general, the output via these methods isn't as good as the PostScript generated via FrameMaker, but it may be good enough. In particular, certain looks (e.g. infomap) are not available.
A
pod2sdf [-m] podfile > outfile
If the -m option is provided, the document is converted as a main document, rather than a topic, i.e. the NAME section is converted to a build_title macro rather than a head1 macro.
POD authors can escape to SDF if and when they need to by using the "=for sdf" and/or "=begin/end sdf" command pair. For example:
=for sdf !block table Name Meaning POD Plain Old Documentation SDF Simple Document Format !endblock
If you want the rest of a POD file to be in SDF, simply put in an "=begin sdf" - the closing "=end sdf" isn't necessary.
POD can now be nested inside SDF via the new pod filter (which is another wrapper around the Pod::Sdf module). e.g.
!block pod =head2 My B<heading> Some verbatim text !endblock
The pod filter can also be specified to the include and execute macros. For example:
!include "perlre.pod"; pod !execute "getpod 'hello.c'"; pod
where getpod is a fictitious program which outputs POD to standard output.
If a file with a .pod, .pm or .PL extension is provided as an argument to the sdf command, the pod filter is implicitly applied. So
will generate HTML for perlre.pod using SDF's HTML output driver. You can also explicitly request pod prefiltering via the -p option. e.g.
When pod prefiltering happens, the output is assumed to be a main document.
A configuration library for building Perl's documentation is provided. The main thing which this provides is semi-intelligent hypertext link generation between Perl's standard documentation and its library documentation. Within this library, the HTML root directory (equivalent to
sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perl*.pod
At the moment, this library is only required for HTML generation.
When editing a topic within a large document, it can be useful to only compile that topic in order to preview its appearance. The new -H option can be used to adjust the initial heading level like this:
sdf -2ps -H3 -kinfomap mytopic.sdf
Without the -H3 option, the H1s within mytopic.sdf would come out as level 1 headings, rather than level 3 headings.
The width of text output can now be controlled from the command line by using the new -w option to the sdf program.
Special characters in headings (like [) no longer cause problems.
The POD output driver has been fixed. In particular, the generation of list items has been fixed.
Some bugs in the pretty printing of source code have been fixed:
Handling of multi-line macro calls within a block or macro has been fixed.
The box filter no longer centers the contents of the box unless the lines parameters is provided.
This release now requires Perl 5. If you are still using Perl 4.036, you will need to upgrade.
As paragraph and phrase styles can no longer start with a lowercase character, you will need to rename any user-defined styles which violate this rule.
Lines within paragraphs which begin with the > or & character will now need to be escaped by a leading \.
Wide example now use a slightly smaller font.
The default values for the DOC_DISTRIBUTION and DOC_STATUS variables are now empty strings. Previously, they were "COMMERCIAL IN CONFIDENCE" and "Draft" respectively.
Making SDF POD-friendly has introduced a number of incompatibilities. These are summarised below:
Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog