Article Wiki

Long-form humanities writing in plain text

Nigel Chapman

Article Wiki is an open-source writing tool for the humanities.  It is designed for long, structured arguments in plain text.  It provides bibliographies, citations, and footnotes without making the plain text unreadable.  This lets you do your writing anywhere you can edit plain text, including offline, online, or in collaboration or version control systems.  It’s a web service, but the software is open source, so you can add new features yourself if you have a little programming skill.  It is opinionated about layout, but always readable online and in print.

This page demonstrates most of Article Wiki’s features, starting with The Index Page (§2), which provides a Table of Contents.  Since page numbers have no meaning in a web document, the Table of Contents shows word counts instead, on the assumption that long articles are usually organised around word limits.

 

Table of Contents

Word Count 263 \\ 5,037
1. Introduction 25 566
1.a. Get Started 237
1.b. Why Use a Wiki? 304
2. The Index Page 392 566
2.a. Settings 174
3. Inline Markup 57 716
3.a. Typography 24
3.b. Sentence Spacing 101
3.c. Square Brackets 382
3.d. Backslashes and Line Breaks 95
3.e. Special Characters 57
4. Four Kinds of Text Blocks 78 1,496
4.a. Paragraphs 135
4.b. Character Blocks 153 683
4.b.i. Alignment Blocks 37
4.b.ii. Summaries 52
4.b.iii. Subheads and Double-stops 163
4.b.iv. Quotes and Captions 51
4.b.v. Lists 26
4.b.vi. Simple Tables 37
4.b.vii. Interlinear Translations 73
4.b.viii. Notes and comments 91
4.c. Function Blocks 228 509
4.c.i. Text Alignment 98
4.c.ii. Formatting Tables 154
4.c.iii. Controlling Whitespace 29
4.d. Spacers and Dividers 91
5. Adding Information 32 824
5.a. Values and Counters 148
5.b. Links and Footnotes 293
5.c. Cross References 131
5.d. Citations and Bibliography 220
6. Cheat Sheet (Print Me!) 175
7. To Do 431

§1.

Introduction

How can you immediately start writing in Article Wiki, and why would anyone use a plain-text wiki format for writing long-form articles?

§1.a.

Get Started

To try writing with the wiki just open the playground1 on any Article Wiki site.  The following three points will cover most of your writing needs, though there are many more features available.  See the Cheat Sheet (Print Me!) (§6) below for a handy reference.

Firstly, you’ll need to know how to lay out text.  A single control character at the start of a line or a paragraph tells you how that block should be formatted, like how > indicates a quotation in email.

@ A Simple Example

Article Wiki is a wiki designed for humanities writing.

> Article Wiki is a triumph!
= Albert Einstein

Powerful and intuitive, without being awkward or intrusive. Check out the amazing:

* footnotes
* bibliographies

A Simple Example

Article Wiki is a wiki designed for humanities writing.

Article Wiki is a triumph!

Albert Einstein

Powerful and intuitive, without being awkward or intrusive.  Check out the amazing:

  • footnotes
  • bibliographies

From this we can see that @ is a subheading, > and = are quotes and captions, and * are bullet points.  See Four Kinds of Text Blocks (§4), for a full list of control characters.

Secondly, you’ll want to add a little styling.  This will get you started, but see Inline Markup (§3) for the full tour.

# *Bold*
# /Italic/
# _Underline_
# `Monospace`
  1. Bold
  2. Italic
  3. Underline
  4. Monospace

Thirdly, you might need to know how to add links and footnotes.  The short answer is that you mark them in the text, then add their content as a subsequent paragraph, anywhere in the same section.  In both cases the magic character is ^.

Here's a ^[link] and a ^[footnote].

Article continues...

^ https://example.org 
^ This is a footnote. 

Here’s a link1 and a footnote.2

Article continues…


1 https://example.org
2 This is a footnote.

This keeps your text free of interruptions, while also giving your links and footnotes as much space as they need.  They’ll be formatted in a way that is equally readable online (with links) and in print.  See Links and Footnotes (§5.b) below, and then the subsequent sections on indexes and bibliographies.


1 https://chapman.wiki/playground

§1.b.

Why Use a Wiki?

If this is already familiar, skip ahead to The Index Page (§2).

It’s Easy.  For simple layout, you can go a long way by pretending that you’re writing plain-text emails.  For the rest, there’s a Help button in the editor, which brings you back to this page.
It’s Powerful.  Some kinds of text layout are easy to describe in plain text, but difficult to achieve in a word processor.  Interlinear Translations (§4.b.vii) are one useful example of this.
Work Anywhere.  You can write articles by email, or on your phone, complete with footnotes, indexes and a bibliography, and they’ll be ready to be copied straight into your document when you get back online.
Just Write, Don’t Do Layout.  Wikis take responsibility for layout – a bit like LaTeX, if you know that, but less complicated.  They can be described as wygiwym rather that wysiwyg.  It’s not that “what you see is what you get”, like in a layout program, but that “what you get is what you mean.”  If you find the wiki gets your layout right, that’s one less thing you have to think about when writing.
Write Once, Publish in Multiple Formats.  Wikis typically produce multiple output formats from a single plain-text master file.  Article Wiki produces only HTML for online use, with a layout that works as well in print.  Your browser can then print this as a PDF in whatever page format you prefer, including wide margins for proof-reading if you like.
Collaborate and Track Changes.  Working in plain text makes it easy to use version control systems for collaboration and cooperative writing.  You can pull from any Git repository (there are free online services for public and private repositories), and later merge your changes and those of others back into it, while preserving its edit history.

§2.

The Index Page

The most important feature of Article Wiki is its structure, which is like a directory of files rather than one very long file, or a set of pages bound together into a book.  These are joined and organised by the outline in the index.txt file or index page.

My Article

$ AUTHOR = Author Name
$ EMAIL = email@example.org
$ DATE = 18 September 2017

A short example document.

~ 

- Introduction
- The Main Argument
- - Part One
- - Part Two
- Conclusion

If there is no index page, the document parts will be arranged in alphabetical order by their titles, and there will be no front matter (headings, author, abstract, table of contents).  Typically, an Article Wiki document will have an outline.

How do I…
… add a new section to a document?
Add it to the outline, and navigate from there.
… reorganise a document’s sections?
Change their order in the outline.
… find sections not appearing in the outline?
They appear in a notification box just below the Table of Contents.
… delete a section?
Use the Delete button in the editor window.

Because Article Wiki aims to take a document from brainstorming through writing to publication, the index page of each document offers a nested ‘outline’ list, which is autolinked to new pages in the online editor.  The index page can thus be used as an outliner and brainstormer, in which sections can be easily added, arranged, and deleted.  Each section corresponds to a file name:

Outline File in Directory
My Article index
- Introduction introduction
- The Main Argument the-main-argument
- - Part One part-one
- - Part Two part-two
- Conclusion conclusion

Table 1.  Titles and ‘slugs’, the names of document parts.

Slugs.  The names of the individual page files are turned into slugs.  This style will be familiar from blog or news URLs, even if the name is unfamiliar.  They are made by taking the page titles, converting special characters to plain text, converting to lowercase, removing punctuation and consolidating spaces into a single dash.

This multi-file document format has strengths and weaknesses.  Its main disadvantage is that changing your headings means changing your file names.  However, the online editor helps with that, and other benefits follow:

  1. It’s easy to rearrange your document by rearranging your outline.
  2. In a wiki designed for long arguments, it is a convenience to be working only on one self-contained part of the argument at a time.
  3. Your document will be clearly organised when someone later – maybe you – has to maintain it.

§2.a.

Settings

You will have seen some lines began with $ in the index page: these are called values or settings.  Some like AUTHOR and DATE are used by the wiki; these are capitalised.  In this document $[DATE] is “26 December 2019”, for example.  You can also make and use your own – see Values and Counters (§5.a) below for a full summary.  Those set in the index page are especially useful because they are shared with all the other sections.

Value Example Explanation
NAME Fred Smith Full name of author
EMAIL fred.smith@example.org Contact email for the author
DATE 18 December 2019 A human readable date, preferably unambiguous (so not 1/2/2020)
LICENSE CC-BY-SA One of several codes representing a Creative Commons License

For Creative Commons licenses, the following codes will result in appropriate notices appended to the end of the page.

CC-BY-SA Creative Commons Attribution-ShareAlike 4.0
CC-BY-NC Creative Commons Attribution-NonCommercial 4.0
CC-ZERO Creative Commons ZERO; like putting the article into the Public Domain

§3.

Inline Markup

Wiki markup is of two main kinds, inline and block markup, respectively.  Inline formatting determines how text is laid out within each text block, say, a paragraph, a list item or a table cell.  There are two kinds of inline formatting, general typography and square brackets.  Markup ofny kind can always be prevented with Backslashes and Line Breaks (§3.d).

§3.a.

Typography

See Backslashes and Line Breaks (§3.d) for entering plain quotemarks as \' and \".  Unicode characters are always supported.

For common markup, just type naturally:

* 'quote's' "quoting"
* dashes --- dashes -- 1-2

Links will be added:

* http://example.org
* email@example.org

Use round brackets for special characters ...

* ACME(TM), (C)1999, 38(D)C. 
* 2(1/4), (3/4) and (1/2)

... and for horizontal space:

| x(S)x(2S)x(4S)x    | /thin/
| x x                | /normal/
| x(EN)x(2EN)x(4EN)x | /en/
| x(EM)x(2EM)x(4EM)x | /em/

For common markup, just type naturally:

  • ‘quote’s’ “quoting”
  • dashes—dashes – 1–2

Links will be added:

Use round brackets for special characters …

  • ACME™, ©1999, 38°C.
  • 2¼, ¾ and ½

… and for horizontal space:

x x  x    x thin
x x normal
x x  x    x en
x x  x    x em

§3.b.

Sentence Spacing

Sentence-ending punctuation (.!?) will always be followed by an extra space for readability.  Like.  This.  It allows for any trailing right-quotes or right-brackets.  You can always escape a punctuation character to prevent the extra spacing; see Backslashes and Line Breaks (§3.d) for more.

* J\. R\. R\. Tolkien. C\. S\. Lewis.
* See Job 11:12, though Heb.\ is unclear.
* ("A!") ('B?') (C.) "D." E.
  • J. R. R. Tolkien.  C. S. Lewis.
  • See Job 11:12, though Heb. is unclear.
  • (“A!”)  (‘B?’)  (C.)  “D.”  E.

Backslashing the period characters in initials, acronyms, and common abreviations is a little inconvenient.  There are text processing systems like LaTeX that maintain a list of common abbreviations and format them appropriately, but this is complex and it still requires occassional work-arounds.  Backslashing is a single, simple principle that gives consistent results in all cases.

§3.c.

Square Brackets

Most inline markup consists of a single control character in front of a set of square brackets, for example *[bold] for bold text.  In the simplest and most common cases it is easier just to type *bold* and get the same effect, but the square brackets handle complex cases better and can be visually clearer in plain text.

Character Wiki Text Formatting Shorthand
/ /[Italic] Italic /Italic/
* *[Bold] Bold *Bold*
_ _[Underline] Underline _Underline_
` `[Monospace] Monospace `Monospace`
! ![Marker] Marker
: :[Sans Serif] Sans Serif
= =[Small Caps] Small Caps
+ +[Inserted] Inserted
- -[Deleted] Deleted
, Superscript'[2] Superscript2
Subscript,[2] Subscript2
Shorthand.  It may seem strange to offer a shorthand version of markup that saves only one character.  However, it seems easier to type the same character twice, it has a lighter impact on readability in the most common 90% of cases, and it is more intuitive for writers familiar with how other wikis work.  The bracket syntax is more powerful, however:
Stacking.  You can stack the control characters in brackets.  Up to five symbols can be stacked in this way, although that seldom helps with readability.
*/_[bold italic underline] bold italic underline
=![Floating Marker] Small-caps Marker

Nesting.  You can’t presently nest brackets or shorthand inside other brackets.  This is on the To Do list, but a low priority.

Information Brackets.  Square brackets are also used to add information, not only formatting, to text.  It is not possible to combine formatting and informational control characters by stacking.  See Adding Information (§5) for more.
$ $[AUTHOR] Nigel Chapman
$ $[n++], $[n++], $[n++] 1, 2, 3
^ ^[Link] Link1
^ ^[Footnote] Footnote2
@ @[cross-references] Cross References (§5.c)
@ @[-cross-references] §5.c
~ ~[Author 2000, p.26] (Author 2000, p.26)a
~ ~[Author, /Title/, p.32] (Author, Title, p.32)b

Table 2.  Information Control Characters


1 http://example.org
2 Footnote

§3.d.

Backslashes and Line Breaks

The wiki formatter will preserve any character that is backslashed, rather than allow it to affect the formatting.  That’s how you’ll see the wiki markup in Square Brackets (§3.c) was entered if you view the wiki text.

. \*[Bold Text] vs. *[Bold Text]
. \"quotes\" vs. "quotes"
*[Bold Text] vs. Bold Text
"quotes" vs.  “quotes”

Note that backslashing doesn’t allow <, > or & characters to be inserted into the wiki’s HTML output, however:

. </br> vs. \</br\> 
. &lt;/br&gt; vs. \&lt;/br\&gt;
</br> vs.  </br>
</br> vs.  &lt;/br&gt;

In some wiki formatting conventions a backslash at the end of a line indicates a line break.  In Article Wiki, however, we use the control characters for aligning paragraphs.  See Alignment Blocks (§4.b.i) for more.

. Line 1
. Line 2
Line 1
Line 2

§3.e.

Special Characters

Use HTML Entities1 to enter special characters; e.g.  write ‘détente’ as d&eacute;tente.  If frequently relying on these characters, it is best to use a keyboard layout for your computer or device that lets you type them directly.

| &alpha; | &Gamma; | &aacute;
    | &aelig; | &ccedil; | &egrave;
    | &iuml; | &ntilde; | &ocirc;
| &cent; | &pound; | &euro;
    | &deg; | &plusmn; | &frac12;
    | &le; | &ge; | &ne;
| &copy; | &reg; | &trade;
    | &sect; | &para; | &dagger;
    | &laquo; | &raquo; | &middot;
α Γ á æ ç è ï ñ ô
¢ £ ° ± ½
© ® § « » ·

1 https://dev.w3.org/html5/html-author/charref

§4.

Four Kinds of Text Blocks

Wiki text is organized in four kind of text blocks.  These are paragraphs, character blocks, function blocks and dividers.  All text blocks are separated from each other by blank lines.  Function blocks, however, may contain blank lines; their start and end points are indicated by three-character delimiters like :

This is a normal *paragraph*. 

> This is a quotation. It is an
example of a *character
block*, indicated by a control
character at the start of the
first line (in this case, `>`,
an angled right-bracket). 

VERBATIM ---
Here's some 
   verbatim text.
      It's an example
         of a *function block*.
            In this case,
               'VERBATIM' is the
                   function name.
---

* * *

(And that's a *divider*.)

This is a normal paragraph.

This is a quotation.  It is an example of a character block, indicated by a control character at the start of the first line (in this case, >, an angled right-bracket).
Here's some 
   verbatim text.
      It's an example
         of a *function block*.
            In this case,
               'VERBATIM' is the
                   function name.

✻ ✻ ✻

(And that’s a divider.)

These simple arrangements should cover almost all formatting needs, at least when augmented by options and settings, which will be described below.

§4.a.

Paragraphs

Paragraphs are just blocks of text separated by blank lines in the source text.

When a paragraph follow another paragraph, it is marked by a first line indent, as illustrated here.  Indenting can also be controlled with Character Blocks (§4.b).

The First Paragraph is the Title.  There must always be a title, it can be as long as you like, and no other markup is required to indicate it.  If writing a letter, say, the title could be hidden by marking it as a comment line, that is, by prefacing it with a % symbol and a space.
Line Wrapping is Optional.  The wiki doesn’t care whether paragraphs are wrapped to a certain width, or continue unbroken, only being wrapped in the editor.  It will rewrap them automatically where possible so the writer doesn’t have to.

§4.b.

Character Blocks

Character Blocks are paragraphs formatted by a single control character at the start of the first line: It must be the first character and it must be followed by a space.

@ Subheadings
> = Block quote; Caption/Citation
: ~ Block indent; Hanging indent
. ; , Align: Left, Centre, Right
* # _ Bullet list; Numbered list, To Do list (recurse with # # #)
! | Simple Tables: Headers, Cells
? % Note (visible), Comment (hidden))
/ Translation (interlinear glosses)
- Chapter outlines (in index.txt)
& = Figures, Captions TO DO
Recursion.  List characters (* # + -), can be repeated to indent them further ( see below).
Captions.  Captions (=) will format themselves for the kind of block that they follow, whether tables, quotes, pull-quotes or anything else.
Line wrapping.  Paragraphs and Character blocks are turned into a single line in the wiki, so the author needn’t manage the line endings.  It is assumed that any editing program will wrap lines automatically.
* This is a single line
* This is a single line too. 
  • This is a single line
  • This is a single line too.

§4.b.i.

Alignment Blocks

Unlike regular paragraphs, aligns and floats have space above and below them.  Repeat the control character to start a new line without spacing.

. Left aligned text
. with no indents
. on following lines.

; Centered text.

, Right aligned text.

~ A hanging indent, meaning that wrapped lines will be indented. 

: A block indent. Wrapped lines are also indented.
Left aligned text
with no indents
on following lines.
Centered text.
Right aligned text.
A hanging indent, meaning that wrapped lines will be indented.
A block indent.  Wrapped lines are also indented.

These can be combined in more sophisticated ways:

. Definition title
: with the definition here.
. Definition title
: with the definition here.
Definition title
with the definition here.
Definition title
with the definition here.

§4.b.ii.

Summaries

An introduction or synopsis may be desired as the start of each section.

The caption function block (=) is always used to explain the element preceding it.  When it follows the initial title paragraph in a section it becomes a summary paragraph.  This will be displayed in larger text for easier skimming.

§4.b.iii.

Subheads and Double-stops

Subheadings within a section do not appear in the navigation, so it’s up to the author to format them however they wish.  This can be done with Alignment Blocks (§4.b.i) and Square Brackets (§3.c).

; =[Here's a Subheading]
; /[And here's a sub-subheading]

(Regular paragraph continues here, after a gap.)
Here’s a Subheading
And here’s a sub-subheading

(Regular paragraph continues here, after a gap.)

There is a form of short-cut called a double-stop that makes this easier to type.  Several of the common format markers (/*_=) can be repeated to either format a whole block of text, or just to mark off some leading text to create a inline subheading.

. // Italicised Subheading.
; ** Bold Subheading.
, == Small Caps Subheading.
; __ Underlined subheading.

. Italics. // Body text...
. Bold face. ** Body text...
. Small caps. == Body text...
. Underline. __ Body text...
Italicised Subheading.
Bold Subheading.
Small Caps Subheading.
Underlined subheading.
Italics.  Body text…
Bold face.  Body text…
Small caps.  Body text…
Underline.  Body text…

However, while this allows a great deal of control, it means equal space above and below the subheading unless extra space is manually entered with a ~ character.  So headlines are best entered with the @ control character, which formats it in a customary manner.  Double-stops are used to select bold or italic.

(Regular paragraph continues here)

@ Subheading

(Regular paragraph continues here)

(Regular paragraph continues here)

Subheading

(Regular paragraph continues here)

A range of common layout requirements can be solved with double-stops, of which the following examples are representative.

Subheading. // This is an inline subheading at the start of a normal auto-indenting paragraph.

> Abstract. ** A bold inline subheading in a quotation will create a sensibly formatted abstract or summary block. 

~ Definition. // Here's a useful way to format some glossaries, definition lists, and so on.

= Table 1. ** A caption line. 

Subheading.  This is an inline subheading at the start of a normal auto-indenting paragraph.

Abstract.  A bold inline subheading in a quotation will create a sensibly formatted abstract or summary block.
Definition.  Here’s a useful way to format some glossaries, definition lists, and so on.

Table 1.  A caption line.

§4.b.iv.

Quotes and Captions

> Simple quotes look like email. 
= Abraham Lincoln
Simple quotes look like email.

Abraham Lincoln

You will have seen that captions (=) are formatted differently depending on what they follow.  One following the title will be read by the wiki as a summary.  One following a table will be formatted as a table caption; see Formatting Tables (§4.c.ii). Likewise for captions after quotes.

§4.b.v.

Lists

Lists have a very simple syntax, whose behaviour can be modified with settings, for example to set the numbering or continue from before.

# List (Ordered)
# # List
# # # List 
# # # # List 
# List

* List (Unordered)
* * List
* * * List 

$ NUMBERING = continue

# This continues the previous
top-level list number
# after an interruption.

$ NUMBERING = 9

# Whereas this starts a list
# from a new number.

_ Buy milk
_ Return books to library
  1. List (Ordered)
    1. List
      1. List
        1. List
  2. List
  • List (Unordered)
    • List
      • List
  1. This continues the previous top-level list number
  2. after an interruption.
  1. Whereas this starts a list
  2. from a new number.
  • Buy milk
  • Return books to library

§4.b.vi.

Simple Tables

There are better ways to enter table data, but this is sometimes sufficient and extremely simple.  See Formatting Tables (§4.c.ii) (below).

! Name ! Number
| John | 7326532765
| Jane | 6397532340 ksjdh kjsh kdsjh sdkjh dskjh dskjh 

= Table $[t++]. ** A Table of Numbers
Name Number
John 7326532765
Jane 6397532340 ksjdh kjsh kdsjh sdkjh dskjh dskjh

Table 1.  A Table of Numbers

This is a good way to lay out questions and answers.

| Q. | How can I best format questions and answers?
| A. | Well, I'm glad you asked! It's like this... 
Q. How can I best format questions and answers?
A. Well, I’m glad you asked!  It’s like this…

§4.b.vii.

Interlinear Translations

Glosses or parallels are commonly required in linguistics, but can be difficult to format.  Wiki markup suits them well, however.  There is no limit on the number of translated phrases that can be stacked together.  Unicode font substitution can be applied to different character ranges, but is presently only set up for Greek – note that the font GFS Didot automatically replaces the body font here:

/ *[1] Παῦλος καὶ Τιμόθεος / Paul and Timothy, 
/ δοῦλοι Χριστοῦ Ἰησοῦ / ^[servants] of Christ Jesus 
/ πᾶσιν τοῖς ἁγίοις / to all ^[those set apart] 
/ ἐν Χριστῷ Ἰησοῦ / in Christ Jesus 
/ τοῖς οὖσιν ἐν Φιλίπποις / who are in Philippi, 
/ σὺν ἐπισκόποις καὶ διακόνοις· 
    / together with the ^[overseers and assistants]. 
/ *[2] χάρις ὑμῖν καὶ εἰρήνη / Grace and peace to you, 
/ ἀπὸ Θεοῦ Πατρὸς ἡμῶν / from God our Father 
/ καὶ Κυρίου Ἰησοῦ Χριστοῦ. / and the Lord Jesus Christ.

^ δοῦλοι, also /slaves/
^ lit. /holy people/, trad. /the saints/
^ trad. /bishops and deacons/ 
1 Παῦλος καὶ Τιμόθεος
Paul and Timothy,
δοῦλοι Χριστοῦ Ἰησοῦ
servants1 of Christ Jesus
πᾶσιν τοῖς ἁγίοις
to all those set apart2
ἐν Χριστῷ Ἰησοῦ
in Christ Jesus
τοῖς οὖσιν ἐν Φιλίπποις
who are in Philippi,
σὺν ἐπισκόποις καὶ διακόνοις·
together with the overseers and assistants.3
2 χάρις ὑμῖν καὶ εἰρήνη
Grace and peace to you,
ἀπὸ Θεοῦ Πατρὸς ἡμῶν
from God our Father
καὶ Κυρίου Ἰησοῦ Χριστοῦ.
and the Lord Jesus Christ.

1 δοῦλοι, also slaves
2 lit.  holy people, trad.  the saints
3 trad.  bishops and deacons
/ '[1:14]  Ἕλλησίν / 無 論 是 希 利 尼 人 、 / To Greeks / मैं यूनानियों / A Griegos / لليونانيين 
/ τε καὶ Βαρβάροις, / 化 外 人 、 / and to Barbarians, / और अन्यभाषियों / y á bárbaros, / والبرابرة 
/ σοφοῖς / 聰 明 人 、 / to the wise / का और बुद्धिमानों / á sabios / للحكماء
/ τε καὶ ἀνοήτοις / 愚 拙 人 、 / and to the foolish, / और निर्बुद्धियों / y á no sabios /  والجهلاء
/ ὀφειλέτης εἰμί. / 我 都 欠 他 們 的 債 。 / am I obligated. / का कर्जदार हूं। / soy deudor. / اني مديون
1:14 Ἕλλησίν
無 論 是 希 利 尼 人 、
To Greeks
मैं यूनानियों
A Griegos
لليونانيين
τε καὶ Βαρβάροις,
化 外 人 、
and to Barbarians,
और अन्यभाषियों
y á bárbaros,
والبرابرة
σοφοῖς
聰 明 人 、
to the wise
का और बुद्धिमानों
á sabios
للحكماء
τε καὶ ἀνοήτοις
愚 拙 人 、
and to the foolish,
और निर्बुद्धियों
y á no sabios
والجهلاء
ὀφειλέτης εἰμί.
我 都 欠 他 們 的 債 。
am I obligated.
का कर्जदार हूं।
soy deudor.
اني مديون

§4.b.viii.

Notes and comments

The " character adds a visible, compact note, with an outline around it.

(Regular paragraph continues here...)

" *Block notes* appear as their own paragraphs, but in a much smaller font, and with a box around them.

(Regular paragraph continues here...)

(Regular paragraph continues here…)

Block notes appear as their own paragraphs, but in a much smaller font, and with a box around them.

(Regular paragraph continues here…)

The % character indicates a comment that is not displayed to the reader.  However, while this text does not appear in HTML (or PDF or ePub, as a result), it is not fully hidden, because a reader can always look at the source in the online editor.  A note can also be used in the title paragraph if you don’t want the title to be visible, say if writing a letter.

* * *

% This text will not be displayed.

* * *

✻ ✻ ✻

✻ ✻ ✻

§4.c.

Function Blocks

Whenever you encounter some special formatting requirements – anything past the point where wiki formatting remains a convenience – then you should expect to find a special function block that lets you enter data in a form that really is convenient, and just knows what to do with it.

Functions, like y = f(x), will be familiar from maths, spreadsheets, or programming; function blocks look like that.

The BOX function just puts a box around a section of text.  The COMPACT function lets you write a digression, or supply a transcript that is not necessarily going to be read, so should occupy minimal space.  Because small text reads better in columns, it takes the options 2cols or 3cols.

BOX ===
COMPACT (2cols) ---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
---
===

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.  Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

COMPACT is one of a set of core functions implemented within the wiki; these handle alignment, table formatting, and whitespace, among a few other common tasks.  If you’re curious about how wiki markup is being placed side-by-side with its formatted output in these examples, that’s done with a function too, called DEMO, wrapped around whatever text is to be displayed.

Also, if you have some skill in programming, you can fairly easily write your own functions.

You can use functions inside other functions so long as you use different delimiters for each layer.  Try:

=== >>> +++ ::: %%% ///

§4.c.i.

Text Alignment

Note.  Right alignment is not dependable for generating eBooks.

The LEFT, CENTER and RIGHT function blocks allow blocks of text to be aligned.  To write a well formatted letter, for example:

RIGHT ---
. Some Fine Locality
. In Yonder Province

. Dec. 1656
---

. Addressee
. Locality
. State

; *_[RE: IMPORTANT]

Dear sir, 

I would have written you a shorter letter, but I did not have the time.

~

RIGHT ---
. Yours etc.,
. 
. 
. ..........................

. Blaise Pascal
---
Some Fine Locality
In Yonder Province
Dec.  1656
Addressee
Locality
State
RE: IMPORTANT

Dear sir,

I would have written you a shorter letter, but I did not have the time.

 

Yours etc.,
 
 
……………………..
Blaise Pascal

If you wanted to align the right-blocks perfectly, you could write RIGHT (30%) to give them both a fixed width.  Also, to write a letter in the editor, remember to comment out the title line (use %) so it isn’t visible.

Quotations can be formatted in the same way, with indents and a smaller font size, which is helpful for poetry:

QUOTE ---
. Quote line 1
: Quote line 2 (indented)
, Quote Source
---
Quote line 1
Quote line 2 (indented)
Quote Source

§4.c.ii.

Formatting Tables

We’ve seen in Character Blocks (§4.b) that simple tables are easily arranged with ! and |.  We can control their positioning and width with CENTER and similar functions.  This covers many simple cases.

CENTER (80%) ---
! Header ! Header
| Data goes here | Data goes here
| Data goes here | Data goes here
---

= Table $[t++]. ** A simple table block. 
Header Header
Data goes here Data goes here
Data goes here Data goes here

Table 2.  A simple table block.

But this has obvious limitations.  We would normally obtain data in CSV format, so why not just use that instead of reformatting?

CSV Tables.  If I wanted to display some CSV1 data in a table, but without fiddly reformatting everytime the data had to be updated, I could use the TABLE function to format the data, with formatting instructions given as arguments.2
TABLE (crl$, headers) ---
ID, First Name, Last Name, Salary
123, Felicity, Masters, 160000
7, Clive, Warner, 45000
---

= Table $[t++]. ** Tables from CSV data.
ID First Name Last Name Salary
123 Felicity Masters 160000
7 Clive Warner 45000

Table 3.  Tables from CSV data.

Note.  Article Wiki does not support more complex table features such as row or column spans.  Some more complex formatting can be done with grids.

Grids.  For really large tables.  For clarity it expects === as the row divider and as the column divider.
GRID +++
Ut enim ad minim veniam.

Quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
===
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+++

= Table $[t++]. ** A `GRID` of square areas.

Ut enim ad minim veniam.

Quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Table 4.  A GRID of square areas.


1 Comma Separated Value files.
2 AsciiDoc has previously used this same approach.

§4.c.iii.

Controlling Whitespace

When you want to preserve text exactly, use VERBATIM.  For the same effect, but with wiki formatting, use TEXT, with or without the ‘verse’ option.

VERBATIM ---
1 2  3   *[4]    5
    Excuse me stewardess,
        I speak jive.
---

TEXT ---
1 2  3   *[4]    5
    Excuse me stewardess,
        I speak jive.
---

TEXT (verse) ---
1 2  3   *[4]    5
    Excuse me stewardess,
        I speak jive.
---
1 2  3   *[4]    5
    Excuse me stewardess,
        I speak jive.
1 2  3   4    5
    Excuse me stewardess,
        I speak jive.
1 2  3   4    5
    Excuse me stewardess,
        I speak jive.

§4.d.

Spacers and Dividers

Some patterns of one to three characters have special meaning when used as a paragraph; they create spaces and dividers.  Tilde symbols create vertical space, up to four lines worth for four tildes.

Single space...

~ 

To here. Quadruple space...

~ ~ ~ ~

To here.

Single space…

 

To here.  Quadruple space…

 

 

 

 

To here.

Otherwise, asterisks, periods, dashes, equals and at symbols can be used to make dividers.  Lines made with three characters will be full-width.  Best used sparingly!

* 

- 

- - -

. . .

= = =

* * *





✻ ✻ ✻

A full-width divider in a CENTER block takes the width of that block, if finer width control is needed.  Note the tildes for spacing.

§5.

Adding Information

The most interesting and useful kinds of wiki formatting are those that manage information – links, footnotes, indexes, bibliographies, and more.  Data handling is a central part of Article Wiki’s design.

§5.a.

Values and Counters

In The Index Page (§2) we saw how document information could be supplied with settings.  In Character Blocks (§4.b) we saw how they can be used to control wiki behaviour.  The same syntax lets users store their own values in variables.

Values.  Any values created with a $ setting = value statements can be echoed back with a $[setting] statement.
$ word = Bird
$ date = 1 Jan 2017
$ website = https://article.wiki

; ** $[word] is the word!
; $[website]
; $[date]

Values set in your index.txt can be used in all other sections.  Values can be changed at any point throughout your document, although this only affects the remainder of that section.

$ name = Smith

~ $[name]. // Hello. My
name is $[name].

$ name = Jones

~ $[name]. // I'm $[name].
Good to meet you.
Smith.  Hello.  My name is Smith.
Jones.  I’m Jones.  Good to meet you.
Counters.  If a value, say $[f], is an integer, you can increase it by one and display the new value by writing $[f++].  If unset, the first number will be one.  Counters have been used throughout this document to count tables, images, figures, and so on.
| $[x++] | $[y++] | $[z++]
| $[x++] | $[y++] | $[z++]
| $[x++] | $[y++] | $[z++]

= Table $[t++]. ** A different counter in each column.
1 1 1
2 2 2
3 3 3

Table 5.  A different counter in each column.

§5.c.

Cross References

Article Wiki supports easy cross referencing between the sections of a document.  Entering @[cross-references] will produce a link to the current subheading, Cross References (§5.c), with the section number added for the benefit of print readers.  Entering @[-cross-references], with a minus at the start, will produce an abbreviated reference, in this case §5.c. You will notice them used throughout this document.  At present, only section headings can be cross-referenced.

Matching is performed in this way.  The wiki will look through the table of contents for an exact match, then for the first one that contains all of the terms in the cross reference.  If there is still no match, or if more than one match was found, an error will be displayed.

§5.d.

Citations and Bibliography

While bibliographies can be formatted entirely manually, or with footnotes, there are often better way to work with references.  Bibliographies can be added at the end of each section, or in a single biblio.txt file, or both.

When adding references in a section (rather than in biblio.txt), separate them from the body of your text with a dividing line containing only underscores (10 works well).  Citations appear in round brackets by default, but these can be hidden with a leading minus character.


@ Citation Examples

See ~[Hays 1996] or ~[-Hays 2005].

* ~[Hays 2005, p.26]
* ~[Hays, /Conversion/, p.32]
* See ~[-Hays, /Moral Vision/, p.63].
* ~[ibid, pp.30-32]

For future development...

* ~[loc. cit.]
* ~[Hays, op. cit., p.67]


_____

Hays, Richard B. 1996. The Moral Vision of the New Testament. 1st edition. San Francisco: HarperOne.
Hays, Richard B. 2005. The Conversion of the Imagination: Paul as Interpreter of Israel’s Scripture. Grand Rapids, Mich.: William B. Eerdmans.

Citation Examples

See (Hays 1996)a or Hays 2005.b

For future development…

  • Citation not matched in bibliography.
  • Citation not matched in bibliography.
Hays, Richard B. 1996.  The Moral Vision of the New Testament. 1st edition. San Francisco: HarperOne. (a, e, f).
Hays, Richard B. 2005.  The Conversion of the Imagination: Paul as Interpreter of Israel’s Scripture. Grand Rapids, Mich. : William B. Eerdmans. (b, c, d).

Your bibliography sections should contain only bibliography lines.  This allows easy export from bibliographical software.  In Zotero,1 for instance, use the export option “Create Bibliography from Items”, selecting your preferred citation style and “Output to clipboard”.  Then just paste it into your bibliography block or file.

Note that when a citation simply reads @[ibid], it will be indexed to the previous citation (though op.  cit. does not track previous works, or loc.cit. previous references).

The main thing to remember with cross-references is that the first heading or bibliography entry to match all the words in the reference will be used.  Headings will be checked first.  Any punctuation or markup will be ignored for the purpose of cross-referencing.  See Cross References (§5.c) for more.


1 https://www.zotero.org/

§6.

Cheat Sheet (Print Me!)

Click the Edit button to see how any effect was achieved in an article or section.  This opens that section in the /playground.  That also lets you print a single section – like this cheat sheet!

Character blocks.  Note that captions can be added to tables and headings as well as quotes.

- Document outline (used in index.txt)
@ Subheading
> = Block quote; Caption
* # _ Lists: Bullets, Numbers, Checkboxes
. ; , Alignment: Left, Centre, Right
: ~ Block Indents, Hanging Indents
! | Simple Tables: Headers, Cells
/ Glosses (interlinear translations)
" % Note (visible), Comment (hidden)

Inline Square Brackets.  For incidental formatting…

  • These are combinable, e.g.  /*[bold italic] for bold italic.
  • Some have shorthand: *bold* /italic/ _underline_
  • Some (*/=) can be used as inline subheadings.
/ * _ ` Italic, Bold, Underline, Monospace
+ - ' , Inserted, Deleted, Superscript2, Subscript2
; = | ;[Sans Serif], Small Caps, Highlight

Inline Information Brackets.  For links and other data operations.

§7.

To Do

Next

  • Fully responsive menu with multiple layouts and drop menus.
  • Allow shorthand FUNCTION Blocks.  HEADER/FOOTER as variations of COMPACT.

Bugs

  • Double-stops don’t accommodate trailing punctuation.  Bold. BoldBold. BoldBold. BoldBold. BoldBold. Bold.
  • Inline markup for links clashes with angled brackets: <http://example.org>;.  (Extra semi-colon appears.)  In &gt; the link is matched until the ;.
  • Putting icons in the wrong place in lists .  (Eliminate icons as unused.  Add Unicode completion to editor.)
  • Wrong spacing in e.g.  (pp.  16–17) . Handle brackets/numbers separately, or require backslashes always?

New Features

  • Ability to cycle checkboxes to ticked and sort them by priorities.
  • < < < and > > > for COMPACT headers and footers.
  • Bibliographies should become the last numbered sections and be more easily editable (side link).
  • Machine-readable CC licenses.
  • Self-documentation functions.  For use in /help especially.
  • Vue textarea: Ctrl-Up/Dn to move lines or selected lines; Ctrl-Up/Dn to move blocks or selected blocks.  Regular shortcuts and autocompletions.
  • Login without returning to home page.
  • Plugins.  BIBLE, MATH:jax, MUSIC:ly, SLIDES, QUIZ, etc

Big changes

  • Multiuser through Github logins; retain local admin.
  • Convert Bottle to FastAPI and run in Lambda; use Saas Redis Store.
  • Assemble articles into larger books as .epub/PDF; + in TOC to recurse; syntax to link between books.
  • Airium for faster/neater HTML generation.
  • Fully relative CSS, so that DEMO or QUOTE blocks will have their content stay in proportion.  (Only for one layer deep.)
  • Figures should become the second last numbered section, and allow text-based image formats like SVG or DOT.  (Implement figures as an attachement to a book page section?)
  • Behavioural testing.
  • Containerised for Docker, with a simple import-archive setup.
  • Show cross-references when editing documents._ Login without returning to home page.

Ideas

  • Git integration; committing major version changes and suggested changes; with version incrementing in any part of a document, and in the header.  1.2.3 = Major.Minor.Subminor versions.
  • Outline slides in documents (hidden, -); use section heading and counter as title?  Possibly Abbreviated block type for slides/quizzes, etc?
SLIDE 
* xxx
* yyy
* zzz
  • Inherit settings from parent in hierarchy (ChainMap).
  • Insert standard or customised templates into documents (popover or dropdown)
  • Allow date (or date-updated) to auto-update.
  • QUIZ blocks (?, with answers collated and rotated 180 degrees?)
  • Template imsertion and completion in the editor.  Tab-through and select patterns?

Bibliography

Author. 2000.  /Book Title/. City: Publisher. 3.c. (a, b).
Boyd, Gregory A. 2007.  The Myth of a Christian Nation: How the Quest for Political Power Is Destroying the Church. Grand Rapids, Mich. : Zondervan.
Hays, Richard B. 1996.  The Moral Vision of the New Testament: Community, Cross, New Creation, A Contemporary Introduction to New Testament Ethics. 1st edition. San Francisco: HarperOne.
Hays, Richard B. 2005.  The Conversion of the Imagination: Paul as Interpreter of Israel’s Scripture. Grand Rapids, Mich. : William B. Eerdmans.
Lincoln, Andrew T. 1981.  Paradise Now and Not yet: Studies in the Role of the Heavenly Dimension in Paul’s Thought with Special Reference to His Eschatology. Cambridge; New York: Cambridge University Press.
Thiselton, Anthony C. 2000.  The First Epistle to the Corinthians: A Commentary on the Greek Text. Grand Rapids, Mich. : W. B. Eerdmans.