>2) 3 : Using HTML fragments  A 
A

The "Tag Manual" for JafSoft's text conversion utilities

E

This documentation can be downloaded as part of the Ldocumentation set in .zip format




Y Previous page $C Back to Contents List#U Next page 


 

3 Using HTML fragments

(

New in version 4

 

3.1 Overview

H

HTML fragments only apply to HTML generation (obviously)

M

The "HTML fragments" feature allows you to define a block of HTML that youFcan then embed in your document at key locations. These fragments areKpure HTML that gets transcribed into the output files, but they may contain[fragment tags that will be replaced by suitable values each timethe fragment is used.

L

Most fragments use reserved names, that is they have a particular meaningKto the program. If you define fragments with these names they will be used5instead of the HTML that is generated by default.

I

Currently only fragments with reserved names are used by the software.FThe ability to define and use your own fragments names may be added in#later versions of the software.

H

You can choose to define empty fragments. This can be done either byAliterally defining a fragment with no HTML in it, or by issuing aŸRESET_HTML_FRAGMENT command - see DEFINE_HTML_FRAGMENT and RESET_HTML_FRAGMENT

K

If an empty HTML fragment is defined then no HTML will be generated. IfHthe fragment name is a reserved name then the result is to suppress thatparticular feature.



For example the command

+

$_$_RESET_HTML_FRAGMENT NAVBAR_TOP

O

would cause the navigation bar at the top of each page to be suppressed when7splitting large documents into several small pages.

L

HTML fragments may be defined either in the source text, or in a separateE"HTML fragments file". This file may then be selected via the policy|"HTML fragments file". Only the fragments themselvesIwill be read from this file, everything else will be ignored, leaving youPfree to add your own comments to this file between the fragment definitions.

O

If you don't want to set the policy you can get the same effect by using theFINCLUDE command as follows

+

$_$_INCLUDE <fragments file>

L

to your source file near the top. This will copy the fragments file intoJyour source text, so in this case you should include no other text in this%file as it will appear in the output.



JYou may, if you wish, re-define the HTML fragment later in the file. ThisJwill take effect from that point onwards. For example if you redefine theIHORIZONTAL_RULE fragment to be an image, you could arrange for this image2to change for different sections of your document.






 *

3.2 How to define a HTML fragment



,Simply use pre-processor commands as follows

*
+      $_$_DEFINE_HTML_FRAGMENT <name>	      ...8      ...<your HTML with embedded "fragment tags">	      ...      $_$_END_BLOCK
1





For example,

*
,      $_$_DEFINE_HTML_FRAGMENT NAVBAR_BOTTOMH      <A HREF="[[PREV_PAGE]]"><IMG SRC="prev.gif"></A>H      <A HREF="[[NEXT_PAGE]]"><IMG SRC="next.gif"></A>      $_$_END_BLOCK
1





Fcould define a navigation bar for the bottom of each page which adds aDhyperlink to the previous and next page which is added to some .gif.TThe fragment tags [[PREV_PAGE]] and [[NEXT_PAGE]] will bereplaced by the correct URLs.

*
(      $_$_RESET_HTML_FRAGMENT NAVBAR_TOP
1

or

*
)      $_$_DEFINE_HTML_FRAGMENT NAVBAR_TOP      $_$_END_BLOCK
1
P

both define an "empty" top navigation bar, thereby suppressing the generation0of a navigation bar at the top of each page.


 

3.3 Fragment tags

P

Within HTML fragments special "fragment tags" are supported. These tags haveLthe same overall format as the more general pre-processor tags, but are only$supported inside HTML fragments.

'

The following tags are supported


 0

3.3.1 Tags for navigation bar fragments

', ! )    ?   6    >   . 5   ) 6 
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
6 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
1 next section in the contents list.
.

 1

3.3.2 Tags for horizontal rule fragments

', ! )    A    9    A    C 
Tag
Description
RULEWIDTHPC


  

The calculated ruler width expressed as a percentage.
? Often the program will detect a line, and will set it
B 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
R 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
E LINERULE tag.
.

N

The above values are all supplied ready to be used as attribute values. AsJsuch they should normally be enclosed in quotes in your HTML fragment. IfPyou're using an <IMG> tag and want to capture the width, use the RULEWIDTHVvalue. If you're generating an <HR> tag we recommend the RULEWIDTHPC percentagevalue instead.


 )

3.4 Reserved HTML fragment names

L

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

 '

3.4.1 Navigation bar fragments

', 2 =   , E   1 >   / =   5 A   ! 2 
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
b 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.
.

 +

3.4.2 The Horizontal rule fragment


F
HORIZONTAL_RULE
The horizontal ruler. Normally this is/ just <HR>, but you can change that by2 defining a HTML fragment of this name, e.g. toY use an <IMG> tag (see A sample HTML fragments file).

 *

3.4.3 Table of contents fragments

H

These fragments can be used to tailor the appearance of a generated contents list.


F
START_TOC
A fragment to be output before any generated2 table of contents. If not defined the default8 behaviour is to output the title "Table of Contents"N
END_TOC
A fragment to be output after any generated table6 of contents. If not defined the default behaviour5 is to simply put out a horizontal rule <HR>

 1

3.4.4 HTML headers and footers fragments

H

The program previously supported the insertion of HTML at the start> and end of each HTML page generated through the policies


a

"HTML header file"
^ "HTML footer file"


F

The new fragments HTML_HEADER and HTML_FOOTER provide exactly the same functionality.

K

The use of fragments is encouraged over that of the previous policies,J so where both are defined, the fragment will be used (e.g. a HTML_HEADER@ fragment will override a "HTML header file" policy value).


 @

3.4.5 HTML header and footers (inside FRAMES) fragments

H

A number of fragments can be used to control the creation of headerC and footer FRAMES, and the creation of headers and footers insideC the main frame. The use of these fragments depends on the values of the policies

.



"Use main header in header frame"
x"Use main footer in footer frame"


1
F

which can be used to promote a HTML header/footer from the top ofE each HTML page into a frame by itself. This allows the same policyD file to be used to generate a non-FRAMES set of pages with headersC and footers on each page, and also a FRAMES set of pages with theB same headers and footers now permanently on display in their own1 frames at the top and bottom of the screen.

M

The following fragments can be used to define the contents of particular frames :-


J
HEADER_FRAME
If defined, this fragment will be used as the7 contents of a header frame at the top of the screenO
FOOTER_FRAME
If defined, this fragment will be used as the3 contents of a footer frame at the bottom of the screenZ
CONTENTS_FRAME
If defined, this fragment will be used as the contents6 of the "contents" frame on the left of the screen.6 If not defined the "contents" frame will contain a generated contents listT
MAIN_FRAME_FOOTER
If defined, this fragment will be used as the0 HTML footer of each page that appears in the2 main frame. If defined this will override any; HTML_FOOTER fragment, or value defined via policy file.T
MAIN_FRAME_HEADER
If defined, this fragment will be used as the0 HTML header of each page that appears in the2 main frame. If defined this will override any; HTML_HEADER fragment, or value defined via policy file.n

T ")

3.5 A sample HTML fragments file

L=

The following sample fragments file does the following

n *
N'      !----- sample HTML fragments fileM PT      Comments in this file (like these) are ignored if the file is selected via the#      "HTML fragments file" policy.T T      !----- Horizontal rulesp }\      ! Here's a redefinition of the horizontal rules <HR> that the program generates.V      ! I'm replacing them by an image, but I'm capturing the (pixel) width and fixing5      ! the height (otherwise the image would scale).;      !O      ! Within this fragment I'm using the [[RULEALIGN]] and [[RULEWIDTH]] HTMLtQ      ! fragment tags to pick up the alignment and width appropriate for the rulee"      ! when the fragment is used.      !tX      ! NOTE, not all <HR> tags created by the program are currently overridden in      !       this way. B.      $_$_DEFINE_HTML_FRAGMENT HORIZONTAL_RULE'      <DIV ALIGN="[[RULEALIGN]]">iG      <IMG SRC="HR.GIF" HEIGHT=4 WIDTH="[[RULEWIDTH]]"><BR>       </DIV>      $_$_END_BLOCKt /      !----- Frame headers i+      $_$_DEFINE_HTML_FRAGMENT HEADER_FRAME       <DIV ALIGN="CENTER">'      <H2>header frame</H2>F‰      <A HREF="http://www.jafsoft.com/">Visit the Jafsoft home page!</A>=      </DIV>      <HR NOSHADE>      $_$_END_BLOCKL <#      !----- bottom navigation bars0I      ! I don't want any bottom navigation bars so issue a reset command.x?      ! I could just as easily have defined an "empty" fragment=+      $_$_RESET_HTML_FRAGMENT NAVBAR_BOTTOM/
1S

/z

The HTML fragments file used on this document is html_fragments.inc


 2

g
Y Previous page d$C Back to Contents List #eU Next page H


B ? 
Valid HTML 4.0!Converted from a single text file by HREF="http://www.jafsoft.com/asctohtm/">AscToHTM
K© 1997-2001 John A. Fotheringhamt
rm