Google

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog


6. 2.000beta10

Enhancements | Fixes | Incompatibilities

6.1. Introduction

The primary objectives of this release are:

  1. To provide a "working prototype" for a POD-friendly SDF.
  2. To rationalise SDF's escaping mechanisms and stabilise it's syntax.
  3. To provide greatly improved man page generation (via pod2man).
  4. To provide PostScript generation without needing a commercial tool.

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:

  1. Converted to SDF and back to POD with a high degree of success (99.95% if the perltoc.pod file is excluded).
  2. Converted to HTML and plain text using the sdf program.

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.

6.2. Enhancements

The enhancements are:

Further details are provided below.

6.2.1. SDF is now POD-friendly

POD users can now use SDF or migrate to SDF when POD isn't powerful enough. In particular:

  • POD can now be converted to SDF and vice versa
  • SDF can now be nested inside POD and vice versa
  • SDF is now largely upwardly compatible with POD in terms of syntax and functionality.

A poddiff program is provided so that users can translate POD -> SDF -> POD and compare the generated POD with the original.

6.2.2. Syntax Enhancements

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:

  • a single \ continues the macro onto the next line
  • exactly 2 backslashes means a single backslash (with no continuation)
  • N backslashes (N >= 3) means N-1 backslashes with continuation

6.2.3. Verbatim paragraphs

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}}

6.2.4. Special symbol escapes

SDF uses a number of special symbols inside paragraphs:

  • A-Z< and > - delimit concise phrases
  • {{ and }} - delimit verbose phrases
  • [[ and ]] - delimit expressions (e.g. variables).

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:

  1. It isn't necessary to escape any symbols within:
    • paragraphs tagged with the V style or > tag
    • paragraphs given the verbatim attribute
    • paragraphs within a verbatim block
  2. It is only necessary to escape a < when it appears after a capital letter.
  3. It is only necessary to escape a > inside a concise phrase. In particular, > is implicitly escaped within a verbose phrase.

6.2.5. Enumerated lists

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:

  • a & special tag (& .. &&&&&& like the other lists), or
  • the LIn style, where n = 1 .. 6.

For example:

& BTW
. by the way
& FYI
. for your information
& RTFM
. read the flamin' manual

The result is:

BTW

    by the way

FYI

    for your information

RTFM

    read the flamin' manual

6.2.6. New macros

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.

6.2.7. New phrase styles

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.

Note: The S and X tags are not yet working for most output formats.

6.2.8. Manpage, LaTeX and fancy text support

The sdf -2man ... command now generates a .out file in POD format and runs pod2man. The old man page generation software was limited in scope and quite buggy, so this will hopefully improve things in the short-to-medium term. The toman.pl output driver has been moved to the contrib/drivers directory just in case anyone really wants to use it instead.

The sdf -2latex ... command now generates a .out file in POD format and runs pod2latex. This creates a .out.tex file which should probably be renamed to delete the .out bit.

The sdf -2text ... command now generates a .out file in POD format and runs pod2text. For compatibility with pod2text, this sends the output to standard output.

Note: Plain text output is still available via the -2txt option.

Hopefully, someone will provide fully functional manpage and LaTeX drivers (complete with table support) eventually.

6.2.9. PostScript generation without a commercial tool

SDF can now generate PostScript without needing a commercial tool. This can be done by:

  1. Using sdf -2podps ... which generates PostScript directly via the freely available pod2ps program.
  2. Using sdf -2man ... which generates a man page which can be converted to PostScript by using the appropriate (*roff) tools.
  3. Using sdf -2latex ... which generates a LaTeX document which can be converted to PostScript by using LaTeX.

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.

6.2.10. POD to SDF conversion

A pod2sdf program is now available which is a wrapper around a Perl module called Pod::Sdf. The SDF generated is more or less identical to the input POD, except that verbatim lines are tagged with a leading ">". The usage of pod2sdf is:

  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.

6.2.11. Nesting of POD within SDF

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

Note: Within the pod filter, all lines before the first command is ignored and leading whitespace implies a verbatim paragraph.

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.

6.2.12. Automatic translation of POD files

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

    sdf -2html perlre.pod

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.

    sdf -2html -ppod abc.pd

When pod prefiltering happens, the output is assumed to be a main document.

6.2.13. Configuration library for Perl documentation

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 pod2html's --htmlroot flag) can be controlled via the PERL_HTML_ROOT variable. The default value is /perl. Typical usage is:

  sdf -2html -cperl -DPERL_HTML_ROOT=/nmanual/perl perl*.pod

At the moment, this library is only required for HTML generation.

6.2.14. Topic previewing

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.

6.2.15. Easier text width control

The width of text output can now be controlled from the command line by using the new -w option to the sdf program.

6.3. Fixes

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:

  • 80 character lines should now fit
  • The >> character sequence is no longer lost
  • form feeds become page breaks.

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.

6.4. Incompatibilities

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:

  • The = character is no longer a shorthand for E: - it is now used for multi-line macro calls.
  • Existing paragraphs which contain the sequence [A-Z]<..> (i.e. a POD-like phrase) as text will need to be changed.
  • The S (strong) and E (example) phrase styles have been renamed to ST and EX respectively. S and E now have the same meaning as their POD counterparts, i.e. "text contains non-breaking spaces" and "escape" respectively. As the S tag was often used for "symbols" (i.e. variables, subroutines) within a library, a Y tag has been introduced for this purpose.

Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog