TeXFOTBuilder

# TeXFOTBuilder: a Generic TeX backend for Jade

By David Megginson

Warning: This is an early draft: it is incomplete, and may contain errors. Use at your own risk!

A LaTeX macro package for use with the output of this backend is under development by Sebastian Rahtz. A draft is on CTAN in macros/jadetex.

## Contents

1. Introduction
2. Flow Objects
   - Pseudo Flow Objects
   - Atomic Flow Objects
   - Non-Atomic Flow Objects
   - More Pseudo-Flow Objects: Headers and Footers
3. Characteristics
   - Inherited Characteristics
   - Non-Inherited Characteristics

## Introduction

The TeXFOTBuilder maps DSSSL flow-objects into generic TeX macro calls. Atomic flow objects appear as single `\insertOBJECT{}` macro calls, while non-atomic flow objects appear as nested pairs of `\startOBJECT{}`..`\endOBJECT{}` macro calls.

The `\insertOBJECT` and `\startOBJECT` calls receive a single argument, which is a list of definitions for inherited and non-inherited characteristics (see below). For example, the following DSSSL handler:

    (element P
      (make paragraph
    	start-indent: 6pt))

would generate the following TeX calls:

    \startParagraph{\def\StartIndent{6pt}}%
    CONTENTS
    \endParagraph{}

The output `.tex` file is not ready to be passed directly through TeX or LaTeX -- instead, it will be necessary to create TeX macro definitions for all of the flow-object macros, and to set default values for the characteristics. The macros are free to make use of TeX primitives, plain TeX, LaTeX, or any other format which is convenient.

It is also important to note that any characters with values >255 will appear as `\insertCharacter{SETTINGS}` macro calls, with the actual character value assigned to the `\Ch` characteristic in the SETTINGS argument, ie.

    \insertCharacter{\def\Ch{1024}}

## Flow Objects

### Pseudo Flow Objects

In addition to nearly all of the flow-object classes currently supported by Jade, the TeXFOTBuilder generates two pseudo flow-object macro calls:

- `\startFOT{}`
- `\endFOT{}`

These are guaranteed to appear at the very beginning and very end of the .tex output file, and give your macros a chance to grab control at both points. They never receive arguments, but will always be printed out with the empty braces.

### Atomic Flow Objects

You will need to define the following macros for atomic flow-object classes:

- `\insertCharacter{SETTINGS}`
- `\insertAlignmentPoint{SETTINGS}`
- `\insertExternalGraphic{SETTINGS}`
- `\insertPageNumber{SETTINGS}`
- `\insertParagraphBreak{SETTINGS}`
- `\insertRule{SETTINGS}`
- `\insertTableAfterColumnBorder{SETTINGS}`
- `\insertTableAfterRowBorder{SETTINGS}`
- `\insertTableBeforeColumnBorder{SETTINGS}`
- `\insertTableBeforeRowBorder{SETTINGS}`
- `\insertTableCellAfterColumnBorder{SETTINGS}`
- `\insertTableCellAfterRowBorder{SETTINGS}`
- `\insertTableCellBeforeColumnBorder{SETTINGS}`
- `\insertTableCellBeforeRowBorder{SETTINGS}`
- `\insertTableColumn{SETTINGS}`

### Non-Atomic Flow Objects

You will need to defined the following TeX macros for non-atomic flow-object classes:

- `\startBox{SETTINGS}`
- `\endBox{SETTINGS}`
- `\startDisplayGroup{SETTINGS}`
- `\endDisplayGroup{SETTINGS}`
- `\startFraction{SETTINGS}` [not currently implemented]
- `\endFraction{SETTINGS}` [not currently implemented]
- `\startLeader{SETTINGS}`
- `\endLeader{SETTINGS}`
- `\startLineField{SETTINGS}`
- `\endLineField{SETTINGS}`
- `\startLink{SETTINGS}`
- `\endLink{SETTINGS}`
- `\startMarginalia{SETTINGS}`
- `\endMarginalia{SETTINGS}`
- `\startParagraph{SETTINGS}`
- `\endParagraph{SETTINGS}`
- `\startScore{SETTINGS}`
- `\endScore{SETTINGS}`
- `\startScroll{SETTINGS}`
- `\endScroll{SETTINGS}`
- `\startSequence{SETTINGS}`
- `\endSequence{SETTINGS}`
- `\startSideLine{SETTINGS}`
- `\endSideLine{SETTINGS}`
- `\startSimplePageSequence{SETTINGS}`
- `\endSimplePageSequence{SETTINGS}`
- `\startTable{SETTINGS}`
- `\endTable{SETTINGS}`
- `\startTableCell{SETTINGS}`
- `\endTableCell{SETTINGS}`
- `\startTablePart{SETTINGS}`
- `\endTablePart{SETTINGS}`
- `\startTableRow{SETTINGS}`
- `\endTableRow{SETTINGS}`

### More Pseudo Flow Objects: Headers and Footers

Jade treats simple-page-sequence headers and footers as if they were separate flow objects, but since they can have no proper characteristics, TeXFOTBuilder implements them as simple macro calls -- in this case, however, the argument will be the flow objects making up the header, rather than a series of \def statements.

- `\SimplePageSequenceCenterFooter{CONTENTS}`
- `\SimplePageSequenceCenterHeader{CONTENTS}`
- `\SimplePageSequenceLeftFooter{CONTENTS}`
- `\SimplePageSequenceLeftHeader{CONTENTS}`
- `\SimplePageSequenceRightFooter{CONTENTS}`
- `\SimplePageSequenceRightHeader{CONTENTS}`

## Characteristics

The SETTINGS argument to the flow-object macros will contain a series of \def statements for both inherited and non-inherited characteristics. These will appear only when the characteristic's value differs from the standard default (in the case of non-inherited characteristics) or from the current value (in the case of inherited characteristics). Since these statements appear as an argument, they will not take effect until you reference the parameter explicitly.

### Inherited Characteristics

The characteristics in the following table are inherited -- you should set these to their default values only once, at the beginning of the parse (but they should always revert to their previous values after a flow-object has finished):

Characteristic | Default Value | DSSSL Equivalent | Used By
--- | --- | --- | ---
`\AsisWrapIndent` | `0 [#f]` | ``
`\BackgroundColor` | `0 [#f]` | ``
`\BackgroundLayer` | `-1` | ``
`\BackgroundTile` | `0 [#f]` | ``
`\BorderAlignment` | `center` | ``
`\BorderOmitAtBreak` | `0 [#f]` | ``
`\BorderPresent` | `1 [true]` | ``
`\BorderPriority` | `0` | ``
`\BottomMargin` | `0pt` | ``
`\BoxBorderAlignment` | `outside` | ``
`\BoxCornerRadius` | `0pt` | [note]
`\BoxOpenEnd` | `0 [#f]` | ``
`\BoxSizeAfter` | `4pt` | ``
`\BoxSizeBefore` | `8pt` | ``
`\BoxType` | `border` | ``
`\CellAfterColumnMargin` | `0pt` | ``
`\CellAfterRowMargin` | `0pt` | ``
`\CellBackground` | `0 [#f]` | ``
`\CellBeforeColumnMargin` | `0pt` | ``
`\CellBeforeRowMargin` | `0pt` | ``
`\CellCrossed` | `0 [#f]` | ``
`\CellRowAlignment` | `start` | ``
`\Color` | current gray | ``
`\Country` | `0 [#f]` | ``
`\DisplayAlignment` | `start` | ``
`\EndIndent` | `0pt` | ``
`\EndMargin` | `0pt` | ``
`\ExpandTabs` | `8` | ``
`\FieldAlign` | `start` | ``
`\FieldWidth` | `0pt` | ``
`\FillingDirection` | `top-to-bottom` | ``
`\FirstLineStartIndent` | `0pt` | ``
`\FloatOutLineNumbers` | `0 [#f]` | ``
`\FloatOutMarginalia` | `0 [#f]` | ``
`\FloatOutSidelines` | `0 [#f]` | ``
`\FontFamilyName` | `iso-serif` | ``
`\FontName` | `0 [#f]` | ``
`\FontPosture` | `upright` | ``
`\FontProportionateWidth` | `medium` | ``
`\FontSize` | `10pt` | ``
`\FontStructure` | `solid` | ``
`\FontWeight` | `medium` | ``
`\FooterMargin` | `0pt` | ``
`\GlyphAlignmentMode` | `font` | ``
`\GlyphReorderMethod` | `??` | ``
`\GlyphSubstMethod` | `??` | ``
`\HangingPunct` | `0 [#f]` | ``
`\HeaderMargin` | `0pt` | ``
`\Hyphenate` | `??` | ``
`\HyphenationKeep` | `0 [#f]` | ``
`\HyphenationLadderCount` | `0 [#f]` | ``
`\HyphenationMethod` | `??` | ``
`\HyphenationPushCharCount` | `2` | ``
`\HyphenationRemainCharCount` | `2` | ``
`\IgnoreRecordEnd` | `0 [#f]` | ``
`\ImplicitBidiMethod` | `0 [#f]` | ``
`\InhibitLineBreaks` | `0 [#f]` | ``
`\InputWhitespaceTreatment` | `??` | ``
`\JustifyGlyphSpaceMaxAdd` | `0pt` | ``
`\JustifyGlyphSpaceMaxRemove` | `0pt` | ``
`\Kern` | `??` | ``
`\KernMode` | `??` | ``
`\Language` | `0 [#f]` | ``
`\LastLineEndIndent` | `0pt` | ``
`\LastLineJustifyLimit` | `0pt` | ``
`\LastLineQuadding` | `relative` | ``
`\Layer` | `0` | ``
`\LeftMargin` | `0pt` | ``
`\Ligature` | `??` | ``
`\LineBreakingMethod` | `0 [#f]` | ``
`\LineCap` | `butt` | ``
`\LineCompositionMethod` | `0 [#f]` | ``
`\LineJoin` | `miter` | ``
`\LineNumberSep` | `??` | ``
`\LineNumberSide` | `??` | ``
`\LineRepeat` | `1` | ``
`\LineSep` | `1pt` | ``
`\LineSpacing` | `12pt` | ``
`\LineThickness` | `1pt` | ``
`\Lines` | `wrap` | ``
`\MarginaliaKeepWithPrevious` | `0 [#f]` | ``
`\MarginaliaSep` | `0pt` | ``
`\MarginaliaSide` | `start` | ``
`\MathDisplayMode` | `??` | ``
`\MinLeaderRepeat` | `1` | ``
`\NColumnsSpanned` | `1` | ``
`\NRowsSpanned` | `1` | ``
`\NumberedLines` | `1 [true]` | ``
`\OrphanCount` | `2` | ``
`\PageHeight` | sysdep | ``
`\PageWidth` | sysdep | ``
`\PositionPointShift` | `0pt` | ``
`\PrincipalModeSimultaneous` | `0 [#f]` | ``
`\Quadding` | `start` | ``
`\RightMargin` | `0pt` | ``
`\ScoreSpaces` | `1 [true]` | ``
`\SidelineSep` | required | ``
`\SidelineSide` | required | ``
`\Span` | `1` | ``
`\SpanWeak` | `0 [#f]` | ``
`\StartIndent` | `0pt` | ``
`\StartMargin` | `0pt` | ``
`\TableAutoWidthMethod` | `0 [#f]` | ``
`\TableCornerRadius` | `0pt` | [note]
`\TablePartOmitMiddleFooter` | `0 [#f]` | ``
`\TablePartOmitMiddleHeader` | `0 [#f]` | ``
`\TopMargin` | `0pt` | ``
`\WidowCount` | `2` | ``
`\WritingMode` | `left-to-right` | ``

#### Notes

1. `\BoxCornerRadius` combines the `box-corner-rounded` and `box-corner-radius` characteristics (its value is `0pt` if box-corner-rounded is `#f`).
2. `\TableCornerRadius` combines the `table-corner-rounded` and `table-corner-radius` characteristics (its value is `0pt` if `table-corner-rounded` is `#f`).

### Non-Inherited Characteristics

The characteristics in the following table are not inherited -- you should set these to their default values at the beginning of every relevant flow-object, before evaluating the SETTINGS argument:

Characteristic | Default Value | DSSSL Equivalent | Used By
--- | --- | --- | ---
`\AlignLeader` | `1 [true]` | ``
`\BreakAfter` | `0 [#f]` | ``
`\BreakAfterPriority` | `0` | ``
`\BreakBefore` | `0 [#f]` | ``
`\BreakBeforePriority` | `0` | ``
`\Ch` | no default | ``
`\CoalesceId` | `0 [#f]` | ``
`\ColumnIndex` | contextual | `column-number [??]` | ``
`\EntitySystemId` | required | ``
`\EscapementDirection` | `` | `writing-mode`
`\GlyphId` | no default | ``
`\IdrefAddress` | `??` | ``
`\IsDisplay` | `0 [#f]` | ``
`\IsDropAfterLineBreak` | unspecified | ``
`\IsDropUnlessBeforeLineBreak` | unspecified | ``
`\IsPunct` | unspecified | ``
`\IsInputTab` | unspecified | ``
`\IsInputWhiteSpace` | unspecified | ``
`\IsRecordEnd` | unspecified | ``
`\IsSpace` | unspecified | ``
`\Keep` | `0 [#f]` | ``
`\KeepWithNext` | `0 [#f]` | ``
`\KeepWithPrevious` | `0 [#f]` | ``
`\Length` | context | ``
`\MathClass` | unspecified | ``
`\MathFontPosture` | unspecified | ``
`\MaxHeight` | contextual | ``
`\MaxWidth` | contextual | ``
`\MayViolateKeepAfter` | `0 [#f]` | ``
`\MayViolateKeepBefore` | `0 [#f]` | ``
`\NotationSystemId` | required | ``
`\Orientation` | required | ``
`\PositionPointX` | `??` | ``
`\PositionPointY` | `??` | ``
`\PositionPreference` | `0 [#f]` | `position-preference`
`\ScaleType` | `maxuniform` | `scale` [note]
`\ScaleX` | n/a | `scale` [note] | ``
`\ScaleY` | n/a | `scale` [note]
`\ScoreLength` | `??` | ``
`\ScoreType` | required | `type`
`\Script` | unspecified | ``
`\SpaceAfterConditional` | `0 [#f]` | `space-after`
`\SpaceAfterForce` | `0 [#f]` | `space-after`
`\SpaceAfterMax` | `0pt` | `space-after`
`\SpaceAfterMaxFactor` | `0` | `space-after`
`\SpaceAfterMin` | `0pt` | `space-after`
`\SpaceAfterMinFactor` | `0` | `space-after`
`\SpaceAfterNominal` | `0pt` | `space-after`
`\SpaceAfterNominalFactor` | `0` | `space-after`
`\SpaceAfterPriority` | `0` | `space-after`
`\SpaceBeforeConditional` | `0 [#f]` | `space-before`
`\SpaceBeforeForce` | `0 [#f]` | `space-before`
`\SpaceBeforeMax` | `0pt` | `space-before`
`\SpaceBeforeMaxFactor` | `0` | `space-before`
`\SpaceBeforeMin` | `0pt` | `space-before`
`\SpaceBeforeMinFactor` | `0` | `space-before`
`\SpaceBeforeNominal` | `0pt` | `space-before`
`\SpaceBeforeNominalFactor` | `0` | `space-before`
`\SpaceBeforePriority` | `0` | `space-before`
`\StretchFactor` | `0` | ``
`\TableWidth` | contextual | ``
`\TruncateLeader` | `0 [#f]` | ``
`\Width` | required | [note]

#### Notes

1. `ScaleType`, `ScaleX`, and `ScaleY` are all the equivalent of the `scale` characteristic: if `ScaleType` is `0` [`#f`], then `ScaleX` and `ScaleY` become relevant.
2. The `Width` characteristic is not required if `table-auto-width` feature is present.