1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
|
<!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>
|
