Documentation for the AscToHTM conversion utility : Using HTML fragments

Documentation for the AscToHTM Text to HTML converter

Using HTML fragments

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

How to define a HTML fragment

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

      $_$_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.

Fragment tags

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

Tags for frame fragments
Tags for heading fragments
Tags for horizontal rule fragments
Tags for navigation bar fragments
Tags for Table of Contents fragments

Tags for navigation bar fragments

Tag Description

PREV_PAGE URL of previous page. If no pervious page then URL
of this page

CURRENT_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
PREV_PAGE	URL of previous page. If no pervious page then URL of this page
CURRENT_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.

Tags for horizontal rule fragments

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.

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.

Tags for frame fragments

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.

Tags for Heading fragments

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).

Tags for Table of Contents fragments

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

Reserved HTML fragment names

Here are the reserved HTML fragment names recognised by the software, and their effect on the HTML generated.

Navigation bar fragments

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_LAST at the bottom of generated pages.

Table fragments

TABLE_HEADER Any HTML fragment to be output before a table.
This won't actually replace the table header itself,
but could be used to insert a title.

TABLE_FOOTER Any HTML fragment to be output before a table.

The horizontal rule fragment

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).

Table of contents fragments

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).

HTML headers, footers and JavaScript 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).

HTML header and footers (inside FRAMES) fragments

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

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 screen
FOOTER_FRAME	If defined, this fragment will be used as the contents of a footer frame at the bottom of the screen
NOFRAMES_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 list
MAIN_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.

Heading fragments

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>

A sample HTML fragments file

The following sample fragments file does the following

Defines a HORIZONTAL_RULE fragment to use an image in place of the <HR> tag. The image uses the HTML fragment tags RULEALIGN and RULEWIDTH to take on the necessary alignment and size.

Defines a HEADER_FRAME that contains a title and link to the home page, both centred on the page. This fragment will only be used when generating a set of FRAMES.

Does a reset on the NAVBAR_BOTTOM fragment. This effectively defines an empty fragment whose effect is to suppress the navigation bar usually put at the bottom of each page when splitting a large file into sections.

      !----- 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

Back to Contents List

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).

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

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_LAST	at the bottom of generated pages.

TABLE_HEADER	Any HTML fragment to be output before a table. This won't actually replace the table header itself, but could be used to insert a title.
TABLE_FOOTER	Any HTML fragment to be output before a table.

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