Ian Clatworthy > sdf > abc

Download:
sdf-2.001.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

abc - output the alphabet

DESCRIPTION ^

This program displays the alphabet like this:

  ABCDEFGHIJ
  KLMNOPQRST
  UVWXYZ

Pretty simple, eh? !endblock #!endblock

gets converted to:

#!block box !block example; listitem =head1 NAME

abc - output the alphabet

DESCRIPTION ^

This program displays the alphabet like this:

> ABCDEFGHIJ > KLMNOPQRST > UVWXYZ

Pretty simple, eh? !endblock #!endblock

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

> sdf -2html perlrun.pod

How does this work? Well, the {{CMD: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 {{FILT:pod}} filter (which converts POD to SDF).

If you want to use the {{CMD: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:

> sdf -2html -ppod xyz.pd

H1: How do I convert from SDF to POD?

By using the {{CMD:sdf}} program. Typical usage is:

> sdf -2pod mydoc.sdf

This will create a file called mydoc.pod in the current directory.

The general usage of the sdf program is:

> sdf [options] filename ...

A {{.sdf}} extension is assumed on each filename (unless a filename without the extension is found).

H1: How do I nest SDF inside a POD document?

If you're generally happy with POD and only need SDF occasionally, SDF can be embedded in POD using POD's =for command or =begin/=end command pair. Some examples are:

!block example Here's our new logo:

    =for sdf !import "mylogo.gif"
  
    And these are the documentation systems we use:
  
    =begin sdf
  
    !block table
    Name    Meaning
    POD     Plain Old Documentation
    SDF     Simple Document Format
    !endblock
  
    =end sdf
!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.

H1: How do I nest POD inside an SDF document?

By using the {{FILT:pod}} filter. Filters can be applied to blocks of text in a file, complete files or the output of programs. Some examples are:

!block example; lang='sdf' # Insert some pod !block pod =head2 My heading

    A normal POD paragraph.

        And some verbatim text.
    !endblock

    # Get pod from a file
    !include "perlre.pod"; pod

    # Get pod from standard output
    !execute "getpod 'hello.c'"; pod
!endblock

So reusing existing POD documentation within an SDF document is easy.

H1: Is it hard to learn SDF?

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:

!block example 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!
!endblock

* Except for lines within a multi-line macro call or a {{MAC:block}}/{{MAC: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:

!block table; listitem; narrow 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 !endblock

. For example, a simple bulleted list is shown below.

!block example * item 1 - item 1a - item 1b * item 2 * item3 !endblock

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

H1: Is SDF more readable than POD?

To its fans, SDF is more readable than POD for the following reasons:

* simple lists look like lists (which is quite important for embedded documentation masquerading as comments)

* a single line macro syntax is available (!-style), making SDF documents less whitespace intensive

* leading whitespace doesn't imply verbatim, so nested things can look nested

* multi-character phrase styles can be used, e.g. E<2{>DOC: SDF for POD UsersE<2}>, making the document source more readable

* within E<2{> style phrases, > doesn't need to be escaped unless a [A-Z]<> phrase is nested, so certain code examples are more readable, e.g. E<2{>C:$arrayref->[0]E<2}>.

Of course, POD's fans argue that POD is more readable for equally valid reasons. Beauty is in the eye of the beholder - even Lisp has it's fans. :-)

H1: What does SDF offer me?

The main reasons for using SDF over POD are:

!block sections ^ Tables + Figures + Variables + Better Extensibility + Configurable Expansion of Links !endblock

These are briefly considered below.

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.

H2: Tables

SDF support tables via the {{table}} filter. Typically, tables are defined using the {{MAC:block}} and {{MAC:endblock}} macros like this:

!block example !block table Name Meaning POD Plain Old Documentation SDF Simple Document Format !endblock !endblock

The result is:

!block table Name Meaning POD Plain Old Documentation SDF Simple Document Format !endblock

The first line specifies the headings and the input format of the data:

* if the first two field names are separated by whitespace, the input format is assumed to be fixed-width * otherwise, the input format is assumed to be "delimited" and the special character separating the first two fields is the delimiter.

For readability reasons, fixed-width format is preferred. Delimited format is useful for tables already in that format and for data exported by spreadsheets.

SDF supports a large number of features for tables including:

* column widths can be dynamically sized or explicitly set * heading, footing and group rows can be specified * table alignment and positioning can be controlled * cells support custom alignment, shading, ruling and colours.

See the {{DOC: SDF User Guide}} for further details.

H2: Figures

Figures are supported in SDF via the {{MAC:import}} macro. The usage is:

> !import "filename" [parameters]

For example:

> !import "mylogo"; align=Right

It is generally best {{not}} to specify an extension for the filename containing the figure, as SDF will then use the best format it can find. The search rules are:

!block table; narrow When_generating The_search_order_is PostScript epsi, eps, wmf, mif, gif HTML jpeg, jpg, png, gif Windows Help bmp !endblock

See the {{DOC: SDF User Guide}} for further details.

H2: Variables

Variables can be defined using the {{MAC:define}} macro like this:

> !define VERSION 1.34

The first argument is the variable name and the second argument is the value. You can use a Perl expression for the value if you wish. For example:

> !define LOGO $ENV{'LOGO'} || "mylogo"

Having defined a variable, it can be used in paragraph text by enclosing it within E<2[> and E<2]>. For example:

> WorldPeace [[VERSION]] is just what you need and > is available for free download from ...

In fact, a Perl expression can be embedded in paragraph text the same way, e.g.

> !define STARS 5 > ... > This movie gets [['*' x $var{'STARS'}]].

Within Perl expressions, SDF variables are available via the %var associative array.

H2: Better Extensibility

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 {{DOC: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 {{CMD:sdf}} command line. This is useful if you want an SDF configuration library for a POD document, say.

H2: Configurable Expansion of Links

For L (Link) phrases, SDF lets you customise:

* the rules for expanding the text * the HTML URL searching/generation rule

This flexibility is important for non-English documentation and non-Perl documentation.

To change the text expansion rules, define one of more of the variables below:

!block table Variable Default_Value FORMAT_LINK_PAGE the $page manpage FORMAT_LINK_PAGE_ENTRY the $entry entry in the $page manpage FORMAT_LINK_PAGE_SECTION the section on "$sect" in the $page manpage FORMAT_LINK_SECTION the section on "$sect" !endblock

For example:

> !define FORMAT_LINK_SECTION 'the "$sect" section'

To change the URL generation rule, override the {{BuildLinkUrl}} subroutine like this:

!block example !block script sub BuildLinkUrl { my ($page, $sect, $entry) = @_; my $url = ... return $url; } !endblock !endblock

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

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

The default value of PERL_HTML_ROOT is /perl.

H1: What's wrong with SDF?

The most common complaints about SDF are:

^ It isn't WYSIWYG. + It doesn't support the output format I need. + It doesn't have the features I need. + It has too much functionality.

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:

* SDF's basic ideas (styles, attributes, macros, filters and variables) and commonly used tags are easy to learn * 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. :-)

H1: Credits

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.

Finally, I'd like to thank the people who encouraged me to merge POD and SDF, including Kenneth Albanowski, Brad Appleton, Achim Bohnet, Jim Esten, Chaim Frenkel, Gerd Knops, Hugues Lafarge, Tuomas J. Lukka, Andy Wardley and Peter Wolfe. I hope the result is useful.

syntax highlighting: