4.3. SDG Format

Purpose

SDG files are used to format information extracted from source code by sdfget.

Description

An SDG is a table of Key-Format pairs. For example:

     Key     Format
     -       "Key\t\tDescription\n"
     *       sprintf("%-15.15s\t%s\n", $key, $data)

The first line specifies the layout of the table and is required. An item is only printed if it has a description. The Key field can be one of the following:

an item name
a minus (-) character, indicating free text
an asterix (*) character, indicating all remaining items

The Format field is a Perl expression. $key and $data are used to indicate the key and description of the current item respectively. Other available symbols are:

$dir - directory component of current file
$base - base component of current file
$ext - extension component of current file
$short - base & extension components of current file

Examples

The SDG file used to format topics within the SDF documentation is:

Key             Format
-               "!use 'sdgmacs'\n!SDG_BEGIN\n"
Title           "H1[id=\"$short\"] $short - $data\n\n"
Purpose         "H2: $key\n\n$data\n\n"
Interface       "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_PRE\n"
Description     "H2: $key\n\n$data\n\n"
-               "!SDG_DESCRIPTION_POST\n"
Notes           "H2: $key\n\n$data\n\n"
Examples        "H2: $key\n\n$data\n\n"
Limitations     "H2: Limitations and future directions\n\n$data\n\n"
See_also        "H2: See also\n\n$data\n\n"
Authors         "H2: $key\n\n$data\n\n"
-               "!SDG_END\n"