Type-able Text Markup for Structured Writing
TypeText Markup -- Text Elements
=========================
Christian Augustin
2011-08-01
en-US
2012-10-30 Draft
~~~~
In TypeText, :text elements: are special inline elements like images, cross references (a.k.a. "links"), callout numbers, abbreviations, numbers and formulas.
~~~~
-------------------------------------------
Inline Images !!Changed 2012-10-30!!
Text with ![image URL][Alt text] inline image.
The image URL can be one of these variants:
![Image File Name] (Document image of unspecified file type)
![Image File Name.ext] (Document image)
![/Image File Name] (Image from central pool)
![Document title/Image File Name] (Image from different document)
![Document title -- Image File name] (dito)
![http://typetext.info/favicon.png] (external image URL)
????
*TBD:* Image with a link around it; could be done by allowing images to be part of the link text (the "HTML way") or by extending the image syntax with a reference feature (rather complex - better use the HTML way ...).
To allow images in references it would be best to avoid double quotes in the image markup to simplify parsing. That's sad, because alt text is begging for them ...
????
-----------------------------------------
Cross References (Links) !!Changed 2012-10-21!!
->"Document Title or URL"
->"Document Title or URL"[]
->"Link text"[Document Title or URL]
->""[Document Titel or URL]
->[Document Title or URL]
->URL
URL
Special cases:
-> "Link text" [URL] - optional spaces
->^"Document Title" - open in new window
->_"Download Title"[URL] - download link
->"Wikipedia: Form follows function" - Wikipedia link (page language version)
->"Wikipedia (de): Form follows function" - German Wikipedia
*Rationale:* The first two characters resemble a link arrow and therefor give a clear indication of what the following text means.
-----------------------------------------
Callout Numbers
This is a callout number: \<1>
Callout numbers have to be numbers (one or two decimal digits) or up to two letters or a combination (e.g. `<1a>`) - there is no more room in a traditional, circled callout number.
Those looking at the source of this page may be curious about the backslash: Callout numbers are still recognized in code blocks, so at least the less-than sign has to be escaped.
This is inspired by AsciiDoc.
-----------------------------------------
Abbreviations and Acronyms
To mark abbreviations and acronyms, and to include the unabbreviated from, the abbreviation is directly followed by a pair of square brackets:
i.e.[that is]
e.g.[for example]
WMF[Windows Metafile] or PNG[]
z.B. or z._B. or z.B.[zum Beispiel]
abbr.[]
The last example shows a way to mark an abbreviation without giving the full length form. While abbreviations like "`i.e.`" can be recognized by a parser and handled accordingly, abbreviations with only one dot and acronyms are much harder and would need a language specific abbreviation dictionary.
*Attention!* Abbreviations should be written always without spaces, even in languages that would normally recommend them (e.g. German); the space can be given as a non-breakable space (underscore), but it is inserted in the output by the parser if necessary. This prevents unwanted line breaks inside the abbreviation in the plain text form and can be handled correctly by the parser (e.g. inserting small spaces in German abbreviations).
-----------------------------------------
Numbers and Units
Numbers and especially numbers followed by units should be written in one of these forms:
10_m^2, 10_kg, 10kg
10_000.00
10,000.00
10^2
2.3e-10
2.3x10^-10
In this way numbers and units are kept together at line endings and can be treated correctly by a parser. The parser can also do some typographically correct treatment of numbers and units (e.g. substituting the thousands separators and spaces by small spaces).
*Tip:* To get full spaces between digits the numbers have to be written with normal spaces instead of underscores; use no-break markup to prevent line breaks:
[.nobr]##BLZ 100 400 00##
-----------------------------------------
Formulas
$$...$$
Inside of a formula a simpler notation for sub- and superscript can be used (as with TeX formulas) and some special characters change their meaning. A formula uses smaller spaces than normal text, but it does break across lines.
=========================
Christian Augustin
2011-08-01
en-US
2012-10-30 Draft
~~~~
In TypeText, :text elements: are special inline elements like images, cross references (a.k.a. "links"), callout numbers, abbreviations, numbers and formulas.
~~~~
-------------------------------------------
Inline Images !!Changed 2012-10-30!!
Text with ![image URL][Alt text] inline image.
The image URL can be one of these variants:
![Image File Name] (Document image of unspecified file type)
![Image File Name.ext] (Document image)
![/Image File Name] (Image from central pool)
![Document title/Image File Name] (Image from different document)
![Document title -- Image File name] (dito)
![http://typetext.info/favicon.png] (external image URL)
????
*TBD:* Image with a link around it; could be done by allowing images to be part of the link text (the "HTML way") or by extending the image syntax with a reference feature (rather complex - better use the HTML way ...).
To allow images in references it would be best to avoid double quotes in the image markup to simplify parsing. That's sad, because alt text is begging for them ...
????
-----------------------------------------
Cross References (Links) !!Changed 2012-10-21!!
->"Document Title or URL"
->"Document Title or URL"[]
->"Link text"[Document Title or URL]
->""[Document Titel or URL]
->[Document Title or URL]
->URL
URL
Special cases:
-> "Link text" [URL] - optional spaces
->^"Document Title" - open in new window
->_"Download Title"[URL] - download link
->"Wikipedia: Form follows function" - Wikipedia link (page language version)
->"Wikipedia (de): Form follows function" - German Wikipedia
*Rationale:* The first two characters resemble a link arrow and therefor give a clear indication of what the following text means.
-----------------------------------------
Callout Numbers
This is a callout number: \<1>
Callout numbers have to be numbers (one or two decimal digits) or up to two letters or a combination (e.g. `<1a>`) - there is no more room in a traditional, circled callout number.
Those looking at the source of this page may be curious about the backslash: Callout numbers are still recognized in code blocks, so at least the less-than sign has to be escaped.
This is inspired by AsciiDoc.
-----------------------------------------
Abbreviations and Acronyms
To mark abbreviations and acronyms, and to include the unabbreviated from, the abbreviation is directly followed by a pair of square brackets:
i.e.[that is]
e.g.[for example]
WMF[Windows Metafile] or PNG[]
z.B. or z._B. or z.B.[zum Beispiel]
abbr.[]
The last example shows a way to mark an abbreviation without giving the full length form. While abbreviations like "`i.e.`" can be recognized by a parser and handled accordingly, abbreviations with only one dot and acronyms are much harder and would need a language specific abbreviation dictionary.
*Attention!* Abbreviations should be written always without spaces, even in languages that would normally recommend them (e.g. German); the space can be given as a non-breakable space (underscore), but it is inserted in the output by the parser if necessary. This prevents unwanted line breaks inside the abbreviation in the plain text form and can be handled correctly by the parser (e.g. inserting small spaces in German abbreviations).
-----------------------------------------
Numbers and Units
Numbers and especially numbers followed by units should be written in one of these forms:
10_m^2, 10_kg, 10kg
10_000.00
10,000.00
10^2
2.3e-10
2.3x10^-10
In this way numbers and units are kept together at line endings and can be treated correctly by a parser. The parser can also do some typographically correct treatment of numbers and units (e.g. substituting the thousands separators and spaces by small spaces).
*Tip:* To get full spaces between digits the numbers have to be written with normal spaces instead of underscores; use no-break markup to prevent line breaks:
[.nobr]##BLZ 100 400 00##
-----------------------------------------
Formulas
$$...$$
Inside of a formula a simpler notation for sub- and superscript can be used (as with TeX formulas) and some special characters change their meaning. A formula uses smaller spaces than normal text, but it does break across lines.