Over the last few years, Perl's POD format has proven itself as a useful tool for documenting Perl's functionality and its library modules. POD is easy to learn, easy to read and easy to embed.

In 1992, I wanted to embed documentation in source code in order to make it easier to keep the documentation up to date. POD didn't exist, so I invented a similar system called SDF (Simple Document Format) and implemented it in Perl, the world's greatest programming language. SDF has grown rapidly over the years and is now a powerful general purpose documentation system. But like POD, SDF has remained simple in spirit: easy to learn, easy to read and easy to embed.

In June 1997, most of POD's syntax and functionality were merged into SDF, making it easier for people to migrate from POD to SDF. This document aims to answer the following questions for POD users:

Note that it isn't actually necessary to use pod2sdf unless you intend migrating to SDF format - the sdf program can be used on a POD file directly like this:

sdf -2html perlrun.pod

How does this work? Well, the sdf program can be configured to automatically prefilter files with certain extensions. The default configuration is to prefilter .pod, .pm and .PL files with the pod filter (which converts POD to SDF).

If you want to use the sdf program on POD files without one of these extensions, you can either edit the sdf.ini configuration file, or explicitly specify the prefiltering like this:

No. 90% of SDF documents use a set of core features which can be summarised in a few pages. For POD users, the main things to know are these:

Leading whitespace is generally ignored in SDF. So, verbatim lines need to be explicitly marked using a > tag, or enclosed within "!block verbatim" and "!endblock".

Commands in POD are called macros in SDF. Macros can be called using the same syntax as POD, i.e. an = at the start of a line starts a macro call which terminates at the next blank line. All of POD's commands are available as macros in SDF.

Interior sequences in POD are called phrases in SDF. Phrases can be called using the same [A-Z]<..> syntax as POD. All of POD's interior sequences are available as POD phrases.

Normal paragraphs in SDF are the same as normal paragraphs in POD, except that paragraphs can be optionally tagged with a paragraph style and/or paragraph attributes. The general syntax is:

style":" text

or

style"["attributes"]" text

Some examples are:

A normal paragraph with
a few lines.
Note: This is a paragraph tagged with
the Note style.
Note[label='Important'] This is an important note!

Except for lines within a multi-line macro call or a block/endblock macro pair, each line may begin a new paragraph or macro. So, if you have a special character or pattern at the start of a line, you will need to escape it by placing a backslash character (\) before it.

To maximise convenience and readability, list items can be tagged using the special characters below:

Tag

Meaning

*

bulleted list item

-

2nd-level bulleted list item

.

plain list item/paragraph

^

first item in an ordered list

+

next item in an ordered list

&

enumerated list item

For example, a simple bulleted list is shown below.

* item 1
- item 1a
- item 1b
* item 2
* item3

Of course, you can always use the over/item/back macros if you prefer them.

Note: Not every output format supported by SDF supports every table/figure feature. In some cases, the SDF -> xxx format driver isn't yet clever enough. In other cases, the target format isn't clever enough! So, your milage may vary with some of these features, particularly in the short term as the SDF format drivers are maturing. Of course, the Perl source code for each format driver is provided with the SDF package, so feel free to improve them.

From its beginning, one of SDF's primary goals has been to support the authoring of documents in a logical manner. Therefore, it is possible to define your own:

paragraph styles

paragraph attributes

phrase styles

phrase attributes

and to either alias these to existing styles/attributes or map them to target format entities.

Likewise, you can define your own macros and filters to do almost anything you want. See the SDF Guru Guide for further details.

Typically, a workgroup or project team will put their extensions in an SDF library, which is essentially a normal SDF file which is included at the start of each document. Alternatively, you can specify a configuration library on the sdf command line. This is useful if you want an SDF configuration library for a POD document, say.

The default implementation of BuildLinkUrl is simplistic by design. This is considered a feature. If you want intelligent URL generation ala pod2html, use the perl configuration library and set the PERL_HTML_ROOT variable like this:

On the WYSIWYG issue, SDF is a tool for people who would rather use a text editor. It tries hard to be readable and an emacs mode is available. If that isn't good enough, then SDF isn't for you.

On the output format issue, I'm working on it. For developers with a good knowledge of Perl and the output format they need, writing an "SDF output driver" isn't hard, it just takes time. Like all of us, I only have so much free time, so any assistance anyone can offer in this regard is very welcome.

On the functionality issue, SDF is growing and will continue growing. If it doesn't have a feature you need, the Perl source code is provided, so you might be able to add it yourself.

If SDF is already too complex, then stick with POD. You can always mix in some SDF or migrate to SDF if you need to at a later date. Personally, I find the "I'm sticking with POD because SDF is too complex" argument a little short-sighted:

I'd rather use the same markup language for embedded documentation, memos, design documents and user documentation.

I prefer SDF to POD for the same reason that I prefer Perl to awk: the latter may be sufficent for a given task, but choosing it will cause me grief the moment the task grows. On the other hand, as the designer of SDF, I'm probably just a little biased. :-)

Thanks to the many people who have used and contributed to SDF over the years, particularly David Cox, Tim Hudson and Chris Moran. Likewise, thanks to Larry Wall for inventing Perl and to everyone who has contributed to Perl over the years. Without it, SDF wouldn't exist.