| Back to Contents List |
|
The most recent version of this document can always be found online
HTML fragments only apply to HTML generation (obviously)
The "HTML fragments" feature allows you to define a block of HTML that you can then embed in your document at key locations. These fragments are pure HTML that gets transcribed into the output files, but they may contain fragment tags that will be replaced by suitable values each time the fragment is used.
Most fragments use reserved names, that is they have a particular meaning to the program. If you define fragments with these names they will be used instead of the HTML that is generated by default.
Currently only fragments with reserved names are used by the software. The ability to define and use your own fragments names may be added in later versions of the software.
You can choose to define empty fragments. This can be done either by literally defining a fragment with no HTML in it, or by issuing a RESET_HTML_FRAGMENT command - see DEFINE_HTML_FRAGMENT and RESET_HTML_FRAGMENT
If an empty HTML fragment is defined then no HTML will be generated. If the fragment name is a reserved name then the result is to suppress that particular feature.
For example the command
$_$_RESET_HTML_FRAGMENT NAVBAR_TOP
would cause the navigation bar at the top of each page to be suppressed when splitting large documents into several small pages.
HTML fragments may be defined either in the source text, or in a separate "HTML fragments file". This file may then be selected via the policy "HTML fragments file". Only the fragments themselves will be read from this file, everything else will be ignored, leaving you free to add your own comments to this file between the fragment definitions.
If you don't want to set the policy you can get the same effect by using the INCLUDE command as follows
$_$_INCLUDE <fragments file>
to your source file near the top. This will copy the fragments file into your source text, so in this case you should include no other text in this file as it will appear in the output.
You may, if you wish, re-define the HTML fragment later in the file. This will take effect from that point onwards. For example if you redefine the HORIZONTAL_RULE fragment to be an image, you could arrange for this image to change for different sections of your document.
Simply use pre-processor commands as follows
$_$_DEFINE_HTML_FRAGMENT <name>
...
...<your HTML with embedded "fragment tags">
...
$_$_END_BLOCK
For example,
$_$_DEFINE_HTML_FRAGMENT NAVBAR_BOTTOM
<A HREF="[[PREV_PAGE]]"><IMG SRC="prev.gif"></A>
<A HREF="[[NEXT_PAGE]]"><IMG SRC="next.gif"></A>
$_$_END_BLOCK
could define a navigation bar for the bottom of each page which adds a hyperlink to the previous and next page which is added to some .gif. The fragment tags [[PREV_PAGE]] and [[NEXT_PAGE]] will be replaced by the correct URLs.
$_$_RESET_HTML_FRAGMENT NAVBAR_TOP
or
$_$_DEFINE_HTML_FRAGMENT NAVBAR_TOP
$_$_END_BLOCK
both define an "empty" top navigation bar, thereby suppressing the generation of a navigation bar at the top of each page.
Within HTML fragments special "fragment tags" are supported. These tags have the same overall format as the more general pre-processor tags, but are only supported inside HTML fragments.
The following tags are supported
Tag Description PREV_PAGE URL of previous page. If no pervious page then URL
of this pageCURRENT_PAGE URL of the current page. Can be useful if
you want to construct a NOFRAMES link to the
current page.NEXT_PAGE URL of next page. If no next page then the URL of
this page.CONTENTS_TOP URL of page containing contents list CONTENTS_NEXT_SECTION As above - but linked to an anchor for the
next section in the contents list.
Tag Description RULEWIDTHPC The calculated ruler width expressed as a percentage.
Often the program will detect a line, and will set it
as a <HR> tag of the appropriate percentage width.
This is that value.RULEWIDTH The calculated ruler width. This will be the
percentage width expressed for a default 800 pixel
wide screen.RULEHEIGHT The ruler height. Not usually varied unless supplied
as part of a LINERULE tag.RULEALIGN The ruler alignment. This may sometimes be set to LEFT
if a less that 100% rule is being generated, or it
may be set to some other value by a user-supplied
LINERULE tag.
The above values are all supplied ready to be used as attribute values. As such they should normally be enclosed in quotes in your HTML fragment. If you're using an <IMG> tag and want to capture the width, use the RULEWIDTH value. If you're generating an <HR> tag we recommend the RULEWIDTHPC percentage value instead.
Currently there is only one fragment tag used inside frames fragments :-
NOFRAMES_URL This is the URL used by default for any NOFRAMES
link. Typically you'd use this inside a NOFRAMES_LINK
fragment to link to the same URL as the default
NOFRAMES link would, while adding your own text and
decoration for the link.
The following tags may be used inside the various Heading tag fragments
HEADER_TEXT The text part of the heading HEADER_LEVEL The heading level (1,2,3...). Note, this is the
logical heading level. The default markup might
use a different <Hn> tag because these values are
limited in range to ensure text is a sensible size
(<H1> is too big, <H4> is too small etc).
The following tags may be used inside the various TOC line tag fragments
TOC_TEXT The text part of the TOC line TOC_LEVEL The TOC level (1,2,3...) TOC_URL The URL for this TOC line
Here are the reserved HTML fragment names recognised by the software, and their effect on the HTML generated.
NAVBAR_TOP_FIRST The navigation bars output at the top of the NAVBAR_TOP first, general or last pages. Usually the first and NAVBAR_TOP_LAST last navigation bars may wish to omit the previous
or next links (since no such page exists). If the
"_FIRST" and "_LAST" fragments are not defined, the
"NAVBAR_TOP" fragment will be used instead.NAVBAR_MIDDLE Any navigation bar output in the middle of a page
as a result of a NAVIGATION_BAR tag.NAVBAR_BOTTOM_FIRST As for the "NAVBAR_TOP" fragments, but this time NAVBAR_BOTTOM
NAVBAR_BOTTOM_LASTat the bottom of generated pages.
HORIZONTAL_RULE The horizontal ruler. Normally this is
just <HR>, but you can change that by
defining a HTML fragment of this name, e.g. to
use an <IMG> tag (see A sample HTML fragments file).
Updated in version 5.0
These fragments can be used to tailor the appearance of a generated contents list.
START_TOC A fragment to be output before any generated
table of contents. If not defined the default
behaviour is to output the title "Table of Contents"END_TOC A fragment to be output after any generated table
of contents. If not defined the default behaviour
is to simply put out a horizontal rule <HR>TOC_LINE_<n> A fragment to be output for TOC contents lines
at heading level <n> (<n> = 1,2,3...)TOC_LINE The default fragment to be used for TOC content lines
if the specific fragment TOC_LINE_<n> is not defined
When create TOC_LINE fragments, you will almost certainly want to use the TOC_TEXT and TOC_URL fragment tags (see Tags for Table of Contents fragments).
The program previously supported the insertion of HTML at the start and end of each HTML page generated through the policies
The new fragments HTML_HEADER, HTML_FOOTER and HEAD_SCRIPT provide exactly the same functionality.
The use of fragments is encouraged over that of the previous policies, so where both are defined, the fragment will be used (e.g. a HTML_HEADER fragment will override a "HTML header file" policy value).
A number of fragments can be used to control the creation of header and footer FRAMES, and the creation of headers and footers inside the main frame. The use of these fragments depends on the values of the policies
"Use main header in header frame"
"Use main footer in footer frame"
which can be used to promote a HTML header/footer from the top of each HTML page into a frame by itself. This allows the same policy file to be used to generate a non-FRAMES set of pages with headers and footers on each page, and also a FRAMES set of pages with the same headers and footers now permanently on display in their own frames at the top and bottom of the screen.
The following fragments can be used to define the contents of particular frames :-
HEADER_FRAME If defined, this fragment will be used as the
contents of a header frame at the top of the screenFOOTER_FRAME If defined, this fragment will be used as the
contents of a footer frame at the bottom of the
screenNOFRAMES_LINK If defined, this fragment will be used in place
of any NOFRAMES link that is created by default.
You would most likely use this with the NOFRAMES_URL
fragment tag to define alternative text on the link.CONTENTS_FRAME If defined, this fragment will be used as the contents
of the "contents" frame on the left of the screen.
If not defined the "contents" frame will contain a
generated contents listMAIN_FRAME_FOOTER If defined, this fragment will be used as the
HTML footer of each page that appears in the
main frame. If defined this will override any
HTML_FOOTER fragment, or value defined via policy file.MAIN_FRAME_HEADER If defined, this fragment will be used as the
HTML header of each page that appears in the
main frame. If defined this will override any
HTML_HEADER fragment, or value defined via policy file.
Where headings are detected in the program, you can use the following HTML fragments
HTML_HEADER_LINE_<n> The fragment to be used for headings
of level <n> (<n> = 1, 2 3...)HTML_HEADER_LINE The default fragment to be used for
headings if there isn't a specific
HTML_HEADR_LINE_<n> for the value of <n>
involved.
The default markup would be to place the heading text in <Hn> tags. Using the Tags for Heading fragments you could reproduce this in your own fragments as follows
<H[[HEADER_LEVEL]]>[[HEADER_TEXT]]</H[[HEADER_LEVEL]]>
e.g. if the heading was "Introduction" and this was a level 1 heading, this would become
<H1>Introduction</H1>
The following sample fragments file does the following
!----- sample HTML fragments file
Comments in this file (like these) are ignored if the file is selected via the
"HTML fragments file" policy.
!----- Horizontal rules
! Here's a redefinition of the horizontal rules <HR> that the program generates.
! I'm replacing them by an image, but I'm capturing the (pixel) width and fixing
! the height (otherwise the image would scale).
!
! Within this fragment I'm using the [[RULEALIGN]] and [[RULEWIDTH]] HTML
! fragment tags to pick up the alignment and width appropriate for the rule
! when the fragment is used.
!
! NOTE, not all <HR> tags created by the program are currently overridden in
! this way.
$_$_DEFINE_HTML_FRAGMENT HORIZONTAL_RULE
<DIV ALIGN="[[RULEALIGN]]">
<IMG SRC="HR.GIF" HEIGHT=4 WIDTH="[[RULEWIDTH]]"><BR>
</DIV>
$_$_END_BLOCK
!----- Frame headers
$_$_DEFINE_HTML_FRAGMENT HEADER_FRAME
<DIV ALIGN="CENTER">
<H2>header frame</H2>
<A HREF="http://www.jafsoft.com/">Visit the Jaf soft home page!</A>
</DIV>
<HR NOSHADE>
$_$_END_BLOCK
!----- bottom navigation bars
! I don't want any bottom navigation bars so issue a reset command.
! I could just as easily have defined an "empty" fragment
$_$_RESET_HTML_FRAGMENT NAVBAR_BOTTOM
The HTML fragments file used on this document is html_fragments.inc
 |
Converted from
a single text file by AscToHTM © 1997-2004 John A. Fotheringham |  |