H1: 2.000beta7

!subsections "Enhancements,Fixes,Incompatibilities"

H2: Enhancements

There are lots of new things in this version including:

!block sections
. Topics mode for HTML
. HTML headers and footers
. HTML control variables
. Macros inside tables
. Wide tables
. Figure enhancements
. Special characters
. Cross-references
. Other goodies
!endblock

Details are given below.

H3: Topics mode for HTML

SDF can now generate a set of HTML topics, rather than a single
HTML file. The command is:

E:   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
* previous topic
* next topic.

H3: 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 {{FILE:html.sdm}}
in the {{FILE: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.

H3: 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:

E:   !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
. COLOR_YELLOW
. COLOR_CYAN
. COLOR_MAGENTA.

These are used as follows:

E:   !define HTML_BG_COLOR COLOR_WHITE

H3: 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 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
!endblock

H3: Wide tables

The {{FILT: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.

H3: Figure enhancements

The {{MAC:import}} macro now supports an {{align}} attribute,
which is passed into the generated HTML. This can be used
in combination with the {{MAC:clear}} macro to control how
figures are aligned with text in HTML.

For example:

!block example
!import "mylogo"; align="right"
Some text.
!clear
!endblock

HTML's {{alt}} attribute is now also supported by the
{{MAC:import}} macro.

H3: Special characters

Special characters can now be entered using E<2{>CHAR:xxxE<2}>
where {{xxx}} is either:

* a symbolic name
* a character code (HTML only).

The symbolic names supported are given below.

!block table
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
!endblock

For convenience, variables with the same name are predefined.
This makes it easy to include a special character. For example:

E:   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, {{CMD:sdf}} will do the best it can (e.g. use a
normal space for enpsace and emspace).

H3: Cross-references

Cross-references are now supported via the {{xref}} phrase attribute.
For example:

V: 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.

!block table
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}}
!endblock

New styles can be added by using the {{xrefs}} configuration filter.
See {{FILE:mif.sdm}} in the {{FILE:kernel}} directory for examples.

Note: Other than [[PostScript]], most targets ignore cross-references.

H3: Other goodies

New macros include:

* {{MAC:output}} - dynamically change the output file used

New filters include:

* {{FILT:changed}} - mark a block as changed (shorthand for {{sdf; changed}})
* {{FILT:topics}} - include a set of sub-topics
* {{FILT:sections}} - create section jumps for html and hlp outputs
* {{FILT:note}} - format a note
* {{FILT:quote}} - format a quotation
* {{FILT:address}} - format an address
* {{FILT:ascii_graphic}} - format an ASCII graphic.

The current directory is now searched first for the configuration
library, i.e. if OPT_CONFIG is {{abc}}, {{CMD:sdf}} first looks
for {{./abc.sdm}} before searching for {{abc.sdm}} in a directory
called {{abc}} on the search path.

H2: Fixes

The copy number field on the mincom cover page has been fixed.

The {{Limitations & Future Directions}} heading in {{FILE:sdfget.sdm}}
has been changed to {{Limitations and future directions}}.

H2: Incompatibilities

The {{objects}} attribute of the {{FILT:table}} filter is now
called {{tags}}.

The {{FILT: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 {{FILT:topics}}
filter.

When pretty-printing files using {{CMD: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 {{MAC: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
{{FILT:langdefs}}.

# ??????? WILL THIS STUFF THINGS UP ???????
#
#The output extension (i.e. OPT_OUT) is now used as the extension
#for {{.html}} jumps.
