Writeup 2.90 Full Reference Guide

Writeup 2.89 Complete Reference Guide

Last updated on 2020-02-07 at 01:23:45 by Andrew Fountain for version 2.90.04 (2020-02-10)

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 604 2020-02-08 03:23:56Z 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.90.04 (2020-02-10) by Andrew M Fountain, http://writeup.org
Copyright (c) Andrew M. Fountain,  2019
  • 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 ( )

✻Note that if only part of a word is to be italic, then this can be effected using a $NULL to invisibly break the word, e.g. her${NULL}_first_ ➜ herfirst. We have to use ${NULL}_first_ and not $NULL_first_ to stop the _ extending the name $NULL.

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: 

non-break:( )

em:( )

regular space: ( ) or ( )

null: ()

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

Force trailing space with (SPACE) at end of line:

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

See note below on alphabetic ordered lists that don’t start with A/a/I:

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.
  • $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. See Switches for more detail.
  • $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

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.3.4 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>)

3.3.5 Switching Block Tags in the middle of lines

Usually each line creates a single block, according to the above rules. However, it’s possible to:

  • end the current block tag and start a new one in the middle of the line:
    The command $newblock blocktagname will end the current block tag and begin a new one.
Switching a <dt> into a <dd>:
$set $blocktag1=dt 
Def Term $newblock dd Definition Description
Def Term
Definition Description
  • temporarily suspend blocks for subsequent lines, returning to close the original block tag later
    The commands $newblock + and $newblock - will switch off and on block-per-line processing.
    This is used internally for including code segments.
  • use the $BR tag with $fakebreak=TRUE to force HTML processing to start a new line but not actually a <br> tag

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.

If the <html> tag is changed, then both the <head> and <body> tag are supressed.

  • For example, an SVG formatted XML document, could be created with the following:
//.Three nested rectangles
$DOCTYPE=<?xml version="1.0" encoding="UTF-8" standalone="no"?>
$html_tag=svg xmlns="http://www.w3.org/2000/svg" width="$MAXX" height="$MAXY"
$MAXX=200
$MAXY=100
$stroke=#000
$pathstyle=fill:$Rfill;stroke:$stroke;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1

$rect($Rx, $Ry, $Rw, $Rh, $Rfill)={
  <path style="$pathstyle" d="M $Rx $Ry L $Rx.plus($Rw) $Ry L $Rx.plus($Rw) $Ry.plus($Rh) L $Rx $Ry.plus($Rh) Z" />
}

$rect 10 10 180 80 #F00
$rect 20 20 160 60 #0F0
$rect 30 30 140 40 #00F

  • Which would generate the following XML document:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
<path style="fill:#F00;stroke:#000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" d="M 10 10 L 190 10 L 190 90 L 10 90 Z" />
<path style="fill:#0F0;stroke:#000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" d="M 20 20 L 180 20 L 180 80 L 20 80 Z" />
<path style="fill:#00F;stroke:#000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" d="M 30 30 L 170 30 L 170 70 L 30 70 Z" />
</svg>
  • And would look like this:

Test SVG

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

  • Note that because Writeup uses a single, global namespace, all argument variables are unset before parsing the supplied arguments.
  • However they are not cleared at the end of a function.
  • But because Writup uses lazy evaluation by default, variables defined within the function should in many cases be evaluated, because a later evaluation might produce different results.
  • This would be the case if they depend on values that are valid only in that particular calling of the function.

4.2.1 The Parameter List

Parameters are defined with a comma-separated list in the function definition. E.g.

$myfunction($x, int $y, real $z)=Values supplied were: $x, $y and $z.

example usage:

$myfunction alpha beta gamma

results in:

Values supplied were: alpha, beta and gamma.

A paramter definition has four parts, all optional except for the pname:

  • type $pname=defaultvalue named:
  • type word, int, real, date, true, var, line, emptyline, newline, multi
    • if type is not specified, word is assumed
    • word takes a single word, or multiple if in quotes
    • int takes an integer
    • real takes a real number
    • date takes a valid date in the form YYYY-MM-DD
    • true (boolean) takes TRUE, !TRUE, FALSE, YES or NO
    • var takes a variable name which can be used by reference
    • line will take everything (except named arguments) up to the end of the line.
      • any subsequent argument processing will be advanced to the next line
      • an empty line will cause the argument variable to be unset unless it has a default value. A default of “” can be used to make a valid, but zero-length, string
      • A value of “” at the start of the line will create an empty string in the argument (the quotes ignored)
      • But if there is anything between the quotes, then the quote characters are preserved since they are assumed to be deliberate.
    • emptyline dummy parameter that will only match against an empty line in the input, else it will give a warning.
      • This is useful at the end of functions with complicated parameters to make sure the user has left a blank line to show completion, and the next line of text won’t accidentally be picked up as an argument.
    • newline dummy parameter that will start looking for parameters on the next line and will give a warning if the rest of the line was not empty.
    • multi Multi-line string terminated by a blank line. As with line, empty lines can be included if the line contains only ““
       
  • defaultvalue any word or quotes words. It can be ““. Special values are:
    • "WARN:words of warning" give warning message if argument missing
    • "" or $NULL will set the default to be an empty string
    • Setting an argument’s value to NOARG will force the default to be used.

Arguments of type line:

  • The first line variable will take the rest of the line on which the function is called.
  • Subsequent line’s will take the contents of the following lines, after any word’s on that line. E.g,:
$words_and_lines( \
$worda, \
$wordb, \
line $line1, \
line $line2, \
$wordc, \
line $line3, \
line $line4)={
-*These are the three words:* $worda, $wordb, $wordc
-*line1:* $line1
-*line2:* $line2
-*line3:* $line3
-*line4:* $line4
}  

example usage:

$words_and_lines Alpha Beta Old MacDonald had a farm
Eee Eye Eee Eye
Gamma Oh
!

results in:

  • These are the three words: Alpha, Beta, Gamma
  • line1: Old MacDonald had a farm
  • line2: Eee Eye Eee Eye
  • line3: Oh
  • line4: !

Let’s try that again, showing how quote marks are handled, and omitting a line.

  • Notice that quotations are always stripped from words (unless escaped) and from lines if they are used to signify an empty line
  • However since quotes are not necessary to identify which words are in a line, they are included in the arguments, since they must be intentional.
$words_and_lines "Alpha but no Beta:" "" "Old MacDonald's farm"
""
'Gamma' 'Eee Eye Eee Eye Oh'
""

results in:

  • These are the three words: Alpha but no Beta:, , Gamma
  • line1: “Old MacDonald’s farm”
  • line2:
  • line3: ‘Eee Eye Eee Eye Oh’
  • line4:

More complex example of different types:

  • (For clarity, each parameter is put on a separate line by using a line continuation \ at the end of each line.)
$funcdemo( \
$DEMword, \
int $DEMint, \
real $DEMreal, \
date $DEMdate, \
true $DEMtrue, \
var $DEMvar, \
line $DEMline, \
emptyline $placeholder, \
multi $DEMmulti)={
-$DEMword, $DEMint, $DEMreal, $DEMdate, $DEMtrue
-LINE: $DEMline
$RED$DEMmulti$eRED
$if $DEMtrue
$floatprecision=10
$setval ${$DEMvar}="Report: On $DEMdate.yeardate the result was: $DEMreal.mult($DEMint)"
$unset $floatprecision
$endif
}  

example usage:

$funcdemo "effectively a word" 12345 -27.123 2020-12-31 YES $report Whatever text to the end of the line

And some
more
lines until ended by empty line

-See if function changed variable: $report

results in:

  • effectively a word, 12345, -27.123, 2020-12-31, YES
  • LINE: Whatever text to the end of the line

((And some

more

lines until ended by empty line))

  • See if function changed variable: Report: On the result was: -334833.435

4.2.2 Default Parameters

  • If no argument is supplied, then any default will be used.
  • If there is no default, then the parameter variable is unset.
  • The following code creates a heading and list, with control over the heading level, and the color:
    • Note that
$alert( \
line $ALtitle=“WARN:Alert needs a title”, \
$ALlevel=3, \
$color=red, \
line $ALsubhead, \
line $ALmessage=”More details to be added later”)={
$block_style=color:$color
<h$ALlevel>$ALtitle</h$ALlevel>
$ifdef $ALsubhead
-_*$ALsubhead*_
$endif
-$ALmessage
$unset $block_style
}  

example usage:

$alert Danger from Falling Squirrels
2 blue Listen for squeaks
If you suspect a rodent is about to fall, place a bag over your head.

results in:

Danger from Falling Squirrels

  • Listen for squeaks
  • If you suspect a rodent is about to fall, place a bag over your head.
  • Running $alert with no arguments will result in the warning message: Warning: Alert needs a title
  • If the title is supplied, then all the other arguments default (except for $ALsubhead which does not have a default, but is tested to see if it is defined.)
  • For example:
$alert Defaults

results in:

Defaults

  • More details to be added later
  • If we want to allow an earlier argument on a line to default, but still set later arguments, then defaut can be forced using a argument value of NOARG
  • For example:
$alert Allow default heading level, but set everything else
NOARG purple This is the subheading
And the warning message

results in:

Allow default heading level, but set everything else

  • This is the subheading
  • And the warning message

4.2.3 Missing or empty arguments and default parameters

  • Here is a function which will test four possibilities
    • word and line parameters with either a default of “” or no default at all
$testdefaults( \
$word1, \
$word2=””, \
line $testtitle, \
line $line1, \
line $line2=””)={
----row
$testtitle.whenunset("_Arguments missing_")
--cell
$word1.whenunset(_unset_)$NULL
--cell
$word2.whenunset(_unset_)$NULL
--cell
$line1.whenunset(_unset_)$NULL
--cell
$line2.whenunset(_unset_)$NULL
}  

The test is run with four calls to the function within a table:

----tl
$thspan2=$set $th_attr1=colspan="2"
|          | $thspan2 word | $thspan2 line |
| Default: |  none  | ""   | none   | ""   |
$testdefaults argval argval Argument: ‹(argval)›
argval
argval
$testdefaults "" "" Argument: ‹("")›
""
""
$testdefaults


$testdefaults NOARG NOARG Argument: ‹(NOARG)›
NOARG
NOARG
----

resulting in:

word line
Default: none ”” none ””

Argument: argval

argval

argval

argval

argval

Argument: ""

Arguments missing

unset

unset

Argument: NOARG

unset

unset

4.2.4 Named (optional) parameters

  • Named/optional parameters operate exactly like regular parameters, except the arguments are optional and can occur in any position.
  • They are identified using a keyword, followed by a colon, and often in CAPS for easy recognition. (Putting keywords in caps also reduces the possibility of falsely identifying them in regular text, and so all caps keywords are spell-checked when parsing.
  • Note that if a line contains only named arguments of type word, it will not count as a blank line, or even a line, for the purposes of the other parameters.

Here is the code for the alert function above, updated to make use of named parameters. (note that the body of the function is unchanged):

$alert2( \
line $ALtitle=“WARN:Alert needs a title”, \
$ALlevel=3 LEVEL:, \
$color=red COLOR:, \
line $ALsubhead SUB:, \
line $ALmessage=”More details to be added later”)={
$block_style=color:$color
<h$ALlevel>$ALtitle</h$ALlevel>
$ifdef $ALsubhead
-_*$ALsubhead*_
$endif
-$ALmessage
$unset $block_style
}  

example usage:

$alert2 Danger from Falling Squirrels
LEVEL:2 COLOR:blue SUB:Listen for squeaks
If you suspect a rodent is about to fall, place a bag over your head.

results in:

Danger from Falling Squirrels

  • Listen for squeaks
  • If you suspect a rodent is about to fall, place a bag over your head.
  • Running $alert with no arguments will result in the warning message: Warning: Alert needs a title
  • If the title is supplied, then all the other arguments default (except for $ALsubhead which does not have a default, but is tested to see if it is defined.)
  • For example:
$alert2 Defaults

results in:

Defaults

  • More details to be added later
  • If we want to allow an earlier argument on a line to default, but still set later arguments, then defaut can be forced using a argument value of NOARG
  • For example:
$alert2 Allow default heading level, but set everything else
COLOR:purple SUB:This is the subheading
And the warning message

results in:

Allow default heading level, but set everything else

  • This is the subheading
  • And the warning message

Here is some code which creates an RSS feel for a podcast, plus an example podcast entry:

$autolinks=FALSE // turn off the flags which will mess up pure XML
$timetag=FALSE
$blanklines=
$blocktag=
$FPFEED=21216 // Feedpress basic feed number
[=<`<link>`>||]=<`</link>`>

$talk($SMdate=WARN:, line $talk_title="Talk title coming soon", $SM_short="", $SMdir="", $SMfname="",\
 $SMvimeo=$FALSE, $audioid=$FALSE, line $talk_scripture_line="", multi $talk_descr="",\
 line $speaker SPEAKER:,\  // If not Andrew
 line $series_line SERIES:,\      // optional num + name
 $vidpage VIDPAGE:,\     // omit /video/ if not set, use $SMweb. If NONE then no video
 $blog BLOG:,\           // Optional link to blog article
 $length LENGTH:,\       // File length in bytes
 $minutes=0:00 MINUTES:,\   // Optional time in minutes
 $cdata CDATA:,\         // Optional, set if true
 $feedpressid FPID:,\    // Optional feedpress ID
 $feedpresslink FPLK:,\  // Optional if not ID-1
 $podtime="11:00" PODTIME:,    \   // change the time
 line $keywords=theology KEYWORDS:\   // Optional keywords
)={
  $summary=
  $if $series_line // Prefix the summary with series info
    $setval $sernumbered=$series_line.first.isint // have to do in two steps because of old processing model
    $if $sernumbered||$setval $summary='$series_line.rest Part $series_line.first$SPACE'
    $else||$setval $summary=$series_line$SPACE||$endif
  $endif
  $setval $descprefix=$summary
  $if $talk_scripture_line
    $summary+=($talk_scripture_line)
  $endif
  $if $descprefix||$dspace=$SPACE||$else||$dspace=||$endif
  $if !$VIDPAGE||$copy $SMvideo=$SM_short
  $else||$copy $SMvideo=$VIDPAGE||$endif

  <item>
  $if $speaker
    <title>$speaker: $talk_title</title>
  $else
    <title>$talk_title</title>
    $speaker=Andrew Fountain
  $endif
  $linkurl=$URL/video/$SMvideo
  $linkgif=
  $if $feedpressid
    $if !$feedpresslink||$setval $feedpresslink=$feedpressid.minus(1)||$endif
    $linkurl=https://tracking.feedpress.it/link/$FPFEED/$feedpresslink
    $linkgif=<img src="https://feedpress.me/$FPFEED/$feedpresslink.gif" height="1" width="1"/>
    $if !$cdata||$linkgif=<`<![CDATA[`>$linkgif<`]]>`>||$endif
  $endif
  [$linkurl]
  <pubDate>$SMdate.datefmt("%a, %d %b %Y") $podtime:00 EST</pubDate>
  $if $cdata
    <description><`<![CDATA[`>
    $set $blocktag=p
    $if $series_line
      $descprefix$dspace$talk_descr
    $else
      $talk_descr
      $descprefix
    $endif
    $set $blocktag=
    $linkgif<`]]>`></description>
  $else
    <description>$descprefix$dspace$talk_descr$linkgif</description>
  $endif
  $fullaudio=gwmedia.s3.amazonaws.com/nlife/$SMdate-$SM_short.mp3
  $if $feedpressid
    <enclosure url="https://tracking.feedpress.it/link/$FPFEED/$feedpressid/$SMdate-$SM_short.mp3" length="$length" type="audio/mpeg"/>
  $else
    <enclosure url="https://$fullaudio" length="$length" type="audio/mpeg"/>
  $endif
  <guid isPermaLink="true">https://$fullaudio</guid>
  <itunes:author>$speaker</itunes:author>
  <itunes:duration>$minutes</itunes:duration>
  <itunes:subtitle>$summary</itunes:subtitle>
  $if $cdata
    <itunes:summary><`<![CDATA[`>
    $set $blocktag=p
    $if $series_line
      $descprefix$dspace$talk_descr
    $else
      $talk_descr
      $descprefix
    $endif
    $set $blocktag=
    <`]]>`></itunes:summary>
  $else
    <itunes:summary>$descprefix$dspace$talk_descr</itunes:summary>
  $endif
  <itunes:image href="http://nlife.ca/sites/default/files/$SMdate-$SM_short-poster-1400.jpg"/>
  <itunes:keywords>$keywords</itunes:keywords>
  <itunes:explicit>no</itunes:explicit>
  <itunes:category text="Religion &amp; Spirituality">\n<itunes:category text="Christianity"/>\n</itunes:category>
  </item>
}

$talk 2020-01-12 How the Man Born Blind challenges you and me
john_man_born_blind John/John_09-01 John9_01-man_born_blind 384407570 -1 John 9
FPID:13149409 MINUTES:30:23 LENGTH:12806798 KEYWORDS:Light, Jesus, Blind
SERIES:14 Gospel of John
On the surface this is a simple healing story, but John has beautifully put together a series of events and conversations that build up to a startling revelation from Jesus, that his light can actually lead people to become blind, and we ourselves need to pay close attention.

The resulting XML code is:

<item>
<title>How the Man Born Blind challenges you and me</title>
<link>https://tracking.feedpress.it/link/21216/13149408</link>
<pubDate>Sun, 12 Jan 2020 11:00:00 EST</pubDate>
<description>Gospel of John Part 14  On the surface this is a simple healing story, but John has beautifully put together a series of events and conversations that build up to a startling revelation from Jesus, that his light can actually lead people to become blind, and we ourselves need to pay close attention.<![CDATA[<img src="https://feedpress.me/21216/13149408.gif" height="1" width="1" />]]></description>
<enclosure url="https://tracking.feedpress.it/link/21216/13149409/2020-01-12-john_man_born_blind.mp3" length="12806798" type="audio/mpeg" />
<guid isPermaLink="true">https://gwmedia.s3.amazonaws.com/nlife/2020-01-12-john_man_born_blind.mp3</guid>
<itunes:author>Andrew Fountain</itunes:author>
<itunes:duration>30:23</itunes:duration>
<itunes:subtitle>Gospel of John Part 14 (John 9)</itunes:subtitle>
<itunes:summary>Gospel of John Part 14  On the surface this is a simple healing story, but John has beautifully put together a series of events and conversations that build up to a startling revelation from Jesus, that his light can actually lead people to become blind, and we ourselves need to pay close attention.</itunes:summary>
<itunes:image href="http://nlife.ca/sites/default/files/2020-01-12-john_man_born_blind-poster-1400.jpg" />
<itunes:keywords>Light, Jesus, Blind</itunes:keywords>
<itunes:explicit>no</itunes:explicit>
<itunes:category text="Religion &amp; Spirituality">
<itunes:category text="Christianity" />
</itunes:category>
</item>

4.2.5 Parsing Arguments manually

In some circumstances the usual format of arguments (space separated) might not be desired. In this case the entire argument line can be read as a string and parsed manually by the function. For example, if space comma is the separator:

$parameters $draw draw_line
$draw={
  $set $explodedelim=" ,"
  $explode $arg $draw_line
  $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.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.x $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 2020-02-09
Title of document (usually from first line, or the command line but can be assigned): $TITLE Writeup 2.89 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 2020-02-07 – 01:23:45
Version of Writeup: $VERSION 2.5
Version string including date: $VERSTRING 2.90.04 (2020-02-10)
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 Set to FALSE to disable:

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 six 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)
§Same as $set but runs after the current line has been processed: $setlater $var=value $set $smartquotes=FALSE $setlater $smartquotes=TRUE Smart "quotes" are sometimes--to be 'avoided'. Smart "quotes" are sometimes--to be 'avoided'.
§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
return TRUE if a number: $isnum $set $f=2.6 $set $i=-20 $f.isnum $i.isnum TRUE TRUE
return TRUE if an integer: $isint $f.isint $i.isint FALSE TRUE
return TRUE if a date: $isdate $set $d=2020-12-31 $d.isdate $i.isdate TRUE FALSE

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}
Slice a substring from a string
(use large number for end of string):
$string.slice(start end) $set $s=0123456789 $s.slice(2 5) $s.slice(-5 -1) -- $s.slice(0 999) 234

5678 – 0123456789

Return first word from varible: $first $set $v="The quick fox" $v.first The
Return rest of varible: $rest $set $v="The quick fox" $v.rest quick fox
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 .datefmt() method is the best way to do one-off date formatting.
  • 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 specified format: $somedate.datefmt(date format) $d renders as $d.datefmt("%Eb %-d") 2012-05-31 renders as

May 31

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 System Functions

Description SyntaxExampleResult
TRUE if the variable is defined: $isdefined($var) $set $var=value $isdefined($var) TRUE
TRUE if it is a system variable: $issystem($var) $issystem($DOCTYPE) TRUE
TRUE if the function is builtin: $isbuiltin($var) $isbuiltin($set) TRUE
TRUE if it is a constant: $isconst($var) $isconst($var) FALSE
TRUE if it is a method: $ismethod($meth) $ismethod($heading) FALSE
TRUE if the function/method has parameters hasparams(value): $hasparams($fun) $hasparams($heading) FALSE

4.7.6 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
Get title of another Writeup file (if in an include, must be relative to that): $gettitle(filename) $gettitle(quickref.txt) Writeup 2.5 Quick Reference Guide
Get path to another file relative to base file: $getrelpath(filename) $setval $path=$getrelpath(writeup32.png) path="$path" [[${path}writeup32.png]] path=””

image: writeup32.png

Create link from title of another Writeup file (experimental): $linkto filename $linkto quickref.txt Writeup 2.5 Quick Reference Guide
no operation: $noop NO$noop OPERATION and no${noop}operation NO OPERATION and 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 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.3 Controlling the HTML generated by Markup

6.4 The Tag Stack

6.5 Tag Redefinition

  • Tags may be redefined, either to another tag, or to something totally different.
  • If the new value starts with '<' then the string is not parsed but taken literally, and the end tag is not changed.
  • If the new value begins with a letter, then the tag name is used to set the end tag. This must be overridden if this is not what is desired.

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

$p_tag=blockquote // simply replace paragraph tags with a blockquote
$p_etag=/blockquote // Do not need to do this, it is done automatically when setting _tag

$p_tag1=blockquote // or use tag1 to apply only to the next paragraph
$p_etag1=/blockquote // and the end tag which is not set automatically for _tag1

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.5.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.5.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=12 // in em units
$dt_style=width:${dlind}em;
$dd_style=margin-left:$dlind.5em;
  • 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.