jst(9)

SYNOPSIS

jst - JASSPA Structured Text

FILES

hkjst.emf - Jasspa structured text file hook definition.

DESCRIPTION

JASSPA Structured Text (jst) is an ASCII text format which includes some reserved text constructs that allow quite complex word processor type documents to be constructed with the minimal amount of additional annotation and which remains readable in its raw ASCII form. The motivation for doing this is to quickly construct documents and notes for publication whilst editing within MicroEmacs.

JST is a richer mark-up than the simpler doc(9) file type.

The main requirements of JST are:

• Easy to remember.
• Easily readable and can be highlighted well in MicroEmacs.
• Well defined, i.e. not ambiguous so formating errors can be generated.
• Extendable.
• May be automatically reformatted.
• Handle things like figure references and internal anchor and references.
• Html and LaTeX output, possibly rtf and text.

The syntax definition used by JST is defined in the next section.

The JST template extensions include a number of converters that will syntax check the text and then format and export the text to a new presentation format that may be imported into a word processor or used directly in the generated form.

BASIC SYNTAX

The syntax of JST reserves basic character sequences which may be unambiguously interpreted into document styling. The basic syntax set allows a simple formatted document to be produced with the minimal amount of work from the author.

JST supports more advanced extensions which allow tables and hypertext tags to be defined, these are discussed in the Advanced Syntax section later.

Quoting

To ensure that all characters may be input as typed then there is no single escape character. The character sequence &[<char>] may be used to escape a character <char>. Our experience is that escaping is not usually necessary.

Basic Styling

The basic character styling is performed with a pair of escape characters at the start and end of a string sequence. The style end token does not have to appear on the same line as the start token and an error is reported if the sequence is not closed properly. Composite styles may be built buy combining the different tokens by inclusion of a new style within another style block. Where styles are nested then they should be closed in the reverse order that they were opened.

""Raw Text""


A pair of double quotes surrounding a text block is treated as verbatim and is not subject to escaping, that is the character format characters are not translated.

**Bold Text**


A pair of star characters denote a emboldened text region.

//Italic Text//


A forward slash pair denotes an italic text region.

__Underline Text__


A underscore pair denotes an underlined region.

@@Mono Text@@


A pair of at symbols denotes a fixed text region rendered in a fixed width font.

``Superscript Text``


A pair of grave accents denotes superscript text region.

,,Subscript Text,,


A pair of commas denotes a subscript text region.

Styles may be nested i.e. //Italic **Bold Italic** Italic Again// To get raw text with a double quote use: ""raw with a &["]" in it""

Styling Paragraphs and Blocks

Blocks of text may be demarked by a single token at the start of the line. A exclamation mark '!' at the start of a paragraph may be followed by one or more style letters to enable the style for the paragraph, for consistency with the in-line tokens then double characters may be used.

!* As an example this baragraph is bold as it started with a '!*'. 

produces

As an example this baragraph is bold as it started with a '!*'.

The exclamation mark may be followed by multiple different styles which are applied together. e.g.

!"@ This paragraph  started with '!"@' so it is quoted and mono-spaced 
style, i.e. @@, "" or ** is ignored. 

You can enable a style over a block of text by using a '!' style definition with no further text to the right. The block is terminated by a '!end!' or '>end>' tag on its own line. It is recommended that you insert a blank line before and after the '!end!' definition so that it does not affect the filling of the following paragraph.

!end! 

Paragraphs may be associated with a literal block of text from a different programming language. These are introduced with a '>type>' tag and end with a '>end>' tag. The tag types that are currently supported include:

emf    - JASSPA MicroEmacs Macro file.
pseudo - Pseudo code block.
bnf    - BNF block.
c      - ANSI C code block.
cpp    - C++ code block.
perl   - Perl code block.
tcl    - TCL code block.
shell  - UNIX shell block.
java   - Java code block.
ini    - MS-DOS/Windows .ini code block
php    - PHP code block.
make   - Makefile fragment.

The aforementioned blocks support syntax language highlighting and indentation. As an example:

    Some example 'C' code: 
    >c> 
    /* This is C code */ 
    int main (int argc, char *argv[]) 
    { 
        printf ("Hello World\n"); 
        return 0; 
    } 
    >end> 

Justification of Paragraphs and Blocks

A paragraph is a block of text delimited by an empty line, by default all paragraphs are left justified. Where the layout of the paragraph is literal and should not be re-formatted then the paragraph should be proceeded by a '>' symbol e.g.

> This paragraph will not be reformatted 
because it starts with a '>', the 
output will respect the position of the new lines. 

Paragraphs may be center justified with a leading '>c' e.g.

>c This is centered text 

With centered text then the indentation of the '>c' centers the text from the indent position. e.g.

        >c Note the initial indent level is important 
        as the text is 
        centered w.r.t. the remainder. 

Text may be right justified with a leading '>r'.

Indentation

Indentation is implicitly defined by the indentation of the first line of the paragraph, each paragraph is effectively independent with respect to determining the indentation level.

The indentation level is defined to be the the column of the first non-white-space character of the first line divided by the Indent Width (see indent-setup) rounded up. For example this the first non-white of this paragraph is the 'F' at column 4, with an indent width of 4 (the default) this is a an indent level of 1.

A line starting with 6 spaces so it has an indent level of 2 (6/4 == 1.5 which is rounded up to 2). Rounding up allows item lists to work with little effort, without introducing ambiguity, for example.

The indentation of a code fragment or literal text block are determined by the indentation of the initial style tag, for example:

    >"@ 
    >c> 
    int myVariable ; 
    >end> 
>end> 

The code block is indented from the left paragraph by the starting block indent.

Headings

Headings may be defined and commence with a equals ('=') character as the first character of the line. The number of equals determines the heading level.

= Top Level Heading 
== Sub-heading 
=== Sub-sub-heading 

The position of the heading may be controlled and may be left, centered or right justified using l, c or r respectively. Left justified is the default when not defined.

=c Centered Top Level Heading 
==r Right justified sub-heading 

Item Lists

Items lists are bullet or number lists of items which are introduced by a formatChar. to start the list, subsequent list items are introduced with a period '.' character only or optionally with the bullet character. Where formatChar identifies the type of list as follows:

*  - bullet list.
1  - Numeric item list.
a  - Lowercase alphabetic list.
A  - Uppercase alphabetic list.
i  - Roman numeral list.
I  - Upper case Roman numeral list.
:. - Text item list.

Indentation and sub-paragraphs are supported within the paragraph. e.g.

 1. Start or a numbered list. 

    Sub-paragraph of numbered list. 

 2. 2nd item in numbered list 

    *. Contained bullet list. 

     . 2nd item of bullet list. 

 . 3rd item in numbered list. 

The text item, or definition, requires some further explanation. This allows a definition item to be defined (e.g. glossary of terms at start of document or note points within a document). These are defined at column 0 e.g.

:. MyDefinition 

   Description of the term. 

ADVANCED SYNTAX

This section defiens the advanced syntax extensions of JST which allow more complex documents to be generated. These extensions may be used to author more complex documents for export.

Tables

Quite complex tables may be supported through JST. A table is introduced with the closing square brace '] character at the start of the line which define the ghlobal properties and dimensions of the table. Each entry in the table is introduced by '] and is followed by the assigned content.

The initial table definition has the syntax

]crh <# columns> <# rows> 

Where 'c' and 'r' are optional and center or right justify the table, 'h' hides the table lines i.e. no border. The dimensions of the table then follow.

A simple definition of a 3x2 table might be defined as:

] 3 2 

] Row 1 col 1 content. 

] Row 1 col 2 content. 

] Row 1 col 3 content. 

] Row 2 col 1 content. 

] Row 2 col 2 content. 

] Row 2 col 3 content. 

The content may include

*. Use item lists
.  Like this
!c Center text
!r Right justify text
also embedded images, see later.
Columns and rows may be joined both horizontally and vertically by specifying the join in the cell definition. ']>' performs a horizontal cell join of two cells, a single '>' should be added for each additional cell so ']>>' joins 3 cells horizontally. A vertical join is similarly specified with ']v'.

] 3 3 

]>> Single top row with 3 columns joined content. 

]v 2 rows joined in the first column content. 

]> 2nd row 2nd and 3rd column joined content. 

] 3rd row 2nd column content. 

] 3rd row 3rd column content. 

Special Characters and Symbols

Special characters are introduced with '&[special]' and are defined as follows:

&[nl] or &[new-line]


Newline.

&[np] or &[new-page]


New page. This is not supported in HTML or text.

&[nf] or &[new-file]


New file, the effect is dependent on the output format:

html


Starts a new html file, typical use of this is when the first file contains the TOC with links to the subsequent files.

latex


Just starts a new page, i.e. same as [[np]].

rtf


Just starts a new page, i.e. same as [[np]].

text


Ignored.

&[toc]


Inserts an automatically generated table of contents.

---


Inserts a horizontal line. This must be the only text on the line.

Tags and Hyperlinks

Most of the more complex formatting is performed with tags. The general format of a tag is defined as:

&[<tag-id><options> <args>]

If a argument contains a space or a ']' then it must be quoted, e.g.:

&[c this-is-okay] 
&[c "this is okay"] 
&[c "this [\"is\"] okay"] 

A tag may support numerous options, the order of the options is not important but the order of their arguments is as specified in the docs, not the order given with the tag therefore &[idw <image> <depth> <width>] is still &[iwd <image> <depth> <width>]. The text that actually appears in any generated document should not appear in a tag as the spelling check should skip the contents of a tag. This means that a link should take the HTML form of encasing the text label with start and end tags rather than being in the tag itself. One exception would be the setting of a variable.

Comment Tag


Inserts a comment.

&[c <0+args>]

There may be any number of arguments, the whole tag is ignored. As the comment ends with a ']' and ']' char in the comment must be quoted, i.e.:

&[c this is a comment with a "]" "char[23]" in it] 

Anchor Tag


Internal document reference.

&[a <name>]

An anchor tag can be placed anywhere and referenced by a link .

Foreground and Background Color Tag


Modifies the color of the text foreground and background.

&[f <color>] .... &[/f]

Sets the current foreground color where <color> is either a direct HTML format color definition (e.g. "#ff0000" for red) or a previously defined color name.

&[b <color>] .... &[/b]

Sets similarly sets the current background color.

A number of options are supported by the color tag as follows:

&[fs <name> <color>]


Define color '<name>' to be '<color>', the <name> may be references in the f/b color references.

&[fd <color>]


Sets the default foreground color to <color>.

&[bd <color>]


Sets the default background color to <color>.

Link Tag


Link to another part of the document or URL.

&[l <url>] .... &[/l]

Creates a hyperlink with the text with '....' going to the <url>, The format of the url uses the standard HTML syntax, a link starting with a hash '#' is assumed to be local and a warning will be issued if the corresponding anchor point is not found. An error is generated if the &[/l] is missing.

Urls appearing in the text like 'http://www.jasspa.com' are automatically turned into links. To avoid this quote the string, i.e. ""http://www.jasspa.com""

Image Tag


Insert an image in the document.

&[i <image-name>]

Inserts an image <image-name>, for example &[i me.png]

Additional options allow the depth and width of the image to be specified:

&[idw <image-name> <depth> <width>]

Where option d specifies the depth of image and w specifies the width of the image. e.g. &[iw test.jpg 60]. The size is given in pixels and the conversion variable 'image-ppi' is used to convert is a physical paper size. The width may also be specified as a percentage, e.g. 50%.

Use Tag


Insert a file at the current point.
&[u <file-name>]

Inserts <file-name> into the current location and processes it as if part of the original docuement. e.g. &[u insert.jst] inserts the file insert.jst at the current position in the file.

Variable Tag


Insert a variable.

&[v <variable-name>]

Inserts the current value of variable <variable-name>, variable names may only contain alphanumeric characters and '-'.

The variable supports a set of simple options that allow the variable value to be manipulated prior to insertion e.g. for handling numbers etc. The option syntax is defined as follows:

&[vdinrs <variable-name> <value> <increment> <reference-name>]

d


Define the reference <reference-name> for the current value.

i


Pre-increment the variable value by <increment> prior to insertion.

n


Do not insert the variable value.

r


Insert the <reference-name> value.

s


Set the value to <value> first.

As an example, consider the following sequence to implement figure labels and reference them:

&[vsn figure 0] 

&[i figure1.jpg] 
Figure &[vid figure 1 figA] - my first figure 

some more text 

&[i figure2.jpg] 
Figure &[vid figure 1 figB] - my second figure 

To see  **figure &[vr figure  figA]** //my first  figure// and **figure 
&[vr figure figB]** //my second figure//. 

To see  **figure &[vr figure  figA]** //my first  figure// and **figure 
&[vr figure figB]** //my second figure//. 

An undefined variable has a value of "ERROR", it can be defined by using either option 's' or 'i' in which case the value is 0, i.e. the following can be used

= Chapter 1: Will be 1 at the top of the doc

A set of special variables are automatically defined:

title


The document title.

author


The author

image-ppi


Image pixels per inch resolution setting, this is the resolution of the generated document in inches.

Output Dump Tag


Dump output text.

&[o <out-type> <raw-text>]

Dumps <raw-text> into the output if the target output type is <out-type>, where <out-type> can be all, html, latex, rtf and text.

Dump Tag


Dumps the tag for processing.

[d <out-type> <text>]

This command is similar to Output Dump Tag except this is done first so the <text> is processed, this can be used to define output specific formatting, e.g. (note that the \ at the end of the line is used here to show that the content should be placed on a single line).

&[d html "&[vsn large-font-start \"..html def..\"] \ 
          &[vsn large-font-end \"..html def..\"]"] 
&[d latex "&[vsn large-font-start \"..latex def..\"] \ 
           &[vsn large-font-end \"..latex def..\"]"] 
&[d text "&[vsn large-font-start \"\"]&[vsn large-font-end \"\"]"] 

so in the main body of the text:

&[v large-font-start] Large Text &[v large-font-end] 

This is a complex concept and is beyond most users requirements, but making this kind of thing possible means that users should be able to do whatever they need to.

TEMPLATE

The template supports highlighting and indention including commands for exporting JST to another format:

jst-to-htm


Export the JST definition to an HTML file with .htm extension.

jst-to-html


Export the JST definition to an HTML file with .htm extension.

jst-to-rtf


Export the JST definition to an RTF file, for this export then the file name is .rtf but the content is HTML. Word(1) and StarOffice(1) know how to convert this when imported.

jst-to-latex


Convert to a LaTeX file format.

FILES

JST is controlled by the macro files hkjst.emf which contains the basic template. jstutl.emf includes the utilities used for conversion to other formats.

INTERNAL FORMAT

JST uses an internal neutral format which is used in the conversion process, this allows different back end output format drivers to be written against the neutral format without dealing with the input syntax. This intermediate format is not visible to the user and does not exist in the output. The internal format is defined as follows:

\bF?....\bf?


Font style change where ? is B,I,U,M,p,b).

\bDD\bDF<color>\bDB<color>\bdD....\bDd


Foreground or background color change where <color> = hexadecimal value RRGGBB. Note that \bDF<c> or \bDB<c> may be be omitted.

\bIT<image-name>\biT


Insert an image without scaling.

\bIT<image-name>\bID<depth>\biD\bIW<width>\biW\biT


Insert an image with scaling.

\bTA<anchor-name>\btA


A local anchor label.

\bTL<link-url>\btL<link-text>\bTl


URL Link.

\bTV<variable-name>_<variable-ref>\btV


A variable name (temporary).

\bSF


Start new file.

\bSL


Start new line.

\bSP


Start new page.

\bSN


No-text symbol.

\bST


Insert the table of content (temporary)

\bPI


Indent level.

\bPT


Indent tab level (used only in generated TOC).

\bPB....\bpB


Paragraph - justification both.

\bPC....\bpC


Paragraph - justification center.

\bPF....\bpF


Paragraph - File style block.

\bPL....\bpL


Paragraph - justification left.

\bPN....\bpN


Paragraph - justification none.

\bPR....\bpR


Paragraph - justification right.

\bH#....\bh#


Heading, e.g. \bH1....\bh1

\bBI\bB?...\bb?\bB?...\bb?\bbI


Item list start and end tags.

\bBB....\bbB


Bullet item.

\bBN#\bBn....\bbN


Item # in numbered item list.

\bBU#\bBu....\bbU


Item # in uppercase letter item list

\bBL#\bBl....\bbL


Item # in lowercase letter item list.

\bBR#\bBr....\bbR


Item # in uppercase roman numeral item list.

\bBS#\bBs....\bbS


Item # in lowercase roman numeral item list.

\bCT<flags>\bCt<widths>\bct....\bcT


Table - Entire table (contains rows).
<flags> can be any of h, c or r.
<widths> is an ME list |no col|width table|width of col 1|width of col 2|...|

\bCR....\bcR


Table - Row (contains columns)

\bCC....\bcC


Table - column (single cell)

SEE ALSO

doc(9), Supported File Types

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12