>2- 2. : Using the pre-processor  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 


 #

2. Using the pre-processor

J

The preprocessor was originally introduced into AscToHTM to allow users/more flexibility in the HTML they generate.

The pre-processor allows AscToHTM and AscToRTF to be used asQan authoring tools, as opposed to a simple text conversion or migration tool.

K

Preprocessor lines are not normally output to the HTML or RTF generated.OInstead they are used to modify the conversion process in a number of ways.


 *

2.1 Marking up sections of text

J

The pre-processor can be used to mark sections in your document so that8the program will correctly process them as you wish.

N
Note:
The software does attempt to spot much user-formatted text: automatically, but this is a difficult area and prone to: error. Hence the use of these directives can reduce the error rate on such occasions.


Examples include :-

I

SECTION

I

This directive is used to divide the document up into named sectionsD that may then be conditionally included/excluded from a particular conversion.

Z

BEGIN/END_TABLE
k BEGIN/END_DELIMITED_TABLE
v BEGIN/END_COMMA_DELIMITED_TABLE

J

These pairs of directives are used to bracket tables of various typesE in the source text. The software will attempt to detect plain textF tables, but if this goes wrong adding these commands can correct the analysis

G

Within these tables you can use other TABLE pre-processor commandsY to tailor the HTML generated (see "The TABLE commands").

_

BEGIN/END_CONTENTS

J

Used to mark up a contents list in the source document. The softwareG will attempt to automatically detect the presence and location of anyF contents list in the document, but the algorithm can be problematic,2 and only really works for numbered headings.

W

BEGIN/END_HTML

H

Delimits a section of raw HTML code to be copied to the output file unchanged.

X

BEGIN/END_CODE
[ BEGIN/END_DIAGRAM
R BEGIN/END_PRE

N

Delimits sections of pre-formatted text. CODE refers to software samples> whilst DIAGRAM refers to ASCII art. PRE is the more general> "pre-formatted" text, although currently all 3 have the same implementation.

[

BEGIN/END_IGNORE

G

Delimits text that should be ignored. This could be anything fromM comments to copyright statements in the original source file that shouldn't' appear in the converted document.


 C

2.2 Commands that influence the indexing of the document

P

Certain directives can be used to alter the document properties. Often these9affect how the document will be searched and indexed.

W

In HTML these mostly lead to tags in the <HEAD>..</HEAD> of each page. Often)these tags produce no visible effect.

M

In RTF these lead to field in the document properties being filled in.



Examples include :-

F

TITLE
O DESCRIPTION
I KEYWORDS
Z STYLE_SHEET (HTML Only)

M

The DESCRIPTION and KEYWORDS commands may be continued on subsequent linesIprovided they also begin with the same $_$_<command> directive.


 3

2.3 Useful one-line pre-processor commands

L

A large number of one-line directives exist. Those for tables are listedQthe section on The TABLE commands. Others include

V

CONTENTS_LIST
K HTML_LINE
H INCLUDE
J LINERULE
U NAVIGATION_BAR
> TOC




2.4 Useful in-line tags

N

A large number of in-line tags are available. These can be used to produce0a number of useful effects. They include :-

Z

BR (line break)
A GOTO
K HYPERLINK
K TIMESTAMP
E SPACES
S SUPER and SUB
H VARIABLE


 !

2.5 The TABLE commands

G

These directives are used to tailor the HTML generated in any tables-AscToHTM creates. They are placed either

)

At the top of the file
E Directives placed here become defaults for the whole file, and will= replace any policies that have been set (see the section on0 "Table Generation" in the AscToHTM manual)

=

Inside a BEGIN_TABLE ... END_TABLE section
B Directives placed here will apply only to the table marked up by! these commands (see 7.1.2).

G

The table commands are described (naturally enough) in the following table.

1@
 ' # $   Y  <   ]  %   [  *   e  !   ]  9   c  3   (  .   e  '   e  )   i  3   (  6   (  7   (  o   i  7   (  2   (  +   (  *   (    q  2   (  1   (  $   e  .   (  C   e  *   (  0   i  5   (  =   (  D   (    [  8   (  4   (     i  5   (  3   (  p   y  2   (  4   (  +   (  n / o  2  { (  :1 t i (  -# n 1 Y i t5 i ; (  gu 1 
Directive
Value
Effect
TABLE_ALIGN
Align
Specifies the alignment of the whole table.
TABLE_BGCOLOR
Colour
Colour of background
TABLE_BORDER
Number
Size of border. 0 = None
TABLE_BORDERCOLOR
Colour
Colour of border
TABLE_CAPTION
Text
Table caption. Added centred at the top
TABLE_CELL_ALIGN
Align
Specifies the default alignment of
 

cells. Left, right or center
TABLE_CELLSPACING
Number
Spacing between cells.
TABLE_CELLPADDING
Number
Padding inside each cell
TABLE_COLO(U)R_ROWS
(none)
If present this specifies that the
 

odd and even rows of the table should
 

be coloured differently. See also the
 

"Colour data rows" policy.
TABLE_CONVERT_XREFS
(none)
If present, indicates that any section
 

cross-references in the table may
 

be converted to hyperlinks
 

(see also the policy line
 

"Convert TABLE X-refs to links")
TABLE_EVEN_ROW_COLO(U)R
Colour
When data rows are to be coloured
 

this specifies the colour of the
 

even numbered rows.
TABLE_HEADER_ROWS
Number
Number of header rows. These
 

will be placed in <TH> .. </TH> markup
TABLE_HEADER_COLS
Number
Number of header columns.
 

These will be marked up in bold
TABLE_IGNORE_HEADER
(none)
If present, indicates that the first
 

few line (i.e. the header) should be ignored
 

when calculating the column structure of the table.
 

See also policy "Ignore table header during analysis"
TABLE_LAYOUT
Layout
Explicit structure of table in terms of
 

number of columns and their widths.
 

See also policy "Default TABLE layout"
TABLE_MAY_BE_SPARSE
(none)
If present, indicates that the TABLE
 

may be sparse (see also the policy
 

"Expect sparse tables")
TABLE_MIN_COLUMN_SEPARATION
Number
Number of spaces to be taken as a
 

column separator when analysing the
 

table (see also the policy
 

"Minimum TABLE column separation").
TABLE_ODD_ROW_COLO(U)R
Colour
When data rows are to be coloured
 

this specifies the colour of the
 

odd numbered rows.
TABLE_WIDTH
Text
The width of the table (see also the
 

policy "Default TABLE width")
)n
U

Colours should be HTML Colours which will placed in the{Ivarious attributes of the <BODY> tag and other. The program simplyt0transcribes your value into the output file.


 T(

2.6 The CHANGE_POLICY command


U
NOTE:
This feature has the potential to cause mayhem, and as such is - offeredJ to users on a "as is" basis. That is, we offer no support for getting6 this feature to have the effect a user may desire.
F

This directive allows you change a particular policy in part of aK document. This is a potentially powerful feature, allowing you to tailoraU the conversion of your file in different sections of that file, oraJ to embed the policy particular to a file in commands inserted at the top of the file itself.

T*

The syntax of the command line is


,

$_$_CHANGE_POLICY <Policy Line>


t

eQ where <Policy_line> is a policy line as it would appear in a policy file,c and (usually) as it appears in the Policy manual.0



=9 For example the following would all be valid directivesP

/*
m1        $_$_CHANGE_POLICY Background Colour : red;        $_$_CHANGE_POLICY Ignore multiple blank lines : Yes_
1/

P

Although how and when they would take affect will depend on the policy.

K

For example, the background colour would only take effect if splittingwI the file up, and only on the next file generation. This works, BTW, soeI if anyone wants to split a file into many pages, all different colours,h then be my guest.

RC

There are a many caveats to this behaviour :-<

 
K

Not all policies may be changed in this way. In particular policiesnE that open other policy files are not supported. Even if a policysG if "changed", it does not follow that changing the policy will haven an effect.


c l
M

It is unlikely that this feature can be sensibly used to influence the I analysis of file, other than when placed at the top of the file only.fD If such a manner it is simply an alternative to using a separate policy file.


 <
N

Output policies are referenced at different times. Only those that areR referenced after the line is read from the source file may beE influenced, thus things like output file name may have no effect.G


e g
C

Not all policies once changed, can be changed back. This isG particularly of policies that contain values to be added to a list.E= This is an issue that may be addresses in later versions.i


b t
L

Messing with policies can cause unpredictable behaviour. For exampleH if you alter the section splitting parameters, then the chances of aF section cross-reference elsewhere in the document being calculated* as a correct hyperlink diminishes.

F

That's why this feature is offered UNSUPPORTED


 t
M

To further complicate matters, AscToHTM uses a readahead, write behind G buffer which means that you may need to experiment with the placing F of your policy change to within 40 lines (the size of the buffer).



>1 This problem is alleviated since version 3.2. 



i <,

2.7 Definition blocks and variables



EAUsing pre-processor tags you can define "blocks" of text known asl"definition blocks".



GLDefinition blocks allow blocks of output to be defined out of sequence, thatJis the content is defined in one location, and then may be instantiated at a number of different locations.



DA definition block has the formi

*
e+        $_$_DEFINE_BLOCK <block name>P
        ..!        text that forms the blocke
        ..        $_$_END_BLOCK>
1.

s



nIThe text inside the block may contain in-line tags, but it cannot containeany other tag directives.i



rTo invoke a block use the EMBED_BLOCK or INSERT_BLOCK commands.a



eoOne tag that is particularly useful inside blocks is the VARIABLE tag.dKYou can define variables throughout the document and then quote them inside&a define block. 



GA possible example of use would be the addition of "page" footers. YoulGcould define the text that goes inside a page footer, and include in it Ja variable called PAGE_NUMBER. You can then re-define the PAGE_NUMBER and,output a new page boundary with the commands

*
 *        $_$_DEFINE_VARIABLE PAGE_NUMBER 21$        $_$_INSERT_BLOCK PAGE_FOOTER
1S
5

having previously defined a PAGE_FOOTER block.

aJ

It should perhaps be pointed out that "pages" are anathema to HTML, butCshould you want this feature this is a possible implementation.

N
 f

2.8 HTML colours

oG

Some tags accept colour values. These values should be HTML colourstQwhich - for example - may be placed in the various attributes of the <BODY>htag.

P

You can enter any value acceptable to HTML. Normally a value is expressed asNa 6-digit hexadecimal value in the range 000000 (black) to FFFFFF (white), butIcertain colours such as "white", "blue", "red" etc may also be recognisedLFby HTML. AscToHTM simply transcribes your value into the output file.:The list of colours recognised in the HTML standard is


'E@
 $ ,  e    f    F  e  B    R  _  R    T  >  S  N  a    n  A  O    2  d  y  e  U  e  e  w    e  o
Colour
HTML Hex value
Black
#000000
Silver
#C0C0C0
Gray
#808080
White
#FFFFFF
Maroon
#800000
Red
#FF0000
Purple
#800080
Fuchia
#FF00FF
Green
#008000
Lime
#00FF00
Olive
#808000
Yellow
#FFFF00
Navy
#000080
Blue
#0000FF
Teal
#008080
Aqua
#00FFFF
.
<
i
O

Only these values will be converted by the software to the equivalent names..ROther names exist outside the standard which may not be universally supported.


 -'

2.9 English/American spellings

L

As far as possible tags support both British English and American EnglishJspellings. This mainly occurs with the word "colour" (or "color"), so forexample the directives

&

$_$_TABLE_ODD_ROW_COLOUR ....

l

and

%

$_$_TABLE_ODD_ROW_COLOR ....

T
f

are equivalent.


 2

B
DY Previous page m$C Back to Contents Listo# U Next page A


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