SDF(1)

📦
version 2.001+1 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing

💖 SDF(1) — User Contributed Perl Documentation 💖

okay bestie, welcome to the SDF(1) manual page from the User Contributed Perl Documentation corner. This is sdf, the SDF Conversion Utility, and it's giving “convert my SDF files into other document formats” energy. I'm obsessed. Let's get into it, fr fr. ✨

🌸 NAME 🌸

sdf — SDF Conversion Utility

That's literally the name. It's giving name. Periodt.

🎀 PURPOSE 🎀

sdf converts SDF files to other document formats. That's the purpose. That's the whole assignment. No cap. 💅

🦋 USAGE 🦋

Here's the usage, bestie. Copy it exactly because it's the blueprint:

        usage  : sdf [+alias] [-h[help]] [-o[out_ext]]
                [-l[log_ext]] [-O[out_dir]] [-2 format]
                [-D variable,..] [-n split_level]
                [-f flag,..] [-I include_path,..]
                [-p[prefilter]] [-a parameters] [-P[plang]]
                [-N[line_numbers]] [-g[get_report]]
                [-r report] [-L locale] [-k look]
                [-s style] [-S page_size] [-c config]
                [-u uses,..] [-H head_level] [-K head_look]
                [-d driver] [-y post_filter]
                [-z post_process,..] [-t target]
                [-v[verbose]] [-T trace_levels,..]
                [-w width] [-Y library_path,..]
                sdf_file ...
       purpose: convert an sdf file to another format
       version: 2.001    (SDF 2.001)

💖 The options are: 💖

  • -h — display help on options
  • -o — output file extension
  • -l — log file extension
  • -O — output to input file's (or explicit) directory
  • -2 — the output format you want
  • -D — define variables
  • -n — heading level to autosplit into topics
  • -f — define flags (i.e. DOC_* variables)
  • -I — search path for include files, templates, etc.
  • -p — pre-filter input file from each argument
  • -a — parameters for the pre-filter
  • -P — pre-filter as a programming language
  • -N — number lines in pretty-printed source code
  • -g — pre-filter using sdfget with the report specified
  • -r — report to run on the SDF to transform it before formatting
  • -L — locale
  • -k — look library
  • -s — style of document
  • -S — page size for paper documents
  • -c — configuration library
  • -u — modules to use
  • -H — initial heading level
  • -K — heading look (H, A or P)
  • -d — format driver - default is expand
  • -y — filter to post-filter the output with
  • -z — list of post processing actions to do
  • -t — logical target format
  • -v — verbose mode
  • -T — debugging trace levels
  • -w — width for text-based outputs
  • -Y — search path for libraries

👑 The aliases are: 👑

  • mc — generate a MIMS chapter
  • ms — generate a MIMS spec
  • mt — generate a MIMS topic
  • sdf2doc_fm — generate Frame binary format via FrameMaker
  • sdf2dvi_sgml — generate DVI format via SGML
  • sdf2fvo_fm — generate FrameViewer format via FrameMaker
  • sdf2hlp_mif — generate Windows Help input files via MIF
  • sdf2html_ — generate a HTML document
  • sdf2html_dir — generate an SDF directory in HTML
  • sdf2html_fm — generate a HTML document via FrameMaker
  • sdf2html_topics — generate HTML topics
  • sdf2htx_ — generate MIMS HTX format
  • sdf2info_sgml — generate GNU info format via SGML
  • sdf2latex_ — generate LaTeX
  • sdf2latex_pod — generate LaTeX format via POD
  • sdf2latex_sgml — generate LaTeX format via SGML
  • sdf2lyx_sgml — generate a LyX file via SGML
  • sdf2man_pod — generate Man page format via POD
  • sdf2mf6_ — generate MIMS F6 help format
  • sdf2mif_ — generate Frame MIF format
  • sdf2pdf_html — generate PDF via HTML
  • sdf2pdf_mif — generate PostScript and PDF via FrameMaker
  • sdf2pod_ — generate POD format
  • sdf2ps_fm — generate PostScript via FrameMaker
  • sdf2ps_fmbook — generate PostScript via a FrameMaker book
  • sdf2ps_html — generate PostScript via HTML
  • sdf2ps_pod — generate PostScript via POD
  • sdf2ps_sgml — generate PostScript via SGML
  • sdf2rtf_fm — generate RTF format via FrameMaker
  • sdf2rtf_mif — generate RTF format via MIF
  • sdf2rtf_sgml — generate RTF format via SGML format
  • sdf2sdf_expand — generate expanded SDF
  • sdf2sdf_raw — generate raw SDF
  • sdf2sgml_ — generate SGML format
  • sdf2txt_ — generate plain text format
  • sdf2txt_fm — generate plain text format via FrameMaker
  • sdf2txt_pod — generate plain text format via POD

💖 DESCRIPTION 💖

Okay bestie, this is the big one, so grab a snack 🍓

-h is your help button and she serves. If you use it with no parameter, you get a cute lil brief description of every single option. But if you want the full tea on one specific option, pass that option letter as the parameter and she'll spill the attributes for you. 💅

By default, whatever sdf generates goes straight to standard output. If you'd rather get one output file per input file, hit up -o and hand it an extension for the output files. And if you use -o with no parameter at all? It just assumes an extension of out. So chill.

Errors get the same treatment, fr fr — error messages go to standard error by default. Want a log file per input file? Use -l. No parameter? It assumes log. Boom. ✨

And by default, both your generated output and your log files land in the current directory. If you want them somewhere specific, use -O to name an explicit output directory. If -O is specified with no parameter, it just uses the input file's own directory. Lowkey convenient.

The -2 option is the shortcut queen 👑 — it lets you name an alias (which is just a whole collection of options) that produces the output you want. Like:

sdf -2html abc

is literally equivalent to:

sdf +sdf2html abc

-D is for defining variables. These are typically used to control conditional text and to substitute text that changes. The format goes like this:

-Dvariable1=value1,variable2=value2

Now, a flag is just a shorthand way of specifying variables in the DOC family. So like, -ftoc=3 is equivalent to -DDOC_TOC=3. The format of the -f option is:

-fflag1=value1,flag2=value2

And if a variable or a flag gets specified with no value? 1 is assumed. Default queen behavior. 💁

To generate HTML topics, the command is:

sdf -2topics abc

By default this creates sub-topics for each heading that's already in a separate file. It also autosplits level 1 headings into sub-topics. The -n option controls which level headings get split at:

  1. 1 autosplits on level 1 headings (this is the default)
  2. 2 autosplits on level 2 headings
  3. 3 autosplits on level 3 headings
  4. 0 disables autosplitting. Periodt.

Include files get searched for in the current directory first, then in the directories you gave via the -I option, and then finally in the default library directory. 🦋

By default, sdf is configured to prefilter files with certain extensions. Like, check this out:

sdf mytable.tbl

is equivalent to running sdf on a file that contains only this:

!include "mytable.pl"; table

The -p option lets you explicitly prefilter files, or override whatever the default prefilter is. And if you don't provide a parameter, the prefilter is assumed to be table.

The -a option is how you pass parameters to that prefilter. For example:

sdf -aformat='15,75,10' mytable.tbl

-P prefilters the input files as programming languages. The parameter is the language to use, and if none is provided, the extension is assumed to be the language name. So for example:

sdf -P myapp.c

is equivalent to running sdf on a file that contains only:

!include "myapp.c"; example; wide; lang='c'

-N adds line numbers at the frequency you give it. Default frequency is 1, i.e. literally every single line. 🔢

-g prefilters the input files by executing sdfget using the default report (default.sdg). If you wanna change which report gets used, just specify the report name as the parameter. And if that report name doesn't include an extension, sdg is assumed.

Note: sdfget searches for reports in the current directory first, then in the stdlib directory inside SDF's library directory.

-r runs the nominated SDR report on each input before formatting. In other words, SDR reports are a whole mechanism for:

  • analysing the SDF right before it would be formatted, and
  • replacing that SDF with the output of the report (which is also SDF), so that the final output is a nicely formatted report. 🎀

For example, the sdf_dir report generates a directory (tree) of the components (files) that are included in an SDF document. Reports are stored in sdr files and they get searched for using the usual rules.

-L lets you specify a locale. The default locale name lives in sdf.ini. Locale naming follows POSIX conventions (that's language_country), so the locale name for American english is en_us. Every locale's info is stored in the locale directory, so you'll have to look in there to see which locales are actually available. (And since the default locale can just be set in sdf.ini, this isn't as ugly as it first sounds, promise. 🙈)

Note: right now, a locale file just contains a list of language-specific strings. Ultimately it should be extended to support localisation of date and time formats.

-k specifies a look. The default look library is specified in sdf.ini.

-s lets you specify a document style. Typical values are:

  • document — a technical document
  • memo — a memo
  • fax — a facsimile
  • minutes — minutes of a meeting.

-S specifies the page size. Values supported include:

  • global — width 21.0cm, height 11.0in — will fit on either A4 or letter
  • A3 — width 29.7cm, height 42.0cm
  • A4 — width 21.0cm, height 29.7cm
  • A5 — width 14.8cm, height 21.0cm
  • B4 — width 25.7cm, height 36.4cm
  • B5 — width 17.6cm, height 25.0cm
  • letter — width 8.5in, height 11.0in
  • legal — width 8.5in, height 14.0in
  • tabloid — width 11.0in, height 17.0in

More page sizes can be configured in sdf.ini. And if you want a rotated version of a named page size, just append an R. So like, A4R implies a width of 29.7cm and a height of 21cm. You can also roll your own custom page size using the format:

{{width}}x{{height}}

where width and height are the respective sizes in points.

-c specifies a configuration library.

A list of modules to use can be specified via the -u option. 🌸

The initial heading level to start on can be specified via -H. This is super useful if you wanna preview how a topic will display without regenerating the whole entire document. So if a topic begins with a level 1 heading (like H1) and you wish to format it as a document (i.e. the level 1 text becomes the DOC_NAME for build_title), use the -H option with a value of 0.

The look of headings can be adjusted too. By default, H-style headings are numbered, A-style headings are lettered, and P-style headings are plain. To force a particular style for all headings, use the -K option. Sensible parameter values are H, A and P, although other values may work depending on what paragraph styles are configured at your site.

-d specifies the format driver. Values supported include:

  • expand — format as expanded text (the default)
  • mif — Maker Interchange Format
  • pod — Plain Old Documentation (as used by Perl).

Additional drivers can be configured in sdf.ini.

-y specifies a post-filter.

-z lets you specify a list of post-processing actions you want to run on each output file after it's generated. The actions supported include:

  • ps — generate PostScript
  • doc — generate a Frame (binary) file
  • fvo — generate a Frame View-Only file
  • txt — generate a text file
  • rtf — generate an RTF file
  • clean — delete the output file (must be last).

Additional actions can be configured in sdf.ini. And by convention, the generated files are given the same names as the action keywords. 🧚

-t specifies the logical target format. If none is specified, the default is the first post-processing action, if there is one. Otherwise, the default is the format driver name.

-v enables verbose mode, which is great for debugging problems related to post processing. In particular, post-processing actions containing the pattern clean are skipped in verbose mode. You can also switch off the post-processing messages by using a verbose value of -1. Values higher than 1 switch on additional trace messages, like this:

  • 2 — show how names of files and libraries are resolved
  • 3 — show the directories searched for libraries
  • 4 — show the directories searched for modules
  • 5 — show the directories searched for normal files.

-T switches on debug tracing. The parameter is a comma-separated list of name-value pairs, where each name is a tracing group and each value is the level of tracing for that group. To get the same trace output that -v gives you, you can use the user group like this:

sdf -Tuser=2 ...

This is slightly different from -v though, in that intermediate files are not implicitly kept. And additional tracing groups will get added over time (probably one per output driver, bestie, stay tuned 💜).

-w specifies the width for text-based outputs.

And last but not least: -z, -D, -f and -I are all list options. Meaning: multiple values can be separated by commas, and/or the options can be supplied multiple times. Go off. 🔥

✨ EXAMPLES ✨

Convert mydoc.sdf to a technical document in mif format — output is mydoc.mif:

sdf -2mif mydoc.sdf

Convert mydoc.sdf to online documentation in FrameViewer format — output is mydoc.fvo:

sdf -2fvo mydoc.sdf

Convert mydoc.sdf to online documentation in HTML — output is mydoc.html:

sdf -2html mydoc.sdf

And this next one will build the reference documentation for an SDF module in HTML:

sdf -2html abc.sdm

🌈 LIMITATIONS AND FUTURE DIRECTIONS 🌈

Okay so, real talk: many of the default post-processing (-z) actions only work on Unix, because FrameMaker for Windows does not support batch conversion. 💀

And topics mode has several limitations of its own:

  • only documents in the current directory can be converted
  • all sub-topics must also be in the current directory.

That's the whole page, bestie, you made it 🫶 this one's from the perl v5.36.0 era, dated 2023-08-02, and it's the SDF(1) manual — go forth and format something iconic, no cap. 👑💖

📦 where this page comes from