Article Wiki = Long-form humanities writing in plain text. $ AUTHOR = Nigel Chapman $ EMAIL = nigel@chapman.id.au $ DATE = 26 December 2019 $ SLUG = help $ LICENSE = CC-BY-SA $ site = https://chapman.wiki Article Wiki is an open-source writing tool for the humanities. It is designed for long, structured arguments in plain text. However, it gives you bibliographies and citations, footnotes and links, all without making the plain text unreadable. This means you can do your writing anywhere you can edit plain text, including in collaboration or version control systems -- or offline, and just paste it in when back online. It's a web service, but can download the software, run it yourself, and add new features if you have a little programming skill. It is opinionated about layout, but always readable online and in print. Try it out! CENTER (80%) --- | Playground | $[site]/playground | Source Code | https://github.com/eukras/article-wiki --- This page demonstrates most of Article Wiki's features, starting with @[index-page], 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. ~ - Introduction - - Get Started - - Why Use a Wiki? - The Index Page - - Settings - Inline Markup - - Typography - - Sentence Spacing - - Square Brackets - - Backslashes and Line Breaks - - Special Characters - Four Kinds of Text Blocks - - Paragraphs - - Character Blocks - - - Alignment Blocks - - - Summaries - - - Subheads and Double-stops - - - Quotes and Captions - - - Lists - - - Simple Tables - - - Interlinear Translations - - - Notes and comments - - Function Blocks - - - Text Alignment - - - Formatting Tables - - - Controlling Whitespace - - Spacers and Dividers - Adding Information - - Values and Counters - - Links and Footnotes - - Cross References - - Citations and Bibliography - Cheat Sheet (Print Me!) - To Do .......... 1 introduction .......... 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 .......... Get Started To try writing with the wiki just open the ^[playground] 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] 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. ^ https://chapman.wiki/playground DEMO --- @ 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], 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] for the full tour. DEMO --- # *Bold* # /Italic/ # _Underline_ # `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 `^`. DEMO --- Here's a ^[link] and a ^[footnote]. Article continues... ^ https://example.org ^ 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] below, and then the subsequent sections on indexes and bibliographies. .......... 1.b why-use-a-wiki .......... Why Use a Wiki? " If this is already familiar, skip ahead to @[index-page]. ~ 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] 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 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. DEMO (index) --- My Article = An example of layout. $ 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 does it help you... . Add a new section to a document? : Add it to the outline in the index, and navigate from there. . Reorganise a document's sections? : Change their order in the outline in the index. . Find sections not appearing in the outline? : They appear in a notification box just below it 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 $[t++]. ** 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: # It's easy to rearrange your document by rearranging your outline. # 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. # Your document will be clearly organised when someone later -- maybe you -- has to maintain it. .......... 2.a settings .......... 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 "$[DATE]", for example. You can also make and use your own -- see @[values-counters] 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 .......... 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]. .......... 3.a typography .......... Typography See @[backslashes] for entering plain quotemarks as `\\\'` and `\\\"`. Unicode characters are always supported. DEMO === 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/ === .......... 3.b sentence-spacing .......... 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] for more. DEMO +++ * 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 .......... 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]` | Superscript'[2] | `'` | `Subscript\,[2]` | Subscript,[2] ~ 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] for more. | `$` | `\$[AUTHOR]` | $[AUTHOR] | `$` | `\$[n++], \$[n++], \$[n++]` | $[n++], $[n++], $[n++] | `^` | `\^[Link]` | ^[Link] | `^` | `\^[Footnote]` | ^[Footnote] | `@` | `\@[cross-references]` | @[cross-references] | `@` | `\@[-cross-references]` | @[-cross-references] | `~` | `\~[Author 2000, p.26]` | ~[Author 2000, p.26] | `~` | `\~[Author, \/Title\/, p.32]` | ~[Author, /Title/, p.32] ^ http://example.org ^ Footnote = Table $[t++]. ** Information Control Characters _____ Author. 2000. /Book Title/. City: Publisher. .......... 3.d backslashes-and-line-breaks .......... 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] was entered if you view the wiki text. DEMO --- . \*[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: DEMO --- .
vs. \ . </br> vs. \</br\> --- 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] for more. DEMO --- . Line 1 . Line 2 --- .......... 3.e special-characters .......... Special Characters Use ^[HTML Entities] to enter special characters; e.g. write 'détente' as `d\é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. DEMO --- | α | Γ | á | æ | ç | è | ï | ñ | ô | ¢ | £ | € | ° | ± | ½ | ≤ | ≥ | ≠ | © | ® | ™ | § | ¶ | † | « | » | · --- ^ https://dev.w3.org/html5/html-author/charref .......... 4 four-kinds-of-text-blocks .......... 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 `---`: DEMO === 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*.) === 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 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]. ~ 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 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. CENTER (80%) --- | `@` | Subheadings | `> =` | Block quote; Caption/Citation (smaller font) | `"` | Featured pull quote (floats right, larger font) | `: ~` | Indents: Block, Hanging | `. ; ,` | Align: Left, Centre, Right | `* #` | Lists: Bullets, Numbers (can recurse with `# # #`) | `! |` | Simple Tables: Headers, Cells (smaller font) | `? % _` | Note (visible), Comment (hidden), To Do List | `/` | Translation (interlinear glosses) | `+ -` | Book or Chapter outlines (in `index.txt`; books are *TODO*) --- ~ 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. DEMO --- * This is a single line * This is a single line too. --- .......... 4.b.i alignment-blocks .......... 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. DEMO --- . 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: DEMO --- . Definition title : with the definition here. . Definition title : with the definition here. --- .......... 4.b.ii summaries .......... 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 .......... 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] and @[square-brackets]. DEMO === ; =[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. DEMO === . // 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 @[delimiter]. 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. DEMO === (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. DEMO === 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 .......... Quotes and Captions DEMO --- > 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]. Likewise for captions after quotes. .......... 4.b.v lists .......... Lists Lists have a very simple syntax, whose behaviour can be modified with settings, for example to set the numbering or continue from before. DEMO --- # 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 --- .......... 4.b.vi simple-tables .......... Simple Tables There are better ways to enter table data, but this is sometimes sufficient and extremely simple. See @[formatting-tables] (below). DEMO --- ! Name ! Number | John | 7326532765 | Jane | 6397532340 ksjdh kjsh kdsjh sdkjh dskjh dskjh = Table $[t++]. ** A Table of Numbers --- This is a good way to lay out questions and answers. DEMO --- | 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 .......... 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: DEMO (wide) --- / *[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/ --- - Multiline glosses DEMO (wide) --- / '[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 .......... Notes and comments The `\"` character adds a visible, compact note, with an outline around it. DEMO --- (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. DEMO --- * * * % This text will not be displayed. * * * --- .......... 4.c function-blocks .......... 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. + Examples of Functions 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`. DEMO +++ 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. --- === +++ `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. + Wrapping Function Blocks You can use functions inside other functions so long as you use different delimiters for each layer. Try: | `---` | `===` | `>>>` | `+++` | `:::` | `%%%` | `\/\/\/` .......... 4.c.i text-alignment .......... 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: DEMO +++ 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 --- +++ 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: DEMO +++ QUOTE --- . Quote line 1 : Quote line 2 (indented) , Quote Source --- +++ .......... 4.c.ii formatting-tables .......... Formatting Tables We've seen in @[character-blocks] 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. DEMO +++ CENTER (80%) --- ! Header ! Header | Data goes here | Data goes here | Data goes here | Data goes here --- = Table $[t++]. ** 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 ^[CSV] 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]. ^ Comma Separated Value files. ^ AsciiDoc has previously used this same approach. DEMO === TABLE (crl$, headers) --- ID, First Name, Last Name, Salary 123, Felicity, Masters, 160000 7, Clive, Warner, 45000 --- = Table $[t++]. ** 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. DEMO ::: 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. ::: .......... 4.c.iii controlling-whitespace .......... 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. DEMO === 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. --- === .......... 4.d spacers-and-dividers .......... 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. DEMO === 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! DEMO === * - - - - . . . = = = * * * === 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 .......... 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 .......... Values and Counters In @[index-page] we saw how document information could be supplied with /settings/. In @[character-blocks] 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. DEMO --- $ 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. DEMO --- $ name = Smith ~ $[name]. // Hello. My name is $[name]. $ name = Jones ~ $[name]. // I'm $[name]. 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. DEMO --- | $[x++] | $[y++] | $[z++] | $[x++] | $[y++] | $[z++] | $[x++] | $[y++] | $[z++] = Table $[t++]. ** A different counter in each column. --- .......... 5.b links-and-footnotes .......... Links and Footnotes The wiki will format `\^[this text]` into a link or footnote using the next /contextual link/ in this section. A contextual link is just a character block that begins with a `^` character. See @[character-blocks] for more. Contextual links allows URLs to stay near to the text in which they are used, but without disrupting the flow of that text or affecting its readability. Links and footnotes will both have footnote markers added, since, for the benefit of print readers, links will also be displayed as footnotes. To avoid gaps in formatting, footnote markers will follow any [trailing punctuation: punctuation, trailing]. DEMO --- . This is a ^[link]. . This is a ^[link to myself]. . This is a ^[footnote]. . Text continues... ^ http://example.org ^ http://example.org|rel=me ^ Footnote goes here. --- Footnotes will appear at the end of the full document in which they appear. References can be entered after each paragraph, or at any convenient point in the same section, including at the end, so long as they appear in the same order as the links they will be matched with. When there are many links, it may be more convenient to list them after each paragraph, but this is a matter of personal preference. ~ Links in text. // URLs and email addresses will be turned into links automatically, without footnoting, for example https://example.org or hello@example.org. If you ever want to enter a link and have it /not/ be recognised, you can use @[backslashes] in the protocol (`https://`) or on the `@` character to prevent them being matched. ~ Links with `rel=\"me\"` properties. // To identify a link as pointing to yourself on social media, add `|rel=me` to the end of its footnote link. This will turn into a hidden property of the link tag. (There are presently no other hidden properties that can be controlled in this way.) .......... 5.c cross-references .......... 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], 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 @[-cross-references]. 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 .......... 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. DEMO --- @ 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. --- Your bibliography sections should contain /only/ bibliography lines. This allows easy export from bibliographical software. In ^[Zotero], 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. ^ https://www.zotero.org/ 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] for more. .......... 6 cheat-sheet-print-me .......... 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. CENTER (80%) --- | `-` | 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. CENTER (80%) --- | `/ * _ \`` | /[Italic], *[Bold], _[Underline], `[Monospace] | `+ - ' ,` | +[Inserted], -[Deleted], Superscript'[2], Subscript,[2] | `; = \|` | ;[Sans Serif], =[Small Caps], ![Highlight] --- Inline Information Brackets. // For links and other data operations. CENTER (80%) --- | `$` | @[values-counters] | `^` | @[links-footnotes] | `@` | @[cross-references] | `~` | @[citations-bibliography] --- .......... 7 to-do .......... To Do @ Bugs _ Double-stops don't accommodate trailing punctuation. *Bold.* *Bold*. *Bold.* *Bold*. *Bold.* *Bold*. *Bold.* *Bold*. *Bold.* *Bold*. _ Inline markup for links clashes with angled brackets: . (Extra semi-colon appears.) In `\>` the link is matched until the `;`. _ :n Putting icons in the wrong place in lists :q. @ New Features _ `< < <` 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. @ Big changes _ 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 imagflast numbere formats like SVG or DOT. _ Assemble articles into larger books as .epub/PDF; `+` in TOC to recurse; syntax to link between books. _ Behavioural testing. _ Containerised for Docker, with a simple import-archive setup. _ Auto-index Bible references (if activated by settings? Or as a plugin?) _ 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? VERBATIM --- 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?) .......... _ biblio .......... 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. 2005. The Conversion of the Imagination: Paul as Interpreter of Israel’s Scripture. Grand Rapids, Mich.: William B. Eerdmans. 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. 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.