>2! 1 : Introduction  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




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


 

1 Introduction

z

JafSoft Limited have produced the following programs


K

These programs share the same text analysis engine, and should do a goodGjob of understanding the structure of the text document and replicatingit in the target format.

O

However frequently users will want to have control over how the output looksFand occasionally the text analysis will go wrong. For that reason thesoftware supports


M

This document describes the tagging system that the software supports.


 *

1.1 Overview of the pre-processor

P

During the analysis process the software reads the source files line-by-line.@The pre-processor recognises special keywords in two ways :-

$

Directives

G

"Directives" consist of a single line in the source file beginning= with the string "$_$_" followed by a recognised keyword and> any additional "attributes" that the directive supports.

&

In-line tags

H

In-line tags, as the name implies, can occur anywhere in the source@ lines. They are enclosed between the special strings "[[" and@ "]]". Between these strings the tag consists of a keyword and, then any attributes that tag supports.

J

In both cases the tag or directive cannot be split over multiple lines,Ithat is directives must be on a line by themselves, and in-line tags must%be wholly contained on a single line.



9Examples of a directive and in-line tags are shown below.

*
      $_$_LINERULE 75%F      The BR tag means this text will be broken [[BR]] into two lines.
1


becomes :-


+

E

The BR tag means this text will be broken
into two lines.




CSome tags can be expressed in either directive or in-line form.


 

1.2 Directives

N

Directives exist on a line by themselves in the source text. They have theform


5

$_$_<keyword> <attribute_list>


N

where the "$_$_<keyword>" must occur at the start of the line and the'<keyword> must be recognised.

Y

If the "$_$_<keyword>" is not at the start of the line, the directive is ignoredGand treated as end-user text. This device has been used to date to aid7conversion of AscToHTM's own documentation to HTML.

P

The format of the <attribute_list> depends on the particular tag, but aCgeneral description is given in 1.4.


 

1.3 In-line tags

U

In-line tags may occur anywhere within end-user text, but not on directiveClines or inside other in-line tags. In-line tags have the form


5

[[<keyword> <attribute_list>]]


W

that is the <keyword> and its <attribute_list> are between "[[" and "]]"Mdelimiters. Initially the start and end delimiters must lie on the same lineof the source text.

\

The <keyword> must be recognised, even if the tag is not yet fully implemented.

@

Note, the delimiters "[[" and "]]" are themselves dynamicallyconfigurable.

P

The format of the <attribute_list> depends on the particular tag, but aCgeneral description is given in 1.4.




1.4 Tag attribute lists

R

The <attribute_list> should be a comma-delimited set of attribute values.QThe number and types of attributes expected will depend on the tag concerned.

K

Some tags allow attributes to be optionally omitted, and a default valueDused instead. If the attribute being omitted is not the last on the7list, then a place-saving comma should be supplied.



Examples


/, -    , )   + 1   * 1   ' 4 
TAG 1,2,3,4
// full list
TAG 1,,3,4
// argument 2 is missing
TAG 1,,3,
// arguments 2 and 4 are missing
TAG 1,,3
// arguments 2 and 4 are missing
TAG 1
// arguments 2, 3 and 4 are missing
6
Y

If a mandatory argument is missing (one for which no default value is.permitted), a TAG_ERROR will be signalled.

T

Each attribute in the list will be of a particular type. Supported types are


K

If a particular attribute value is incorrect for the expected type, then"a TAG_ERROR will be signalled.

I

String attributes should be be placed in quotes if they contain commasMthemselves. It's probably good practice to place them in quotes in any case.=Quotes within string attributes should be doubled up e.g.

8

"This string has the word ""quotes"" in quotes"



becomes

4

This string has the word "quotes" in quotes



Here are some examples


/,  )    +   +    < 
TAG 1,2
 TAG ,2

// arg 1 is '1', arg 2 is '2'
0 // arg 1 is missing, arg 2 is '2'
TAG "one",2
' TAG "say one",2

// arg 1 is 'one', arg 2 is '2'
2 // arg 1 is 'say one', arg 2 is '2'
TAG "a,b", 2
- TAG "say ""one"""", 2

// arg 1 is 'a,b', arg 2 is '2'
4 // arg 1 is 'say "one"', arg 2 is '2'
TAG
 TAG ,
 TAG ,,

// both arguments missing, defaults will be used
: // both arguments missing, defaults will be used
? // both arguments missing, defaults will be used
6


 

1.5 Error handling

 2

1.5.1 Unrecognised and unimplemented tags

M

Unrecognised and unimplemented tags will be signalled via messages. TheseMmessages will be given different severities. The software allows messages toKbe filtered by severity and type, so in this way the testing and production?versions of the software can be made to report differently.


 

1.5.2 Parse errors

Q

All failures to fully parse a tag will be reported. The actual error recoveryI(if any) will vary on a tag-by-tag basis. Usually the tag will simply bePignored, removed from the end-user text and signalled as in error. Occasionally0a certain default behaviour may be possible.

M

For example, a failure to fully parse the attribute list of a LINERULE tagSwould probably default to outputting a simple <HR> into the HTML, rather than-completely ignoring the LINERULE request.


 !

1.6 Tagging restrictions


4

Directives must be on a line by themselves.

B

You can have multiple in-line tags on one line, but no single0 in-line tag may be spread over multiple lines.

 2


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


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