This is the user manual (incomplete) for the genetic encoder.
- general information on genetic encoder: a/u/encoder
- user interface
- command-line interface (yet undocumented)
- page daemon in auto-refresh mode,
which is an effective push-button front-end for the encoder
/ this is the primary user interface, at present
- encodes in two passes
1. scans elements in depth-first order,
recognizing 2 basic patterns of candidate element:
[ marginal leaf
/ Encoder.encode_isMarginalLeaf
/ formerly "line leaf"
: any gene with start tag abutted to left margin
: except the document element
- will (when coded) process line breaks/splices/etc. of the element
[ marginal-leaf parent
/ Encoder.encode_isMarginalLeafParent
: any element with bare start tags
: except marked non-genetic
: except a marginal leaf
- element may be converted to a (marginal-leaf parent) gene
- any child line (single lines of content) may be converted to:
| marginal leaf
| single line gene
2. re-scans in any order,
recognizing 1 pattern of candidate element:
/ re-scan may be redundant now, but this may change, so keep it
[ ordinary gene
: any element
: except marked non-genetic
: except a marginal leaf
: except a marginal-leaf parent
/ so a multi-line h1, with co-linear text,
ineligible as marginal (parent or leaf)
- if not a gene, element converted to gene
- this will detail how to convert an ordinary XML document
into a recombinant text, with the aid of the genetic encoder
- for example, to convert this XHTML document:
http://reluk.ca/project/textbender/a/u/encoding/example/conversion-verse-10-br.xht
encoded as example/conversion-verse-10-br.xht_source.txt
to Recombinant XHTML:
http://reluk.ca/project/textbender/a/u/encoding/example/conversion-verse-40.xht.
encoded as example/conversion-verse-40.xht_source.txt
Begin with an XHTML 1.1 document. Depending on the particular coding style, it might look like verse-10-br, or verse-10-pre, or something else.
Ensure each stanza is encoded as a ‘p’ element.
Break stanzas of many lines into shorter logical sections, using ‘div’ elements. There is no fixed upper limit, but four to twenty lines per stanza is nice. Runs of 50 or 100 lines will begin to strain the machine somewhat.
The same goes for contiguous stanzas. If there are long runs of many contiguous stanzas (or of any sibling elements at all) try to reduce the number by dividing them into logical parts or sections, each enclosed in a separate ‘div’ element. And so on, up the hierachy.
Remove line-break formatting from verse lines. For instance, remove any trailing ‘br’ elements. Or, if ‘pre’ elements are used for line formatting, remove or replace them. The genetic encoder will do its own line breaks. It requires only that each line of the verse be encoded as a separate line of the file. For example, see verse-20.
Alter the document type to Recombinant XHTML:
PUBLIC "-//textbender//DTD XHTML recombinant//EN" "xhtml-recombinant.dtd"
Add the following attributes to the ‘html’ element:
xmlns:t="http://reluk.ca/_/name/textbender" t:g="-"
This declares the textbender namespace; and marks the ‘html’ element as non-genetic.
Add the following attribute to the ‘head’ element:
t:g="--"
This marks all head elements as non-genetic, so the genetic encoder will skip them.
Create a wide margin on the left by indenting all body text. This step is optional, needed only if you wish to preserve the indentation profile of the text.
Genetic markup will be added to the left margin, as shown here. If the margin is not wide enough, some of the text will be pushed to the right. Approximately 14-16 columns are needed, depending on DOCTYPE and length. [But standardize it temporarilly, to simplify clipboard transfers. At 20 for marginal leaves, like lines of verse, and other bare text lines. Others, like ‘p’ tags, need only be indented by 1 space or more.]
Use spaces or tabs to create the margin. [But only a tab width of 4 is currently supported.] [No, stick with spaces, per above.]
Add a tail element, to store genetic meta-data. It goes near the end of the document, immediately after the ‘body’ end tag:
<tail xmlns="http://reluk.ca/_/name/textbender" t:document-meta-data="1" t:g="--">
</tail>
| addition of tail can now be automated,
just by running the brancher from the page daemon
- see example/blank-verse.xht
= run the brancher on it, to assign a new revision line ID
/ must there document how, exactly
At this stage, the format of the document should be comparable to verse-20.
= run the genetic encoder on it
/ must say how, exactly
The encoded result will look something like verse-30.
- make final corrections:
| convert to prose format
/ the tool assumes verse,
and encodes each line as a ‘div’
/ prose is not really supported, yet
- if there are prose sections, change their ‘div’ elements
to ‘span’, to restore the natural text flow
- an example of prose format: d/population/index-test/test.xht
| manually convert marginal leaves
- add a textbendermark
- for example:
<div class="signature-block" t:g="--">
textbender_ title or other identifier of this work _mark. <!-- http://reluk.ca/project/textbender/d/population/note.xht#textbendermark -->
</div>
- add script tag for boot.js
- to boot the page daemon
<script src='http://reluk.ca/var/cache/textbender-demo/textbender/a/r/page/boot.js' t:g="-" type='text/javascript'></script>
- etc
The final result looks like verse-40.
- encoder creates both marginal leaf and ordinary genes
- in case it creates the one, where you would prefer the other...
<div t:g="4"> An example of the conversion </div>
<em t:g="3">Of XHTML to Recombinant XHTML.</em>
<div t:g="2"> In this example, the layout is verse-like. </div>
- the second line above would be easier
to edit manually (and have the encoder handle breaks/splices/etc.)
if it were converted to a marginal leaf
| move tag left, to abut margin
<em t:g="3"> Of XHTML to Recombinant XHTML. </em>
- or:
| wrap with new element (start tag in margin),
and move the t:g into it
<div t:g="3"> <em>Of XHTML to Recombinant XHTML.</em> </div>
<div t:g="4"> Here is how to convert a marginal leaf to an ordinary gene. </div>
- you might want to change that to a title
<h2 t:g="4"> Here is How to Convert a Marginal Leaf to an Ordinary Gene. </h2>
- and imagine (this example is contrived) that you want to break it into two lines,
for some reason
<h2 t:g="4"> Here is How to Convert a Marginal Leaf
to an Ordinary Gene. </h2>
/ the browser will still lay it out as a single line, if there is room
- however, this is still a marginal leaf,
and, on the next run of the encoder, it will be broken into two (h2) genes,
which is not what you want; so:
| move tag right, away from margin
<h2 t:g="4">Here is How to Convert a Marginal Leaf
to an Ordinary Gene. </h2>
- now the encoder will leave it alone