Writeup 2.0 Quick Reference Guide

A markup language, similar to Markdown or textile.
A pre-processing language with variables, functions, conditional compilation and includes.
HTML/XML/CSS generation fuctionality for classes, styles and other attributes.

The program is run from the command line using the syntax: writeup [options] sourcefile
- There are many command-line options which are documented with the --help option.

1. General Syntax

A Writeup file is a simple text file.
- (Can be either in ascii or utf-8. Line endings can be unix or dos style.)
The first line of the file is usually a heading or a comment. If so, it will be used to generate the title of the document.
At some point in every file the constant $VER should be set to the version of Writeup that the document was written to.
- (The purpose of this is that if api changes are made in the future, this will “future-proof” your document.)
Each line normally generates a block element, so a paragraph is one long line, (propbably wrapping in your text editor).
Any line can contain a comment using //
- to intentionally put // in a line, use the $SLASHES constant
All white space is stripped from the end of lines
A line may be continued (joined with the following line) by ending it with a \
If the document is stored in a version control system, such as Subversion, then if a line such as:
$ID=$Id: quickref.txt 359 2012-02-11 04:35:43Z andrewfn $

is inserted near the top of the document, it will allow Writeup to extract version control metadata for use in the document.
Tabs are treated as a single white space

2. Command Line Options

This is the output from the --help option

writeup: allows complex HTML documents to be generated from plain text files
usage: writeup [options] [-o <outfile>] <infile>
  options: -h|?|--help --usage --version -v[v]|--verbose|-q[q]|--quiet --debug
-b    --body       body only (no headers)
      --debug      same as -vvvvv
-f    --for        <outputtype> set the $FOR variable, e.g. -f web
-h    --help       display help
-I    --noinclude  no includes allowed in body (for security)
-m    --macro      macro processor only (test)
-o    --output     <outfile> output to outfile rather than infile.html
-q[q] --quiet      quiet   (-qq very quiet)
-r    --stdout     redirect output to stdout
-s[s] --set        <set> set a variable e.g. -s test=true
      --usage      summary of usage
-v[v] --verbose    verbose (-vv very verbose)
-V    --version    version string
      --versionnum version number
-x    --extract    <varname> extract varible to stdout or to file if -o defined
-X    --export     <[$]pattern> export variables in bash or Writeup format
-y    --yes        answer Yes to any keyboard prompts
Version:  1.93.00 (2012-02-11) by Andrew M Fountain, http://writeup.org
Copyright (c) Andrew M. Fountain, 2012 GPLv3

3. Markup Language

3.1 Inline Character Markup

Note that the effect of each markup is completely redefinable

Emphasize/italic:	`_underscore_ defaults to em (italic) unless alphanumeric_both2_sides`	underscore defaults to em (italic) unless alphanumeric_both2_sides
Bold/strong:	`asterisks default to strong (bold) text`	asterisks default to strong (bold) text
Smart quotes can be supressed using `$smartquotes` variable:	`'single, "double" <<angle>> & apostrophe's glyph`	‘single, “double” «angle» & apostrophe’s glyph
long dash:	`em--dash or en -- dash if a space both sides`	em—dash or en – dash if a space both sides
Three ways of getting a non-break space:	`Non-break space: (\/), ($SP) or ( )`	Non-break space: ( ), ( ) or ( )

3.1.1 Links and Images

Hyperlinks (think of the `^` arrow pointing to the link):	`No link text <^http://writeup.org^> or <^http://writeup.org^with linking text^>`	No link text writeup.org or with linking text
The value of `$hrefbase` is prepended to the link unless it starts with a scheme, e.g. `http://`:	`$set $hrefbase=http://drup.org <^/mypage^> or <^http://writeup.org/mypage^>`	/mypage or writeup.org/mypage
This effect may be supressed by putting a `:` at the start of the uri:	`<^:/mypage^> instead of <^/mypage^>`	/mypage instead of /mypage
Images (think of the `#` being a tiny picture frame):	`No alt/title text <#writeup32.png#> or with alt and title text <#writeup32.png#Writeup logo#>`	No alt/title text or with alt and title text
Same for images, but use `$imgbase`:	`$set $imgbase=writeup <#32.png#>`

3.1.2 Special Characters

Will use literal character entities for < > & unless part of html structure:	`< > and & but <u>tag</u> and ● and ®.`	< > and & but tag and ● and ®.
utf-8 characters and named/numbered entities can simply be inserted:	`UTF8: ⅞ Named entity: £ Numbered: £`	UTF8: ⅞ Named entity: £ Numbered: £

3.1.3 Escape sequences

Characters can be forced to be literal with ‘\’:	`\\ \< \> \& \* \$`	\ < > & * $
Hexadecimal unicode or byte characters:	`Unicode: \u25CF Hex: (\x7E)`	Unicode: ● Hex: (~)

3.1.4 Pre-defined symbols

Although these are considered constants, they can be re-assigned to a new value if necessary, e.g. a different asterisk character could be used or it could be wrapped in a span

Named character constants:	`$CENT $POUND $EURO $YEN $COPYRIGHT`	¢ £ € ¥ ©
Fractions:	$QUARTER $HALF $THREEQUARTERS↵ $THIRD $TWOTHIRDS	¼ ½ ¾ ⅓ ⅔
Punctuation:	$MDASH $NDASH↵ $LSQUO $RSQUO $LDQUO $RDQUO $LAQUO $RAQUO	— – ‘ ’ “ ” « »
Dots:	`$DOT $BULL $BULLET $ELIP`	· • ● …
Misc (note `$SLASH == \x2F`):	`$LT $GT $AMP $QUOT $APOS $SLASH $SLASHES`	< > & " ' / /
Others:	$ASTERISK $UNDERSCORE $UNDERLINE↵ $ATSYMBOL $CIRCUMFLEX $PERCENT $HASH $DOLLAR	* _ _ @ ^ % # $
Spaces:	non-break:($SP) em:($EMSP)↵ regular space: ($SPACE) null: ($NULL)↵ force space:(\ )	non-break:( ) em:( ) regular space: ( ) null: () force space:( )

3.2 Line Breaks

Unless within a table (see below), a vertical bar | is identical to starting a new line
- This is for convenience when it is easier to combine several lines together e.g. $if $test|*testing*|$endif
To get a vertical bar, use the $VB constant
To generate a newline within a function, use $VB or \n
To end a line with an HTML break <br />, simply end it with /
- Alternatively the $BR constant can be used
A line that begins with just two minus signs -- will create a horizontal rule <hr />

If it begins with three --- then it will cause a page break. (This is accomplished by adding the css contained in the variable $pagebreakstyle (see below) to the subsequent block tag.

3.3 Block Markup

Heading tags 1—6 are supported:	...Heading level 3 (h3 tag)↵ .....Heading level 5 (h5 tag)↵ ......Heading level 6 (h6 tag)	Heading level 3 (h3 tag) Heading level 5 (h5 tag) Heading level 6 (h6 tag)
Ordered lists:	1. Can use a number↵ #. or default numbering↵ 5. New numbering sequence↵ A. indent to start nested list↵ #. and so on↵ i. upper or lower case or roman numerals↵ ii. Any depth of list supported↵ #. Indent one space per level of nesting↵ #. Back to top level	Can use a number or default numbering New numbering sequence indent to start nested list and so on upper or lower case or roman numerals Any depth of list supported Indent one space per level of nesting Back to top level
Unordered lists:	-Simply use minus sign↵ -and indentations↵ a. Can be mixed with ordered lists↵ b. to any depth↵ -third level↵ -and again	Simply use minus sign and indentations Can be mixed with ordered lists to any depth third level and again
Lists extras:	-A blank line before a list item puts the "firstline" class on it:↵ ↵ -CSS can then be use to create extra space↵ A third kind of list is the "simple list"↵ This is simply done with indentation↵ and works as expected.↵ -It can also be used to add extra paragraphs↵ to one of the other lists↵ -Sometimes a list level needs to be forcibly ended, and this can be done with a minus exclamation mark:↵ -!	A blank line before a list item puts the “firstline” class on it: CSS can then be use to create extra space A third kind of list is the “simple list” This is simply done with indentation and works as expected. It can also be used to add extra paragraphs to one of the other lists Sometimes a list level needs to be forcibly ended, and this can be done with a minus exclamation mark:

3.3.1 Tables

Tables are started and ended with four hyphens:

----↵
| table cell | table cell |↵
| table cell | table cell |↵
----↵

table cell	table cell
table cell	table cell

The top cells can be headings by adding a “t”:

----t↵
| table head | table head |↵
| table cell | table cell |↵
----↵

table head	table head
table cell	table cell

The left by adding “l”, or both with “tl”:

----tl↵
| table head | table head | table head |↵
| table head | table cell | table cell |↵
----↵

table head	table head	table head
table head	table cell	table cell

Tables can also be created using a line (or multiple lines) per cell.

A | at the end of the line ends the current cell.
Two |‘s (||) at the end will end the row.
Also, a | at the start of a line will force a new row to start (and end any previous row).:

----t↵
every line↵
is in a cell↵
till a line↵
ending in a bar |↵
Then the next↵
cell starts|↵
and↵
a third|↵
| a bar↵
at the start| ↵
starts|↵
a row |↵
| another way↵
to start a row|↵
is to end↵
the previous row|↵
with two bars||↵
so no bar| is needed | at the start↵
----↵

every line

is in a cell

till a line

ending in a bar

Then the next

cell starts

and

a third

a bar

at the start

starts

a row

another way

to start a row

is to end

the previous row

with two bars

so no bar

is needed

at the start

3.4 Comments

3.5 Code

4. Text Processing Language

4.1 Basic variable assignment and function definition

A variable/function name consists of a $ followed by one or more alphanumeric/underscore characters.
If the first non-white-space character on a line is a valid variable name, immediately followed by = then the remainder of the line is assigned to the variable/function.
- Note that all comments and trailing spaces will have been stripped.
Variables and functions may also be created inline using $set and other functions listed below

4.2 Flow Control

$if <condition>
$else //optional else clause
$endif

There are two other variants:
- $ifdef <variable_name> tests to see if variable is defined
- $ifndef <variable_name> converse of above
No looping is currently provided (although it can be effected using recursion)

4.2.1 Pre-defined constants

Today’s date:	`$TODAY`	2012-02-11
Title of document (usually from first line, or the command line but can be assigned):	`$TITLE`	Writeup 2.0 Quick Reference Guide
Path of document, filename and filename with no extension:	`$PATH, $FILENAME↵ $FILE`	/home/andrew/code/cpp/writeup/tests/, quickref.txt quickref
date and time of last change:	`$DATE -- $TIME`	2012-02-10 – 11:35PM
Version of Writeup:	`$VERSION`	1.93
Version string including date:	`$VERSTRING`	1.93.00 (2012-02-11)
Environment - Linux, Windows or MacOS:	$OS	Linux

4.3 Pre-defined variables

Description	Variable	Default Value
Value prepended to all href urls (unless starts with scheme, e.g. `http://` or “`:`” ):	`$hrefbase`
Value prepended to all img src urls (unless starts with scheme, e.g. `http://` or “`:`” ):	`$imgbase`
Doctype at top of document:	`$doctype`	`<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">`
Style tag inserted into body (not header) of document, e.g. for email:	`$bodystyle`
Delimiter used for `$explode` function (default to space):	`($explodedelim)`	`( )`
Delimiter used for `$implode` function (default to space):	`($implodedelim)`	`( )`
Replacement character used by `$replacetext` function:	`$replacechar`	`=`
Replacement character used by `$replacespaces` function (default to space):	`$replacespacechar`	`_`
Default date format used by `$fmtdate` function:	`$dateformat`	`%b %e`
Default newline representation in documentation `\n` character:	`$docNL`	`<span class="docNL">↵</span>`
The character produced from an escaped space `\` :	`($escspace)`	( )
If set, undefined variables are replaced with this value :	`$set $defaultval=D ($newvar) $unset $defaultval`	(D)
Default attributes for `<style>` tags in header:	`$style_attr`	`type="text/css"`
Default attributes for `<script>` tags in header:	`$script_attr`	`type="text/javascript"`
Default `<style>` tag for page:	`$style`	`table.borders {border-width: 2px; border-spacing:2px; border-style: outset; border-color: gray;} table.borders th, table.borders td {border-width:1px; padding:1px 5px; border-style:inset; vertical-align:top;} table.borders th {background-color:#DDD;} table.borders tbody th {text-align:left;} table.borders p, table.borders ul, table.borders ol {margin-top:0; margin-bottom:0;} h1 {color: darkblue; border-bottom:solid windowtext 1.0pt; padding:0in 0in 1.0pt 0in}`
Default CSS to create a page break:	`$pagebreakstyle`	`page-break-before:always; margin:0;`
If this is set, it’s contents are appended to the document:	`Default: ($postamble)`	Default: ()
Author (must be set by user):	$author (=default value if not set)	unknown author (=default value if not set)

4.4 Switches

Description Variable Effect

$smartquotes If FALSE, smart quote conversion disabled (and also double hyphen)

Default to TRUE:

'single'--"double" -- <<angle>> $set $smartquotes=FALSE 'single'--"double" -- <<angle>> $set $smartquotes=TRUE

‘single’—“double” – «angle» 'single'--"double" -- <<angle>>

$tableclasses If TRUE then automatic classes are set on all <tr>, <th> & <td> tags in tables.

Default to FALSE:

----t↵
$set $tableclasses=TRUE ↵
| tr.row1 th.col1 | tr.row1 th.col2 |↵
| tr.row2 td.col1 | tr.row2 td.col2 |↵
----↵

tr.row1 th.col1	tr.row1 th.col2
tr.row2 td.col1	tr.row2 td.col2

$listclasses If TRUE then automatic classes are set on all <ol>, <ul>, <li> & <div> tags in lists.