Writeup 2.75 Full Reference Guide

Last updated on 2016-09-05 at 01:23:45 by Andrew Fountain for version 2.75.02 (2016-09-08)

Table of Contents

1. General Syntax

2. Command Line Options

3. Markup Language

4. Text Processing Language

5. Defining New Keyword Patterns

6. HTML/XML/CSS Attribute Generation

7. Supported features in Github GFM and Markdown

8. Known limitations


Writeup is a tool for generating content. It takes a plain text file and processes it into HTML, XML and/or CSS. It has three components:

  1. A markup language, similar to Markdown or textile.
  2. A pre-processing language with variables, functions, conditional compilation and includes.
  3. 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.

0.1 Philosophy

  • As simple as possible for the end-user to create complex documents. They need know nothing about Writeup
  • The end-user writes semantically and does not have to worry about markup
  • Write once, use everwhere. A single source document can be used for web-pages, slide presentations, printed copy etc.
  • All the complexities of markup are abstracted into functions contained in include files
  • These functions are hidden from the user and are created by Writeup “experts” who have mapped the simple syntax given to end-users into the desired markup for whatever use will be made of the document

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. See File type detection for more details.
  • When the --strict option is set, at some point in the 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 //
    • A valid comment must have whitespace either before or after the //, and not have a : before.
      • e.g. http:// does not count as a comment, nor does path//path/filename.txt
    • To intentionally force // 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: fullref.txt 563 2016-09-05 19:47:25Z 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)
-c[c] --close      close open tags quietly at end of document (-cc not just at end)
      --debug      same as -vvvvv
-f    --for        <outputtype> set the $FOR variable, default -f web
-g    --github     enable Markdown with GitHub enhancements
-h    --help       display help
-I    --noinclude  no includes allowed in body (for security)
-k    --strict     striKt checKing for valid syntax
-o    --output     <outfile> output to outfile rather than infile.html
-m    --markdown   enable Markdown compatibility
-p    --process    language processor only, no html rendering (for testing)
-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:  2.75.02 (2016-09-08) by Andrew M Fountain, http://writeup.org
Copyright (c) Andrew M. Fountain, 2016
  • Note that the values of --body, --process, --markdown and --github, plus the effects of --quiet, --verbose and --debug can be set within the document using variables. See Pre-defined variables for details.

2.1 Examples of Command line options

  • writeup -Iybqq -o myfile-out.html -s include=recipe_inc.txt -s format=Recipe -s VER=2.0 myfile.txt
    • -I No includes allowed in body; -y yes to questions; -b HTML body only; -qq very quiet; -o output file myfile-out.html
    • -s set include file; -s set $format variable; -s set $VER
    • Note that setting VER or --body from the command line has the side-effect of supressing the check for a well-formed title line (to allow for the processing of simple text fragments).

2.2 File type detection

  • A well-formed Writeup main document will usually begin with .Title of Document which will start the document with the title as an h1, and also set the document title tag
    • To start with a lower level h-tag, use more dots, e.g. ..Title of Document for h2
    • To supress a heading tag at the top of the document, use the syntax: //.Title of Document (no spaces at the start)
  • To mark the document as another $TYPE then place the type name between the
    • e.g. if first line begins with //inc.Title of document then $TYPE will be set to inc if an attempt is made to run the file as the main document
    • The main purpose for this type detection is for document management tools
  • If the value of $VER is set from the command line then it will force Writeup to recognize the document as being in Writeup format (to allow, for example, web pages to be processed where $VER is not set, nor is there any top-line title.

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
en dash (medium): range 1--10 or if a space both -- sides. Force with ':-' e.g. May:-June range 1–10 or if a space both – sides. Force with ‘:-’ e.g. May–June
em dash (long): All other cases give em--dash. Using '---' e.g. 1---10 will force em-dash All other cases give em—dash. Using ‘—’ e.g. 1—10 will force em-dash
Two ways of getting a non-break space: Non-break space: ($SP) or (&nbsp;) Non-break space: ( ) or ( )
Hyperlinks: [[http://writeup.org]] no link text, or [[http://writeup.org with linking text]] writeup.org no link text,

or with linking text

Autolinks are turned on by default $autolinks=TRUE.
Delimited by any non-alphanum at start and whitespace at end:
http://gw.ca/link or https://gw.ca/xx or -http://gw.ca/. or (http://gw.ca/), But not xhttp://gw.ca or [[gw.ca within another link http://gw.ca]]. Note that any .,:;) characters at the end of the url will not be included in the link. gw.ca/link or gw.ca/xx or -gw.ca. or (gw.ca), But not xhttp://gw.ca or within another link http://gw.ca. Note that any .,:;) characters at the end of the url will not be included in the link.
Links longer than $autolinkslen are displayed abbreviated…: The link: http://gw.ca/content/long-link.of-meaningless-words is abbreviated. The link: gw.ca/…nk.of-meaningless-words is abbreviated.
Hyperlinks can span multiple lines, if / used to supress paragraph-per-line:
/[[http://gw.ca 
...Linked heading
in multiline link
]]

Linked heading

in multiline link

Mailto links are obfuscated by default to deter spammers. (Turn this off with $emailhide=FALSE: [[mailto:a@gw.ca]] a@gw.ca
MediaWiki style hyperlinks can be achieved by setting [=${LINK} and ]=</a>: MediaWiki style link [http://writeup.org with linking text] MediaWiki style link with linking text
Images: No alt/title text [[writeup32.png]] or with alt and title text [[writeup32.png Writeup logo]] No alt/title text image: writeup32.png or with alt and title text Writeup logo
Autolinks work in exactly the same way with images: Here is an image http://writeup.org/writeup32.png in the text Here is an image image: writeup32.png in the text
To link to an image, override the URL detection by setting $mediatype: $set $mediatype1=link [[writeup32.png This is a link to the image]]. Use image for an image. This is a link to the image. Use image for an image.
Using $hrefroot & $imgroot: See below in URL root and base values to see how url’s can have strings automatically prepended to them.

3.1.2 Special Characters

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

3.1.3 Escaped characters/sequences

Characters can be forced to be literal with ‘\’: \\ \* \$ \_ \a \ * $ _ a
To get $lt; &gt; $amp; &quot; &apos; &nbsp;: \< \> \& \" \' word \/\/word < > & " ' word //word
Special cases for forcing non-escaped characters: \! \n | end-of-line
Hexadecimal single-byte characters or unicode (utf8): Hex: (\x7E) Unicode: \u25CF Hex: (~) Unicode: ●

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) or (\ )
null: ($NULL)
zero width space (for allowing word breaks): ($ZWSP)
Force trailing space with (SPACE) at end of line:(SPACE)

non-break:( )

em:( )

regular space: ( ) or ( )

null: ()

zero width space (for allowing word breaks): (​)

Force trailing space with (SPACE) at end of line:(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 /
  • To insert an HTML break <br />, in the middle use the two characters:/+anywhere/+in the line
    • 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

3.3.1 Headings

  • Note that in some situations a document that is included in another might need all its heading levels adjusted. e.g h1→h2 etc. This can be accomplished by setting $headingbase the base value of heading levels to a value other than 1.
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)
if $headingbase is set, it is modifies the level:
$set $headingbase=3 
.Heading level 3 (using only 1 dot)

Heading level 3 (using only 1 dot)

  • Note that if $autoclose is set to TRUE any open tags are closed at the end of the block with no error messages.

3.3.2 Lists

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
  1. Can use a number
  2. or default numbering
  3. New numbering sequence
    1. indent to start nested list
    2. and so on
      1. upper or lower case or roman numerals
      2. Any depth of list supported
    3. Indent one space per level of nesting
  4. 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
    1. Can be mixed with ordered lists
    2. to any depth
      • third level
      • and again
Plain lists

These are what GML called “simple lists” but the <sl> tag never made it into HTML so we fake it with <ol> and list-style-type:none;.

Set $plainlists FALSE to ignore whitespace at the start of lines.:

Plain list
 Simply indent
  one space per level
  and it works as expected.
 -It can also be used to add extra paragraphs
  to one of the other lists
Turn off plainlists $set $plainlists=FALSE 
   Indent ignored!

Plain list

  • Simply indent
    • one space per level
    • and it works as expected.
    • It can also be used to add extra paragraphs
      to one of the other lists

Turn off plainlists

Indent ignored!

Lists extras:
A blank line before a list item puts the "firstline" class on it:

-CSS can then be used to create extra space etc. e.g.: .firstline {margin-top: 6px;}
 -Sometimes a list level needs to be forcibly ended, and this can be done with a minus exclamation mark:
-!
-New list started

A blank line before a list item puts the “firstline” class on it:

  • CSS can then be used to create extra space etc. e.g.: .firstline {margin-top: 6px;}
    • Sometimes a list level needs to be forcibly ended, and this can be done with a minus exclamation mark:
  • New list started
  • Note: Plain lists are implemented with a <div class="plainlist" style="margin-left:40px;". The inline style is included in case no CSS is set, but can be suppressed using $unset $div_plainlist_style.

3.3.3 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.
  • --cell at the line start creates a new cell.
  • ----row will start a new row.
  • Cell content can be on the same and/or following lines.
  • first ----row in table is optional.:
----t
every line
is in a cell
--cell Then the next cell
--cell and
a third cell
----row A new row
implicitly a new cell
--cell second column
--cell third column
----row
--cell and
--cell one more
--cell row
----

every line

is in a cell

Then the next cell

and

a third cell

A new row

implicitly a new cell

second column

third column

and

one more

row

3.4 Comments

Anything after a // on the line is commented out: Anything after a // on the line is commented out Anything after a
Block /* comments */ work as expected: Anything between /* on the line */ is commented out Anything between is commented out
HTML comments can simply be inserted: <!--Here is an HTML comment.-->
Hard comments will not even appear in the html: The <!!comment!!> will be removed The will be removed
They can also be inserted programmatically: $set $a=<!! $set $b=!!> The $a disappearing $b word The word
Or programmatically comment out the whole line: At the start of a new line, place a $COMMENT and the line is commented out At the start of a new line, place a

3.5 Inline Code and Pre

3.5.1 <code> and <pre>

  • Surrounding inline text with <( and )> will
    • cause all markup to be escaped, e.g. <span>
    • surround the text with <code> ... </code>
  • If the <( )> block surrounds the whole line, or multiple lines, then the <pre> tag will be used, e.g.
<p>this block is <em>all</em> a <pre> tag
and can be multiple lines</p>

3.5.2 Inline code (passed through raw)

  • Surrounding inline text with <` and `> will cause everything inside to go through raw.
    • This is useful for, say, php or javascript code.
  • This can also be used for blocks, as above

3.5.3 Header Tags

By default the document starts with:

Contents-of-$DOCTYPE-variable
<html>
<head>
<style>Contents-of-$style-variable</style>
<title>Contents-of-$TITLE-variable</title>
</head>
<body>

It is possible to redefine <html>, <head> and <body> using tag redefinition so as to create an arbitrary XML document.

  • For example, a kindle .ncx XML document, could be created with the following:
//.NCX index file for kindle book
$copy $doctitle=$TITLE  // Make copy of title before erasing it
$TITLE=                 // Suppress Title tag
$metatag0=              // Supress Generator metatag
$uid=f958ea3c-f687      // Set uid

$html_tag=<ncx>||$html_etag=</ncx>
$body_tag=||$body_etag=
$DOCTYPE=<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"\n   "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
$html_attr=version="2005-1" xml:lang="en-us" xmlns:ns2="http://www.daisy.org/z3986/2005/ncx/"
$metatag=name="dtb:uid" content="$uid"

/<docTitle><text>$doctitle</text></docTitle>

Which would generate the following XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005–1//EN"
   "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<ncx>
<head>
<meta name="dtb:uid" content="f958ea3c-f687" />
</head>
<docTitle><text>NCX index file for kindle book</text></docTitle>
</ncx>

3.6 Easily adding class and id attributes

  • There is a shorthand for generating class and id attributes for tags such as <div> and <span>
    e.g. <div.myclass>, <span.red>, <mark.highlight> will become:
    • <div class="myclass">, <span class="red">, <mark class="highlight">
    e.g. <div#myid>, <span#first>, <mark#pageid> will become:
    • <div id="myid">, <span id="first">, <mark id="pageid">
  • The same syntax can be used when closing a tag, but it is ignored, and only used for documentation purposes
    e.g. </div.myclass></div#myid>, will become: </div></div>
  • Headings can be given id’s by putting #idname immediately following the periods
    e.g. ..#headid, will become: <h2 id="headid">

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.
  • There are three ways of assigning variables: whole line, inline or block
  • Important: whole line and block assignments are “lazy” (the assigned string does not get evaluated until it is used), whereas inline assignment evaluates the string before putting it into the variable.
    • inline assignment can be made lazy by putting the string in quotes. (see example below)

4.1.1 Whole line variable assignment

  • 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. e.g.
    $var1=The contents of variable one // whole line assignment
    $var1+=, and more content is appended to it
    • resulting in: The contents of variable one, and more content is appended to it
    • Note that all comments and trailing spaces will have been stripped except for a trailing SPACE.
  • The main advantage of this method is that the string is only terminated by the end of the line
  • A multiline value can be created using $NL or \n
  • The line may be continued onto multiple lines by placing \ at the end

4.1.2 Inline variable assignment

  • Variables and functions may also be created inline using $set and other functions listed below. e.g.
    $set $var1=newvaluewithnospaces or $set $var1="The contents of variable one"
  • Many functions operate on the varible that was modified in the last $set or $modify function. (See Variable handling for more details) e.g.
    $set $x=$y.plus( 2 ) or $modify($name).concat(" B.Sc.") which is equivalent to:
    $set $x=1 $plus 2 or $modify $name $concat " B.Sc."
  • The expression $set $x=$variable1 will evaluate $variable1 before putting it into $x
  • The expression $set $x="$variable1" will put the literal string $variable1 into $x (i.e. evaluation is lazy).

4.1.3 Inserting the value of variables into the document (i.e. printing)

  • Simply including the variable name, e.g. $var will insert it’s value after evaluating it.
  • Note that when variable evaluation is “lazy” it will not occur until the variable is actually inserted into the document.
  • An exception to this is when an evaluation is forced, explicitly using $eval or $setval, or implicitly when an inline function is used with $set or $modify (see above).
  • Methods (functions that operate on the current variable) can be invoked using “dot-notation”, e.g.:
    $myname.uppercase will invoke the $uppercase function and print the result. These may be cascaded as in:
    $date.monthdate.lowercase
  • When dot-notation used with methods that take parameters, the parameters must be put in parenthesies, e.g.
    $set $name=Peter
    $name.uppercase.concat(" ").repeat(5) PETER PETER PETER PETER PETER
  • User written methods: This can be used with user-written methods which must be declared as such using the $setmethod function.
    Parameter declaration marks the variable as a function, so to override it, $setmethod must be after $parameters, e.g.
  $parameters $welcome greeting degree     // specify two parameters: greeting & degree
  $setmethod $welcome
  $welcome=\                               // method to add greeting and degree to the current result
    $copy $old_result=$result\
    $set $result="$greeting $old_result $degree!"

  $name=Martin Smith                       // put a value into the name variable
  $name.welcome(Hi "B.Sc. Ph.D.")          // run the method
  $name.welcome(Hello junior)
  • Hi Martin Smith B.Sc. Ph.D.!
  • Hello Martin Smith junior!
  • dot-notation can also be used on immediate values (as opposed to variables) by using $mkvar, e.g.
    There are $mkvar(60).mult(60).mult(24) seconds in a day.
    There are 86400 seconds in a day.

4.1.4 Block variable assignment

  • Variables and function may be multi-line using the following syntax:
 $nameofvar={
   multiple lines
 }
  • It is possible to use this syntax for a single line, for example when a space must be included at the end of the variable, e.g.:
    [={$li_class1=done }
  • Note that block variable assigments should not be used for inline variables/functions since line-end characters will be included.
    • Instead, simply use continuation lines, e.g.:
 $longmonth=\
    $pushset $monthdatefmt="%A %B %-d"\
    $day.monthdate\
    $pop $monthdatefmt

4.1.5 Single Character variables

  • One of the strengths of Writeup is the ability to define certain single characters as variables
    • They are the characters: [ ] { } which can be set individually
    • Plus the eight alternating characters: ~ @ # % ^ * _ ` which are used in matching pairs, e.g. *boldly*
  • These can be assigned simply by:

(example needed)

  • Note that as of Writeup version 2, you can only set the eight alternating characters inline if you use their long form. e.g.
    $set ${:sAT}="Value of first \@" $set ${:eAT}="Value of alternating \@"
    resulting in @--and--@ becoming: Value of first @—and—Value of alternating @
  • Here are the long forms of all the single character variables:
    $:sCURL{ $:eCURL} $::CURL{}
    $:sSQR[ $:eSQR]); <($::SQR[]
    $:sHASH# $:eHASH# $::HASH#
    $:sCIRC^ $:eCIRC^ $::CIRC^
    $:sPCENT%$:ePCENT%$::PCENT%
    $:sTILD~ $:eTILD~ $::TILD~
    $:sAT@ $:eAT@ $::AT@
    $:sTICK` $:eTICK` $::TICK`
    $:sASTR<strong>$:eASTR</strong>$::ASTR*
    $:sUNDR<em> $:eUNDR</em> $::UNDR_

4.1.6 Parentheses

  • Parentheses can be used to evaluate an expression, e.g.
Simple expression:
$( 1 $plus 1 $)

2

This is functionally identical to:
$set $result=1 $plus 1 $result

2

They are typically used for a temporary result:
$set $greet="Hello world!" $( $greet $whenunset "hi" $uppercase $)

HELLO WORLD!

4.2 Function Parameters—passing arguments

4.2.1 The Parameter List

If a parameter list is defined with the same name as the function, then when the function is called, the values following the call will be parsed for arguments, up to the end of the line.

  • The definition can be before or after the function. e.g.:
$greet=Hi $fname, I see you are $salutation $lname now!  // define the function
$parameters $greet salutation fname lname                // define the parameters

// now call the function with some arguments:
$greet Dr. Andrew Fountain --How are you?
  • The result is:

Hi Andrew, I see you are Dr. Fountain now! —How are you?

  • There are four kinds of parameter:
    • single token (default)
    • variable name (the parameter name starts with $)
    • string up to the end of the line (the parameter name ends with line)
      • any subsequent argument processing will be advanced to the next line
    • string up to the end of the line, non-zero length (the parameter name ends with linz)
      • a zero-length argument will not be accepted (so the default value is used if supplied)
      • if it is the only parameter on a line and the line is blank, argument processing will not be advanced to the next line
  • In the following example, the first parameter is a variable, the second and third are single tokens, and the last is the rest of line:
$parameters $heading hlevel hclass $href hline // define parameters for $heading
$heading={<h$hlevel class="$hclass">$hline</h$hlevel> // heading of level hlevel & class hclass
  $setval ${$href}=<<$hline>> // save title string in the address supplied by the argument href
}

// now call the function
$heading 2 content $htitle Testing out parameters
This is a paragraph about "$htitle"!
  • The result is:

Testing out parameters

This is a paragraph about “«Testing out parameters»”!

  • Now the function is called with different arguments:
$heading 3 comment $htitleb More testing of parameters
After hearing about "$htitle", this is a paragraph about "$htitleb"!

More testing of parameters

After hearing about “«Testing out parameters»”, this is a paragraph about “«More testing of parameters»”!

4.2.2 Default Parameters

Default parameter values are set up in the same way as parameters, e.g.

$parameters $heading_default 3 baseclass $hval "Default Title" // set defaults for $heading function
  • Now if the $heading function is called with missing arguments, defaults will be used.
    • Note that the number of arguments supplied was available in $heading_args:
$heading
This is a paragraph about "$hval" but only $heading_args arguments were given!

Default Title

This is a paragraph about “«Default Title»” but only 0 arguments were given!

4.2.3 Default Parameters, the hard way

An alternative way of checking parameters is to do it manually, e.g.

$parameters $func f0 f1 f2 fline
$parameters $func_default A B // only default the first two
$parameters $func f0 f1 f2 fline
$func={
  $modify $f2 $whenunset -noArg2- // manual default of the last two parameters
  $modify $fline $whenunset -noArg3-
Count=$func_param ($f0)($f1)($f2)($fline...
}
  • Now four possible calls:
$func a b c d e f
$func can't catch me for a toffee flea
$func a b
$func
  • resulting in:

Count=4 (a)(b)(c)(d e f...

Count=4 (can’t)(catch)(me)(for a toffee flea...

Count=4 (a)(b)(-noArg2-)(-noArg3-...

Count=4 (A)(B)(-noArg2-)(-noArg3-...

4.2.4 Parsing Arguments manually

$parameters $draw drawline
$draw={
  $set $explodedelim=" ,"
  $explode $arg $drawline
  $set $explodedelim=" "
Draw a "$( $arg2 $whenunset "thing" $)" at ($arg0, $arg1)
}
$draw 5, 6, office block
$draw 123,   678,    factory and industrial area
$draw 654,908,home
$draw 23,45
  • resulting in:

Draw a “office block” at (5, 6)

Draw a “factory and industrial area” at (123, 678)

Draw a “home” at (654, 908)

Draw a “thing” at (23, 45)

4.2.5 Example of multi-line parameters

  • Declare a function that takes seven parameters:
    • three on the first line, the third taking the rest of the line
    • two on the second line, the second taking the rest of the line
    • then two full lines, both optional, defaulting to “f f f f” & “g g g g”
$parameters $f a b c_line d e_line f_linz g_linz
$parameters $f_default aaaa bbbb "c c c c" dddd "e e e e" "f f f f" "g g g g"
  • Note that it is a good idea to prevent multiple blank lines creating extra vertical space in the input by setting
    $blanklines=
  • Now define the function to simply print a list of the arguments:
$f={
-\$a=$a
-\$b=$b
-\$c_line=$c_line
-\$d=$d
-\$e_line=$e_line
-\$f_line=$f_linz
-\$g_linz=$g_linz
Last argument supplied was number $f_args
}
  • Call the function with all arguments supplied:
$f This is a multi-line function
with a second line
an optional third line
Plus an optional fourth line
  • $a=This
  • $b=is
  • $c_line=a multi-line function
  • $d=with
  • $e_line=a second line
  • $f_line=an optional third line
  • $g_linz=Plus an optional fourth line

Last argument supplied was number 7

  • And again, but with arguments missing (and empty lines):
$f Now just
"three arguments"

  • $a=Now
  • $b=just
  • $c_line=
  • $d=three arguments
  • $e_line=
  • $f_line=f f f f
  • $g_linz=g g g g

Last argument supplied was number 5

4.3 Flow Control

4.3.1 If

$if <condition>
$elseif //optional elseif clause
$else //optional else clause
$endif
  • There are three other variants:
    • $ifdef <variable_name> tests to see if variable is defined
    • $ifndef <variable_name> converse of above
    • $ifexists <file_name> the file name can be contained in a variable and can be absolute or relative to the directory of the current document.
  • No looping is currently provided (although it can be effected using recursion)
  • There is a conditional statement: $iftrue <testvariable> <true-result> <false-result>. See Pre-defined Inline Functions

4.3.2 Include

  • Files may be included using the $include <filename> function
    • If the file is not found in the current directory, and not an absolute path, then its parent is searched, and so on, up to the root
      • (This enables include files to be stored in one place)
      • To prevent this search, use $includex (include exact) instead
    • If the filename includes a relative path, e.g. includes/my_inc.txt then a search will be performed in the order:
      • includes/my_inc.txt, ../includes/my_inc.txt, ../../includes/my_inc.txt etc.
  • If there are no includes in the document, then Writeup will automatically add $include top.txt at the top of the document
    • To prevent this happening, the line $include NONE can be added
  • The constant $INCLUDED is set to the current inclusion depth, where 0=top level. See Pre-defined constants.
4.3.2.1 Include paths

In order to help functions within include files to set up paths for other includes, css, javascript etc, the functions can find out information about how the file system is set up through the following variables:

  • $INCLUDEPATH contains the absolute path of the current file, including the final ‘/’
    • So if an included file is not contained in the current directory, the value of $INCLUDEPATH will be different to its value within the main document.
    • If you need to include a file from somewhere else in the file structure, This value can be set to a search base (i.e. the bottom of the tree, and search is upwards, however in most cases it would be better to use an absolute path.)
  • From within an include file, $RELPATH gives the relative address of the main document (not including the final ‘/’)
  • From within an include file, $REVERSEPATH gives the relative address the main document would need to use to access the directory containing the include file
    • e.g. within an include file that is in the directory above the main file, $REVERSEPATH would be ..
    • The values of $RELPATH or $REVERSEPATH from the most recent include will still be availabe in the main document.
      • But if their values need to persist past other includes, they should be $copy‘ed into another variable.
    • In Writeup 2.0 $RELPATH and $REVERSEPATH are set to FALSE if the included file is not in a directory that is a direct ancestor of the current directory. (This may change in future versions.)

4.3.3 exit

  • $exit will immediately abort. It can be in the middle of a line.
    • Writeup will attempt to close any open tags with no error messages.
    • If a warning message should be generated, then use $warningmsg before $exit.

4.4 Pre-defined constants

Description Variable Current Value
Today’s date: $TODAY 2016-09-08
Title of document (usually from first line, or the command line but can be assigned): $TITLE Writeup 2.5 Complete Reference Guide
Title of included document (from first line, with the TYPE of the file suffixed—for example the current include file is of type: inc): $TITLE_inc Text Processing Language
Path of document, filename

and filename with no extension:

$PATH, $FILENAME $FILE /home/andrew/code/cpp/writeup/tests/, fullref.txt

fullref

Type of document (writeup, inc or undefined): This document is of type "$TYPE" This document is of type “writeup”
date and time of last change: $DATE -- $TIME 2016-09-05 – 01:23:45
Version of Writeup: $VERSION 2.5
Version string including date: $VERSTRING 2.75.02 (2016-09-08)
Environment - Linux, Windows or MacOS:
$OS 

Linux

Directory separator for current environment:
($DIRSEP)

(/)

Extracting/Exporting is taking place (command line -x or -X): $EXTRACTING FALSE
Depth at which this particular file is currently included in others (0=not included): This file is an include at level: $INCLUDED This file is an include at level: 1

4.5 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
Override media type in link: $mediatype -not set-
Doctype at top of document: $DOCTYPE <!DOCTYPE html>
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 $monthdate function: $monthdatefmt %Eb %-d
Default date format used by $yeardate function: $yeardatefmt %Eb %-d, %Y
Default date format used by $customdate function: $customdatefmt %Ea %Eb %-d, %Y
Default newline representation in documentation \n character: $docNL <span class="docNL">↵</span>
The character produced from: \ , an escaped space : ($escspace) ( )
Replace tabs in the input with this string : ($tabreplace) ( )
As above, but at start of line : ($tabstartreplace) ( )
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;} div.indent {margin-left:40px;} ul.plainlist {list-style-type:none;}
Default CSS to create a page break: $pagebreakstyle page-break-before:always; margin-top:0;
A blank line causes this class to be set on the next list item: $linespaceclass newline
Multiple blank line handling.
  • $blanklines=TRUE default handling
  • $blanklines=FALSE supress blank line handling
  • $blanklines=custom handler where # of lines is passed in $blanklinecount:
$blanklines TRUE
If this is set, it’s contents are appended to the document: $postamble
Author (must be set by user):
default value: $author 

default value: unknown author

Date format of <time> title attribute: Default: ($timetag_title) Default: (%Eb %-d, %Y)
Overrides default calculation precision for floating point numbers: $floatprecision -not set-
Same as setting --body option on command line: $OPT_body -not set-
Same as setting --process option on command line: $OPT_process -not set-
Same as setting --markdown option on command line: $OPT_markdown -not set-
Same as setting --github option on command line: $OPT_github -not set-
Equivalent to setting --verbose option on command line:

-3 = (-qqq) show only fails

-2 = (-qq) show only errors

-1 = (-q) show only warnings & errors

 0 = default

 1 = (-v) verbose

 2 = (-vv) very verbose

 3 = (-vvv) garrulous)

 5+ = (--debug):

$OPT_verbose -1

4.5.1 URL root and base values

There are three kinds of URL:

It is common to test a page on one site, but move in into production on another. To facilitate this, the variables $hrefroot or $imgroot are automatically prepended to root-relative url’s.

  • This effect may be supressed and the url fixed by putting a : at the start of the url
Effect of setting: Relative Root-relative Absolute Fixed
$hrefroot
= ‘’
<^about^>
about
<^/about^>
/about
<^http://writeup.org/about^>
http://writeup.org/about
<^:/about^>
/about
$hrefroot
= ‘http://drup.org’
<^about^>
about
<^/about^>
http://drup.org/about
<^http://writeup.org/about^>
http://writeup.org/about
<^:/about^>
/about
  • Image urls can be controlled in the same way using $imgroot
  • Often images are stored in an images folder and this can be specified using $imgbase which will be prepended to relative url’s only.
    • If after adding $imgbase the url becomes root-relative, then as expected, $imgroot will also be prepended.
Effect of setting: Relative Root-relative (Absolute & Fixed are unchanged)
$imgroot=””
$imgbase=””
<#pic.jpg#>
⇒ <img src=“pic.jpg” />
<#/pic.jpg#>
⇒ <img src=”/pic.jpg” />
$imgroot=“http://drup.org”
$imgbase=””
<#pic.jpg#>
⇒ <img src=“pic.jpg” />
<#/pic.jpg#>
⇒ <img src=“http://drup.org/pic.jpg” />
$imgroot=””
$imgbase=“myimages/”
<#pic.jpg#>
⇒ <img src=“myimages/pic.jpg” />
<#/pic.jpg#>
⇒ <img src=”/pic.jpg” />
$imgroot=“http://drup.org”
$imgbase=“myimages/”
<#pic.jpg#>
⇒ <img src=“myimages/pic.jpg” />
<#/pic.jpg#>
⇒ <img src=“http://drup.org/pic.jpg” />
$imgroot=“http://drup.org”
$imgbase=”/images/”
<#pic.jpg#>
⇒ <img src=“http://drup.org/images/pic.jpg” />
<#/pic.jpg#>
⇒ <img src=“http://drup.org/pic.jpg” />
  • Notes:
    • $hrefbase works similarly to $imgbase but there are very few use cases for it
    • $hrefroot and $imgroot should never end in a /
      -$hrefbase and $imgbase will always end in a /

4.6 Switches

Note that all of these switches except $noerrors can have a “1” suffixed to them to make them one time only.

  • e.g. $tableclasses1=TRUE will only affect the next table. The variable will then self-delete.
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.

Default to FALSE:

$set $listclasses=TRUE 
-ul.ul1 li.ul1
 -ul.ul2 li.ul2
 a. ol.ol2 li.ol2
 b. li.ol2
  -ul.ul3 li.ul3
   cl3
 c. li.ol2
   ul.pl3 li.pl3
  • ul.ul1 li.ul1
    • ul.ul2 li.ul2
    1. ol.ol2 li.ol2
    2. li.ol2
      • ul.ul3 li.ul3
        cl3
    3. li.ol2
      • ul.pl3 li.pl3
$noerrors If TRUE then all error reporting is supressed.

Default to FALSE:

$set $noerrors=TRUE 
unchecked code
$set $noerrors=FALSE

unchecked code

$compacttables If TRUE then paragraph tags in table cells are not generated.

Default to FALSE. (Note that cells generated using the

| cell1 | cell2 | etc... shorthand will always be compact):

$set $compacttables=TRUE 
----
cell has no paragraph tag 
----
cell has no paragraph tag
$autolinks If TRUE then xx.yy is converted into a link.

Default to TRUE:

Converted to link: http://gw.ca
$set $autolinks=FALSE 
not converted: http://gw.ca

Converted to link: gw.ca

not converted: http://gw.ca

$autolinkslen Links longer than this are displayed abbreviated if possible

Default to 30:

The link: http://gw.ca/content/long-link/goes-on?q=with%20arguments is abbreviated.

The link: gw.ca/…ntent/long-link/goes-on is abbreviated.

$forcelista If TRUE then alphabetic lists do not have to be started at the beginning.

(This is usually FALSE to prevent acronyms accidentally starting lists:

$set $forcelista1=TRUE 
H. G. Wells is now an alphabetic list item "H."
#. List continues.
  1. G. Wells is now an alphabetic list item “H.”
  2. List continues.
$forcelisti If TRUE then Roman numeral lists do not have to be started at the beginning.

(This is usually FALSE to prevent acronyms accidentally starting lists:

$set $forcelisti1=TRUE 
MCMXCIX. This is list item 1999.
#. Next list value is 2000.
  1. This is list item 1999.
  2. Next list value is 2000.
$autoclose If TRUE then any open tags will automatically be closed at the end of the block:
$set $autoclose1=TRUE opened <mark>but not closed

opened but not closed

$timetag If TRUE (default value) then dates will be displayed using the <time> tag:
$set $timetag1=TRUE $( $TODAY $yeardate $)

$emailhide If TRUE (default value) then mailto: email addresses will be ‘hidden’ using numeric entities: $set $emailhide=TRUE [[mailto:a@gw.ca]] a@gw.ca
$plainlists If TRUE then plain lists (no bullet or number) are allowed.: Defaults to: $plainlists. See [[#lists lists]] for an example. Defaults to: TRUE. See lists for an example.

4.7 Pre-defined Inline Functions and Methods

4.7.1 Variable handling

  • These functions can be placed inline anywhere.
  • All values can be delimited by spaces, ", ', : or /
  • The first five functions, marked § have the following side effect:
    • They set their first parameter to be the “current variable”, for use with functions like $plus
  • The functions marked have the side effect of triggering a constructor if one has been defined
  • In the examples below, the result of the operation is often shown in (parenthesis). They have no function apart from clearly marking out the result.
Description SyntaxExampleResult
§Puts value into $var: $set $var=value $set $num=65536 Resulting in ($num) Resulting in (65536)
  …example with a ' delimiter: $set $var=delimitedvalue $set $var='a phrase' Resulting in ($var) Resulting in (a phrase)
§Same as $set but copies contents: $copy $var2=$var1 $copy $cp=$var Resulting in ($cp) Resulting in (a phrase)
Same as $set but value is delimited by end of line: $setline $var=rest of line $setline $var=rest of line
Resulting in ($var)
Resulting in (rest of line)
§Same as $set but evaluates expressions immediately rather than doing lazy evaluation : $setval "expression" $setval $em_title1="em:$( $num $plus 1 $)" _hover over me_ hover over me
…and is implicitly terminated if begins with $( : $setval $( expression $) $setval $halfnum=$( $num $div 2 $) ($halfnum) (32768)
§Makes into the “current variable” for modification: $modify($var) or $modify $var $modify($num).div( 32 ) now:$num and $modify $num $div 32 now:$num now:2048 and

now:64

“Explodes” value into array

Count returned in array name

Array members start at zero:

$explode $arrayname=values $explode $ar=$var ($ar $ar0 $ar1 $ar2) (3 rest of line)
Same as $explode but value is delimited by end of line: $explodeline $arrayname=word word word… $explodeline $ar=Line of text
Resulting in ($ar $ar0 $ar1 $ar2)
Resulting in (3 Line of text)
“Implodes” array into value: $implode $string=$arrayname $implode $s=$ar ($s) (Line of text)
Removes a variable or function: $unset $var $unset $var2
Push variable onto the stack: $push $var $push $s
Pop variable off stack: $pop $var $pop $new ($new) (Line of text)
Push variable onto the stack and set a new value. (Shorthand for $push then $set): $pushset $var=value $pushset $s="new string"
($s) $pop $s ($s)
(new string) (Line of text)
If current variable not set, replace with value: $whenunset value $( $newval $whenunset 777 $) 777
Evaluate contents of current variable: $eval $set $y='$( 7 $plus 8 $)' $eval ($y) (15)
Conditional statement: $iftrue $testvariable true-result false-result $iftrue $s "s=$s " "s is FALSE" s=Line of text
Dereference variable: $deref $set $y="$empty" $( $y $deref $whenunset is-empty $) is-empty
Set or override constant

(put constant in quotes if includes spaces):

$constant $constant $MYCONST='My Company' Work done by $MYCONST this year Work done by My Company this year
Make value into variable so as to use dot-notation: $mkvar The date is $mkvar(2016-05-14).yeardate The date is

4.7.2 Numeric Methods

Description SyntaxExampleResult
add value to the current variable : $plus $var $( 2.5 $plus 1.5 $) 4
subtract value from the current variable: $minus $var $( 2.5 $minus 1.5 $) 1
multiple value with the current variable: $mult $var $( 2.5 $mult 1.5 $) 3.75
divide value into the current variable : $div $var $( 25 $div 1.5 $) 16.6667
divide value into the current variable rounding to nearest integer: $idiv $var $( 25 $idiv 1.5 $) 17
fix the current variable at a given number of decimal places (see also $floatprecision): $fixdecimals $var $( 2.5 $fixdecimals 2 $) 2.50

4.7.3 Text processing Methods

Description SyntaxExampleResult
Concatenate value with current variable (can be quote delimited): $concat value $set $v=Paul $( Andrew $concat "& $v" $) Andrew& Paul
Same as $concat but does any variable subsitituion first: $concatv value $set $v=Paul $( Andrew $concatv "& $v" $) Andrew& Paul
Replace all text with $replacechar character
(Used for underlining):
$replacetext $( "Don't Bother!" $replacetext $) =============
Convert current variable to upper case: $uppercase $( "Don't Bother!" $uppercase $) DON’T BOTHER!
Convert current variable to lower case: $lowercase $( "Don't Bother!" $lowercase $) don’t bother!
Replace spaces with $replacespacechar character: $replacespaces $( "Don't Bother!" $replacespaces $) Don’t_Bother!
Remove punctuation from current variable: $removepunct $( "Don't Bother!" $removepunct $) Dont Bother
Strip HTML from current variable: $striphtml $( "<b>a long <br />_long_ time</b>" $striphtml $) a long long time
A combination of the last four operations can be used to generate an ID or URL: $lowercase $striphtml $removepunct $replacespaces $( "Don't Bother!" $lowercase $striphtml $removepunct $replacespaces $) dont_bother
Ensure special characters are interpreted literally, but allow variables: $litspecialchars $( ^%~@*_`{}[]&#x2611;$v $litspecialchars $) ^%~@*_`{}[]&#x2611;Paul
For documentation purposes ensure < > and & print literally: $litdoc $( <s>&#x2611;$v</s> $litdoc $) <s>&#x2611;$v</s>
Text is encoded to ensure that no substitution occurs, usually for code: $litcode $( <s>{&#x2611;$v}</s> $litcode $) {☑$v}
Remove following character if a space (useful within functions): $nosp abcd$nosp efgh abcdefgh

4.7.4 Time/Date processing Functions and Methods

These functions allow variables of the date type “date” to be manipulated and displayed.

  • A date variable is simply a string of the form yyyy-mm-dd (ISO standard format) and may be created displayed with no special functions.
  • The date can be converted to another format using the C++ strftime specification of which a simplified summary is:
Using dates Examples below based on: 2012-02-05T09:23:45 – 2018-07-19T13:45:00
Year %Y20122018 %y1218
Month %BFebruaryJuly %EbFebJuly %bFebJul %m0207 %-m27
Day of month %d0519 %-d519 %e 519 (leading space)
Day of week %ASundayThursday %EaSunThurs %aSunThu %w04 (%u not supported by MS)
Hour %H0913 %I%P09am01pm %-I%P9am1pm %l%p 9AM 1PM (leading space)
Min & Sec %M2345 %S4500
Typical long date %A %B %-d, %Y Sunday February 5, 2012 Thursday July 19, 2018
Typical med date %Ea %Eb %-d, %Y Sun Feb 5, 2012 Thurs July 19, 2018
ISO and modified iso %Y-%m-%d 2012-02-05 2018-07-19 %Y-%b-%d 2012-Feb-05 2018-Jul-19
US and UK/Canada %m/%d/%y 02/05/12 07/19/18 %d/%m/%Y 05/02/2012 19/07/2018
12 and 24hr time %-I:%M%P9:23am1:45pm %H:%M:%S09:23:4513:45:00
  • Note that Unix defines %E as available for alternative formats, so Writeup defines:
    • %Eb as an alternative form of %b where June, July & Sept are 4 letters instead of three to conform with popular usage.
    • %Ea as an alternative form of %a where Tues & Thurs are the short days instead of Tue and Thu to conform with popular usage.
    • Note that the %- prefix removes leading zeros or spacing
  • The conversion format is stored in the following variables:
    • $monthdatefmt is used by $monthdate and has the default value: %Eb %-d.
    • $yeardatefmt is used by $yeardate and has the default value: %Eb %-d, %Y.
    • $customdatefmt is used by $customdate and has the default value: %Ea %Eb %-d, %Y.
      • note that as usual you can append “1” to the name to override the value for the next conversion. e.g. $monthdatefmt1 .
  • The date is displayed using the HTML5 <time> tag if $timetag is TRUE. (Default value is TRUE)
  • The time tag below is made more visible using the CSS:
    • time {border-bottom: 1px dotted #0A0; cursor:help;} time:hover {border:none;}
  • The <time> tag by default will have it’s title attribute set to the date, formatted using $timetag_title.
    • Unset $timetag_title to prevent this.
Description SyntaxExampleResult
Set and display basic date: format: yyyy-mm-dd $set $d=2012-05-31 The date is $d The date is 2012-05-31
Add or subract works with numbers considered to be days: date - date ⇒ integer $set $i=$d $minus 2012-04-30 The 2nd date is $i days earlier The 2nd date is 0 days earlier
An example of add: date + integer ⇒ date $set $d2=$d $plus 700 Adding 100 weeks to $d gives $d2 Adding 100 weeks to 2012-05-31 gives 2014-05-01
Months can also be added or subtracted allowing complex date calculations: $addmonths integer or $addmonths -integer Last day of Feb 2016 is $( 2016-01-01 $addmonths 2 $minus 1 $) Last day of Feb 2016 is 2016-02-29
Print the date as a <time> tag using month format: $monthdate $d renders as $( $d $monthdate $) using format: $monthdatefmt 2012-05-31 renders as

using format: %Eb %-d

Print the date as a <time> tag using year format: $yeardate $d renders as $( $d $yeardate $) using format: $yeardatefmt 2012-05-31 renders as

using format: %Eb %-d, %Y

Print the date as a <time> tag using custom format: $customdate $d renders as $( $d $customdate $) using format: $customdatefmt 2012-05-31 renders as

using format: %Ea %Eb %-d, %Y

Print the date as a <time> tag using ISO format: $isodate $d renders as $( $d $isodate $) 2012-05-31 renders as

change the format for one date: $yeardatefmt or $yeardatefmt1 $set $yeardatefmt1="%A %B %d, %Y" Date: $( $d $yeardate $) Date:
Instead of rendering the <time> tag, simply evaluate the formated date: $set $timetag=FALSE The date string is $set $timetag=FALSE $( $d $yeardate $) The date string is May 31, 2012
Time is supported by $...datefmt but any date-math sets time to 00:00: ISO time: yyyy-mm-ddThh:mm:ss $set $dt=${d}T17:35 $set $customdatefmt1="%l:%M%P on %Eb %e, %Y" $( $dt $customdate $)

4.7.5 Other Functions

Description SyntaxExampleResult
Generate a warning message ($MSGINFO, $MSGWARNING, $MSGERROR or $MSGCRITICAL): $warningmsg MSGLEVEL "delimited words" $warningmsg $MSGINFO "Informational message"
_Message will only be seen at the time the file is compiled_
Message will only be seen at the time the file is compiled
Mark function as a method (see user written methods): $setmethod $setmethod $newmethod
no operation: $noop NO$noop OPERATION or no${noop}operation NO OPERATION or nooperation

5. Defining New Keyword Patterns

5.1 Simple replacements

Short character sequences such as [ or * are pre-defined to map to variables, but new ones can be defined.

E.g. to define @@ as a new pattern:

  • $keywordset @@ ${ATAT} ANY will cause every occurrance of @@ to be replaced by the variable ${ATAT}, anywhere in the line
  • $keywordset @@ ${ATl} LEFT will cause @@ at the left end of lines to be replaced by ${ATl}
  • $keywordset @@ ${ATr} RIGHT will cause @@ at the right end of lines to be replaced by ${ATr}
  • $keywordset @@ ${AT} BOTH will cause lines that contain only @@ to be replaced by ${AT}
  • It is recommeded that variable include the {} characters so they don’t accidentally combine with any characters following.
  • So if we define the following (just as an illustration):
$ATAT=<img src="i.jpg"/>
$ATl=<img src="l.jpg"/>
$ATr=<img src="r.jpg"/>
$AT=<img src="b.jpg"/>
  • Then it will replace this line:
    @@a line with an image at each end@@and one in the middle@@
  • with:
    <img src="l.jpg" />a line with an image at each end<img src="i.jpg" />and one in the middle<img src="r.jpg" />
  • and a line containing just @@ will become:
    <img src="b.jpg"/>

5.2 Alternating replacements

  • If a new keyword is intended to alternate between start and end values, like * does, then this may be accomplished with:
$keywordset "::" ${mark} ANY     // register the keyword pattern in the normal way
$keywordalt $mark $smark $emark // convert to an alternating pair by registering start and end varables
$smark=<mark>                   //assign values
$emark=</mark>
  • Then it will replace this line:
    This is a way to ::highlight:: a word
  • With this:
    <p>This is a way to <mark>highlight</mark> a word</p>

5.3 Paired replacements

  • Sometimes Keyword patterns are used in pairs. If Writeup is informed of this, more intelligent error messages can be generated if a pair is not closed. E.g.
$keywordset "((" ${RED} ANY  // register the keyword patterns in the normal way
$keywordset "))" ${eRED} ANY //
$keywordpair $RED $eRED     // register them as paired
$RED=<span class="red">     //assign values
$eRED=</span>
  • Then it will replace this line:
    The values will work as a ((pair)) with an intelligent error if the closing )'s are missing.
  • With this:
    <p>The values will work as a <span class="red">pair</span> with an intelligent error if the closing )‘s are missing.</p>

5.4 Deleting keywords

  • Keywords can be deleted using $keyworddel pattern

5.5 Limitations

  1. Care must be taken with single character keywords to prevent circular references
  2. At present, there are limits to the evaluation of variables that are used in non-inline text, such as attributes and styles.
    • Such variables cannot at present contain built-in functions

6. HTML/XML/CSS Attribute Generation

6.1 Attribute variables

These varibles can be set to modify the attributes of tags that follow. Most of these variables can have a “1” suffixed to them which means they are cleared after one use, which will be the next occurrence of the tag:

  • $tagname_class sets the class on following tags of that type.
    • e.g. $li_class=menu will make list items of class “menu”
    • e.g. $li_class1=menu will make the next list item of class “menu”
  • $tagname_style sets the style on following tags of that type.
    • e.g. $li_style=font-weight:bold; will make list items bold
    • e.g. $li_style1=font-weight:bold; will make the next list item bold
  • $tagname_attr sets the attribute on following tags of that type.
    • e.g. $td_attr=colspan="2" will set colspan=“2” on all td’s
    • e.g. $td_attr1=colspan="2" will set colspan=“2” on the next td
  • $tagname_title sets the title attribute on following tags of that type.
    • e.g. $h3_title=Conclusions will set title=“Conclusions” on all h3 tags
    • e.g. $h3_title1=Conclusions will set title=“Conclusions” on the next h3 tag
  • $tagname_id sets the id on the following tags of that type (a “1’ is assumed since id’s must be unique)
    • e.g. $li_id=firstitem will set id=“firstitem” on the next list items
    • e.g. $li_id1=firstitem identical to $li_id
  • The attribute can be applied only to tags of a particular class using the syntax:
    • $tagname_tagclass_xxxx —Note that as of Writeup 2.0 this will only apply if the class is generated automatically, i.e. in tables and lists where Writeup can created numbered classes for row/col or list-indent.
    • e.g. $li_row3_class=red will add the class “red” to the third row of tables (if $tableclasses=TRUE)
    • Note that this selector will take precedence over $li_class if it can be matched.
  • There are two “wildcard” tags: block and inline. These will only be matched if no other variable match.
    • e.g. $inline_style1=display:none; will hide the next inline element

6.2 Paragraph or other block tags

  • no automatic paragraph/block tag on the line if
    • line begins with /
    • line begins with </endtag>
    • $blocktag is set to “”
    • line begins with <a block tag>
  • else if table, list or heading, use its paragraph tag
  • else use $blocktag for paragraph tag (defaults to <p>)

6.3 Setting the colgroup tag

  • The colgroup tag can simply be controlled from a variable
    • $colgroup will set the columngroup tag for all following tables
    • $colgroup1 will set the columngroup tag for one table only
  • e.g.
    • $colgroup1=<col /><col class="c2" /><col class="c3" />
    • and set up styles:
    • $bodystyle=col.c2 {width:400px; background-color:yellow;} col.c3 {background-color:blue;}
Table Col1 Table Col2 Table Col3
Header cell cell
Header cell cell

6.4 Controlling the HTML generated by Markup

6.5 The Tag Stack

6.6 Tag Redefinition

Tags may be redefined, either to another tag, or to something totally different.

6.6.1 Simple tag redefinition (one tag simply replaced by another):

$p_tag=blockquote // simply replace paragraph tags with a blockquote
$p_etag=/blockquote // must do the end tag as well
$p_tag1=blockquote // or use tag1 to apply only to the next paragraph
$p_etag1=/blockquote // and the end tag

resulting in:

This is a paragraph redefined as a blockquote.

Back to normal paragraphs.

  • Note that attribute variables will be applied to simple redefinitions, but not to complex redefinitions.

6.6.2 Complex tag redefinition (other text or attributes included):

$li_tag=<li class=item>Item:$SP // adds a class and some characters. Don’t need to change li_etag.

  • Item: backpack
  • Item: boots
  • Item: food
  • Item: water

This will have to be explicitly ended with $unset $li_tag

6.6.3 Example redefining an ordered list as a definition list

  • Use a combination of simple and complex redefinitions
$ul1_tag=dl    // start and end the definition list
$ul1_etag=/dl
$li1_tag=dt    // a level one list item will start a definintion term
$li1_etag=
$ul2_tag=</dt>
$ul2_etag=
$li2_tag=dd
$li2_etag=/dd
$dlind=12em
$dt_style=width:$dlind;
$dd_style=margin-right:$dlind;
  • e.g. $li_tag=<li><span class="listitem">
    • $li_etag=</span></li>

7. Supported features in Github GFM and Markdown

7.1 Markdown Feature support

Feature Default $OPT_markdown $OPT_github Notes
Inline HTML  
Escape special chars More robust than Markdown
## style headers    
underline style headers       not currently supported
blockquotes ✓‡ up to three levels of indent
list much fuller support than Markdown
code blocks    
horizontal rules ✓‡ supports either - - - or * * *
links  
reference-style links       Does not make sense when Writeup’s variables provide a far richer solution.
images  
emphasis Turning on $OPT_markdown or $OPT_github will disable Writeup’s distinction between _ and *
code   Nested back-ticks not supported.
backslash escapes  
automatic links       Much simpler to user Github GFM automatic links, as below
multi-line paragraphs     Github reports this as the #1 source of errors in Markdown
  • Default support of feature can be turned off by setting $OPT_markdown_default=FALSE

7.2 Github GFM Feature Support

Feature Default $OPT_markdown $OPT_github Notes
Newlines = Paragraphs    
Multiple underscores in words  
URL autolinking  
Strikethrough ✓‡  
Fenced code blocks ✓‡  
Syntax highlighting       This is more of a Github use case
Task Lists  

8. Known limitations

  • Varibles defined using the single line method cannot have trailing underscores in the name, nor can curly brackets be used to delimit the variable name
  • Special characters, (_*{}[]~`@%^) have to be escaped if they occur in an “autolinks” URL
  • Most of the built in functions, such as $plus cannot be used within styles/attributes etc without first doing an $eval
  • A multi-line definition cannot appear within another multi-line definition.

It is anticipated that all the above limitations will be lifted in a future release.