Simbel

This article is a stub. You can help by expanding it.

Simbel
Created by				Alexander Nicholi
Written in				C, C*
OSes				Sirius DOS
ISAs				i286
Licence				ASL 1.1

Simbel is a document generation tool that consumes several categories of input information to create an abstract document tree that can then be rendered logically into various publication mediums including XHTML, HTML5, and PDF (and therefore including print).

Conceptual overview

The central object of Simbel is a schematic which references all of the input in their various forms, including details about their placement, weight, truncation and other context. This schematic can then be rendered into one of several output formats described below, or it may be finalised and compressed as-is in the Abu format for preservation or further processing by other tools. The schematic itself never contains the content, not even text.

Forms of input

Simbel ingests several forms of content input, including:

• Cliffdocs — a terse, source-embedded form of code documentation
• Manual pages, or "manpages" — long-form literature text that explains code in-depth
• Diagrams — flowcharts and other easily vectorised technical graphics that aid explanation
• Photographs — DCT-type raster images for more subjective illustrations
• Hypermedia — not a direct format but a property of the other input formats that is merged and collated

Abstract document model

The abstract document model, or ADM, is the master blueprint of what will ultimately be rendered into the various output formats. It has the following characteristics:

• Content block A and Content block B: Two content columns, each of which are sized to hold 76 glyphs
• Internal links block: A narrow third middle column that gives book—chapter—verse numbers for all of a page's internal references
• External links block: A full-page footer column that contains a page's external references

Here's a shorthand term list for the above:

• Content block A → Block A
• Content block B → Block B
• Internal links block → Block I
• External links block → Block E

Publication coherency

One of the biggest challenges imposed by any publication format that targets several kinds of outputs is maintaining layout coherency of complex elements. For example, there may be some passage of text that uses both blocks A and B. But later on, there is an explanatory graphic, and the editor may want this to take precedence over text and float into block B instead.

Simbel solves this problem intelligently using anchors and weights. Anchors are invisible points within your leading text body that are placed in an editor program, relative to which you can tie another piece of content, such as a graphic. They are also used to place both internal and external references. Every visually active anchor (i.e. all anchors containing content except reference anchors) has a weight associated with it, which is a normalised number in the range $(0,1]$. A weight of $1$ is equivalent to black hole level gravity and will force the anchor's content to be as close to the content in block B as physically possible. The value will compete with the weights of other nearby visually active anchors, so make sure not to put too many highly weighted anchors nearby, as this will destroy the fabric of your document.

Syntax

Here is a work-in-progress example of how an ADM source file could look:

<* this is a comment <* yes it can nest *> *>
<# simbel logic goes here <* comments also work *> #>

<* none of the above RENDERS in any case *>
<* to render literal angle brackets, double them up
 * so "<<" renders as "<" and ">>" renders as ">" *>

<h1:"Corpus" or whole-document level heading:>
<h2:"Book" level heading:>
<h3:"Chapter" level heading:>

<ol:<li:Ordered list item one:>
<li:Ordered list item two
<ol:<li:Ordered sublist item one:>
<li:Ordered sublist item two:>:>:>
<li:Ordered list item three
<ul:<li:Unordered sublist item one
<ol:<li:Ordered sublist within unordered sublist item one:>:>:>:>:>:>
<parbrk><* that is a paragraph break *>
This is a paragraph of normal text. <b:this is bold text.:>
This is still on the same paragraph: <i:italic:>, <u:underlined:>,
<sup:superscript:>, <sub:subscript:>, 

<pgbrk><* that is a page break *>
<col cmyk8(0,1,2,3):this is 8-bit-per-channel CMYK coloured text:>
<* other col functions include cmyk4, cmyk16, rgb5, rgb10, gray8,
 * gray16 and pal *>
<col pal(mypalette, 69):this is palette-coloured text:>
<* "mypalette" identifier must be defined in <# simbel logic #> *>

<anchor id(123) wt(0.1)><* here is anchor #123, with a weight of 0.1 *>
<lnk bcv(1,1,1):link to book 1, chapter 1, verse 1:>

Handling output

Simbel targets the following formats for rasterization of its ADM:

• XHTML 1.0 (for reading on tablets and computers)
  • when rendering with this, dedicated space for blocks I and E are unnecessary, as hyperlinks can be embedded directly
• LaTeX (to be translated into page description formats like PDF)
• Abu format (see below)

Abu format

Simbel will provide a stabilised public ABI via a file format that contains all of the necessary data and metadata for output. This allows others to target new formats using nothing more than the knowledge of this file format, and it also allows dynamic rendering and navigation in the form of editor plugins. Abu also serves as the "intermediate representation" that Simbel uses to instantiate its templates for XHTML, HTML and LaTeX.

Interface

Program name

simbel^Unix SIMBEL.COM^DOS

Verbs

check check a schematic for validation and resource satisfiability

[schematic file] the schematic to check for validity

--verbose, -v be verbose about the checking process

graph graph a schematic's resource dependencies

[schematic file] the schematic to graph

--ascii, -a _optional output in ASCII to stdout (this is the default when no flag is given)

--vector, -v _optional output in vector graphics format to stdout

render render a schematic into a file

[schematic file] the schematic to render from

[output file] the output file to be rendered

--guess, -g _optional guess the output format from the file extension (this is the default when no flag is given)

--xhtml, -x _optional output to XHTML 1.0

--dvi, -d _optional output to DVI

pack pack up a schematic for preservation or transmission

[schematic file] the schematic to pack

[abu archive file] the Abu-compatible archive file to output to

--fat, -f _optional output a fat archive, embedding all resources (this is the default when no flag is given)

--thin, -t _optional output a thin archive, only referencing all resources

--lz4, -l _optional compress the archive with LZ4

--lzip, -L _optional compress the archive with Lzip

--uncompressed, -u _optional do not compress the archive

--normal, -n _optional use normal compression levels with LZ4/Lzip (this is the default when a bare compression flag is given)

--max, -m _optional use maximum compression levels with LZ4/Lzip