NicomDoc 2 Specification

Updated: 2-Mar-2009
John Niclasen, NicomSoft
Email: docs at niclasen dot name


1. Introduction
2. Primary implied paragraph types
2.1 Paragraph
2.2 Space
2.3 Example
3. Styles
3.1 Predefined styles
4. Character Level Commands
4.1 The Escape Character
4.2 Character Level State Changes
4.3 Mail Merge
5. Paragraph Level Commands
5.1 Comment
5.2 Misc
5.3 Blocks
5.4 Table
5.5 Sets
5.6 Includes
5.7 Paragraph Level State Changes
6. Document Level Commands
7. Math
7.1 The Math Dialect
7.2 Inline Math
7.3 Standalone Math
8. Reserved

1. Introduction


NicomDoc version 1 was based on the MakeDoc2 document format from REBOL Technologies.
NicomDoc version 2 is a continuation of the basic ideas from NicomDoc 1 with the addition of mathematical formulas and mail merge among other things.

So far there are output-engines for:

  • HTML
  • Plain text

In the future there might be output-engines for formats like:

  • Adobe PDF (Portable Document Format)
  • Adobe PostScript
  • RTF (Rich Text Format)
  • OpenDocument

It would also be a big benefit, if an input-engine could be made to import RTF documents.

2. Primary implied paragraph types

2.1 Paragraph

A paragraph is some lines of text ended with an extra newline (an empty line).

2.2 Space

Ekstra vertical space can be added by putting more newlines after each other.

2.3 Example

An example is made with just indenting a paragraph, e.g. put a tab in front of every line.

3. Styles

Style commands have to be at the beginning of a line.

3.1 Predefined styles

These are also sections.

-1-         Heading 1
-2- Heading 2
-3- Heading 3
-4- Heading 4

4. Character Level Commands

A character level command can happen anywhere in the text.

4.1 The Escape Character

An escape character is necessary to be able to write any text (also commands as text).

\           Escape next character

The escape character will only be recognized, if the escape mode is on, and it's default off. Use =escape command to set it on.

4.2 Character Level State Changes

A state change will influence the text until another state change of the same type or until end of paragraph.

[reset]             Reset character level state

[b] Bold
[/b] Bold off
[i] Italic
[/i] Italic off
[s] Strike through
[/s] Strike through off
[u] Underline
[/u] Underline off

[sub] Subscript
[/sub] Subscript off
[sup] Superscript
[/sup] Superscript off

[c word! | tuple!] Colour
[/c] Colour off

[font integer! | rm | sf | tt | string!]
Font, an integer! set size,
which should be relative
-4, ... -1, +1, ... +5,
rm = Roman Family font,
sf = Sans Serif Family font,
tt = Typewrite Family font,
string! set font name.
[/font] Font off, return to default

[url (link)] A URL, optional link
if it's different from the text
[/url] URL off

[math] | [m] Enter inline math mode.
(See separate section!)
[/math] | [/m] Leave inline math mode.

In addition these can be used, if =magic is on:

*bold*          The text between * will be bold
~italic~ The text between ~ will be italic
-strike- The text between - will be striked through
_underline_ The text between _ will be underlined

4.3 Mail Merge

To do mail merge, a data file is needed together with the source document. The first line of the data file holds the fieldnames, the next line holds the data. Separator character is semicolon (;). Only one record is computed, so the output is only one document.

[field <name>]      The command is replaced with the
string-value of the field.

5. Paragraph Level Commands

All paragraph level commands have to be at the beginning of a line.

5.1 Comment

A comment is indicated at the beginning of a line.

;           Comment

5.2 Misc

--          A horizontal line,
can have any number of '-' more than one.
=newpage Ends the current page. This has no effect for HTML
and plain text output.

5.3 Blocks

These commands holds a block of text and commands.

=note (title) []        A note, optional title
=table (no-header) [] A table, tables hold rows and cells.
Optional no-header.
=math [] Mathematical formulas.
(See separate section!)

5.4 Table

These commands are to be found inside table blocks.

=cell (rowspan <integer!>) (colspan <integer!>)
(bgcolor <tuple!> | <colorname>)
Table cell
=row New table row
(the first row shouldn't be declared,
as it is implied)

It's also possible to construct a table without the =cell and =row commands. Then each line is a row, and cells are separated by tabs.

5.5 Sets

These commands usually come together in sets.

#           Numbered points
#> Numbered points 2
#>> Numbered points 3

* Bullet points
** | *> Bullet points 2
*** | *>> Bullet points 3

:<define> -<definition> A definition

5.6 Includes

=image (left | center | right) (scale <decimal!>) <file!>
An image, optional "left", "center" and "right"
specify alignment, default is center.
Optional scale specify scaling,
1.0 means scaling 100%.

5.7 Paragraph Level State Changes

=reset              Reset paragraph level state

=center Align center
=left Align left
=right Align right

=inleft (number!) Indent left
=/indent All indent off

=magic Makes it possible to use *bold*, ~italic~,
-strike- and _underline_ notation
=/magic Magic off, back to standard
[b], [i], [s] and [u]

=escape Turn escape mode on.
Makes it possible to use a backslash (\)
to escape characters.
=/escape Turn escape mode off.
Escape mode is off by default.

6. Document Level Commands

=toc (title)            Table Of Contents, optional title

=template (template) A template

### End of Document.
Allow notes, comments to follow.

7. Math

A whole math sub-language has been created with the purpose of producing mathematical formulas. The math is shown in HTML using
jsMath, which can be seen as TEX implemented in JavaScript. So what the math dialect within NicomDoc does, is to convert math input from the user to TEX syntax, which is understood by jsMath.

To be able to see the formulas correctly in the browser, you as a writer need to install jsMath and the jsMath fonts. If you plan to make your writing viewable by others (e.g. on the internet), you need to install jsMath and the image fonts on the server, where your document is located. When a user view a document, jsMath will fall back on image fonts, if the user hasn't installed the TeX fonts.

The default template used in NicomDoc doesn't include jsMath, so it can't be used to produce math output. A template ready to produce math can be found here: default_science.html

Put it in your local template directory and include a =template command in your documents like this:

=template templates/default_science.html

7.1 The Math Dialect

There are lots of commands and symbols included in the math dialect within NicomDoc. The math dialect documentation can be found here:
NicomDoc Math
(The document will load faster, if you install the
TeX fonts for jsMath.)

The source NicomDoc document used to produce that documentation is here: math.txt
It's a good example of a complex NicomDoc document. Especially the math examples in the end might be useful for writers using NicomDoc.

7.2 Inline Math

Math can be mixed with normal text by using the [m] and [/m] tags.

7.3 Standalone Math

Mathematical formulas will be centered on a separate line by using the =math [ ... ] command.

8. Reserved

These commands are reserved for later implementation.

=styledef <style> []    A style definition

-<style>- A style in use

=infirst number! Indent first line
=inright number! Indent right

=tab number! | [] Tabs

=margin [] Margins
=mbottom Margin bottom
=mleft Margin left
=mright Margin right
=mtop Margin top

=options Options, any of toc, nums, indent, no-indent,
no-toc, no-nums, no-template, no-title
=index Index

=header [] Page header
=footer [] Page footer

[footnote] A footnote

NicomDoc - 2-Mar-2009