Text with Instructions (.texti) - Structured Documents in Text with Formatting Conventions

The Best of Markdown, Wikipedia Markup, LaTeX & Friends - All Together Now

Why? Why? Why?

Evolution vs Frozen Forever (100 % Complete)

Is the English language frozen? Is the Python or Ruby scripting language frozen? Is the Hypertext markup language (HTML) frozen?

Let’s welcome the living language. Let’s evolve Markdown. And let’s evolve Wikipedia Markup.

Use what works and don’t use what doesn’t work. Have we learned anything in the last 10+ years? Anyone? Anything?

Hint: AsciiDoc? Have you heard about AsciiDoc?

What’s wrong with AsciiDoc?

The obvious ;-) a silly name, that is, text in 2020 is more than 7 or 8-bit ASCII (American Standard Code for Information Interchange).

More serious - AsciiDoc is a new language. Text with Instructions (.texti) is NOT a new text language - it evolves Markdown and Wikipedia Markup, that is, the majority (lets say 70%) is still Markdown or Wikipedia Markup but with (lets say 20%) deletions (e.g. .. for hard-line breaks, ![]() for image links, etc.) and (lets say 10%) changes (e.g. headings start with =, for example).

Markdown Evolved. 10+ Years Later. Additions. Changes. Deletions.

To repeat: Have we learned anything in the last 10+ years? Anyone? Anything?

Use what works and don’t use what doesn’t work.

Let’s Welcome Wikipedia Markup

A dream… One day Wikipedia Markup and Markdown evolved into one text language. Imagine writing your Wikipedia articles in the same text language as your notes or your next book.

A start let’s change the headings to Wikipedia markup headings = is the # to make Wikipedians feel at home.

Next let’s change page links to Wikipedia links [[...]] is the new [...] and [...] gets only used for “external” links.

What’s wrong with Markdown (.md)?

The name is too clever. Markdown is a play on markup. Up and down. Markdown is markup done right, get it? Sale! Sale! 70 % Markdown! Every Markup Tag Must Go!

The file extension is .markdown, .mdown, .mkdn or .md. Again too cryptic.

Why Text with Instructions?

The idea is that it’s just text, text, text. No clever name that hides the obvious it’s just text. You have a text box? Use text with instructions. It’s just text.

The ideal file extension is .txt or .text. More realistic and pragmatic to avoid confusion with other text formats use .texti or .txti as the “official” Text with Instructions file extensions.

Again the idea is that it’s just text.

What about CommonMark?

CommonMark is great. It has different goals for the evolution of Markdown than Text with Instructions.

The goal of CommonMark is a strictly specified Markdown with hundreds of collected verifable test cases. That’s great. Must I use a space between the heading marker # and the text? Must I use blank line before a heading? And so on.

Text with Instructions evolves Markdown, that is, Deletions. Yes. Deletions. Changes. Additions.

Evolutions

Changes

Headings marker change to Wikipedia Markup (`=` is the new `#`)

= Heading 1 =
== Heading 2 ==
=== Heading 3 ==
==== Heading 4 ==
===== Heading 5 ==
====== Heading 6 ==

or

=Heading 1
==Heading 2
===Heading 3
====Heading 4
=====Heading 5
======Heading 6

Why?

Let’s welcome the Wikipedians. Use the headings convention from Wikipedia Markup.
# is the universal comment (in the unix world). Let’s use the same comment sign for markdown and meta data blocks (in YAML, JSON 1.1, etc.)

More changes.

Headings are headings. Period.

You CANNOT use headings inside lists or code blocks etc. A heading always MUST start on a new line. Period.

Old syntax (Do NOT use):

- ### Big ###
- ## Bigger ##
- # Biggest #

Paragraph
Heading
----               <-- heading 2 marker, please!?
Paragraph

We should not be looking at top-level = setext headings, but second-level - ones, because they’re ambiguous with “thematic breaks”. There are four general ways to parse this:

Paragraph, heading, paragraph

Heading (with 2 lines), paragraph

Paragraph (with 2 lines), separator, paragraph

Paragraph (with 4 lines)

(Source: talk.commonmark.org/t/issues-we-must-resolve-before-1-0-release-8-remaining)

Easy rule in Text with Instructions (.texti). Setext headings MUST be followed by a blank line.

Heading 1
=========

Heading 2
---------

If you do NOT want to use blank lines after headings use = for headings e.g.:

=Heading 1
==Heading 2
===Heading 3
====Heading 4
=====Heading 5
======Heading 6

Note: Using a space between the heading and = is optional. Wikipedia markup uses the “compact” version without any spaces e.g. =Markup language= or ==Type== etc.

Bold / Strong Emphasis

**This is bold**  or **This is a text with strong emphasis**
'''This is bold''' or '''This is a text with strong emphasis'''

Old syntax (Do NOT use):

__This is bold__ or __This is text with strong emphasis__

Text with Instructions (.texti) follows txt2tag and use double underlines for underline e.g.

New syntax:

__This is underlined__

and

--This is strike-through--
or
~~This is strike-through~~

Links change to Wikipedia Markup (`[[...]]` is the new `[...]`)

Why?

Markdown has no links between Markdown pages.

Use triple [[[..]]] for intra page links also known as anchors.
Use double [[..]] for page links.
Use single [..] for “classic” (external) web links.

Note:

Use [^1 ..] for footnotes / references
Use [@see ...] for citations / references

Additions

Comments, Please!

# This is a comment. Where's the heading?

### This is another comment.

A human language without comments - is that human or possible? Let’s welcome # (+space) for single-line comments. Or #### (+space).

Note: The comment marker is # must be followed by a space, that is, #1 or #77 is just regular text.

More comments:

For backwords compatibility HTML comments are supported too:

<!-- This is a comment. Where's the heading? -->

Todo - Also add LaTex comments by default? Why? Why not?

% This is a comment. Where's the heading?
%%  This is another comment.

Meta Data Blocks

You can start a document with a meta data (front matter) block. Example:

---
# this is a meta data block
# this is a comment in the meta data block

...
---

# this is a comment in the text body

== Heading 2 ==

=== Heading 3 ===

Note: You can end a document with a meta data (back matter) block too. Example:

---
See also:
  - Comparison of document markup languages
  - Curl (programming language)
  - List of markup languages
  - Markdown
  - ReStructuredText
  - Programming language
  - Style language

Categories:
  - Markup languages
  - Formal languages
  - American inventions
---

If both are present (front matter and back matter) than they will get (deep) merged.

“Generic” Block and Inline

To be done - like in HTML - generic marker for a block (div) and inline run (span).

:: Note :::::::::::::::::::::::::::::

A paragraph. 

Another paragraph.

- A list item.
- Another list item.

And so on.

:::::::::::::::::::::::::::::::::::::

Note: Use two or more double colons (::) with a block type name e.g. Note, Hint, Warning, Power User Box, David Says or anything.

The type will use a “urlified” name / slug - the optinal trailing (:) gets skipped and all letters will get lowercased e.g.:

Note, NOTE, Note: => note
Hint, HINT, Hint: => hint
Warning => warning
Power User Box => power_user_box
David Says => david_says

Use two or more double colons (::) to end generic marker block.

Use a “compact” version (requires a trailing colon (:) after the box type label e.g. Note:):

:: Note: Keep it simple.

or two or three lines - start all lines with double colons (::):

::::: Note ::::::::::::::::::
:: Keep it simple.

Unicode “pretty” version use box drawing character:

┌─ Note ────────────┐ 
│ Keep it simple.   │
└───────────────────┘

DRAFT - WORK-IN-PROGESS

Deletions

Image Links

Old syntax (Do NOT use):

![](i/cover.png)

Use the new template syntax from Wikipedia markup:

 
{{ fig|cover.png }}

or

{{ img|cover.png }}

DRAFT - WORK-IN-PROGESS

Hard-line Breaks with End-of-Line Space Space (••\n)

Old syntax (Do NOT use):

How doth the little crocodile••
Improve his shining tail,••
And pour the waters of the Nile••
On every golden scale!

Use the new hard-line break syntax (use // or \\):

How doth the little crocodile      //
Improve his shining tail,          //
And pour the waters of the Nile    //
On every golden scale!

Or use the new verbatim (preformatted) block with triple quotes ("""):

"""
How doth the little crocodile
Improve his shining tail,
And pour the waters of the Nile
On every golden scale!
"""

or use Unicode-Text-Art (⌜-top left corner bracket and ⌞-bottom left corner bracket or ⌟ bootom right corner bracket). (Why? Less visible and smaller than """). Even works without requiring its own line for the marker.

⌜
How doth the little crocodile
Improve his shining tail,
And pour the waters of the Nile
On every golden scale!
⌞

⌜How doth the little crocodile
 Improve his shining tail,
 And pour the waters of the Nile
 On every golden scale!⌟

Note: Inside a verbatim (preformatted) block with triple quotes (""") all formatting (e.g. bold, italics, lists, footnotes, code, etc.) works as expected.

No Formatting Blocks

What markers to use for <nowiki>..<nowiki>?

Use !!! e.g.:

!!!
 ...
!!!

Or use “inline” too e.g.:

some text !!!..!!!

Allow just two !! too - why? why not?

Any better alternatives?

WORK-IN-PROGESS

Separators / Horizontal Rulers

A dash-three-times (---) is no longer a separator (horizontal ruler). To avoid confusion --- is reserved for spliting documents into meta data blocks and text blocks.

Use * * * or - - - or -=- or _ _ _ and so on. Or use dash-five-times ----- etc.

Text with Instructions (.texti) @ GitHub

Text with Instructions (.texti) Samples

Article - Markup language

.texti Source:

samples/Markup_language.texti.txt

(Auto-)Generated Formats:

samples/Markup_language.md.txt - Markdown
samples/Markup_language.latex.txt - LaTeX
samples/Markup_language.html - Hypertext Markup Language (HTML)

(Source: Markup language @ Wikipedia, Wikimedia Markup Source Text)

What’s different?

Text with Instructions (.texti) Compared to Wikipedia Markup

(Inline) References

[^1|{{MerriamWebsterDictionary|markup language}}]

-or-

[^2|Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]]

-or-

[^3|{{cite web
  |last=Bray|first=Tim|authorlink=Tim Bray
  |url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
  |title=On Semantics and Markup, Taxonomy of Markup
  |website=www.tbray.org/ongoing
  |date=9 April 2003
  |access-date=9 July 2015}}]

Note: The number e.g. ^1 is “symbolic”, that is, it’s a placeholder - you can write ^1 ^1 ^1 as often as you like (when generated references will get auto-numbered).

<ref>{{MerriamWebsterDictionary|markup language}}</ref>

-or-

<ref>Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]</ref>

-or-

<ref>{{cite web|last=Bray|first=Tim|authorlink=Tim Bray
|url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
|title=On Semantics and Markup, Taxonomy of Markup
|website=www.tbray.org/ongoing
|date=9 April 2003
|access-date=9 July 2015}}</ref>

Inline Code

An example of descriptive markup would be HTML's `<cite>` tag.

-or-

The codes `h1`, `p`, and `em` are examples of semantic markup.

An example of descriptive markup would be HTML's <code>&lt;cite></code> tag.

-or-

The codes <code>h1</code>, <code>p</code>, and <code>em</code> are examples of semantic markup.

Appendix

Wikipedia Markup Cheatsheet for Text with Instructions (.texti)

What’s news? What’s different?

Notes: no changes. changes

Text Formatting

Italic / Emphasis

''italic text'' or
''emphasized text''

Additions. Alternative Syntax

_italic text_ or
*emphasized text*

Bold / Strong Emphasis

'''bold text''' or
'''strongly emphasized text'''

Additions. Alternative Syntax

**bold text** or
**strongly emphasized text**

Italic + Bold

'''''italic bold text''''' or
'''''strongly emphasized emphasized text'''''

Bulleted List

* Wikipedia
* Encyclopédie

Additions. Alternative Syntax

- Wikipedia
- Encyclopédie

+ Wikipedia
+ Encyclopédie

Numbered List

Old syntax

# A - Azymites
# B - Cézimbra

Why?

# (+space) is reserved / used for comments e.g. # this is a comment.

New syntax:

1. A - Azymites
2. B - Cézimbra

1. A - Azymites
1. B - Cézimbra

Note: Use the same number to use the number as placeholder as before (will get auto-numbered).

Or use roman numberals, the alphabet, etc.

 I. A - Azymites
II. B - Cézimbra

a. A - Azymites
b. B - Cézimbra

Headings

=Heading 1 Text=
==Heading 2 Text==
===Heading 3 Text===
====Heading 4 Text====
=====Heading 5 Text=====
======Heading 6 Text======

Additions. Alternative Syntax for Heading 1 and Heading 1

Heading 1
=========

Heading 2
---------

Links

Internal `[[..]]`

Internal Link (to another page)

[[Denis Diderot]]

Internal Link with Different Text

[[Denis Diderot|Diderot]]

External `[..]`

Link to another website

[http://loc.gov]
[http://loc.gov Library of Congress Website]

Additions. Alternative Syntax

[Library of Congress Website | http://loc.gov]
[Library of Congress Website  url=http://loc.gov]

DISCUSS - make separator | optional - why? why not ???
DISCUSS - keep url= version - why? why not???

[Library of Congress Website](http://loc.gov)

Reference style:

[Library of Congress Website][1]

...

[1]: http://loc.gov

(Inline) References

Old syntax (Do NOT use).

<ref>{{MerriamWebsterDictionary|markup language}}</ref>

-or-

<ref>Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]</ref>

-or-

<ref>{{cite web|last=Bray|first=Tim|authorlink=Tim Bray
|url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
|title=On Semantics and Markup, Taxonomy of Markup
|website=www.tbray.org/ongoing
|date=9 April 2003
|access-date=9 July 2015}}</ref>

Why change <ref> to [^]?

The idea of Texti is to be format independent - that is - Texti instructions should not look like html tags or latex commands, for example. Text with instructions tries to be “orthogonal” to html and latex. The idea is that you can easily mix and match texti with html or latex without escaping one or the other e.g. how do you know that <ref> is NOT an html tag or <references>? Simple, use [^] and {{references}} - if it looks like a html tag it is a html tag, if it doesn’t it doesn’t, that’s by design :-).

New (Inline) References:

[^1|{{MerriamWebsterDictionary|markup language}}]

-or-

[^2|Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]]

-or-

[^3|{{cite web
  |last=Bray|first=Tim|authorlink=Tim Bray
  |url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
  |title=On Semantics and Markup, Taxonomy of Markup
  |website=www.tbray.org/ongoing
  |date=9 April 2003
  |access-date=9 July 2015}}]

Note: The number e.g. ^1 is “symbolic”, that is, it’s a placeholder - you can write ^1 ^1 ^1 as often as you like (when generated references will get auto-numbered).

Or use the refrence form or reference short form or use “classic” daggers († ‡):

yada yada [^1] yada yada yada [^2][^3] yada yada


^1: {{MerriamWebsterDictionary|markup language}}
^2: Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]
^3: {{cite web
  |last=Bray|first=Tim|authorlink=Tim Bray
  |url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
  |title=On Semantics and Markup, Taxonomy of Markup
  |website=www.tbray.org/ongoing
  |date=9 April 2003
  |access-date=9 July 2015}}
  
-or-

yada yada [^] yada yada yada [^^][^^^] yada yada

^:  {{MerriamWebsterDictionary|markup language}}
^^:  Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]
^^^: {{cite web
  |last=Bray|first=Tim|authorlink=Tim Bray
  |url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
  |title=On Semantics and Markup, Taxonomy of Markup
  |website=www.tbray.org/ongoing
  |date=9 April 2003
  |access-date=9 July 2015}}

-or-

yada yada† 

†: {{MerriamWebsterDictionary|markup language}}

yada yada yada†‡ yada yada

†: Michael Downes. [http://www.ams.org/notices/200211/comm-downes.pdf "TEX and LATEX 2e"]
‡: {{cite web
  |last=Bray|first=Tim|authorlink=Tim Bray
  |url=http://www.tbray.org/ongoing/When/200x/2003/04/09/SemanticMarkup#p-1
  |title=On Semantics and Markup, Taxonomy of Markup
  |website=www.tbray.org/ongoing
  |date=9 April 2003
  |access-date=9 July 2015}}

Categories, See also, etc.

As an easier alternative use meta data (back matter) for categories, see also, etc. Example:

---
Categories:
  - Markup languages
  - Formal languages
  - American inventions

See also:
  - Comparison of document markup languages
  - Curl (programming language)
  - List of markup languages
  - Markdown
  - ReStructuredText
  - Programming language
  - Style language
---

Using a page template, for example, you can turn your categories (automagically) into links and more.

Markdown Cheatsheet for Text with Instructions (.texti)

Fixing (Evolving) Markdown - Deletions. Yes. Deletions. Changes. Additions.

Design Principles

NEVER FORGET - IT’S DESIGNED FOR WRITING BY HUMANS
- Offer alternatives. There’s more than one way to do it. Sometimes even more alternatives is the better way e.g. see the new link alternatives - id first? yes, id second? yes - why not?, without () why not?, etc.).

Strict (Enterprise-y) Version

For Python fans. There’s only one way to do it. Offer a “strict” profile or recommendations on usage. FUTURE (NOT IMPORTANT)

What’s news? What’s different?

Notes: Works. Old syntax (Do NOT use).

Text Formatting

Italic / Emphasis

Intra-word emphasis with underscores does NOT work anymore.

print_hello_world    <--  just regular text

Why?

Intra-word use of underscore (_) is quite common for replacing spaces in wikipedia, tags, scripts, numbers, etc.

Bold / Emphasis

Double underscore (__) alternative. Old syntax. Do NOT use:

This is __no longer bold__ or text with __strong emphasis__.

Why?

Double underscore is reserved for underline.

This is now __underlined__.

Headings

Heading marker (#). Old syntax. Do NOT use:

# Heading 1 #
## Heading 2 ##
### Heading 3 ###
#### Heading 4 ####
##### Heading 5 #####
###### Heading 6 ######

Headings marker change to Wikipedia Markup (= is the new #) e.g.:

=Heading 1
==Heading 2
===Heading 3
====Heading 4
=====Heading 5
======Heading 6

Why?

Let’s welcome the Wikipedians. Use the headings convention from Wikipedia Markup.
# is the universal comment (in the unix world). Let’s use the same comment sign for markdown and meta data blocks (in YAML, JSON 1.1, etc.)

More changes.

Headings are headings. Period.

You CANNOT use headings inside lists or code blocks etc. A heading always MUST start on a new line. Period.

Old syntax (Do NOT use):

- ### Big ###
- ## Bigger ##
- # Biggest #

Paragraph
Heading
----               <-- heading 2 marker, please!?
Paragraph

We should not be looking at top-level = setext headings, but second-level - ones, because they’re ambiguous with “thematic breaks”. There are four general ways to parse this:

Paragraph, heading, paragraph

Heading (with 2 lines), paragraph

Paragraph (with 2 lines), separator, paragraph

Paragraph (with 4 lines)

(Source: talk.commonmark.org/t/issues-we-must-resolve-before-1-0-release-8-remaining)

Easy rule in Text with Instructions (.texti). Setext headings MUST be followed by a blank line.

Heading 1
=========

Heading 2
---------

If you do NOT want to use blank lines after headings use = for headings e.g.:

=Heading 1
==Heading 2
===Heading 3
====Heading 4
=====Heading 5
======Heading 6

Note: Using a space between the heading and = is optional. Wikipedia markup uses the “compact” version without any spaces e.g. =Markup language= or ==Type== etc.

“Generic” Inline Block

> Note:
>

The “old” quotation block is now a “generic” inline block e.g. in html think div with a class instead of blockquote tag.

DRAFT - WORK-IN-PROGESS

Image Links

Old syntax (Do NOT use):

![](i/cover.png)

Use the new template syntax from Wikipedia markup:

 
{{ fig|cover.png }}

or

{{ img|cover.png }}

DRAFT - WORK-IN-PROGESS

Hard-line Breaks with End-of-Line Space Space (••\n)

Old syntax (Do NOT use):

How doth the little crocodile••
Improve his shining tail,••
And pour the waters of the Nile••
On every golden scale!

Use the new hard-line break syntax (use // or \\):

How doth the little crocodile      //
Improve his shining tail,          //
And pour the waters of the Nile    //
On every golden scale!

Or use the new verbatim (preformatted) block with triple quotes (""") or ('''):

"""
How doth the little crocodile
Improve his shining tail,
And pour the waters of the Nile
On every golden scale!
"""

Note: Inside a verbatim (preformatted) block with triple quotes (""") or (''') all formatting (e.g. bold, italics, lists, code, footnotes, etc.) works as expected.

Text with Instructions (.texti) - Structured Documents in Text with Formatting Conventions

Why? Why? Why?

What’s wrong with AsciiDoc?

Markdown Evolved. 10+ Years Later. Additions. Changes. Deletions.

Let’s Welcome Wikipedia Markup

What’s wrong with Markdown (.md)?

What about CommonMark?

Evolutions

Changes

Headings marker change to Wikipedia Markup (= is the new #)

Bold / Strong Emphasis

Links change to Wikipedia Markup ([[...]] is the new [...])

Additions

Comments, Please!

Meta Data Blocks

“Generic” Block and Inline

Deletions

Image Links

Hard-line Breaks with End-of-Line Space Space (••\n)

No Formatting Blocks

Separators / Horizontal Rulers

Text with Instructions (.texti) Samples

Article - Markup language

What’s different?

Appendix

Wikipedia Markup Cheatsheet for Text with Instructions (.texti)

Text Formatting

Italic / Emphasis

Bold / Strong Emphasis

Italic + Bold

Bulleted List

Numbered List

Headings

Links

Internal [[..]]

External [..]

(Inline) References

Categories, See also, etc.

Markdown Cheatsheet for Text with Instructions (.texti)

Text Formatting

Italic / Emphasis

Bold / Emphasis

Headings

“Generic” Inline Block

Image Links

Hard-line Breaks with End-of-Line Space Space (••\n)

Meta

Headings marker change to Wikipedia Markup (`=` is the new `#`)

Links change to Wikipedia Markup (`[[...]]` is the new `[...]`)

Internal `[[..]]`

External `[..]`