UNLIMITED CIRCULATION
SDF 2.001
SDF
Release Notes
(Final)
Document No: MTR-SDF-0008.001
Ian Clatworthy
25 May 1999, 14:46.55 SDF 2.001 SDF Release Notes
Table of Contents 1 2.001 ...... 3 2 2.001beta1 ...... 10 3 2.000 ...... 14 4 2.000beta12 ...... 18 5 2.000beta11 ...... 22 6 2.000beta10 ...... 26 7 2.000beta9a ...... 35 8 2.000beta9 ...... 37 9 2.000beta8a ...... 40 10 2.000beta8 ...... 44 11 2.000beta7c ...... 65 12 2.000beta7b ...... 67 13 2.000beta7a ...... 70 14 2.000beta7 ...... 71 15 2.000beta6c ...... 77 16 2.000beta6b ...... 78 17 2.000beta6a ...... 79 18 2.000beta6 ...... 81 19 2.000beta5 ...... 84 20 2.000beta4c ...... 87 21 2.000beta4b ...... 89
25 May 1999, 11:54.31 Page 2 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
1. 2.001
1.1 Enhancements The enhancements are: Level 0 headings New command line options Table enhancements HTMLDOC support Improved LaTeX support HTML formatting enhancements HTML meta information and stylesheet support Stylesheet-friendly HTML generation Embedded documentation enhancements Miscellaneous stuff
1.1.1 Level 0 headings H0, A0 and P0 are now supported as paragraph styles. Level 0 headings are implicitly converted to: !define DOC_NAME "text of heading" !build_title
This feature makes it easier to structure large documents as topics each of which begins with H1. To format a particular topic as a document, sdf's -H option can be used to set the initial heading level to zero like this: sdf -2html -H0 mytopic.sdf
1.1.2 New command line options The sdf program has some new command line options: -O, -g and -K.
The -O option specifies an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used. For example, to convert mydir1/ mydir2/myfile to HTML and put the output in the same directory as the original file, the command is: sdf -2html -O mydir1/mydir2/myfile
25 May 1999, 11:54.31 Page 3 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Note: The -O option doesn't always work. In particular, HTML topics generation doesn't support it yet.
The -g option prefilters the input files by executing sdfget using the default report (default.sdg). To change the report used, specify the report name as the parameter. If the report name doesn't include an extension, sdg is assumed.
The -K option sets the look of headings. Sensible parameter values are H, A and P. For example, to get the embedded documentation out of a script, make the headings plain, generate a document (rather than a topic) and convert it to HTML, the command line is: sdf -g -KP -H0 -2html myscript
1.1.3 Table enhancements The predefined table style names (columns, rows, grid, plain and shade) now have edit- case aliases (i.e. Columns, Rows, Grid, Plain and Shade). If the edit-case versions are used, quotes are not needed, e.g. !block table; style=Plain !endblock
The keepindents parameter has been introduced for the table filter. If set, leading whitespace in cells is kept, e.g. !block table; keepindents Directory Description sdf top level directory bin scripts bat batch file wrappers around scripts perllib sdf sdf libraries Pod pod libraries !endblock
The output is:
Directory Description sdf top level directory bin scripts bat batch file wrappers around scripts perllib sdf sdf libraries Pod pod libraries
25 May 1999, 11:54.31 Page 4 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
1.1.4 HTMLDOC support To convert a document to HTML ready for Michael Sweet's HTMLDOC program, the command is: sdf -2html -DHTMLDOC ...
Alternatively, sdf can call HTMLDOC itself in order to generate PostScript or PDF. The commands to do this are: sdf -2ps_html ... sdf -2pdf_html ...
Note: To maintain backwards compatibility, FrameMaker is still the default back-end for generating PostScript and PDF. If you wish to make HTMLDOC the default back- end, edit the FormatMappings sections of the sdf.ini file and change ps to mean ps_html and pdf to mean pdf_html. Once this is done, the following commands will use HTMLDOC rather than FrameMaker: sdf -2ps ... sdf -2pdf ...
When sdf invokes HTMLDOC, it sets the appropriate HTMLDOC options by using the following SDF variables: DOC_TITLE (build from DOC_NAME and DOC_TYPE), DOC_TOC, DOC_TWO_SIDES, OPT_PAGE_SIZE, OPT_MARGIN_INNER, OPT_MARGIN_OUTER, OPT_MARGIN_TOP and OPT_MARGIN_BOTTOM. In addition, a new variable called HTMLDOC_OPTS can be used to pass additional options through to the HTMLDOC command line, e.g. sdf -2pdf_html "-DHTMLDOC_OPTS:--gray --jpeg" ...
To do: add support for AUTHOR, COPYRIGHT and DOCNUMBER.
At the moment, SDF headers and footers are not converted to their HTMLDOC equivalents. To access HTMLDOC's header/footer support, it's currently necessary to use the HTMLDOC_OPTS variable.
1.1.5 Improved LaTeX support Valerio Aimale's (mailto:[email protected]) LaTeX driver is now part of the standard distribution. Refer to the file doc/notes/latex.notes for usage details.
1.1.6 HTML formatting enhancements The following phrase attributes are now supported when generating HTML: color, family, size, bold, italic, underline, bgcolor and changed. A changed phrase or paragraph is shown with the background color given by the HTML_CHANGED_COLOR variable. The default value is teal.
25 May 1999, 11:54.31 Page 5 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The following paragraph attributes are now supported when generating HTML: align, first, left, right.
See the SDF files within the examples/2001/stylesheets directory for examples of using these attributes.
1.1.7 HTML meta information and stylesheet support The meta filter can now be used to add META tags to the HEAD of a HTML document. This filter expects a table with columns called Name and Content, e.g. !block meta Name|Content description|Tools for building Java systems keywords|Java,development tools !endblock
Stylesheets can be linked or embedded using the links and stylesheet filters respectively. Here's a linked stylesheet: !block links Jump test.css !endblock
Here's how to embed the same stylesheet: !include "test.css"; stylesheet
Phrases and paragraphs now support the following attributes: • class - give this phrase or paragraph the nominated HTML CLASS attribute • style - format this phrase or paragraph using the nominated style information.
Here's an example of applying a custom style: [style='background-color: blue;; color: red'] A styled paragraph.
Note: SDF uses a single semi-colon to separate attributes, so attributes values with embedded semi-colons need to use ';;' to mean ';'. (The general rule is to use N+1 consecutive semi-colons to get N semi-colons).
1.1.8 Stylesheet-friendly HTML generation Generated HTML documents are now "stylesheet-friendly" in that: • DIVs are placed around interesting parts of the document • parts of the title are implicitly given classes • tables are implicitly given classes.
25 May 1999, 11:54.31 Page 6 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Here are the document sections placed in DIVs:
Document part DIV name title section title table of contents contents main body main header section header footer section footer navigate section navigate
The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.)
Here's the list of classes placed on parts of the title:
Class Comments doc-title title of document doc-id id of document doc-author author list doc-status document status doc-modified modification date
Tables are implicitly given a class named after the SDF table style. Heading and footing rows within tables are given classes of heading and footing respectively. Here's a set of Cascading Style Sheet (CSS) rules for a colorful table: TABLE.columns {background-color: yellow} TABLE.columns TR.heading {background-color: aqua} TABLE.columns STRONG {font-size: 20pt} TABLE.columns TD {color: purple}
See the SDF files within the examples/2001/stylesheets directory for more examples of using these features.
1.1.9 Embedded documentation enhancements A new filter called get has been added.
Support for embedded documentation in IDL has been improved (the IDL now gets pretty-printed in the "Interface" section).
The getdoc and getcode macros now guess the get-rule using the formatting extension.
25 May 1999, 11:54.31 Page 7 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The sdfget program has been enhanced in several ways: • if specified without a parameter, the get-rule is now guessed from the file extension (see the sdfget documentation for details on how this is done) • the new -v option enables verbose mode (which shows the get-rule guessed) • a new option (-f) can be used to specify the the filename to use for formatting (which is useful when the text is coming from standard input) • a new get-rule called bat is supported for DOS batch files • if a report filename doesn't have an extension, sdg is assumed.
The default.sdg report has been enhanced to support new sections called Notes, See_also and Authors.
A new SDG report called all.sdg has been added. This report formats all embedded documentation sections (unlike default.sdg which only extracts selected sections).
The default.sdg and all.sdg reports have been enhanced to support the SDG_BEGIN and SDG_END macros. These macros are empty by default so authors can override these to customise the display of extracted documentation.
1.1.10 Miscellaneous stuff A new module called homepage has been added to make it easier to build SDF-like home pages. For an example of usage, see the source for SDF's home page (doc/ home.sdf).
A Russian locale (ru_ru) has been added thanks to Alexey L. Popov ([email protected]).
New macros called div and enddiv can be used to put divisions in documents.
If sdf's -p option is specified without a parameter, table prefiltering is assumed. 1.2 Fixes Indented tables now work as expected, i.e. leading whitespace at the beginning of the heading row is now accepted and remaining rows have that amount of whitespace trimmed.
When generating txt output, leading cell whitespace now works as expected. Previously, multiple spaces were converted to a single space.
Attribute values containing ;; no longer have the whitespace around the character sequence trimmed.
25 May 1999, 11:54.31 Page 8 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Internally, unhandled internal directives no longer produce a warning. (As a result, it's now easier to extend things without "breaking" existing drivers.)
When generating HTML, the HTML_PRE_SECTION is no longer prepended unless a table of contents is generated. 1.3 Incompatibilities When HTML is generated, the default footer no longer contains a line. To get the old behaviour, set the HTML_OLD_FOOTERS variable, e.g. sdf -2html -DHTML_OLD_FOOTERS ...
The HTML driver no longer uses special embedded comments to work out where to put the table of contents.
The getcli macro no longer searches the include path: it just executes the command.
25 May 1999, 11:54.31 Page 9 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
2. 2.001beta1
2.1 Enhancements The enhancements are: Better documentation build_title enhancements Library search path Improved searching rules Pretty printing enhancements Localisation improvements New verbose levels and debug tracing Miscellaneous stuff
2.1.1 Better documentation The SDF Quick Reference has been greatly improved. It now documents 95% of SDF's features rather than the 10% of features most frequently used.
2.1.2 build_title enhancements If DOC_CODE is set and DOC_NAME is not set, build_title will now lookup DOC_NAME via references data if it can.
The separator between DOC_CODE and DOC_VERSION in DOC_ID can now be controlled by setting DOC_ID_SEP. The default value is '.'.
2.1.3 Library search path
Previously, libraries had to be placed in the perllib/sdf/home directory. Now, sdf's new -Y option can be used to specify a comma-separated list of directories to search for libraries. For example, if you want sdf to search c:\mysdflib and c:\ for libraries on a MS-DOS/Windows system, the command is: sdf -Yc:\mysdflib,c:\ ...
If your search path for libraries is always the same, the SDFOPTS environment variable can be used, e.g. the following sequence of commands will have the same effect as above: set SDFOPTS=-Yc:\mysdflib,c:\ sdf ...
25 May 1999, 11:54.31 Page 10 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
2.1.4 Improved searching rules Previously, libraries had to be placed in a fixed location but modules used the same search rules as normal files. Now that sdf supports a library search path, libraries, modules and normal files have different search rules. The new rules are:
File type Directories searched libraries current directory, document's directory, directories on the library path, perllib/sdf/home modules current directory, document's directory, directories on the module path, perllib/sdf/home, perllib/sdf/home/stdlib normal files current directory, document's directory, directories on the include path, perllib/sdf/home
The library path and the module path are initialised by sdf's -Y option. The include path is initialised by sdf's -I option. Inheriting a library (via a configuration library or the inherit macro) appends the library's directory to the module path and the include path.
2.1.5 Pretty printing enhancements Language names are now case insensitive. The keywords for Perl, Java and IDL have also been improved. Python support has been added.
2.1.6 Localisation improvements Strings within dates and times can now be localised using the datestrings filter. See en_au.sdl for an example.
A Czech locale (cz_cz) is now provided (although it doesn't have localised date strings yet).
2.1.7 New verbose levels and debug tracing sdf's -v option now supports additional verbose levels: 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.
As before, level 1 shows the post-processing actions and leaves intermediate files around.
25 May 1999, 11:54.31 Page 11 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
In addition, sdf's new -T option can be used to switch 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 trace output provided by the -v option, one can use the user group like this: sdf -Tuser=2 ...
This is slightly different from the -v option in that intermediate files are not implicitly kept. Additional tracing groups will be added over time (probably one per output driver).
2.1.8 Miscellaneous stuff Class filters now support a variables parameter which implicitly defines a variable for each object. The variable name is the same as the object name with non-alphanumeric characters replaced with '_'. (This feature should simplify configuration libraries for projects.)
The jumps macro has been introduced as a more convenient form of the subsections macro. (This feature should simplify web pages for projects.)
KP and KN have been added as paragraph styles. These are shorthands for N[keep_prev] and N[keep_next] respectively.
SUB and SUP have been introduced as phrase styles for subscripts and superscripts respectively. (Consider these experimental features for now, as I haven't had a chance to test them.) 2.2 Fixes The SDF Templates link on the home page included in the distribution now points to the SDF web site as it should.
Mac filename handling should finally be ok now. (However, installation instructions for the Mac are yet to be added.)
Minor corrections have been made to the SDF User Guide.
The conversion of PRN files to GIF files has been improved: a margin is no longer added as ps2gif is prone to incorrectly make it black.
Books generated with the fancy look now have a correctly formatted table of contents.
Java pretty printing has been fixed.
25 May 1999, 11:54.31 Page 12 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
2.3 Incompatibilities The Improved search rules may introduce some unexpected incompatibilities, particularly if custom file searching was implemented. Previously, advanced users could customise the search rules (to integrate a configuration management system, say) by overriding the FindFile subroutine. The default FindFile subroutine no longer searches perllib/sdf/home/stdlib, but otherwise, the search rule for normal files has not changed so custom FindFile routines should still hopefully work. The new routine called FileModule will need to be overriden if your custom FindFile is also needed for finding modules (or similar things like sdg, sdr and sdp files).
25 May 1999, 11:54.31 Page 13 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
3. 2.000
3.1 Enhancements As this is the first public production release of SDF, the focus has been to fix bugs and improve the documentation. The enhancements are: 1. Better documentation 2. Better packaging 3. Better support for non-English languages 4. Table enhancements 5. Object management enhancements 6. Example/verbatim enhancements 7. Miscellaneous things.
3.1.1 Better documentation The following documents have been improved: • The SDF Document Development System • SDF Reference.
The SDF Web Site has also been improved by the addition of the following sections: • SDF Latest News • SDF Template Catalog • SDF Resource Center • SDF Sample Showcase.
3.1.2 Better packaging The PostScript and PDF versions of the documentation have been removed from the core distribution making it substantially smaller. The PostScript and PDF documents can still be accessed as needed from http://www.mincom.com/mtr/sdf/catalog.html.
The SDF distribution is now CPAN-compliant, thanks to the efforts of Achim Bonnet ([email protected]). As a result, several things have changed: • installation is much easier • the SDFHOME environment variable is no longer used to find files: – Perl libraries are now assumed to be available on Perl's library path
25 May 1999, 11:54.31 Page 14 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
– configuration files, including sdf.ini, are now located within the sdf/home directory somewhere on Perl's library path. • the test directory has been renamed to t • the sdftest script is now located within the t directory.
3.1.3 Better support for non-English languages Russian characters (and characters from other non-English languages) are now hopefully better handled for users running on Perl 5.004 or later. (Thanks to Nikolaj Logvinov for this fix.)
A German locale (de_de.sdl) has also been added. (Thanks to Andreas Lohrum for this.)
3.1.4 Table enhancements The table filter now supports some new parameters: • colvaligns - a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns. For the lazy people, a single word containing the letters T, M, B and L can be used for the value as well. • select - a comma-separated list of columns to display. • delete - a comma-separated list of columns to delete.
The delete parameter is particularly useful if you want to sort or filter a table (using the sort and where parameters, respectively) using a column which you don't want in the output.
3.1.5 Object management enhancements Class filters also support the colaligns, colvaligns, select and delete parameters provided by the table filter.
A new feature called object views has been introduced. See Understanding Class Interfaces within the SDF Reference for details.
The catalog macro can now apply the filtering mask to an attribute other than the name. To specify the attribute, use a mask of the format: attribute":"mask_pattern
3.1.6 Example/verbatim enhancements The verbatim and example filters now support a listitem attribute (ala the table filter), although this attribute currently only indents the text for these filters.
25 May 1999, 11:54.31 Page 15 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The skipheader attribute of the example and verbatim filters now uses the lang attribute, if any, to determine the commenting conventions. Previously, it assumed comments began with # and were terminated by the end of line.
3.1.7 Miscellaneous things A module with support for Use Cases has been added (stdlib/usecases.sdm).
The insert macro can now be used to insert/execute a macro which may not be defined. 3.2 Fixes sdftest on Windows/DOS systems now works.
For plain text output, unwanted lines between consecutive example paragraphs have been removed.
File handling on the Macintosh should now be fixed. (Thanks to David Schooley.)
Within sdfget reports, * processing now works again.
When generating an rtf file via FrameMaker, the intermediate mif file is now deleted.
Inner and Outer no longer produce warnings as unknown values for the align parameter for the table or box filter.
Consecutive normal paragraphs within a box filter or a multi-paragraph table cell no longer run together when HTML is generated.
The about filter works correctly again for HTML output.
The FILE phrase style is now mapped to TT for HTML output.
The OPT_PAGE_SIZE and OPT_WIDTH variables are no longer ignored if they are set via the init macro.
Generating PostScript and DVI via SGML-Tools 1.02 or later should now work.
Column alignments within tables are no longer ignored when SGML is generated.
None is now a legal value for cell rulings within tables. (Thanks to Cliff Krumvieda for this fix.) 3.3 Incompatibilities Configuration files are now located differently. See Better packaging, above, for details.
25 May 1999, 11:54.31 Page 16 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The scripts in the bin directory now use /usr/local/bin/perl, rather than /usr/ local/bin/perl5, i.e. the default version of Perl installed at a site is now assumed to be 5.003 or later.
The PDF and PostScript versions of the documentation are no longer shipped with the SDF package. Instead, the document catalog points to PDF and PostScript files on SDF's web site. (This change was made to reduce the size of the SDF distribution.)
If you are generating outputs via SGML-Tools, you now need SGML-Tools 1.02 or later (rather than 0.99 or later).
The paper document style now leaves headings as they are defined. Previously, it implicitly changed H-style headings to P-style headings and slid them down one level.
The sdtgen script has been renamed sdngen to reflect the fact that sdn is the extension now used for tuning modules.
25 May 1999, 11:54.31 Page 17 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
4. 2.000beta12
4.1 Enhancements
Note: The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.
The major enhancements are: Output format naming rationalisation Automatic figure format conversion Better HTML customisation and documentation New output formats Locales Template processing Paragraph text is now the default output Post filtering
The minor enhancements are: • when include files and figures are searched for, the directory containing the document is now searched after the current directory • a Perl document catalog is now included (perl/catalog.sdf) • generation of non-MIF outputs is now slightly faster.
Further details on the major enhancements are provided below.
4.1.1 Output format naming rationalisation As SDF occasionally provides several ways to generate an output: • a convention has been introduced for output format names (i.e. the parameter to the -2 option) • a mapping table has been added to sdf.ini so that sites can customise the mapping from logical format names to actual format names.
As a result, it is now easy to change sdf.ini so that PostScript generation (i.e. -2ps) is via POD format rather than via FrameMaker, say. Furthermore, regardless of the default setup for PostScript generation: • PostScript via FrameMaker can be explicitly requested via -2ps_fm, and
25 May 1999, 11:54.31 Page 18 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
• PostScript via POD can be explicitly requested via -2ps_pod.
Generally speaking, a name of xxx_yyy means format xxx via yyy. Likewise, a name of xxx_ means format xxx directly.
4.1.2 Automatic figure format conversion As requested (many years ago, in fact), SDF will now automatically convert figure formats for you if it needs to. In particular, if you have a prn file on the search path, sdf will convert it to gif for HTML and eps for PostScript. Likewise, if you have an eps for PostScript, sdf will convert this to gif when you generate HTML.
Creating a prn file as a easy as printing to a PostScript file from most Windows apps including MS-Office and Rational Rose. As a result, figure management should no longer be the hassle its been in the past.
The conversion rules are stored in bin/sdf.ini. Feel free to have a look and/or forward me any additions/enhancements to the rules. One of the rules uses a new program supplied in SDF called prn2ps. This new command makes the output from a Windows 95/NT "print PostScript to a file" command acceptable to Ghostscript's ps2epsi.
4.1.3 Better HTML customisation and documentation A large number of HTML customisation features already existed, but were poorly documented. The new customisation features in this release are: • HTML_PRE_HEADER/HTML_POST_FOOTER support • HTML_TEXT_* support • HTML_SECTION_LEVEL/HTML_PRE_SECTION support.
See the new tutorial titled Generating HTML Using SDF for details.
4.1.4 New output formats SDF can now be converted to SGML like this: sdf -2sgml mydoc.sdf
By default, the linuxdoc DTD is used. Alternatively, the SGML_DTD variable can be used to change the DTD to qwertz, say, like this: !define SGML_DTD "qwertz"
If SGML-Tools 1.02 or later is installed, you can also generate the formats given below.
25 May 1999, 11:54.31 Page 19 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Command Output format Via sdf -2latex_sgml LaTeX SGML-Tools sdf -2dvi_sgml DVI SGML-Tools and LaTeX sdf -2ps_sgml PostScript SGML-Tools and LaTeX sdf -2rtf_sgml RTF SGML-Tools sdf -2info_sgml GNU info SGML-Tools sdf -2lyx_sgml LyX SGML-Tools
4.1.5 Locales SDF now has better support for non-English languages via locales. The -L option of the sdf command can be used to specify a locale. The default locale name is specified in sdf.ini. Locale naming follows POSIX conventions (i.e. language_country), so the locale name for American english is en_us. The information for each locale is stored in the locale directory, so you'll need to have to look in there to see what locales are available. (As the default locale can be set in sdf.ini, this isn't as ugly as it first sounds.)
At the moment, a locale file simply contains a list of language specific strings, although it should ultimately be extended to support localisation of date and time formats. Feel free to send me new locales so I can include them in future versions of SDF.
4.1.6 Template processing SDF can now also be used as a generic template processor, i.e. you can create C source, say, with ! macros and [[..]] expressions within it and use sdf to process it. For example, if you have a file called xx.sdt like this: !if DATE
The date is [[DATE:DOC_START]]. !else
The time is [[TIME:DOC_START]]. !endif
you can process it like this: sdf xx.sdt | less sdf -DDATE xx.sdt | less
If the file doesn't have a sdt extension, you need to specify template processing like this: sdf -ptemplate myskel.cpp | less
25 May 1999, 11:54.31 Page 20 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
4.1.7 Paragraph text is now the default output If you run the sdf program on a file without giving a target, the text of each paragraph is output. Therefore, you can now do things like:
sdf mydoc.sdf | spell -b
4.1.8 Post filtering It is now possible to post filter the output of a format driver before the results are written to disk. The -y option of the sdf command can now be used to specify a post filter name. A post filter called xxx maps to a routine called xxx_PostFilter in the file perllib/sdf/post_xxx.pl.
Note: This feature is only useful for SDF developers who want to create a new output format which is very simliar to an existing one.
4.2 Fixes Heading numbering in HTML and text outputs should be fixed now.
The file and line number in messages should generally be right now. Certain filters may still lead to incorrect line numbers being reported, but messages containing '$fullname', line number 0 or -1 should no longer appear.
Man page generation now works again. Previously, pod2man fell over unless a DOC_PROJECT and DOC_RELEASE was defined.
MIMS HTX and F6 Help formats should be working correctly now. The MIMS_CLIENT_CODE variable must now be specified on the command line when generating MIMS F6 help.
The APIs for SDF's Perl libraries are now present again in the SDF Guru Guide. 4.3 Incompatibilities The sdf2... wrapper scripts are no longer provided - use the -2 option of the sdf command instead.
Given the rationalisation of output format naming, some of the previously used names (e.g. fmrtf, sgmllatex) have been changed. If the sdf command complains about an unknown alias, have a look in sdf.ini to see what the new name is.
The interface to FindFile, a subroutine which some users override to integrate SDF into their CM system, has changed. See the FindFile documentation for details.
25 May 1999, 11:54.31 Page 21 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
5. 2.000beta11
5.1 Enhancements The enhancements are: Documentation improvements Better Perl documentation Multi-line records in tables Better man page support Better PDF support More flexible embedded documentation support SDF expressions within inline blocks.
Further details are provided below.
5.1.1 Documentation improvements The documentation has been improved in the following ways: • it is now supplied in PDF format (in addition to PostScript and HTML) • the white paper, quick reference and tutorials are now single HTML documents, rather than sets of topics • the home page has been improved • the FAQ has been expanded and added to the catalog.
5.1.2 Better Perl documentation The new mkpldocs program can be used to build the Perl documentation suite. Usage is: cd
The perl configuration library now generates better looking HTML with relative URLs. As such, the documentation can be easily moved after it is generated.
See http://www.mincom.com/mtr/perl/pod/perl.html for a publicly available version of the HTML generated by SDF for Perl 5.004_01. If you want a local copy, you can download it in either tar.gz or zip format. The URLs are: ftp://ftp.mincom.com/pub/mtr/sdf/perl/perlshtml-5.004_01.tar.gz ftp://ftp.mincom.com/pub/mtr/sdf/perl/psh50041.zip
25 May 1999, 11:54.31 Page 22 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
5.1.3 Multi-line records in tables Records in tables can now be continued onto the next line by terminating the line with a backslash. Like !-style macros: • exactly 2 terminating backslashes means a real backslash • N (N >= 3) terminating backslashes means N-1 real backslashes with continuation.
5.1.4 Better man page support The -2man option nows sends output to standard output, rather than to a .man file. This improves compatibility with pod2man and makes it easier to do things like: sdf -2man faq.sdf | nroff -man | less
The following variables can now be used to change the headers and footers generated for man pages:
Variable Meaning DOC_PRODUCT the center string in the header (e.g. Simple Document Format) DOC_PROJECT the release name for the product (e.g. SDF 2.000beta11) DOC_SECTION the section this man page is in
These variables are typically defined in a configuration library. You can also provide them on the command line using the -D and/or -f options like this: sdf -2man -DDOC_SECTION=3 ... sdf -2man -fsection=3 ...
5.1.5 Better PDF support PDF support has been improved. To generate PostScript (via FrameMaker) and distill it to PDF, the new -2pdf option can be used like this: sdf -2pdf mydoc.sdf
If PostScript is being generated via a FrameMaker book or via pod2ps, the -zpdf option can be used like this: sdf -2book -zpdf mydoc.sdf sdf -2podps -zpdf mydoc.pdf
Note: The -2pdf option assumes that you have Adobe Acrobat's distill program on your path.
25 May 1999, 11:54.31 Page 23 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
5.1.6 More flexible embedded documentation support Mark Stavar's enhancements to SDF's embedded documentation support have now been integrated, but are not yet documented. These enhancements make it possible to put documentation into buffers which are formatted independently of the main one. Amongst other things, this makes it possible to have subtopics for each procedure/ method/function in a library, each with its own set of Interface, Description, Examples, etc.
When time permits, I'll put together a tutorial explaining the different ways SDF can be used for embedded documentation. Until then, if you need further information on the multiple buffer approach, send me some email.
5.1.7 SDF expressions within inline blocks SDF expressions are now supported within text processed by the inline filter thanks to a patch from Tim MacKenzie. For example, !define VERB "is" ... !block inline; expand
This HTML [[VERB]] expanded. !endblock 5.2 Fixes Most of the links within the Perl documentation should now work correctly.
S phrases (i.e. phrases with non-breaking spaces) now work correctly for HTML and MIF formats. The nbsp variable has also been introduced as another way to insert non- breaking spaces.
HTML escapes (E phrases and CHAR phrases) are now supported by the mif and plain text drivers.
The default language used for pretty printing .h files is now C++, rather than C.
Non-last multi-line cells are now working correctly for delimited format (but aren't yet supported for fixed-width format).
Included some patches from Tim MacKenzie for: • handling filenames with non-alphanumeric characters like - • removing the need to have mif2rtf and sdfbatch on your path • improving compatibility with FrameMaker 4 • better packaging of Pod:Sdf.pm.
25 May 1999, 11:54.31 Page 24 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
To fix the formatting of MIMS specifications, the +ms option has been introduced.
When a FrameMaker book is generated: • the list of figures, list of tables and index, if any, should now appear in the table of contents • the last chapter now has a terminating line for infomap documents.
Missing libraries and modules now create a warning rather than an error.
The default footer for manuals has been changed to: • include the project name, if any • exclude the status if it's Final. 5.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 25 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
6. 2.000beta10
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 [email protected].
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: SDF is now POD-friendly Syntax Enhancements Verbatim paragraphs Special symbol escapes Enumerated lists New macros New phrase styles Manpage, LaTeX and fancy text support PostScript generation without a commercial tool
25 May 1999, 11:54.31 Page 26 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
POD to SDF conversion Nesting of POD within SDF Automatic translation of POD files Configuration library for Perl documentation. Topic previewing Easier text width control
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
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.
25 May 1999, 11:54.31 Page 27 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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.
25 May 1999, 11:54.31 Page 28 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Symbol Escape < E
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
25 May 1999, 11:54.31 Page 29 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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.
25 May 1999, 11:54.31 Page 30 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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
25 May 1999, 11:54.31 Page 31 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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
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.
25 May 1999, 11:54.31 Page 32 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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.
25 May 1999, 11:54.31 Page 33 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
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.
25 May 1999, 11:54.31 Page 34 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
7. 2.000beta9a
7.1 Enhancements A series of LOGO_BASE variables have been introduced so that the browser-time location of HTML images can be different to the compile-time location. For example, by defining: !define DOC_LOGO "mylogo" !define DOC_LOGO_BASE "/images/"
the URL of the logo image will be "/images/mylogo.gif".
New aliases have been introduced to make it easier to rebuild topics (+mt) and chapters (+mc) in the MIMS documentation. For example, to build the PostScript for the MIMS topic called 3201_msm200a.sdf, the command is: sdf -2ps +mt 3201_msm200a 7.2 Fixes Perl 5.004 introduced a warning about an odd number of elements in a hash list which previous versions of SDF occasionally triggered. The cause of the warning has now been fixed.
The label parameter on the note filter now works.
Some minor documentation corrections have been made. In particular, the URL for the Ultimate editor is now correct.
Lines now appear above and below notes in HTML. 7.3 Incompatibilities The box filter has been changed to do what people expect. The old behaviour is available by adding the lines parameter. 7.4 Future Incompatibilities! The next version of SDF is probably going to be (almost) upwardly compatible with Perl5's POD format. As a result, the = character will be a multi-line macro invocation, rather than being a shorthand for E:. If you are currently using =, please replace it with E: in preparation for the next release.
Making SDF upwardly compatible with POD will undoubtedly introduce a few other incompatibility problems. However, I'll do what I can to minimise these. The goal is to make it possible to use SDF for Perl5 module documentation when POD is not sufficient.
25 May 1999, 11:54.31 Page 35 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
If you have any feedback on the idea of making SDF upwardly compatible with POD, send some email to the SDF users mailing list ([email protected]).
This release will also be the last one supporting Perl 4.036. Future releases will require Perl 5.
25 May 1999, 11:54.31 Page 36 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
8. 2.000beta9
8.1 Enhancements
8.1.1 Overview The contrib directory now contains an SDF mode for Emacs and a rudimentary RTF to SDF converter. Like other things in the contrib directory, these are unsupported but may be useful.
The other enhancements are: Improved documentation Improved text tables New filters Citation support.
Further details are provided below.
8.1.2 Improved documentation The documentation has been improved in a number of ways: 1. The SDF User Guide has been revised and updated. 2. The SDF Guru Guide now has a chapter on extending SDF. 3. The manuals provided with SDF now have an index. 4. The SDF 2.000 Migration Guide is no longer provided in the standard distribution (as it is only useful for SDF 1.x users within Mincom).
8.1.3 Improved text tables Thanks to Tim MacKenzie ([email protected]): tables output in txt format have been improved: • all cells are now word wrapped (not just the last one in each row) • cell alignment is now supported • Line paragraph styles within cells are now supported • heading underlining has been improved.
8.1.4 New filters Thanks to Tim Hudson ([email protected]), a number of new filters are now available:
25 May 1999, 11:54.31 Page 37 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Name Description built-in: nofill format a set of lines simple generic filter for building other filters defines.sdm: product_defines define products and variables for each section_defines define section names as variables testcase.sdm: testcases collect testcases from A3s into a table at the end of document
8.1.5 Citation support References can now be easily numbered and the numbers can be inserted in paragraph text. The new features which make this possible are: • the references class now supports a Cite attribute which produces a string of the form [n] • the REF phrase style now supports a cite attribute which inserts the reference number using the syntax [n].
For example: H1: References !include "doc.reg"; references; columns='Cite,Document' H1: Some heading Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}.
If you want to put the reference table at the back of the document, it is necessary to forward declare which documents will be cited by using the cited parameter of the references filter. The table of cited references can then be built later by using the catalog macro. For example: !include "doc.reg"; references; cited H1: Some heading Refer to {{REF[cite]ABC}} and {{REF[cite]ME2}}. H1: References !catalog references 'cited'; columns='Cite,Document'
25 May 1999, 11:54.31 Page 38 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
8.2 Fixes FrameMaker 4.x compatibility has been improved thanks to a patch from Tim MacKenzie ([email protected]).
The document control section (on the inside of the front cover) of project documents has been improved. (In fact, it is now much easier to customise output of the build_title macro.)
The about filter was fixed to work better with documents formatted using the infomap look.
For Windows 3.x/MS-DOS users: • the sdftest.bat file has been fixed • the sdfget.bat file has been added.
Date formatting for years >= 2000 has been fixed. 8.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 39 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
9. 2.000beta8a
9.1 Enhancements
9.1.1 Overview The enhancements are: • List formatting changes • Multiple records per row in a table • Programming languages filters • Dynamic filter loading • Variable access in where attributes • Generalised file extensions for references columns • New images • Class value functions • Component directory files • The catalog macro • MIMS specific formats • Reporting.
Further details are provided below.
9.1.2 List formatting changes Following readability feedback: • the default list item indent has been reduced to 18 points • the size of bullets has been increased • dashes are now used for 2nd level list items (and 4th and 6th).
9.1.3 Multiple records per row in a table The table filter now supports the wrap attribute which puts multiple physical records into a single row. The wrap attribute is also supported by class filters.
This feature is useful for producing online HTML indexes.
25 May 1999, 11:54.31 Page 40 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
9.1.4 Programming languages filters If a filter matches the name of a programming language, the text is formatted as an example in that language, e.g. !block C int i; !endblock
is now implicitly: !block example; lang='C' int i; !endblock
9.1.5 Dynamic filter loading If a filter is not found, SDF now looks for a file called filter_name.sdp and dynamically loads the filter from that file if it can. See the stdlib/module.sdp file for an example.
9.1.6 Variable access in where attributes Variables can now be accessed in the where attribute of the table filter and class filters. For example: !define MODULE_CODE "XYZ" ... !include "../document.reg"; references; compact; \ where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \ columns="PS,REF:Reference,DOC:Document,CONCISE:Date"
9.1.7 Generalised file extensions for references columns If a reference attribute is all uppercase (e.g. TXT), a clickable image for a file with that (lowercase) extension (e.g. mydoc.txt) is generated, using an image matching the extension name (e.g. txt.gif). Likewise, an all uppercase attribute with a leading underscore (e.g. _DIR) generates an image for a HTML file with that suffix (e.g. mydoc_dir.html) using an image matching the extension name (e.g. dir.gif).
This feature has been added so that SDF doesn't need to be extended every time a new file type needs to be included in a document catalog.
9.1.8 New images The following images have been added to the images library:
File Comments dir.gif for _dir.html files (see below) htx.gif for MIMS .htx files mf6.gif for MIMS F6 help files
25 May 1999, 11:54.31 Page 41 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
9.1.9 Class value functions Calculation functions can now be defined for a class. (Previously, calculation functions were only supported for an attribute-class combination.)
This feature is used to support arbitary file extensions for the references class (see above).
9.1.10 Component directory files As large documents often contain lots of topics, SDF now provides an option for generating a HTML file which displays the topic directory tree for a document.
The command is: sdf -2_dir mydoc
This creates a file called mydoc_dir.html. A web browser can then be used to view the topic hierarchy and view the SDF files used to build a document.
Note: Once a browser has downloaded an SDF file, it is easy to load it into your preferred editor. However, if you wish to change the master copy of an SDF file, you will need to save your changes to the appropriate location (on the server, say).
9.1.11 The catalog macro The new catalog macro can be used to build a catalog of loaded objects. Filtering is provided on the name making it easy to produce online HTML indexes.
9.1.12 MIMS specific formats The following output formats are now supported: • mf6 - MIMS F6 help • htx - MIMS HTX files.
9.1.13 Reporting SDF now supports a generalised mechanism for producing a report on an SDF file. See the stdlib/sdf_dir.sdr report file for an example.
This feature is used to support the -2_dir option (see above). 9.2 Fixes The word wrapping algorithm used by txt format has been fixed so that really long words (e.g. URLs) that don't fit on any line no longer wrap onto the next line unless doing so is better that leaving the word on the current line.
25 May 1999, 11:54.31 Page 42 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Formatting of title blocks for txt format is better.
The label attribute now works for headings in txt format.
The objects attribute for the table filter has been added back in as an alias for the coltags attribute. 9.3 Incompatibilities The changes to list formatting mean that documents with lists will be formatted differently, e.g. a given document might have page breaks in different places.
The SDF logo images are now named sdflogo.gif and sdflogo.bmp, rather than sdf.gif and sdf.bmp.
25 May 1999, 11:54.31 Page 43 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
10. 2.000beta8
10.1 Enhancements There are lots of new things in this version. The general enhancements are: Easier enumerated values Look improvements Style rationalisation More build_title control variables Miscellaneous things.
The table enhancements are: Easier column widths Heading/footing rows for tables Table positioning Table filtering and sorting Landscape tables Column alignment Cell attributes Spreadsheet calculations.
The page formatting enhancements are: Arbitrary page sizes Headers and footers Header/footer special tags Header/footer borders Page backgrounds Page layout variables Page control within a book.
The configuration enhancements are: FrameMaker templates are no longer required
25 May 1999, 11:54.31 Page 44 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Event processing enhancements.
Details are given below.
Note: For html and txt targets, this release is slightly faster than the previous one. For mif (and ps), this release may be slightly slower (as SDF templates, not FrameMaker ones, are now used).
10.1.1 Easier enumerated values Enumerated values no longer need to be quoted. In a set of name-value pairs, if an expression is a single word where: • the first character is uppercase • the remaining characters are lowercase
then the word is assumed to be an enemerated value and it is automatically converted to a string. For example, the following two lines are now equivalent: P1[align="Center"] My Title P1[align=Center] My Title
10.1.2 Look improvements The overall appearance (i.e. look) of an SDF document can be controlled via the -k option or the OPT_LOOK variable. SDF now supports the following looks: • simple - the default look, useful for general documentation • fancy - QSD-like look, but without any logos • infomap - look based on Information Mapping™ • overhead - look suitable for overhead transparencies.
Note: For backwards compatibility, plain is now an alias for simple.
10.1.3 Style rationalisation SDF now supports the styles (i.e. document types) below.
Style Purpose General: document a normal document manual a manual paper a technical paper
25 May 1999, 11:54.31 Page 45 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Style Purpose Administration: admin generic administration document fax a fascimile memo a memorandum newslttr a newsletter minutes minutes of a meeting Miscellaneous: listing a source code listing
The build_title macro is used to build the cover page for the general styles. The title filter is used to build the title block for the administation styles. The miscellaneous styles do not have a title.
Adding new styles for a look is now much easier than it was previously. Furthermore, manual is now just another style rather than a special mode.
10.1.4 More build_title control variables build_title now supports the following variable: • DOC_COVER - the logical name of the cover page to use.
Supported DOC_COVER values and their meanings are given below:
Value Meaning original SDF's original cover page layout project a cover page useful for project documentation manual the cover page used when OPT_STYLE is manual paper the cover page used when OPT_STYLE is paper
The manual cover supports a new macro called DOC_OFFICES, i.e. if DOC_OFFICES is defined, its contents are appended after the inside cover page.
10.1.5 Miscellaneous things The SDF What's Planned document and bugs.html have been replaced by the SDF Bug Database. In fact, the organisation of the documentation has been improved quite a bit.
Any document can now be converted to a FrameMaker book, i.e. it is no longer necessary to specially organise files in order to create a FrameMaker book.
25 May 1999, 11:54.31 Page 46 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Tables of style columns (the default) now have a thin line above group rows.
Tables can now be specified as list items by using the listitem parameter of the table filter. The value is the logical indent of the list (e.g. 1, 2, etc.). When generating HTML which contains a table within a numbered list, the listitem parameter is necessary in order to prevent the numbering from resetting.
The new box filter can be used to place a box around one or more lines of text.
The new center filter can be used to center a region of text.
The new paragraph attribute called wide can be used to specify that a paragraph straddles the side-head area in addition to the main text area. Likewise. class filters (e.g. terms, references, etc.) now also support the wide attribute.
By default, SDF automatically generates an id attribute for all headings in the table of contents. However, it is occasionally necessary to disable this, particularly when the same heading appears multiple times in a file. The new paragraph attribute noid can be used to prevent an id being generated for a paragraph.
The title for an administration-style document can now be changed by either setting the DOC_TYPE variable or by using the new type parameter to the title filter. For example, if you want the title "Urgent Memo" rather than the default "MEMORANDUM" for a memo, you can now do the following: !init OPT_STYLE="memo" !block title; type="Urgent Memo" usual name-values pairs go here ... !endblock
The title filter now also supports a format parameter which can be used to tune the column widths, when necessary.
RTF can now be generated via FrameMaker by using the new sdf2fmrtf alias, i.e. the command is (say): sdf -2fmrtf myfile.sdf
When RTF is generated via FrameMaker, Word's standard style names are used, where possible. This makes it easier to import the RTF file into an existing Word document.
Lists of tables and lists of figures can now be generated for normal documents, i.e. it is no longer necessary to use a FrameMaker book to build these lists.
The new variable TXT_MARGIN can be used to control the width for txt output. Likewise, the new variable POD_MARGIN can be used to control the width of tables for pod format.
25 May 1999, 11:54.31 Page 47 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The new bugtrack module can be used to build a simple bug tracking system like SDF's bug database.
The new namevalues macro can be used to output a set of name-value pairs for an object. The parameters are: • the class name • the object name • a comma-separated list of attribute names.
For example: !namevalues 'bugs'; 'sd0001'; 'Priority,Status,Type'
Finer control over object catalog formatting is now available via the new style and headings attributes. style is the table style to use. The default value is plain. If headings is set, column headings are output. (By default, they are not.)
10.1.6 Easier column widths SDF now supports dynamic column widths for paper documentation, i.e. if a width is not specified for a column, then the column is sized based on the text within it and the space available. Proportional column widths are also supported.
The format attribute of the table filter is either: • a single number, in which case each digit represents 10% of the width available to the table, or • a comma-separated list of column width specifications.
Examples of the column width specifications now supported are given below.
Value Meaning 30pt an exact size (other supported units are cm, mm, " and in) 30% a percentage of the size available 30 a percentage of the size available (% is implicit) 10-20 dynamic size between 10% and 20% of the total width -20 dynamic size between 0% and 20% of the total width 10- dynamic size between 10% and 100% of the total width - dynamic size between 0% and 100% of the total width 3* 3 units of the remaining space * same as 1*
25 May 1999, 11:54.31 Page 48 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
For example, in the table below, the second column will be twice the size of the last column. !block table; format="20,2*,10,*" Name Column2 Column3 Column4 A B C D X Hello dear world Y Z !endblock
The output is:
Name Column2 Colu Column4 mn3 ABCD X Hello dear YZ world
If a column is not given a size, the following rules are used: 1. The last unspecified column size is implicitly '*' (i.e. the rest), unless the narrow attribute is set, in which case the size is implicitly '-' (i.e. as much as needed). 2. The other unknown sizes are implicitly '-'.
For example, the first and third columns in the table below will be dynamically sized. The first column will take as much space as required and the last column will expand so that the table takes the full width of the text area. !block table; format=",30,,10" Name Column2 Column3 Column4 A B C D X Hello dear world Y Z !endblock
The output is:
Name Column2 Column3 Colu mn4 AB C D X Hello dear world Y Z
However, in the example below, each column will only take as much space is required, making the table narrower than it would be otherwise.
25 May 1999, 11:54.31 Page 49 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
!block table; narrow Name Column2 Column3 Column4 A B C D X Hello dear world Y Z !endblock
The output is:
Name Column2 Column3 Column4 AB C D X Hello dear world Y Z
If an = character is used in place of a - character for a column width, then those columns will be equalised in size. For example, the second and forth columns in the table below will be made equal in size. !block table; format="20,5=30,10,=" Name Column2 Column3 Column4 A B C D X Hello dear world Y Z !endblock
The output is:
Name Column2 Colu Column4 mn3 AB CD X Hello dear world Y Z
Note: As previously, the format parameter has no impact on HTML generation, i.e. all columns in HTML remain dynamically sized. Dynamic sizing is also ignored for txt and pod targets.
10.1.7 Heading/footing rows for tables The table filter now supports the following attributes: • headings - the number of heading rows at the top of the table • footings - the number of footing rows at the end of the table.
If the headings attribute is not defined, then as previously done, the column headings are generated using the column names given on the parsing line. For example, the column headings in the table below will be Name and Age:
25 May 1999, 11:54.31 Page 50 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
!block table Name Age Bill 42 !endblock
Alternatively, if the headings attribute is defined, then that number of data rows are used as the column headings, i.e. the parsing line is not used to build the column headings. For example, the column headings in the table below will be "Title" and Age (remembering that a filter attribute is implicitly given the value 1 is no value is supplied). !block table; headings A B "Title" Age Bill 42 Sally 23 !endblock
Likewise, the column headings below will be Preferred Title and Likely Age with each heading taking 2 rows. !block table; headings=2 A B Preferred Likely Title Age Bill 42 Sally 23 !endblock
Collectively, these new attributes improve things in several ways: • heading rows can now include non-alphanumeric characters • macros (e.g. change bars) can be applied to heading rows • multi-line heading and footing rows are now supported.
10.1.8 Table positioning The horizontal alignment and vertical placement of a table can be controlled by setting the align and placement parameters of the table filter respectively. The permitted align values are:
Value Meaning Left left-align the table Center center the table Right right-align the table Inner align the table with the inner margin Outer align the table with the outer margin
25 May 1999, 11:54.31 Page 51 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Note: The wide parameter changes the left indent of a table to include the sidehead of a page. Therefore, the wide parameter will impact the horizontal positioning of any table which is not right-aligned.
The permitted placement values are:
Value Meaning Float next column if necessary Pagetop top of the next page Columntop top of the next column Lefttop top of the next left-hand page Righttop top of the next right-hand page
10.1.9 Table filtering and sorting Tables can now be filtered and sorted by using the new where and sort attributes of the table filter. These attributes are also supported by the class filters (e.g. terms, references). In either case, filtering is done before sorting.
The where attribute takes an expression which is evaluated for each record. Special symbols available are:
Symbol Meaning $_ the current record $o{"xyz"} the value of column xyz
sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.
10.1.10Landscape tables Landscape tables are now supported via the landscape parameter of the table filter. The value is the height allocated to the area in which the table is placed. If a unit is not specified, the value is assumed to be a percentage of the text column height. For convenience, a value of 1 implies a full page table. Some examples are given below.
25 May 1999, 11:54.31 Page 52 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Value Meaning landscape="50pt" height allocated to table is 50 points landscape="50%" half page table landscape=50 half page table (% is the default units) landscape=1 full page table (1 implies 100%) landscape full page table (syntactic shorthand for above)
Note: This feature is currently use at your own risk. In particular, long tables and table titles confuse it badly. Furthermore, the align and placement parameters are effectively ignored for landscape tables.
10.1.11Column alignment The colaligns parameter of the table filter can now be used to control the alignment of text within columns of a table. For example: !block table; colaligns="LCCR" Name Column2 Column3 Column4 A B C 1.0 X Hello dear world Y 10.2 !endblock
The output is:
Name Column2 Column3 Column4 A B C 1.0 X Hello dear world Y 10.2
The value of colaligns is usually a sequence of the letters L, C and R (which mean what one would expect). If you prefer, a comma-separated list of the values Left, Center and Right can be specified. For example: !block table; colaligns="Left,Center,Center,Right" Name Column2 Column3 Column4 A B C 1.0 X Hello dear world Y 10.2 !endblock
10.1.12Cell attributes Cells within a table can now be given attributes by preceding the cell value with a semicolon-separated list of name-value pairs enclosed in square brackets. For example:
25 May 1999, 11:54.31 Page 53 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
!block table; colaligns="LCCR" Name Column2 Column3 Column4 A [align=Left]B C [bgcolor=Green]1.0 X Hello dear world Y [bgcolor=Red]10.2 !endblock
The output is:
Name Column2 Column3 Column4 AB C 1.0 X Hello dear world Y 10.2
The cell attributes supported are given below.
Name Value General: align horizontal alignment (Left, Center, Right) valign vertical alignment (Top, Middle, Bottom, Baseline) cols the number of columns this cell spans (default is 1) rows the number of rows this cell spans (default is 1) bgcolor background colour of cell (see below) PS only: fill background colour fill percentage truling ruling setting for top of cell bruling ruling setting for bottom of cell lruling ruling setting for left of cell rruling ruling setting for right of cell angle angle of text (0, 90, 180, 270) HTML only: nowrap disable word wrap for this cell Special: sdf treat the cell text as SDF (rather than as phrase text) tag phrase tag to apply to cell text paratag paragraph style to apply to cell text
For PS (i.e. MIF) generation, the supported colour values are Black, White, Red, Green, Blue, Yellow, Cyan and Magenta. If a different colour is specified, it is ignored.
25 May 1999, 11:54.31 Page 54 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
The supported fill values are 100, 90, 70, 50, 30, 10 and 3. If a fill value is not specified, 100% fill is used.
For HTML generation, any of the HTML colours names (including those supported for PS generation) or the "#rrggbb" form can be used.
The permitted ruling values are Vthin, Thin, Medium, Thick and Double.
The sdf, tag and paratag attributes control the way in which the cell text is converted to SDF: 1. If sdf is set, the cell text is already SDF. 2. Otherwise if tag is set, the SDF paragraph is paratag:{{tag:text}}. 3. Otherwise, the paragraph is paratag:text.
tag is usually set via the tags or groups parameters of the table filter.
Note: paratag is not yet implemented.
10.1.13Spreadsheet calculations The spreadsheet expression evaluator and the documentation below was written by Tim Hudson ([email protected]).
Spreadsheet style calculations have been introduced into SDF using the standard [[ ]] syntax with a prefix of + (or =) indicating that the expression is to be evaluated by the calculation routines.
This extension has been loosely modelled on Microsoft Excel® in terms of the initial functions supported and the syntax used.
Note: Calculation support for a table can be disabled by adding in an attribute of nocalcs (otherwise the pointers required to table data that are needed when doing spreadsheet calculations occur for each table cell).
Each cell in a table has an cellid which is made up of a single uppercase letter indicating the column index and a number indicating the row index (counting from 1 and excluding the heading rows). The upper left cell is hence A1.
An example grid indicating cellids:
25 May 1999, 11:54.31 Page 55 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Title1 Title2 Title3 Title4 Title5 A1 B1 C1 D1 E1 A2 B2 C2 D2 E2 A3 B3 C3 D3 E3 ...... A100 B100 C100 D100 E100
A range of cellids is specified using the syntax cellid1:cellid2. For example: A1:C1 is exactly the same as A1,B1,C1
An expression consists of a combination of standard Perl operators and spreadsheet functions and cellids or cellid ranges.
Standard Perl operators include: • + - * /
Spreadsheet functions use the syntax FUNCTION(ARG1,ARG2,...ARGN).
The following functions are supported: • AVERAGE - the average - SUM(ARGS)/COUNT(ARGS) • SUM - the sum of the args - same as ARG1+ARG2+...+ARGN • MIN - the minumum argument value • MAX - the maximum argument value • COUNT - the number of arguments • PRODUCT - the product of the args - same as ARG1*ARGN*...*ARGN • ROWSUM - the SUM of all the cells in the row to the left of the current cell • ROWPROD - the PRODUCT of all the cells in the row to the left of the current cell • COLSUM - the SUM of all the cells in the column above the current cell • COLPROD - the PRODUCT of all the cells in the column above the current cell
A simple example: !block table; style="grid" Count Price Total 10 5 [\[=A1*B1]\] 15 5.23 [\[=ROWPROD]\] [\[=COLSUM]] [\[=B1+B2]\] [\[=COLSUM]\] !endblock
25 May 1999, 11:54.31 Page 56 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Which generates the result below. (Ok, summing two prices is meaningless, but it illustrates the syntax.)
Count Price Total 10 5 50.00 15 5.23 78.45 25.00 10.23 128.45
Note: values are available until the next table is processed so you can refer to data inside normal paragraphs after the table like this [\[=A1]\] which evaluates to 10.00
A spreadsheet expression will recursively evaluate any expressions contained in cells that are used in an expression. In the example above, the expression in cell C3 depends on the results of the expression in cell C1 and C2.
10.1.14Arbitrary page sizes Generally speaking, SDF can now support arbitrary page sizes. The catch is that the page size must now be specified up front via the OPT_PAGE_SIZE variable on the init line or via sdf's -S option. (Previously, the (no longer supported) DOC_PAGE_SIZE variable could be specified anywhere in the document.)
The supported values of OPT_PAGE_SIZE are given below. The default page size is global.
Name Width Height Comment global 21.0cm 11.0in will fit on either A4 or letter A3 29.7cm 42.0cm A4 21.0cm 29.7cm A5 14.8cm 21.0cm B4 25.7cm 36.4cm B5 17.6cm 25.0cm letter 8.5in 11.0in legal 8.5in 14.0in tabloid 11.0in 17.0in
Note: global is 0.23" narrower than letter and 1.76cm shorter than A4.
25 May 1999, 11:54.31 Page 57 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
New page sizes can be defined in sdf.ini. A rotated version is also available for each page size. Rotated sizes are named with an appended R. For example, the rotated A4 size is called A4R.
10.1.15Headers and footers SDF now provides 3 ways of controlling headers and footers: • The OPT_HEADINGS variable (high level control) • PAGE_page_HF_ICOn variables (medium level control) • PAGE_page_HF macros (low level control)
where: • page is FIRST, RIGHT or LEFT • HF is HEADER or FOOTER • ICO is INNER, CENTER or OUTER • n is the line number within the header or footer (usually 1 or 2).
The meaning of each page type is explained below.
Page Usage FIRST the first page in the document RIGHT the page used for single-sided documents and the right hand side of double-sided documents LEFT the left hand side of double-sided documents; ignored for single-sided documents
Supported OPT_HEADINGS values and their meanings are given below:
Value Meaning 0 no header, no footer 1 single line header, single line footer 2 two line header and two line footer 3 two line header and three line footer 4 two line header and four line footer
10.1.16Header/footer special tags The following special tags are supported within headers and footers:
25 May 1999, 11:54.31 Page 58 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Tag Meaning PAGENUM current page number PAGECOUNT highest page number PARATEXT paragraph text (e.g. Hardware requirements) PARANUM paragraph number (e.g. Appendix A) PARANUMONLY paragraph number only (e.g. A) PARASHORT value of short attribute of paragraph PARALAST text of last paragraph on page with the nominated style
The PARA* tags require a comma separated list of paragraph styles to be nominated as the text of the phrase, e.g. {{PARATEXT:H1,A1,P1}}.
The PARASHORT tag is useful for placing an alternative heading in a header, say. For example, you might set up your header to include {{PARASHORT:H1}} and have the following text in your document: H1[short='Getting started'] Getting started with SDF
The PARALAST tag is useful for producing dictionary-like headers.
10.1.17Header/footer borders High level control over header/footer borders is provided by the OPT_BORDERS variable. The supported values and their meanings are given below:
Value Meaning 0 no header/footer borders 1 line below header, line above footer 2 lines above and below header, line above footer
Finer control is available by setting the following variables:
Name Value PAGE_page_HEADER_BORDER border specification string PAGE_page_FOOTER_BORDER border specification string
where page is either FIRST, RIGHT or LEFT.
25 May 1999, 11:54.31 Page 59 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
A border specification string is a comma-separated list of attributes which collectively describe the border. The format of each attribute is name[=value]. The supported attributes are: • top - a line above the area • bottom - a line below the area • box - a box around the area • radius - for a box, the radius of the corner.
For top, bottom and box, the value of the attribute is the line width in points.
10.1.18Page backgrounds In order to support fancy background images, SDF supports the following variables:
Name Value PAGE_page_BACKGROUND the logical image name
where page is either FIRST, RIGHT or LEFT.
When FrameMaker is being used to generate PostScript, the image name is mapped to a master page called backgrnd within a file called backgrnd.mif.
Note: At the moment, objects from the master page (excluding TextRects) are directly transferred to the generated MIF file. This means that objects in the lower right hand corner of an A4 master page will not will be positioned nicely if the paper size is changed to A5, say.
10.1.19Page layout variables Page margins can now be controlled via the following variables:
Name Value OPT_MARGIN_TOP size of the margin above the header, if any OPT_MARGIN_BOTTOM size of the margin below the footer, if any OPT_MARGIN_INNER size of the inner margin OPT_MARGIN_OUTER size of the outer margin
The positioning of headers and footers can now be controlled via the following variables:
25 May 1999, 11:54.31 Page 60 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Name Value PAGE_page_HEADER_HEIGHT height of the area allocated to the header PAGE_page_HEADER_GAP size of the gap between the header area and the text area PAGE_page_FOOTER_HEIGHT height of the area allocated to the footer PAGE_page_FOOTER_GAP size of the gap between the text area and the footer area
where page is either FIRST, RIGHT or LEFT.
After the margins and header/footer are allocated, the remaining text area contains 1 or more text columns and an optional side head. The layout of these is controlled by the following variables:
Name Value OPT_COLUMNS numbers of text columns OPT_COLUMN_GAP space between columns OPT_SIDEHEAD_WIDTH size allocated to the sidehead OPT_SIDEHEAD_GAP space between the side-head and first text column
The following read-only variables provide information on the page layout:
Name Value DOC_PAGE_WIDTH width of page DOC_PAGE_HEIGHT height of page DOC_FULL_WIDTH width of text area including the side-head DOC_TEXT_WIDTH width of text area available for text columns DOC_TEXT_HEIGHT height of text area DOC_COLUMN_WIDTH width of a text column
All the information variables are in units of points. The text area is the area allocated to text, excluding the header and footer (if any) on the RIGHT page.
25 May 1999, 11:54.31 Page 61 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
10.1.20Page control within a book When a book is being generated, each component of the book may have its own FIRST, RIGHT and LEFT pages, i.e. all of the macros and variables above support an extended set of page values component_FRL where: • component is the name of the component • FRL is FIRST, RIGHT or LEFT.
The component names supported are given below.
Name Meaning FRONT the cover component PRETOC components before the contents TOC the table of contents LOF the list of figures LOT the list of tables PRECHAPTER components before the chapters CHAPTER a normal chapter APPENDIX an appendix PREIX components before the index IX the index
If a component does not have a component-specific macro/variable defined, then the generic macro/variable is used.
10.1.21FrameMaker templates are no longer required Previously, SDF produced MIF documents by merging generated MIF paragraphs into FrameMaker templates. This approach was easy to implement but maintaining the FrameMaker templates was difficult as every look required several templates for each page size!
FrameMaker templates can still be used but are no longer needed, nor recommended. Instead, the definitions of paragraph styles, phrase styles, table styles and graphic (border) frames is now done via SDF templates. SDF templates have the following advantages: 1. Templates can be parameterised so that a single template can support any number of page sizes.
25 May 1999, 11:54.31 Page 62 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
2. Each look only requires a single template, rather than a template for each component of a FrameMaker book. 3. Templates can inherit definitions from other templates, making it much easier to create and maintain templates. 4. Each definition supports inheritance, so a new paragraph style, say, can be defined in terms of the differences between it and a parent style.
The new sdtgen command can be used to build an SDF template from a FrameMaker one. Typically, sdtgen is used to create an initial template which is then simplified via definition inheritance and template inheritance.
10.1.22Event processing enhancements The following new symbols are now available within event processing for paragraphs:
Symbol Meaning $level the current heading level (before this paragraph) $prev_style the style of the previous paragraph $prev_text the text of the previous paragraph %prev_attr the attributes of the previous paragraph
These symbols make it much easier to do some really nice things. For example, the following rule can be used to put level 2 headings on a new page unless the heading is the first one within a chapter: !on paragraph '[HAP]2';; if ($level != 1) {$attr{'top'} = 1} 10.2 Fixes Tim Hudson has contributed a number of fixes to this release including: • this version should now work with Perl 5 again - the previous version triggered a Perl 5 syntax error • the IMPORT pragma now supports filename extension adding ala the import macro • centred figures now work as expected in HTML • numerous Windows help generation fixes/enhancements.
Other fixes include: • the renaming of xx.out.ps to xx.ps is now done by sdfbatch, so failures (due to lack of disk space, say) are now handled much better than they previously were
25 May 1999, 11:54.31 Page 63 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
• topics mode now generates an error if the heading of a topic is duplicated within a file (see Miscellaneous things above) • headings containing a ? character should no longer cause problems • some bugs in sdfget's extraction of documentation from C code have been fixed (thanks to Keith Ponting). 10.3 Incompatibilities As the default page size is now global rather than A4, page breaks may occur slightly earlier than they previously did. The advantage of changing to global is that documents should now print successfully on US letter paper.
Memos, faxes, minutes and newsletters no longer have the company address in the top right hand corner. (I'll fix this soon, but it is not a high priority at the moment.)
As txt and pod outputs use a different algorithm for deciding column widths when a table does not have a format parameter, some table cells may no longer fit when these output formats are used.
The table attribute previously called headings has been renamed to parseline to better reflect its purpose and to make way for the new meaning.
The DOC_TOCTEXT variable has been renamed to DOC_TOC_TITLE. The DOC_TOCGRAPHIC variable has been renamed to DOC_TOC_GRAPHIC.
The newsletter style has been renamed to newslttr.
overhead is now a look, rather than a style. The overhead look is untested and rarely used, so use it at your own risk.
The aliases sdf2htmls and sdf2txts have been renamed to sdf2fmhtml and sdf2fmtxt respectively.
/usr/local/bin/perl5 is now the default perl interpreter used.
25 May 1999, 11:54.31 Page 64 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
11. 2.000beta7c
11.1 Enhancements The aliases CC and cc have been added for C++ pretty printing. This makes it easier to pretty print files with these extensions. Pretty printing of CORBA IDL is also now supported.
A number of improvements have been made to improve the formatting of document catalogs: • the TXT field has been added for text documents • the DOC field has been added for Word documents • REFNUMONLY:Reference can now be used to display just the code and version parts of a reference code • the Printer field has been renamed to Printdoc to match the name of the script in cgi-bin (the old name is still supported for backwards compatibility).
If you use the Printdoc field, the following variables control parameter values passed to the script: • PRINTDOC_ROOT (mandatory) - the absolute URL of the directory containing the documents • PRINTDOC_BACK (optional) - the absolute URL of the file to jump back to. (If not set, the html file matching the input file in the PRINTDOC_ROOT directory is used.)
Within the subsections macro, an empty section name now causes a new-line to be added at that point in the jump line output for HTML.
The text of a phrase can now be changed by setting the text attribute. (This is occasionally useful in event processing.) 11.2 Fixes If a file doesn't exist, empty output files are no longer created. Some bugs associated with filenames containing dots have also been fixed.
The nl character now works for ps and mif targets.
Several bugs were fixed in the formatting of document catalogs: • if a file doesn't exist, an empty date is now output • detection of special file formats (e.g. PDF, TXT) has been improved
25 May 1999, 11:54.31 Page 65 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
• the page count for PostScript generated by Word is no longer 0 • the back parameter to the printdoc script is no longer hard-coded.
Memos converted to html no longer have a table of contents unless one is explicitly requested.
REF[qsd] now works for any mincom document. 11.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 66 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
12. 2.000beta7b
12.1 Enhancements The new features in this version are: Object catalog formatting Subsections support Appending text to phrases New figure attributes Other 2.000beta7b goodies
Details are given below.
12.1.1 Object catalog formatting The user can now control how a catalog of objects (e.g. a table of references) is presented by setting the columns and compact parameters. columns is a comma- separated list of: [tag":"]attribute
where: • tag is a phrase style (or expression format) • attribute is the name of an attribute of the class.
compact is a boolean flag which reduces the spacing between the rows in the table.
This feature is extremely useful for building "project overview" Web pages. See the SDF document catalog for an example.
12.1.2 Subsections support The new subsections macro can now be used to specify the subsections in a topic. This has several advantages: • subsections can be given a hypertext id which contains the current topic name (making them unique) • for HTML, a "jump line" can be generated.
For example: H1: MyApp !subsections "Purpose,Usage,Description,Examples"
25 May 1999, 11:54.31 Page 67 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
In this case, the subsections macro changes the id generated for the headings listed to: MyApp - heading
For HTML, it will also generate a line of jumps to the headings.
12.1.3 Appending text to phrases Event processing on phrases has now been extended to support appending text to a phrase, i.e. prepending text to the rest of the paragraph. Text is appended by setting $append. For example: !on phrase 'PRD';; $append .= '(tm)'
Note: This feature is used to provide "qsd-style" (document name and code) expansion for REF phrases.
12.1.4 New figure attributes The IMPORT phrase style and the import macro now support new attributes: • base - the prefix to prepend to the figure pathname to get the location needed for the HTML output • jump - the URL to jump to • border - the border width in pixels.
These attributes are currently only supported for HTML output.
12.1.5 Other 2.000beta7b goodies The table filter now supports new attributes: • cellpadding - the pixels between the cell boundary and contents • cellspacing - the pixels between cells.
These attributes are currently only supported for HTML output.
In topics mode, the default header for the main topic now contains jumps to the next and previous topics.
The Values subroutine can now be used to lookup the value of an attribute for an object in a class.
Calculation subroutines can now be defined for attributes in a class. See perllib/sdf/ values.pl for examples.
25 May 1999, 11:54.31 Page 68 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
12.2 Fixes Unzipping SDF 2.000beta7a on MS-DOS caused problems as symbolic links on Un*x were not being unzipped correctly. This should now be fixed - the new distribution does not contain symbolic links for files, just directories.
SECT phrases are now output again in PostScript documents. (However, there is a still a bug in the cross reference support which caused this problem.)
A number of obscure errors in formatting list items for HTML are now fixed.
Warnings are now produced again for unknown parameters to filters. (This was broken by the performance enhancements added in 2.000beta5, I think.)
An error is now output for tables which have repeated headings. Previously, columns were silently "ignored".
A "noheadings" table with no data rows no longer produces unexpected output.
A number of problems are now fixed in the mincom/mims library. In particular, the screen dumps for MSM000A and MSM000B now look as they should. 12.3 Incompatibilities The sdf2mimsus and sdf2qsdus aliases have been renamed to sdf2mimsl and sdf2qsdl respectively.
25 May 1999, 11:54.31 Page 69 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
13. 2.000beta7a
13.1 Enhancements The background colour of a table can now be set via the bgcolor parameter of the table filter.
The COLOR_GREY variable is now supported.
Headings at level 6 are now supported.
The QSD front cover template now supports footers. (This is used within the MIMS documentation to show the MIMS version number.) 13.2 Fixes Text output (txt) works again.
Memo title blocks are formatted correctly again.
The HTML generation of Delphi documents now has the "Description" heading in it, as requested by John Benders. (Previously, the heading was removed for all non-hlp targets. It is now kept for all non-ps targets.)
Topics mode now works for headings containing commas.
The box table style is now available inside QSD templates. 13.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 70 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
14. 2.000beta7
14.1 Enhancements There are lots of new things in this version including: Topics mode for HTML HTML headers and footers HTML control variables Macros inside tables Wide tables Figure enhancements Special characters Cross-references Other goodies
Details are given below.
14.1.1 Topics mode for HTML SDF can now generate a set of HTML topics, rather than a single HTML file. The command is: sdf -2topics myfile.sdf
If you want to manually control how a document is split into topics, simply include other sdf files which contain headings. These manual topics, if any, can be supplemented with automatically generated topics. By default, level 1 headings are used as topic breaks, in addition to the manual ones. The -n option can be used to change this: • -n0 disables autosplitting • -n2 uses level 1-2 headings to autosplit • -n3 uses level 1-3 headings to autosplit • etc.
To make it easy to navigate around the topics, SDF generates a default header and footer for a topic which supports jumping to the: • main topic (i.e. the contents) • parent topic
25 May 1999, 11:54.31 Page 71 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
• previous topic • next topic.
14.1.2 HTML headers and footers These macros give you total control over the headers and footers used: • HTML_HEADER - header on a HTML document (or main topic) • HTML_FOOTER - footer on a HTML document (or main topic) • HTML_TOPIC_HEADER - header on a HTML topic • HTML_TOPIC_FOOTER - footer on a HTML topic.
The default implementation of these macros is in html.sdm in the kernel library. The default versions of these macros use the variables below, if they are set. On most occasions, useful headers and footers can be obtained by simply setting these variables: • HTML_URL_HOME - URL of the home page • HTML_URL_CATALOG - URL of the catalog • HTML_URL_SEARCH - URL of the search facilities.
14.1.3 HTML control variables To fine tune HTML output, the following variables are useful: • HTML_BG_COLOR - the background colour of the page • HTML_BG_IMAGE - the background image of the page • HTML_TEXT_COLOR - the colour of normal text • HTML_LINK_COLOR - the colour of unvisited links • HTML_VLINK_COLOR - the colour of visited links.
To set a colour, use the RGB (red-green-blue) value as used by HTML. For example: !define HTML_BG_COLOR "ffffff"
For convenience, a number of variables are defined for common colours: COLOR_WHITE COLOR_BLACK COLOR_RED COLOR_GREEN COLOR_BLUE
25 May 1999, 11:54.31 Page 72 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
COLOR_YELLOW COLOR_CYAN COLOR_MAGENTA.
These are used as follows: !define HTML_BG_COLOR COLOR_WHITE
14.1.4 Macros inside tables Macros can now be used inside tables. In particular: • rows can now be conditionally included or excluded • rows can be marked as changed.
For example: !block table Code Description BTW By the way !block changed RTFM Read the (fine) manual !endblock !if ALL_TERMS SOS Save our souls !endif !endblock
14.1.5 Wide tables The table filter now supports a new attribute called wide. When it is used, the table spans the side-head in addition to the text column.
14.1.6 Figure enhancements The import macro now supports an align attribute, which is passed into the generated HTML. This can be used in combination with the clear macro to control how figures are aligned with text in HTML.
For example: !import "mylogo"; align="right" Some text. !clear
HTML's alt attribute is now also supported by the import macro.
14.1.7 Special characters Special characters can now be entered using {{CHAR:xxx}} where xxx is either: • a symbolic name
25 May 1999, 11:54.31 Page 73 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
• a character code (HTML only).
The symbolic names supported are given below.
Name Description bullet c copyright symbol cent dagger doubledagger emdash a hyphen which is the width of the point size endash a hyphen which is half the width of the point size emspace a space which is the width of the point size enspace a space which is half the width of the point size nbdash a non-breaking hyphen nbspace a non-breaking space nl newline pound r registered trademark tab tab character tm trademark yen
For convenience, variables with the same name are predefined. This makes it easy to include a special character. For example: Copyright [\[c]\] 1996, Us Pty Ltd.
Note: Some target formats do not yet support all of these characters. For example, HTML does not yet support Em or En spaces. In these cases, sdf will do the best it can (e.g. use a normal space for enpsace and emspace).
14.1.8 Cross-references Cross-references are now supported via the xref phrase attribute. For example: Refer to page {{N[xref="pagenum"] Samples}} for more samples.
The value specifies the cross-reference style to use. The phrase text is used to find the target location. The predefined styles are given below.
25 May 1999, 11:54.31 Page 74 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
Name Value pagenum the page number paratext the paragraph text paratag the (FrameMaker) paragraph tag paranum the paragraph number (e.g. Appendix A) paranumonly the paragraph number only (e.g. A) section section paranumonly, paratext, on page pagenum
New styles can be added by using the xrefs configuration filter. See mif.sdm in the kernel directory for examples.
Note: Other than PostScript, most targets ignore cross-references.
14.1.9 Other goodies New macros include: • output - dynamically change the output file used
New filters include: • changed - mark a block as changed (shorthand for sdf; changed) • topics - include a set of sub-topics • sections - create section jumps for html and hlp outputs • note - format a note • quote - format a quotation • address - format an address • ascii_graphic - format an ASCII graphic.
The current directory is now searched first for the configuration library, i.e. if OPT_CONFIG is abc, sdf first looks for ./abc.sdm before searching for abc.sdm in a directory called abc on the search path. 14.2 Fixes The copy number field on the mincom cover page has been fixed.
The Limitations & Future Directions heading in sdfget.sdm has been changed to Limitations and future directions.
25 May 1999, 11:54.31 Page 75 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
14.3 Incompatibilities The objects attribute of the table filter is now called tags.
The sections filter now generates SECT jumps for each paragraph within the block, provided the output is html or hlp. To include sub-topics (sub-sections), use the new topics filter.
When pretty-printing files using sdf, use the -N option to control line numbering. The - n option is now used to specify the level when autosplitting into HTML topics.
The message macro has been simplified - the message type is now an optional second parameter.
The obj* configuration filters have been renamed to phrase* to better reflect their purpose. (This shouldn't affect normal documents.)
The cfg_lang configuration filter has been renamed to langdefs.
25 May 1999, 11:54.31 Page 76 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
15. 2.000beta6c
15.1 Enhancements
A template directory has been added. This contains skeleton SDF files for different document types.
Prefilters now have their own subdirectory under lib. 15.2 Fixes None. 15.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 77 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
16. 2.000beta6b
16.1 Enhancements Tables now have a new style called box that simply puts a thin-line around the table.
The cover page generated for the mincom look has been improved. 16.2 Fixes If a look library and a configuration library had the same name, only one was begin loaded. This has now been fixed.
Nested jumps within HTML files no longer cause problems - the inner jump is now ignored. 16.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 78 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
17. 2.000beta6a
17.1 Enhancements The documentation now includes a draft version of an overview paper called The SDF Document Development System. This is recommended reading for all SDF users.
For Mincom users, Mincom-style title pages can now be generated for technical documents. To do this, initialise the OPT_LOOK variable using the init macro on the top line of the document like this: !init OPT_LOOK='mincom'
sdf's -k option can also be used to override the default look. For example: sdf -2ps -kmincom mydoc.sdf
The SDF Reference has been improved - most of the filters and macros now have a description and an example.
The build_title macro now outputs the date the document was last modified when the target is HTML.
Section jumps across documents are now supported via the doc phrase attribute. For example: See {{SECT[doc='SDF User Guide'] Event Processing}} in the {{DOC:SDF User Guide}} for further details.
The default target for the inline filter is now html.
The namevalues filter can now be used to specify a table of names and values. This is useful at the top of QSD procedures, etc.
The search order for figure importing into PostScript documents is now eps, pct, gif and finally bmp. 17.2 Fixes Under certain circumstances, figure importing into PostScript documents was broken by the previous version. It should now be working again.
Tables with titles no longer cause blank pages to be appended to the end of the document. This was a [FrameMaker]] 5.0 bug which I now workaround by producing "simple" titles. As a result, table titles are no longer repeated when a table crosses a page boundary.
Encapsulated PostScript figures output by Visio are now correctly sized.
25 May 1999, 11:54.31 Page 79 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
URLs in PostScript documents are no longer blue.
A large number of bugs in the QSD templates have been fixed. These had been introduced by the upgrade from FrameMaker to version 5.
The build_title macro (as implemented in the plain library) no longer outputs a page break after the Document control stuff.
Change bars no longer cause example text (e.g. source code) to be badly formatted in HTML. 17.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 80 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
18. 2.000beta6
18.1 Enhancements
18.1.1 Easier Usage sdfcvt is now called sdf. Furthermore, a -2 option has been added which simply maps through to the relevant alias. i.e. sdfcvt +sdf2ps abc.sdf
can now be specfied via: sdf -2ps abc.sdf
As a side effect of this, the sdfcvt.ini file has disappeared - its contents have been merged into sdf.ini.
The sdf2... wrapper scripts are still available, but are no longer documented.
The -2 option may eventually support a list of formats. e.g. sdf -2ps,html abc.sdf
18.1.2 FrameMaker 5 Support FrameMaker 5 can now be used instead of FrameMaker 4. This has several advantages: • a larger range of figure types can now be imported • book generation via fmbatch no longer causes a core dump • useful PDF can be generated (see below).
The main disadvantage is that FrameMaker 5 has a bug in calculating the last page number in books.
18.1.3 Easier Figures As FrameMaker 5 supports a larger range of figure types, the search rules for figures without an extension have now been expanded. The new rules are given below.
Format Extensions html gif hlp bmp other eps, then eps, then bmp
To take advantage of these rules, specify the figure file without an extension. e.g.
25 May 1999, 11:54.31 Page 81 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
!import "sdfarch"
18.1.4 PDF Support PDF can now be generated from the PostScript output from FrameMaker 5 by using the appropriate Adobe software. A contents panel is generated for normal documents.
Note: FrameMaker 5 has a bug which prevents the necessary information for a contents panel being included in the PostScript when a book is printed to file via fmbatch. If you want a contents panel for a book, it is currently necessary to use FrameMaker manually to set the Include Acrobat Data option and print the file.
18.1.5 Direct Conversion of Text Files Plain text files can now be directly generated from SDF - FrameMaker is no longer required. As a result, the conversion process is much quicker and the output looks much better.
18.1.6 POD Support SDF documents can now be converted to POD, the file format used by the Perl community. The Perl 5 distribution includes pod2man and pod2latex, so SDF files can now be indirectly converted to these formats too.
18.1.7 HTML Headers, Footers, Colors and Backgrounds Headers and footers to place at the top and bottom of each HTML page can now be defined. Colors and background images can also be specified. See the sdf.sdm for examples.
18.1.8 Delphi Help Enhancements
A large number of fixes and improvements have been made to this. See the samples/ delphi stuff for examples.
18.1.9 Topics Mode When generating HTML, it is often useful to create a table of contents and a large number of small pages, rather than a monolithic document. This release includes a prototype version of topics mode which illustrates how this might work. To try it, define each topic as a separate file and use the following command: sdf -2html -ftopics *.sdf
The main document will be converted to a table of contents. The remaining documents will be converted to topics.
Note: If the -ftopics option is not provided, a monolithic document will be generated.
25 May 1999, 11:54.31 Page 82 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
18.1.10Configuration Reporting Reference documentation for an SDF module can now be automatically generated by using the following command: sdf -2html mymodule.sdm
A summary of the terms, references, organisations and products, if any, will be included in the generated documentation. As a result, the reference documentation for a project library serves as a glossary and bibliography for the project.
18.1.11fm2ps An alias has been added for sdfbatch called fm2ps. This command converts FrameMaker documents to PostScript. It can be called via eiher way below: sdfbatch +fm2ps abc.doc fm2ps abc.doc 18.2 Fixes Unknown variables in restricted families (like DOC, OPT, etc) are now flagged as unknown (rather than read-only).
A page break is added by build_title when PostScript is being generated.
A number of pretty-printing bugs have been removed.
The escaping of special characters (<, >, &) has been fixed in HTML.
Spacing inside table cells (for Netscape) has been improved. 18.3 Incompatibilities None.
25 May 1999, 11:54.31 Page 83 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
19. 2.000beta5
19.1 Enhancements
19.1.1 Performance Performance is now 2-3 times faster for most documents. There is still some work to do here, but the performance is now "respectable" (rather than "disappointing").
19.1.2 Perl 5 This release has been tested with Perl 5.002 and is configured to use it, by default. However: • the odd "eval" buglet still (randomly?) appears when using Perl 5 • the mif2rtf script has not been tested.
If you wish to use Perl 4 instead, you will need to change the top line of the scripts in the bin directory after installing SDF.
19.1.3 Newsletters There is now a new style called newsletter.
The title filter now supports a toc parameter for specifying a table of contents. For example: !block title; toc=$var{'OPT_TARGET'} eq 'html' ? 2 : 0 Name Value Title My Newsletter Editor Me !endblock
This produces a title block for a newsletter and only gives it a table of contents when the target is HTML.
19.1.4 Pre-Filtering sdfcvt's -p option prefilters the input file for each argument. The (optional) parameter is the filter to use. For example: sdfcvt -ptable mytable.tbl
is equivalent to executing sdfcvt on a file which only contains: !include "mytable.pl"; table
File extensions can be mapped to filters in sdfcvt.ini. For example, sdfcvt.ini now contains the following:
25 May 1999, 11:54.31 Page 84 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
[PreFilters] Name Aliases Module table tbl module sdm,sde frmodule
As tbl is mapped to table, creating nicely formatted tables is now quite easy. For example: sdfcvt -p -aformat='15,75,10' mytable.tbl
(The -a option can be used to specify prefilter parameters.)
For a given prefilter, a module can be configured in sdfcvt.ini to be loaded before the filter is applied. As a result, it's possible to do really clever things via autoloaded filters. Examples include: • automatically documenting SDF modules • converting other formats to SDF on the fly.
For example, the following command will build the reference documentation for a SDF module in HTML (real soon now): sdfcvt +sdf2html -p abc.sdm 19.2 General Fixes The sdf2txt stuff now works. 19.3 HTML Fixes Empty cells now look better. (This was supposed to be fixed by the previous release but I had missed a few.)
Paragraphs with multiple anchors are now handled better (although the odd problem probably remains with this stuff).
If a table of contents is requested and SDF doesn't know the "right" place for it, it is now prepended (rather than being dumped).
Title blocks for correspondence look much better now. 19.4 HLP Fixes Absolute path names for libraries now correctly go into HPJ files. / characters are now also mapped to \ characters.
Title blocks for correspondence look much better now.
25 May 1999, 11:54.31 Page 85 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
19.5 Incompatibilities None.
25 May 1999, 11:54.31 Page 86 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
20. 2.000beta4c
20.1 Enhancements None. 20.2 General Fixes If an imported figure is not given an extension, an extension is added based on the target format: • hlp for Windows help • gif for HTML • eps otherwise (not epsi).
The SDF User Guide had most of the Advanced Features section commented out - this has now been fixed. The architecture figure in SDF Getting Started has been updated to show direct HTML generation.
All hypertext jumps throughout the documentation should now be working correctly. 20.3 HTML Fixes Blank cells in tables no longer look ugly.
References and terms are now formatted as a table. 20.4 HLP Fixes URLs no longer come out in blue.
Bitmaps no longer need to be in the directory when hcp.exe is executed, as the HPJ file now contains a search path. The HPJ file can still be generated on a Unix box (even though hcp.exe runs under Windows) as the search path is build using a new optional variable called SDF_DOSHOME.
Any option in the HLP file (xxx, say) can be set via the matching SDF variable called HLP_OPTIONS_xxx.
[email protected] has fixed a number of bugs in mif2rtf including: • table titles now work • formatted phrases at the beginning of a note or bulleted list now work • notes now have a closing line.
25 May 1999, 11:54.31 Page 87 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
20.5 Incompatibilities None.
25 May 1999, 11:54.31 Page 88 of 89 MTR-SDF-0008.001 (Final) SDF 2.001 SDF Release Notes
21. 2.000beta4b This is the first publicly available release of SDF 2.000.
25 May 1999, 11:54.31 Page 89 of 89 MTR-SDF-0008.001 (Final)