SDF 2.001 SDF Release Notes (Final) Document No: MTR-SDF
Total Page:16
File Type:pdf, Size:1020Kb
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.