<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>SDF 2.001: SDF Release Notes: 2.001</TITLE>
</HEAD>
<BODY BGCOLOR="ffffff">
<DIV CLASS="header">
<P><IMG SRC="../sdflogo.gif" ALIGN="Right"></P>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="rn_sdf.html">Contents</A> | <A HREF="rn_sdf.html">Parent Topic</A> | <A HREF="rn_sdf.html">Previous Topic</A> | <A HREF="2001b1.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
<BR CLEAR="Right">
</DIV>
<DIV CLASS="main">
<H1>1. 2.001</H1>
<P ALIGN="Left"><A HREF="#2.001 - Enhancements">Enhancements</A> | <A HREF="#2.001 - Fixes">Fixes</A> | <A HREF="#2.001 - Incompatibilities">Incompatibilities</A></P>
<HR>
<H2><A NAME="2.001 - Enhancements">1.1. Enhancements</A></H2>
<P>The enhancements are:</P>
<UL>
<A HREF="2001.html#Level 0 headings">Level 0 headings</A>
<BR>
<A HREF="2001.html#New command line options">New command line options</A>
<BR>
<A HREF="2001.html#Table enhancements">Table enhancements</A>
<BR>
<A HREF="2001.html#HTMLDOC support">HTMLDOC support</A>
<BR>
<A HREF="2001.html#Improved LaTeX support">Improved LaTeX support</A>
<BR>
<A HREF="2001.html#HTML formatting enhancements">HTML formatting enhancements</A>
<BR>
<A HREF="2001.html#HTML meta information and stylesheet support">HTML meta information and stylesheet support</A>
<BR>
<A HREF="2001.html#Stylesheet-friendly HTML generation">Stylesheet-friendly HTML generation</A>
<BR>
<A HREF="2001.html#Embedded documentation enhancements">Embedded documentation enhancements</A>
<BR>
<A HREF="2001.html#Miscellaneous stuff">Miscellaneous stuff</A></UL>
<H3><A NAME="Level 0 headings">1.1.1. Level 0 headings</A></H3>
<P>H0, A0 and P0 are now supported as paragraph styles. Level 0 headings are implicitly converted to:</P>
<PRE>
!define DOC_NAME "text of heading"
!build_title
</PRE>
<P>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, <A HREF="../ref/sdf.html">sdf</A>'s -H option can be used to set the initial heading level to zero like this:</P>
<PRE>
sdf -2html -H0 mytopic.sdf
</PRE>
<H3><A NAME="New command line options">1.1.2. New command line options</A></H3>
<P>The <A HREF="../ref/sdf.html">sdf</A> program has some new command line options: -O, -g and -K.</P>
<P>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 <TT>mydir1/mydir2/myfile</TT> to HTML and put the output in the same directory as the original file, the command is:</P>
<PRE>
sdf -2html -O mydir1/mydir2/myfile
</PRE>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>The -O option doesn't always work. In particular, HTML topics generation doesn't support it yet.
<HR WIDTH="80%" ALIGN="Left"></P>
<P>The -g option prefilters the input files by executing <A HREF="../ref/sdfget.html">sdfget</A> 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.</P>
<P>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:</P>
<PRE>
sdf -g -KP -H0 -2html myscript
</PRE>
<H3><A NAME="Table enhancements">1.1.3. Table enhancements</A></H3>
<P>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.</P>
<PRE>
!block table; style=Plain
!endblock
</PRE>
<P>The <EM>keepindents</EM> parameter has been introduced for the <A HREF="../ref/ftable.html">table</A> filter. If set, leading whitespace in cells is kept, e.g.</P>
<PRE>
!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
</PRE>
<P>The output is:</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Directory</STRONG>
</TD>
<TD>
<STRONG>Description</STRONG>
</TD>
</TR>
<TR>
<TD>
sdf
</TD>
<TD>
top level directory
</TD>
</TR>
<TR>
<TD>
bin
</TD>
<TD>
scripts
</TD>
</TR>
<TR>
<TD>
bat
</TD>
<TD>
batch file wrappers around scripts
</TD>
</TR>
<TR>
<TD>
perllib
</TD>
<TD>
</TD>
</TR>
<TR>
<TD>
sdf
</TD>
<TD>
sdf libraries
</TD>
</TR>
<TR>
<TD>
Pod
</TD>
<TD>
pod libraries
</TD>
</TR>
</TABLE>
<H3><A NAME="HTMLDOC support">1.1.4. HTMLDOC support</A></H3>
<P>To convert a document to HTML ready for Michael Sweet's <A HREF="http://www.easysw.com/~mike/htmldoc/">HTMLDOC</A> program, the command is:</P>
<PRE>
sdf -2html -DHTMLDOC ...
</PRE>
<P>Alternatively, <A HREF="../ref/sdf.html">sdf</A> can call HTMLDOC itself in order to generate PostScript or PDF. The commands to do this are:</P>
<PRE>
sdf -2ps_html ...
sdf -2pdf_html ...
</PRE>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>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 <EM>FormatMappings</EM> sections of the <TT>sdf.ini</TT> file and change <EM>ps</EM> to mean <EM>ps_html</EM> and <EM>pdf</EM> to mean <EM>pdf_html</EM>. Once this is done, the following commands will use HTMLDOC rather than FrameMaker:</P>
<PRE>
sdf -2ps ...
sdf -2pdf ...
</PRE>
<P><HR WIDTH="80%" ALIGN="Left"></P>
<P>When <A HREF="../ref/sdf.html">sdf</A> 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.</P>
<PRE>
sdf -2pdf_html "-DHTMLDOC_OPTS:--gray --jpeg" ...
</PRE>
<P>To do: add support for AUTHOR, COPYRIGHT and DOCNUMBER.</P>
<P>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.</P>
<H3><A NAME="Improved LaTeX support">1.1.5. Improved LaTeX support</A></H3>
<P>Valerio Aimale's (<A HREF="mailto:mailto:valerio@publinet.it">mailto:valerio@publinet.it</A>) LaTeX driver is now part of the standard distribution. Refer to the file <TT>doc/notes/latex.notes</TT> for usage details.</P>
<H3><A NAME="HTML formatting enhancements">1.1.6. HTML formatting enhancements</A></H3>
<P>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 <EM>teal</EM>.</P>
<P>The following paragraph attributes are now supported when generating HTML: align, first, left, right.</P>
<P>See the SDF files within the <TT>examples/2001/stylesheets</TT> directory for examples of using these attributes.</P>
<H3><A NAME="HTML meta information and stylesheet support">1.1.7. HTML meta information and stylesheet support</A></H3>
<P>The <EM>meta</EM> 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.</P>
<PRE>
!block meta
Name|Content
description|Tools for building Java systems
keywords|Java,development tools
!endblock
</PRE>
<P>Stylesheets can be linked or embedded using the <EM>links</EM> and <EM>stylesheet</EM> filters respectively. Here's a linked stylesheet:</P>
<PRE>
!block links
Jump
test.css
!endblock
</PRE>
<P>Here's how to embed the same stylesheet:</P>
<PRE>
!include "test.css"; stylesheet
</PRE>
<P>Phrases and paragraphs now support the following attributes:</P>
<UL>
<LI><EM>class</EM> - give this phrase or paragraph the nominated HTML CLASS attribute
<LI><EM>style</EM> - format this phrase or paragraph using the nominated style information.</UL>
<P>Here's an example of applying a custom style:</P>
<PRE>
[style='background-color: blue;; color: red']
A styled paragraph.
</PRE>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>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).
<HR WIDTH="80%" ALIGN="Left"></P>
<H3><A NAME="Stylesheet-friendly HTML generation">1.1.8. Stylesheet-friendly HTML generation</A></H3>
<P>Generated HTML documents are now "stylesheet-friendly" in that:</P>
<UL>
<LI>DIVs are placed around interesting parts of the document
<LI>parts of the title are implicitly given classes
<LI>tables are implicitly given classes.</UL>
<P>Here are the document sections placed in DIVs:</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Document part</STRONG>
</TD>
<TD>
<STRONG>DIV name</STRONG>
</TD>
</TR>
<TR>
<TD>
title section
</TD>
<TD>
title
</TD>
</TR>
<TR>
<TD>
table of contents
</TD>
<TD>
contents
</TD>
</TR>
<TR>
<TD>
main body
</TD>
<TD>
main
</TD>
</TR>
<TR>
<TD>
header section
</TD>
<TD>
header
</TD>
</TR>
<TR>
<TD>
footer section
</TD>
<TD>
footer
</TD>
</TR>
<TR>
<TD>
navigate section
</TD>
<TD>
navigate
</TD>
</TR>
</TABLE>
<P>The navigate DIV is nested within header and footer. (This makes it easy to format the navigation section regardless of its location.)</P>
<P>Here's the list of classes placed on parts of the title:</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Class</STRONG>
</TD>
<TD>
<STRONG>Comments</STRONG>
</TD>
</TR>
<TR>
<TD>
doc-title
</TD>
<TD>
title of document
</TD>
</TR>
<TR>
<TD>
doc-id
</TD>
<TD>
id of document
</TD>
</TR>
<TR>
<TD>
doc-author
</TD>
<TD>
author list
</TD>
</TR>
<TR>
<TD>
doc-status
</TD>
<TD>
document status
</TD>
</TR>
<TR>
<TD>
doc-modified
</TD>
<TD>
modification date
</TD>
</TR>
</TABLE>
<P>Tables are implicitly given a class named after the SDF table style. Heading and footing rows within tables are given classes of <EM>heading</EM> and <EM>footing</EM> respectively. Here's a set of Cascading Style Sheet (CSS) rules for a colorful table:</P>
<PRE>
TABLE.columns {background-color: yellow}
TABLE.columns TR.heading {background-color: aqua}
TABLE.columns STRONG {font-size: 20pt}
TABLE.columns TD {color: purple}
</PRE>
<P>See the SDF files within the <TT>examples/2001/stylesheets</TT> directory for more examples of using these features.</P>
<H3><A NAME="Embedded documentation enhancements">1.1.9. Embedded documentation enhancements</A></H3>
<P>A new filter called <A HREF="../ref/fget.html">get</A> has been added.</P>
<P>Support for embedded documentation in IDL has been improved (the IDL now gets pretty-printed in the "Interface" section).</P>
<P>The <A HREF="../ref/mgetdoc.html">getdoc</A> and <A HREF="../ref/mgetcode.html">getcode</A> macros now guess the get-rule using the formatting extension.</P>
<P>The <A HREF="../ref/sdfget.html">sdfget</A> program has been enhanced in several ways:</P>
<UL>
<LI>if specified without a parameter, the get-rule is now guessed from the file extension (see the <A HREF="../ref/sdfget.html">sdfget</A> documentation for details on how this is done)
<LI>the new -v option enables verbose mode (which shows the get-rule guessed)
<LI>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)
<LI>a new get-rule called <EM>bat</EM> is supported for DOS batch files
<LI>if a report filename doesn't have an extension, sdg is assumed.</UL>
<P>The <EM>default.sdg</EM> report has been enhanced to support new sections called <EM>Notes</EM>, <EM>See_also</EM> and <EM>Authors</EM>.</P>
<P>A new SDG report called <EM>all.sdg</EM> has been added. This report formats all embedded documentation sections (unlike <EM>default.sdg</EM> which only extracts selected sections).</P>
<P>The <EM>default.sdg</EM> and <EM>all.sdg</EM> 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.</P>
<H3><A NAME="Miscellaneous stuff">1.1.10. Miscellaneous stuff</A></H3>
<P>A new module called <EM>homepage</EM> 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 (<TT>doc/home.sdf</TT>).</P>
<P>A Russian locale (ru_ru) has been added thanks to Alexey L. Popov (<A HREF="mailto:alpopov@elkamail.ru">alpopov@elkamail.ru</A>).</P>
<P>New macros called <EM>div</EM> and <EM>enddiv</EM> can be used to put divisions in documents.</P>
<P>If <A HREF="../ref/sdf.html">sdf</A>'s -p option is specified without a parameter, <A HREF="../ref/ftable.html">table</A> prefiltering is assumed.</P>
<HR>
<H2><A NAME="2.001 - Fixes">1.2. Fixes</A></H2>
<P>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.</P>
<P>When generating txt output, leading cell whitespace now works as expected. Previously, multiple spaces were converted to a single space.</P>
<P>Attribute values containing ;; no longer have the whitespace around the character sequence trimmed.</P>
<P>Internally, unhandled internal directives no longer produce a warning. (As a result, it's now easier to extend things without "breaking" existing drivers.)</P>
<P>When generating HTML, the HTML_PRE_SECTION is no longer prepended unless a table of contents is generated.</P>
<HR>
<H2><A NAME="2.001 - Incompatibilities">1.3. Incompatibilities</A></H2>
<P>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.</P>
<PRE>
sdf -2html -DHTML_OLD_FOOTERS ...
</PRE>
<P>The HTML driver no longer uses special embedded comments to work out where to put the table of contents.</P>
<P>The <A HREF="../ref/mgetcli.html">getcli</A> macro no longer searches the include path: it just executes the command.</P>
</DIV>
<DIV CLASS="footer">
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="rn_sdf.html">Contents</A> | <A HREF="rn_sdf.html">Parent Topic</A> | <A HREF="rn_sdf.html">Previous Topic</A> | <A HREF="2001b1.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
</DIV>
</BODY>
</HTML>