>2+ 7 : Using the preprocessor  A 8
AscToHTM 

Documentation for the OAscToHTM conversion utility



9

This documentation can be downloaded as part of the  documentation set in .zip format (370k)




V Previous page $@ Back to Contents List#R Next page 


 ,

7 Using the preprocessor

G

The preprocessor was introduced to allow users more flexibility in@ the HTML they generate. As such it allows AscToHTM to be usedE as a HTML authoring tool, as opposed to a simple text conversion or migration tool.

#

The preprocessor looks for


    
  1. F "Directives". These are lines that begin with a special character( sequence. Presently this is "$_$_".

  2. 
  3. 3 "Tags" that are enclosed in "[[" and "]]".
  4. 
g

A separate document - the Tag manual - has been produced to describeG the pre-processor commands in detail. That document replaces much ofE the contents that were originally in this section and the next.

K

Some commands may be either tags or directives, this is explained more in the tag manual.

 

7.1 Directives

 *

7.1.1 Marking up sections of text

L

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



These include :-

J

"BEGIN/END_CODE"
O "BEGIN/END_CONTENTS"
M "BEGIN/END_DIAGRAM"
G "BEGIN/END_HTML"
K "BEGIN/END_IGNORE"
E "BEGIN/END_PRE"
I "BEGIN/END_TABLE"
9 "SECTION"

l

"BEGIN/END_COMMA_DELIMITED_TABLE"
] "BEGIN/END_DELIMITED_TABLE"


 P

7.1.2 Commands that influence the <HEAD>..</HEAD> of a file

O

Some commands can be used to control the contents of the HTML <HEAD>F section. These attributes are largely non-visual, but may influence; how the document is indexed (e.g. by search engines).



Commands include :-

8

"TITLE"
A "DESCRIPTION"
; "KEYWORDS"
A "STYLE_SHEET"
: "BASEHREF"

~

To fully understand how titles are calculated, see the discussion in 5.6.1


 .

7.1.3 One line pre-processor commands

E

These commands exist on a line by themselves. They either causeG something to be executed at the point they occur, or are used to mark, that location in the file in some way.

The commands include :-

H

"CONTENTS_LIST"
= "HTML_LINE"
9 "INCLUDE"
; "LINERULE"
G "NAVIGATION_BAR"
1 "TOC"


 !

7.1.4 The TABLE commands

G

A large number of delimiters influence the detection, analysis andc generation of tables. These are discussed in the Tag manual in theN The TABLE commands section.

&

The table commands include :-

L

"BEGIN/END_TABLE"

H

"TABLE_BGCOLOR"
C "TABLE_BORDER"
M "TABLE_BORDERCOLOR"
E "TABLE_CAPTION"
M "TABLE_CELLPADDING"
M "TABLE_CELLSPACING"
K "TABLE_CELL_ALIGN"
Q "TABLE_COLO(U)R_ROWS"
Q "TABLE_CONVERT_XREFS"
Y "TABLE_EVEN_ROW_COLO(U)R"
M "TABLE_HEADER_COLS"
M "TABLE_HEADER_ROWS"
Q "TABLE_MAY_BE_SPARSE"
a "TABLE_MIN_COLUMN_SEPARATION"
W "TABLE_ODD_ROW_COLO(U)R"

l

"BEGIN/END_COMMA_DELIMITED_TABLE"
] "BEGIN/END_DELIMITED_TABLE"
A "TABLE_ALIGN"
Q "TABLE_IGNORE_HEADER"
C "TABLE_LAYOUT"


 (

7.1.5 The CHANGE_POLICY command

B

The CHANGE_POLICY command allows policies as described in thea Policy manual. You can read more about this in the Tag ManualR under The CHANGE_POLICY command


 

7.1.6 Block definition

F

The programs allows you to define "blocks" of text that can laterB be inserted or embedded wherever you want in the text. For morev details read the Tag Manual section Definition blocks and variables



Commands include :-

n

"DEFINE/END_BLOCK and RESET_BLOCK"
I "DEFINE_VARIABLE"
A "EMBED_BLOCK"
C "INSERT_BLOCK"

j

"SAVE_CONTEXT...RESTORE_CONTEXT"


 

7.1.7 HTML Fragments

*

New in version 4

F

It is possible to define blocks of HTML that the program will useH instead of the HTML it normally produces in certain circumstances.

K

These blocks of HTML can themselves contain special HTML fragment tags< to allow the HTML to be customized. For example the blockM HORIZONTAL_RULE can be used to replace the <HR> tag produced whereverE lines are detected by a .gif of your choice. If you want this .gifH to adopt suitable length and alignment (to match those in the originalG text) you can use the HTML fragment tags RULEWIDTH and RULEALIGN.

A full description of HTML fragments can be found in the Tag manual.


 

7.2 In-line tags

@

In-line tags are introduced in version 3.2. They allow youD to place special codes in your source text to achieve effects thatH couldn't be done by converting plain text alone. As such they greatlyD enhance AscToHTM's ability to be used as a web authoring tool.


 %

7.2.1 Format of in-line tags

I

In-line tags are an extension of the preprocessor tags introduced inD earlier versions. As the name implies, in-line tags may be placedN "in line" with the source tag, giving greater flexibility for their use.

H

In-line tags are signified by the start and end delimiters "[[" and "]]", for example :-


<

[[HTML_COMMENT this will become an HTML comment]]


M

The whole tag must be contained within a single line of the source file,H that is there cannot be any newline characters in the middle of a tag.G You can have as many tags as you like on any given line, but they may not be nested.

b

In-line tags are fully documented in the Tag manual. A summary[ of some of the in-line tags available is given in 7.2.2.


 &

7.2.2 Summary of in-line tags

B

This is a brief list of the available in-line tags. A fullerd description of using in-line tags is available in the Tag manual



Tags include :-

L

"BR (line break)"
; "COLO(U)R"
E "CONTENTS_LIST"
7 "ENTITY"
3 "FONT"
3 "GOTO"
3 "HTML"
C "HTML_COMMENT"
= "HYPERLINK"
= "LINKPOINT"
7 "SPACES"
Y "NB "non-breaking spaces"
E "SUPER and SUB"
3 "TEXT"
= "TIMESTAMP"

F

"TABLE_LAYOUT"
; "FILENAME"
; "FRACTION"
A "IGNORE_THIS"
; "VARIABLE"
9 "VERSION"


 2


V Previous page $@ Back to Contents List#R Next page 


B& 
Valid HTML 4.0!Converted from 6 a single text file by A AscToHTM
J© 1997-2001 John A Fotheringham