├── notes-per-slide-long.pdf
├── notes-per-slide-short.pdf
├── markup-history-long-16x9.pdf
├── markup-history-long-4x3.pdf
├── markup-history-short-4x3.pdf
├── cc-attribution-sharealike-88x31.png
├── .gitignore
├── Makefile
├── unused-slides.txt
├── README.rst
├── markup-history-short.rst
├── markup-history-long.rst
├── markup-history-long-wide.rst
├── assorted-text.txt
├── notes-per-slide-short.rst
├── notes-per-slide-long.rst
└── markup-history-extended-notes.rst


/notes-per-slide-long.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/notes-per-slide-long.pdf


--------------------------------------------------------------------------------
/notes-per-slide-short.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/notes-per-slide-short.pdf


--------------------------------------------------------------------------------
/markup-history-long-16x9.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/markup-history-long-16x9.pdf


--------------------------------------------------------------------------------
/markup-history-long-4x3.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/markup-history-long-4x3.pdf


--------------------------------------------------------------------------------
/markup-history-short-4x3.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/markup-history-short-4x3.pdf


--------------------------------------------------------------------------------
/cc-attribution-sharealike-88x31.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tibs/markup-history/HEAD/cc-attribution-sharealike-88x31.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Editor artefacts
 2 | *.swo
 3 | *.swp
 4 | *~
 5 | 
 6 | # Generated files
 7 | *.html
 8 | 
 9 | # Hovercraft artefacts
10 | slides/
11 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | # This version of the Makefile assumes that pandoc and (enough of) TeX are
 2 | # available.
 3 | 
 4 | .PHONY: default
 5 | default: html pdf
 6 | 
 7 | # We don't try to provide an HTML version of the slides in this version
 8 | # - use the PDF produces by 'slides' instead.
 9 | # For various reasons, pandoc won't render markup-history-extended-notes.rst
10 | # as PDF, so we don't bother.
11 | .PHONY: html
12 | html:
13 | 	rst2html.py README.rst README.html
14 | 	# github's rendering of reStructuredText uses Linguist to syntax
15 | 	# highlight code. Unfortunately, it knows the name "roff" for roff
16 | 	# style code, whilst pygments, used by rst2html.py, does not recognise
17 | 	# that name. So we shall make do by converting on the fly...
18 | 	sed -e 's/:: roff/:: groff/' markup-history-extended-notes.rst | rst2html.py > markup-history-extended-notes.html
19 | 
20 | # The available aspect ratio of slides (for beamer only) are 1610 for 16:10,
21 | # 169 for 16:9, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 43 for 4:3 which is
22 | # the default, and 32 # for 3:2. It's probably enough to go for the following
23 | # pair of resolutions.
24 | # We also make the notes-per-slide as PDF, because we can and it might be useful.
25 | .PHONY: pdf
26 | pdf: slides notes
27 | 
28 | .PHONY: slides
29 | slides: markup-history-long-4x3.pdf markup-history-long-16x9.pdf markup-history-short-4x3.pdf
30 | 
31 | .PHONY: notes
32 | notes: notes-per-slide-long.pdf notes-per-slide-short.pdf
33 | 
34 | markup-history-long-4x3.pdf: markup-history-long.rst
35 | 	pandoc $< -t beamer -o $@ -V aspectratio:43
36 | 
37 | markup-history-long-16x9.pdf: markup-history-long-wide.rst
38 | 	pandoc $< -t beamer -o $@ -V aspectratio:169
39 | 
40 | markup-history-short-4x3.pdf: markup-history-short.rst
41 | 	pandoc $< -t beamer -o $@ -V aspectratio:43
42 | 
43 | notes-per-slide-long.pdf: notes-per-slide-long.rst
44 | 	pandoc $< -o $@ -V papersize:a4
45 | 
46 | notes-per-slide-short.pdf: notes-per-slide-short.rst
47 | 	pandoc $< -o $@ -V papersize:a4
48 | 
49 | .PHONY: clean
50 | clean:
51 | 	rm -f *.html
52 | 
53 | .PHONY: help
54 | help:
55 | 	@echo 'make         same as: make html slides'
56 | 	@echo 'make pdf     create markup-history-*-[4x3|16x9].pdf and notes-per-slide-*.pdf'
57 | 	@echo 'make html    create HTML files using rst2html'
58 | 	@echo 'make clean   delete HTML files'
59 | 


--------------------------------------------------------------------------------
/unused-slides.txt:
--------------------------------------------------------------------------------
  1 | ======================================
  2 | Slides removed due to time constraints
  3 | ======================================
  4 | 
  5 | To get it down to roughly 40 minutes
  6 | 
  7 | ----
  8 | 
  9 | Digital Standard Runoff
 10 | -----------------------
 11 | 
 12 | .. code:: roff
 13 | 
 14 |     .TITLE A simpler DSR example
 15 |     .CHAPTER This is a chapter
 16 | 
 17 |     This is the first paragraph.
 18 |     .LIST
 19 |     .LIST ELEMENT;This is a list element. We have *bold\* and
 20 |     &underline\&.
 21 |     .LIST ELEMENT;This is another list element. I like
 22 |     interrobangs ?%!
 23 |     .END LIST
 24 | 
 25 | .. note:: I'm not sure anyone else is interested in DSR, and I don't think
 26 |    it gives any extra information over talking about the roffs in general.
 27 |    Perhaps mention it in passing.
 28 | 
 29 | ----
 30 | 
 31 | 2009: Docbook 5
 32 | ---------------
 33 | 
 34 | ::
 35 | 
 36 |    <?xml version="1.0" encoding="UTF-8"?>
 37 |    <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
 38 |      <title>Very simple book</title>
 39 |      <chapter xml:id="chapter_1">
 40 |        <title>Chapter 1</title>
 41 |        <para>Hello world!</para>
 42 |        <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
 43 |      </chapter>
 44 |      <chapter xml:id="chapter_2">
 45 |        <title>Chapter 2</title>
 46 |        <para>Hello again, world!</para>
 47 |      </chapter>
 48 |    </book>
 49 | 
 50 | .. note:: **skippable** Docbook 5
 51 | 
 52 |    Example from wikipedia (for Docbook 5, which is relatively recent).
 53 | 
 54 |    DocBook 5 is an XML language, formally defined by a RELAX NG schema with
 55 |    integrated Schematron rules.
 56 |  
 57 | ----
 58 | 
 59 | 1994: POD
 60 | ---------
 61 | 
 62 | ::
 63 | 
 64 |   =pod
 65 | 
 66 |   =head1 DESCRIPTION
 67 | 
 68 |   This is not I<really> representative of POD usage.
 69 | 
 70 |   =over 2
 71 | 
 72 |   =item This is a list item.
 73 | 
 74 |   =item This is another list item.
 75 | 
 76 |   =back
 77 | 
 78 |   =cut
 79 | 
 80 | .. note:: 1994 POD *Presentational*. Still in use today.
 81 | 
 82 |   Perl's "Plain Old Documentation".
 83 | 
 84 |   Same year as wikiwikiweb
 85 | 
 86 |   An example of markup to a specific purpose, and clearly very successful.
 87 | 
 88 |   Note that the blank lines are required around the POD commands.
 89 | 
 90 |   I don't think you can do multi-paragraph list items. The POD definitions
 91 |   contains ambuguities, although how to handle some of them is explained in
 92 |   the POD documentation.
 93 | 
 94 | ----
 95 | 
 96 | 1995: Javadoc
 97 | -------------
 98 | 
 99 | ::
100 | 
101 |   /**
102 |    * Short one line description.
103 |    * <p>
104 |    * Longer description. If there were any, it would be here.
105 |    * <p>
106 |    * And even more explanations to follow in consecutive
107 |    * paragraphs separated by HTML paragraph breaks.
108 |    *
109 |    * @param  variable Description text text text.
110 |    * @return Description text text text.
111 |    */
112 |   public int methodName (...) {
113 |       // ...
114 |   }
115 | 
116 | .. note::  **skippable** javadoc
117 | 
118 |   1995 javadoc *Presentational*. Still in use today.
119 | 
120 |   Has never specified the subset of HTML it allows.
121 | 
122 | ----
123 |  
124 | 1991: setext
125 | ------------
126 | 
127 | ::
128 | 
129 |   Why setext?
130 |   -----------
131 | 
132 |     I agree that FAQ's would best be written in something like setext_.
133 |     Why?  Because this document is written in setext and it includes
134 |     the ability to embed HTML hypertext links without being obnoxious.
135 | 
136 |     As you can see it's easy to write setext documents, and as Edward
137 |     pointed out, it uses existing text conventions for **bold** and _italic_
138 |     words and titles.
139 | 
140 |   .. _setext http://www.bsdi.com/setext/
141 |   ..
142 | 
143 | .. note:: 1991 setext *Presentational*. Lightweight.
144 | 
145 |   Ian Feldman, for use in writing the TidBITs electronic newsletter.
146 | 
147 |   Excerpted from a document called "Why setext".
148 | 
149 |   Partly a reaction to SGML. Clearly influential on
150 |   all of the succeeding lightweight markups.
151 | 
152 |   Same year as HTML
153 | 
154 | ----
155 | 
156 | ----
157 | 
158 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
159 | 


--------------------------------------------------------------------------------
/README.rst:
--------------------------------------------------------------------------------
  1 | A history of markup languages
  2 | =============================
  3 | 
  4 | This is a slideshow originally produced for `PyCon UK 2017`_.
  5 | 
  6 | History
  7 | ~~~~~~~
  8 | * The version presented at `Write the Docs Prague 2018`_ can be found at tag
  9 |   WriteTheDocs_Prague_2018_
 10 | 
 11 |   The "short" version of the slides is as actually presented at 
 12 |   `Write the Docs Prague 2018`_. It is meant to be about 30 minutes long.
 13 |   You can see it `as recorded at WtD Prague 2018`_. This verson *was* 30
 14 |   minutes long.
 15 | 
 16 |   The "long" version of the slides here is as presented at `Write the Docs
 17 |   Cambridge`_ in `February 2018`_. It is meant to be about 40-45 minutes
 18 |   long.
 19 |   
 20 |   I also gave this longer version of the talk at work in May 2018.
 21 | 
 22 | * The version presented at `PyCon UK 2017`_ can be found at tag pycon-uk-2017_.
 23 |   You can see it `as recorded at PyCon UK 2017`_. This version was 30 minutes long.
 24 | 
 25 | * The earlier version given to CamPUG_ in `October 2017`_ can be found at tag
 26 |   campug-oct-2017_. It was about 45 minutes long.
 27 | 
 28 | The files
 29 | ~~~~~~~~~
 30 | All sources are in reStructuredText_, and thus intended to be readable as
 31 | plain text.
 32 | 
 33 | * The sources for the slides are in `<markup-history.rst>`_ and
 34 |   `<markup-history-wide.rst>`_ (customised for 4x3 and 16x9 respectively,
 35 |   although they're actually the same bar some formatting).
 36 | * Notes per slide (for the presenter) are separated out into `<notes-per-slide.rst>`_.
 37 | * Extended notes (with links) are in `<markup-history-extended-notes.rst>`_.
 38 | 
 39 | (Note that github will present the ``.rst`` files in rendered form as HTML,
 40 | albeit using their own styling (which makes notes a bit odd). If you want
 41 | to see the original reStructuredText source, you have to click on the "Raw"
 42 | link at the top of the file's page.)
 43 | 
 44 | Since this version of the talk uses PDF slides, which I produce via pandoc_
 45 | and TeX_, I'm including the resultant PDF files in the repository. These
 46 | will not necessarily be as up-to-date as the source files, so check their
 47 | timestamps.
 48 | 
 49 | There are two versions of the slides here - the shorter (about 25 minutes)
 50 | version, and the longer (about 45 minutes) version.
 51 | 
 52 | * Longer:
 53 | 
 54 |   * The 4x3 aspect ratio slides are `<markup-history-long-4x3.pdf>`_.
 55 |   * The 16x9 aspect ratio slides are `<markup-history-long-16x9.pdf>`_.
 56 |   * There is a PDF version of the notes per slide in `<notes-per-slide-long.pdf>`_.
 57 | 
 58 | * Shorter:
 59 | 
 60 |   * The 4x3 aspect ratio slides are `<markup-history-short-4x3.pdf>`_.
 61 |   * There is a PDF version of the notes per slide in `<notes-per-slide-short.pdf>`_.
 62 | 
 63 | Making the PDF and HTML files
 64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 65 | For convenience, you can use the Makefile to create the PDF slides, create the
 66 | HTML version of the extended notes, and so on. For instance::
 67 | 
 68 |   $ make pdf
 69 | 
 70 | will make the PDF files.
 71 | 
 72 | For what the Makefile can do, use::
 73 | 
 74 |   $ make help
 75 | 
 76 | Requirements to build the documents:
 77 | 
 78 | * pandoc_ and TeX_ (on mac, BasicTeX should be enough). Not needed if you're
 79 |   just going to do ``make html``.
 80 | * docutils_ (for reStructuredText_).
 81 | 
 82 | and an appropriate ``make`` program if you want to use the Makefile.
 83 | 
 84 | .. _`Write the Docs Prague 2018`: https://www.writethedocs.org/conf/prague/2018/
 85 | .. _`PyCon UK 2017`: http://2017.pyconuk.org/
 86 | .. _CamPUG: https://www.meetup.com/CamPUG/
 87 | .. _`write the docs cambridge`: https://www.meetup.com/Write-The-Docs-Cambridge/events/246750191/
 88 | .. _`February 2018`: https://www.meetup.com/Write-The-Docs-Cambridge/events/246750191/
 89 | .. _`October 2017`: https://www.meetup.com/CamPUG/events/tpcsxlywnbfb/
 90 | .. _`as recorded at PyCon UK 2017`: https://www.youtube.com/watch?v=qQMXPXzrE_s
 91 | .. _`as recorded at WtD Prague 2018`: https://www.youtube.com/watch?v=P-7hwjocEpM&list=PLZAeFn6dfHplRZcYDQjST22bAVeeWML4d&t=0s&index=22
 92 | .. _campug-oct-2017: https://github.com/tibs/markup-history/tree/campug-oct-2017
 93 | .. _pycon-uk-2017: https://github.com/tibs/markup-history/tree/pycon-uk-2017
 94 | .. _WriteTheDocs_Prague_2018: https://github.com/tibs/markup-history/tree/WriteTheDocs_Prague_2018
 95 | .. _pandoc: https://pandoc.org/
 96 | .. _docutils: http://docutils.sourceforge.net/
 97 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 98 | .. _TeX: https://www.ctan.org/starter
 99 | 
100 | --------
101 | 
102 |   |cc-attr-sharealike|
103 | 
104 |   This slideshow and its related files are released under a `Creative Commons
105 |   Attribution-ShareAlike 4.0 International License`_.
106 | 
107 | .. |cc-attr-sharealike| image:: cc-attribution-sharealike-88x31.png
108 |    :alt: CC-Attribution-ShareAlike image
109 | 
110 | .. _`Creative Commons Attribution-ShareAlike 4.0 International License`: http://creativecommons.org/licenses/by-sa/4.0/
111 | 
112 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
113 | 


--------------------------------------------------------------------------------
/markup-history-short.rst:
--------------------------------------------------------------------------------
  1 | .. A history of markup languages
  2 | .. =============================
  3 | 
  4 | .. -------
  5 | 
  6 | A history of markup languages
  7 | -----------------------------
  8 | 
  9 | By Tibs / Tony Ibbs
 10 | 
 11 | .. The slightly shorter version.
 12 | ..
 13 | .. This is intended to fit within 25 minutes.
 14 | 
 15 | This version for the Write The Docs, Prague, 2018
 16 | 
 17 | Written using reStructuredText_.
 18 | 
 19 | Converted to PDF slides using pandoc_ and beamer_.
 20 | 
 21 | Source and extended notes at https://github.com/tibs/markup-history
 22 | 
 23 | .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 24 | .. _pandoc: https://pandoc.org
 25 | .. _beamer: https://github.com/josephwright/beamer
 26 | 
 27 | .. |TeX| replace:: :math:`\text{\TeX}`
 28 | 
 29 | .. |LaTeX| replace:: :math:`\text{\LaTeX}`
 30 | 
 31 | .. Slide notes are in notes-per-slide.rst - they're too long to fit
 32 | .. comfortably in the presenter notes, and this file reads better if
 33 | .. "following along" on github without the extra notes being inline.
 34 | ..
 35 | .. Also, it's not clear that pandoc/beamer/PDF supports presenter notes
 36 | .. in the way I'd want.
 37 | 
 38 | .. Full notes (and links) are in markup-history-extended-notes.rst
 39 | 
 40 | ----
 41 | 
 42 | Timeline
 43 | --------
 44 | 
 45 | * 1960s TYPSET and RUNOFF, GML
 46 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
 47 | * 1980s |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
 48 | * 1990s HTML, setext, Docbook, WikiWikiWeb, XML
 49 | * 2000s reStructuredText, AsciiDoc, markdown
 50 | 
 51 | ----
 52 | 
 53 | The types of markup
 54 | -------------------
 55 | 
 56 | Presentational or Semantic
 57 | 
 58 | ...but also lightweight, and maybe programmable
 59 | 
 60 | ----
 61 | 
 62 | 1964: RUNOFF
 63 | ------------
 64 | 
 65 | .. code:: roff
 66 | 
 67 |   .LINE LENGTH 60
 68 |   .LEFT MARGIN 0
 69 |   .PARAGRAPH 5
 70 |   Call us on our toll free number
 71 | 
 72 |   .CENTER
 73 |   1-800-555-5555
 74 | 
 75 |   and we will respond as soon as convenient.
 76 | 
 77 | ----
 78 | 
 79 | 1969: GML / 1986: SGML
 80 | ----------------------
 81 | 
 82 | *DTD for a list:*
 83 | 
 84 | .. code:: DTD
 85 | 
 86 |   <!--      ELEMENT MIN CONTENT             >
 87 |   <!ELEMENT list    - - (item)+             >
 88 |   <!ELEMENT item    O O (#PCDATA, (list)*)  >
 89 | 
 90 | *and such a list:*
 91 | 
 92 | .. code:: XML
 93 | 
 94 |   <list>
 95 |   <item>First item</item>
 96 |   <item>Second item</item>
 97 |   <item>Last item</item>
 98 |   </list>
 99 | 
100 | ----
101 | 
102 | 1970s: roff, nroff, troff, groff
103 | --------------------------------
104 | 
105 | .. code:: Groff
106 | 
107 |   .TH CORRUPT 1
108 |   .SH NAME
109 |   corrupt \- modify files by randomly changing bits
110 |   .SH SYNOPSIS
111 |   .B corrupt
112 |   [\fB\-n\fR \fIBITS\fR]
113 |   [\fB\-\-bits\fR \fIBITS\fR]
114 |   .IR file ...
115 |   .SH DESCRIPTION
116 |   .B corrupt
117 |   modifies files by toggling a randomly chosen bit.
118 |   .SH OPTIONS
119 |   .TP
120 |   .BR \-n ", " \-\-bits =\fIBITS\fR
121 |   Set the number of bits to modify.  Default is one bit.
122 | 
123 | ----
124 | 
125 | 1977/1978: |TeX| / 1983: |LaTeX|
126 | --------------------------------
127 | 
128 | .. code:: latex
129 | 
130 |     \begin{center}
131 |     \rule{5in}{0.1mm}
132 |     \end{center}
133 | 
134 |     \section*{Captain Competent strikes again}
135 | 
136 |     The superhero is a familiar concept in comics, science
137 |     fiction and many other fields. However, I am more
138 |     interested in what might be called `the competent
139 |     hero'. This is a subtler form of protagonist---a
140 |     person who has attained {\em competence} in their
141 |     daily life.
142 | 
143 | ----
144 | 
145 | 1987: TEI
146 | ---------
147 | 
148 | .. code:: XML
149 | 
150 |   <lg type="sestina">
151 |   <lg type="sestet" rhyme="ababab">
152 |   <l>I saw my soul at rest upon a
153 |      <rhyme label="a" xml:id="A">day</rhyme></l>
154 |   <l>As a bird sleeping in the nest of
155 |      <rhyme label="b" xml:id="B">night</rhyme>,</l>
156 |   <l>Among soft leaves that give the starlight
157 |      <rhyme label="a" xml:id="C">way</rhyme></l>
158 |   <l>To touch its wings but not its eyes with
159 |      <rhyme label="b" xml:id="D">light</rhyme>;</l>
160 |   <l>So that it knew as one in visions
161 |      <rhyme label="a" xml:id="E">may</rhyme>,</l>
162 |   <l>And knew not as men waking, of
163 |      <rhyme label="b" xml:id="F">delight</rhyme>.</l>
164 |   </lg>
165 | 
166 | ----
167 | 
168 | 1991: HTML
169 | ----------
170 | 
171 | .. code:: HTML
172 | 
173 |   <!DOCTYPE html>
174 |   <html>
175 |     <head>
176 |       <title>This is a title</title>
177 |     </head>
178 |     <body>
179 |       <p>Hello world!</p>
180 |     </body>
181 |   </html>
182 | 
183 | ----
184 | 
185 | 1991: Docbook
186 | -------------
187 | 
188 | .. code:: XML
189 | 
190 |   <?xml version="1.0" encoding="UTF-8"?>
191 |   <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
192 |   "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
193 |   <article>
194 |    <title>DocBook Tutorial</title>
195 |    <articleinfo>
196 |     <author>
197 |      <firstname>Adrian</firstname> <surname>Giurca</surname>
198 |     </author>
199 |     <date>April 5, 2005</date>
200 |    </articleinfo>
201 |    <section>
202 |     <title>What is DocBook ?</title>
203 |     <para>DocBook is an SGML dialect developed by O'Reilly
204 |     and HaL Computer Systems in 1991.</para>
205 |    </section>
206 |   </article>
207 | 
208 | ----
209 | 
210 | 1991: setext
211 | ------------
212 | 
213 | .. code:: reST
214 | 
215 |    This is the title. There can be only one.
216 |    =========================================
217 |      Body text must be indented by two spaces.
218 | 
219 |    A subheading
220 |    ------------
221 |      **Bold words** and ~italic~ are supported.
222 |      _Underlined_words_ are also supported.
223 |      `Backquoted words` are not touched.
224 | 
225 |    > This text will be represented using a monospaced font.
226 | 
227 |    * This text will have a bullet mark before it.
228 | 
229 |    .. Two dots introduce text that can be ignored.
230 |    .. Two dots alone mean the logical end of text.
231 |    ..
232 | 
233 | ----
234 | 
235 | 1994/1995: wikiwikiweb
236 | ----------------------
237 | 
238 | .. code::
239 | 
240 |   Paragraphs are not indented.
241 | 
242 |   * This is a list item
243 |   ** This is a sub-list item
244 | 
245 |     Indented text is monospaced.
246 | 
247 |   We have ''emphasis'', '''bold''', '''''bold italic''''',
248 |   and a LinkToAnotherPage.
249 | 
250 |   But we can A''''''voidMakingAWikiLink.
251 | 
252 |   No HTML, tables, headers, maths, scripts.
253 |   No links within a page.
254 | 
255 | ----
256 | 
257 | 2001/2002: reStructuredText
258 | ---------------------------
259 | 
260 | .. code:: reST
261 | 
262 |    This is a heading
263 |    =================
264 |    This is a paragraph. Body text is not indented.
265 | 
266 |      - This is a list item. Words can be *emphasized*,
267 |        **strong** or ``teletype`` - yes, that's paired
268 |        backquotes [1]_.
269 |      - This is a list item as well.
270 | 
271 |        This is more of the second list item. It is indented
272 |        appropriately.
273 | 
274 |    This is a sub-heading
275 |    ---------------------
276 |    Sub-section body text is not indented either.
277 | 
278 |    .. [1] Note the indentation inside the list item.
279 | 
280 | -----
281 | 
282 | 2002: Asciidoc
283 | --------------
284 | 
285 | .. There doesn't seem to be a Pygments mode for AsciiDoc
286 | 
287 | .. code:: reST
288 | 
289 |   This is a heading
290 |   -----------------
291 |   This is a paragraph. Body text is not indented.
292 | 
293 |   - This is a list item. Words can be _italic_, *bold* or
294 |    +mono+ - yes, that's paired plus-signs.
295 |   - This is a list item as well.
296 |   +
297 |   This is more of the second list item. It is "`joined on`"
298 |   by the `+`.footnote:[Note the quotation marks around
299 |   _joined on_.]
300 | 
301 |   This is a sub-heading
302 |   ~~~~~~~~~~~~~~~~~~~~~
303 |   Sub-section body text is not indented either.
304 | 
305 | ----
306 | 
307 | 2004: markdown
308 | --------------
309 | 
310 | .. There doesn't seem to be a Pygments mode for markdown
311 | 
312 | .. code:: reST
313 | 
314 |    # This is a heading
315 | 
316 |    This is a paragraph. Body text is not indented.
317 | 
318 |    - This is a list item. Words can be *emphasized*,
319 |    **strong** or `inline` - that's single backquotes.
320 |    - This is a list item as well.
321 | 
322 |        This is more of the second list item. Its first line
323 |      must be indented by 4 spaces or a tab.
324 | 
325 |    ## This is a sub-heading
326 | 
327 |    Sub-section body text is not indented either.
328 | 
329 |    (No footnotes. But <tt>HTML</tt> is allowed.)
330 | 
331 | ----
332 | 
333 | Fin
334 | ---
335 | 
336 | * 1960s TYPSET and RUNOFF, GML
337 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
338 | * 1980s |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
339 | * 1990s HTML, setext, Docbook, WikiWikiWeb, XML
340 | * 2000s reStructuredText, AsciiDoc, markdown
341 | 
342 | Written using reStructuredText_.
343 | 
344 | Converted to PDF slides using pandoc_ and beamer_.
345 | 
346 | Source and extended notes at https://github.com/tibs/markup-history
347 | 
348 | .. Since this version is to give to Write the Docs people, I assume they know
349 | .. about the relevant website
350 | ..
351 | .. You may also be interested in Write the Docs: http://www.writethedocs.org/
352 | 
353 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
354 | 


--------------------------------------------------------------------------------
/markup-history-long.rst:
--------------------------------------------------------------------------------
  1 | .. A history of markup languages
  2 | .. =============================
  3 | 
  4 | .. -------
  5 | 
  6 | A history of markup languages
  7 | -----------------------------
  8 | 
  9 | 
 10 | By Tibs / Tony Ibbs
 11 | 
 12 | This version for the Cambridge Write The Docs meetup, Feb 2018
 13 | 
 14 | Written using reStructuredText_.
 15 | 
 16 | Converted to PDF slides using pandoc_ and beamer_.
 17 | 
 18 | Source and extended notes at https://github.com/tibs/markup-history
 19 | 
 20 | .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 21 | .. _pandoc: https://pandoc.org
 22 | .. _beamer: https://github.com/josephwright/beamer
 23 | 
 24 | .. |TeX| replace:: :math:`\text{\TeX}`
 25 | 
 26 | .. |LaTeX| replace:: :math:`\text{\LaTeX}`
 27 | 
 28 | .. Slide notes are in notes-per-slide.rst - they're too long to fit
 29 | .. comfortably in the presenter notes, and this file reads better if
 30 | .. "following along" on github without the extra notes being inline.
 31 | ..
 32 | .. Also, it's not clear that pandoc/beamer/PDF supports presenter notes
 33 | .. in the way I'd want.
 34 | 
 35 | .. Full notes (and links) are in markup-history-extended-notes.rst
 36 | 
 37 | ----
 38 | 
 39 | Timeline
 40 | --------
 41 | 
 42 | * 1960s TYPSET and RUNOFF, GML
 43 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
 44 | * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
 45 | * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
 46 | * 2000s reStructuredText, AsciiDoc, markdown
 47 | 
 48 | ----
 49 | 
 50 | The types of markup
 51 | -------------------
 52 | 
 53 | Presentational or Semantic
 54 | 
 55 | ...but also lightweight, and maybe programmable
 56 | 
 57 | ----
 58 | 
 59 | 1964: RUNOFF
 60 | ------------
 61 | 
 62 | .. code:: roff
 63 | 
 64 |   .LINE LENGTH 60
 65 |   .LEFT MARGIN 0
 66 |   .PARAGRAPH 5
 67 |   Call us on our toll free number
 68 | 
 69 |   .CENTER
 70 |   1-800-555-5555
 71 | 
 72 |   and we will respond as soon as convenient.
 73 | 
 74 | ----
 75 | 
 76 | 1969: GML and 1986: SGML
 77 | ------------------------
 78 | 
 79 | .. code:: sgml
 80 | 
 81 |   <td> The Implication of SGML for the Preparation of
 82 |   Scientific Publications
 83 |   <au> Joan M. Smith
 84 |   ...
 85 |   <ab> The &SGML (SGML) is a draft international standard
 86 |   for publishing.
 87 |   ...
 88 |   <h1>Introduction
 89 |   <p> The official title of SGML, currently, is ISO/DIS 8879,
 90 |   <ci> Information Processing &end Text and Office Systems
 91 |   &end &SGML (SGML) </ci>. <ref> ISO/DIS 8879 ... </ref>
 92 |   ...
 93 |   <p>There are several points worthy of note here:
 94 |   <ul>
 95 |   <li> the normal publishing delay with ISO standards...
 96 |   ...
 97 |   </ul>
 98 | 
 99 | 
100 | ----
101 | 
102 | SGML DTD
103 | --------
104 | 
105 | *DTD for a list:*
106 | 
107 | .. code:: DTD
108 | 
109 |   <!--      ELEMENT MIN CONTENT             >
110 |   <!ELEMENT list    - - (item)+             >
111 |   <!ELEMENT item    O O (#PCDATA, (list)*)  >
112 | 
113 | *and such a list:*
114 | 
115 | .. code:: sgml
116 | 
117 |   <list>
118 |   <item>First item</item>
119 |   <item>Second item</item>
120 |   <item>Last item</item>
121 |   </list>
122 | 
123 | ----
124 | 
125 | 1997: XML
126 | ---------
127 | 
128 |  "XML is an application profile of SGML"
129 | 
130 | ----
131 | 
132 | 1970s: roff, nroff, troff
133 | -------------------------
134 | 
135 | .. code:: roff
136 | 
137 |   .TH CORRUPT 1
138 |   .SH NAME
139 |   corrupt \- modify files by randomly changing bits
140 |   .SH SYNOPSIS
141 |   .B corrupt
142 |   [\fB\-n\fR \fIBITS\fR]
143 |   [\fB\-\-bits\fR \fIBITS\fR]
144 |   .IR file ...
145 |   .SH DESCRIPTION
146 |   .B corrupt
147 |   modifies files by toggling a randomly chosen bit.
148 |   .SH OPTIONS
149 |   .TP
150 |   .BR \-n ", " \-\-bits =\fIBITS\fR
151 |   Set the number of bits to modify.  Default is one bit.
152 | 
153 | ----
154 | 
155 | 1990: groff
156 | -----------
157 | 
158 | .. code:: roff
159 | 
160 |   ..INCLUDE mission-statement-strings.mom
161 |   .TITLE    "\*[Groff-Mission-Statement]
162 |   .SUBTITLE "\*[2014]
163 |   .INCLUDE  mission-statement-style.mom
164 |   .PP
165 |   As the most widely deployed implementation of troff in use
166 |   today, groff holds an important place in the Unix universe.
167 |   Frequently and erroneously dismissed as a legacy program
168 |   for formatting Unix manuals (manpages), groff is in fact a
169 |   sophisticated system for producing high-quality typeset
170 |   material, from business correspondence to complex,
171 |   technical reports and plate-ready books. \*[BU3]With an
172 |   impressive record for backward compatibility, it continues
173 |   to evolve and play a leading role in the development of
174 |   free typesetting software.
175 | 
176 | ----
177 | 
178 | 1977/1978: |TeX|
179 | ----------------
180 | 
181 | .. code:: tex
182 | 
183 |   \name{Name Redacted} wrote:
184 | 
185 |   \beginletter
186 |   Thoughts on ``Why I like children's books'':
187 | 
188 |   \beginlist
189 |   \item{\blob} They aren't afraid to show a sense of wonder.
190 |   \item{\blob} They aren't `duty bound' to include love
191 |   interest for the sake of it.
192 |   \item{\blob} They are rarely cynical, rarely bitter---but
193 |   the best do not avoid tragedy and truth.
194 |   \item{\blob} They are willing to teach the simple lessons
195 |   of being human---which adult books so often scorn, but
196 |   which we all need to learn and relearn.
197 |   \endlist
198 | 
199 | ----
200 | 
201 | 1983: |LaTeX|
202 | -------------
203 | 
204 | .. code:: latex
205 | 
206 |   \begin{center}
207 |   \rule{5in}{0.1mm}
208 |   \end{center}
209 | 
210 |   \section*{Captain Competent strikes again}
211 | 
212 |   The superhero is a familiar concept in comics, science
213 |   fiction and many other fields. However, I am more
214 |   interested in what might be called `the competent
215 |   hero'. This is a subtler form of protagonist---a
216 |   person who has attained {\em competence} in their
217 |   daily life.
218 | 
219 | ----
220 | 
221 | 1980: Scribe
222 | ------------
223 | 
224 | .. code:: scribe
225 | 
226 |     @Heading(The Beginning)
227 |     @Begin(Quotation)
228 |         Let's start at the very beginning, a @i(very good
229 |         place) to start
230 |     @End(Quotation)
231 | 
232 | *which can also be written:*
233 | 
234 | .. code:: scribe
235 | 
236 |     @Heading(The Beginning)
237 |     @(Quotation
238 |         Let's start at the very beginning, a @i(very good
239 |         place) to start
240 |     )
241 | 
242 | ----
243 | 
244 | 1987: TEI
245 | ---------
246 | 
247 | .. code:: XML
248 | 
249 |   <lg type="sestina">
250 |   <lg type="sestet" rhyme="ababab">
251 |   <l>I saw my soul at rest upon a
252 |      <rhyme label="a" xml:id="A">day</rhyme></l>
253 |   <l>As a bird sleeping in the nest of
254 |      <rhyme label="b" xml:id="B">night</rhyme>,</l>
255 |   <l>Among soft leaves that give the starlight
256 |      <rhyme label="a" xml:id="C">way</rhyme></l>
257 |   <l>To touch its wings but not its eyes with
258 |      <rhyme label="b" xml:id="D">light</rhyme>;</l>
259 |   <l>So that it knew as one in visions
260 |      <rhyme label="a" xml:id="E">may</rhyme>,</l>
261 |   <l>And knew not as men waking, of
262 |      <rhyme label="b" xml:id="F">delight</rhyme>.</l>
263 |   </lg>
264 | 
265 | ----
266 | 
267 | 1991: HTML
268 | ----------
269 | 
270 | .. code:: HTML
271 | 
272 |   <!DOCTYPE html>
273 |   <html>
274 |     <head>
275 |       <title>This is a title</title>
276 |     </head>
277 |     <body>
278 |       <p>Hello world!</p>
279 |     </body>
280 |   </html>
281 | 
282 | ----
283 | 
284 | 1991: Docbook
285 | -------------
286 | 
287 | .. code:: XML
288 | 
289 |   <?xml version="1.0" encoding="UTF-8"?>
290 |   <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
291 |   "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
292 |   <article>
293 |    <title>DocBook Tutorial</title>
294 |    <articleinfo>
295 |     <author>
296 |      <firstname>Adrian</firstname> <surname>Giurca</surname>
297 |     </author>
298 |     <date>April 5, 2005</date>
299 |    </articleinfo>
300 |    <section>
301 |     <title>What is DocBook ?</title>
302 |     <para>DocBook is an SGML dialect developed by O'Reilly
303 |     and HaL Computer Systems in 1991.</para>
304 |    </section>
305 |   </article>
306 | 
307 | ----
308 | 
309 | 1991: setext
310 | ------------
311 | 
312 | .. code:: reST
313 | 
314 |    This is the title. There can be only one.
315 |    =========================================
316 |      Body text must be indented by two spaces.
317 | 
318 |    A subheading
319 |    ------------
320 |      **Bold words** and ~italic~ are supported.
321 |      _Underlined_words_ are also supported.
322 |      `Backquoted words` are not touched.
323 | 
324 |    > This text will be represented using a monospaced font.
325 | 
326 |    * This text will have a bullet mark before it.
327 | 
328 |    .. Two dots introduce text that can be ignored.
329 |    .. Two dots alone mean the logical end of text.
330 |    ..
331 | 
332 | ----
333 | 
334 | 1994/1995: wikiwikiweb
335 | ----------------------
336 | 
337 | .. code:: wiki
338 | 
339 |   Paragraphs are not indented.
340 | 
341 |   * This is a list item
342 |   ** This is a sub-list item
343 | 
344 |     Indented text is monospaced.
345 | 
346 |   We have ''emphasis'', '''bold''', '''''bold italic''''',
347 |   and a LinkToAnotherPage.
348 | 
349 |   But we can A''''''voidMakingAWikiLink.
350 | 
351 |   No HTML, tables, headers, maths, scripts.
352 |   No links within a page.
353 | 
354 | ----
355 | 
356 | 
357 | 1996: StructuredText
358 | --------------------
359 | 
360 | .. code:: reST
361 | 
362 |    This is a heading
363 | 
364 |      This is a paragraph. Body text is indented.
365 | 
366 |      - This is a list item. Words can be *emphasized*,
367 |      _underlined_, **strong** or 'inline' - yes, that's
368 |      using single quotes [1].
369 | 
370 |      o This is a list item as well.
371 | 
372 |      This is a sub-heading
373 | 
374 |        Sub-section body text is indented even further. This
375 |        indented body text makes the sub-heading a heading.
376 | 
377 |    .. [1] Or we could use ``backquotes``.
378 | 
379 | ----
380 | 
381 | 2001/2002: reStructuredText
382 | ---------------------------
383 | 
384 | .. code:: reST
385 | 
386 |    This is a heading
387 |    =================
388 |    This is a paragraph. Body text is not indented.
389 | 
390 |      - This is a list item. Words can be *emphasized*,
391 |        **strong** or ``teletype`` - yes, that's paired
392 |        backquotes [1]_.
393 |      - This is a list item as well.
394 | 
395 |        This is more of the second list item. It is indented
396 |        appropriately.
397 | 
398 |    This is a sub-heading
399 |    ---------------------
400 |    Sub-section body text is not indented either.
401 | 
402 |    .. [1] Note the indentation inside the list item.
403 | 
404 | -----
405 | 
406 | 2002: Asciidoc
407 | --------------
408 | 
409 | .. There doesn't seem to be a Pygments mode for AsciiDoc
410 | 
411 | .. code:: reST
412 | 
413 |   = This is a title heading
414 |   This is a paragraph. Body text is not indented.
415 | 
416 |   - This is a list item. Words can be _italic_, *bold* or
417 |    +mono+ - yes, that's paired plus-signs.
418 |   - This is a list item as well.
419 |   +
420 |   This is more of the second list item. It is "`joined on`"
421 |   by the `+`.footnote:[Note the quotation marks around
422 |   _joined on_.]
423 | 
424 |   == This is a sub-heading
425 |   Sub-section body text is not indented either.
426 | 
427 | ----
428 | 
429 | 2004: markdown
430 | --------------
431 | 
432 | .. code:: markdown
433 | 
434 |    # This is a heading
435 |    This is a paragraph. Body text is not indented.
436 | 
437 |    - This is a list item. Words can be *emphasized*,
438 |    **strong** or `inline` - that's single backquotes.
439 |    - This is a list item as well.
440 | 
441 |        This is more of the second list item. Its first line
442 |      must be indented by 4 spaces or a tab.
443 | 
444 |    ## This is a sub-heading
445 |    Sub-section body text is not indented either.
446 | 
447 |    (No footnotes. But <tt>HTML</tt> is allowed.)
448 | 
449 | ----
450 | 
451 | Fin
452 | ---
453 | 
454 | * 1960s TYPSET and RUNOFF, GML
455 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
456 | * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
457 | * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
458 | * 2000s reStructuredText, AsciiDoc, markdown
459 | 
460 | Written using reStructuredText_.
461 | 
462 | Converted to PDF slides using pandoc_ and beamer_.
463 | 
464 | Source and extended notes at https://github.com/tibs/markup-history
465 | 
466 | .. Since this version is to give to Write the Docs, I assume they know
467 | .. about the relevant website
468 | .. You may also be interested in Write the Docs: http://www.writethedocs.org/
469 | 
470 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
471 | 


--------------------------------------------------------------------------------
/markup-history-long-wide.rst:
--------------------------------------------------------------------------------
  1 | .. A history of markup languages
  2 | .. =============================
  3 | 
  4 | .. -------
  5 | 
  6 | A history of markup languages
  7 | -----------------------------
  8 | 
  9 | 
 10 | By Tibs / Tony Ibbs
 11 | 
 12 | This version for the Cambridge Write The Docs meetup, Feb 2018
 13 | 
 14 | Written using reStructuredText_.
 15 | 
 16 | Converted to PDF slides using pandoc_ and beamer_.
 17 | 
 18 | Source and extended notes at https://github.com/tibs/markup-history
 19 | 
 20 | .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 21 | .. _pandoc: https://pandoc.org
 22 | .. _beamer: https://github.com/josephwright/beamer
 23 | 
 24 | .. |TeX| replace:: :math:`\text{\TeX}`
 25 | 
 26 | .. |LaTeX| replace:: :math:`\text{\LaTeX}`
 27 | 
 28 | .. Slide notes are in notes-per-slide.rst - they're too long to fit
 29 | .. comfortably in the presenter notes, and this file reads better if
 30 | .. "following along" on github without the extra notes being inline.
 31 | ..
 32 | .. Also, it's not clear that pandoc/beamer/PDF supports presenter notes
 33 | .. in the way I'd want.
 34 | 
 35 | .. Full notes (and links) are in markup-history-extended-notes.rst
 36 | 
 37 | ----
 38 | 
 39 | Timeline
 40 | --------
 41 | 
 42 | * 1960s TYPSET and RUNOFF, GML
 43 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
 44 | * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
 45 | * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
 46 | * 2000s reStructuredText, AsciiDoc, markdown
 47 | 
 48 | ----
 49 | 
 50 | The types of markup
 51 | -------------------
 52 | 
 53 | Presentational or Semantic
 54 | 
 55 | ...but also lightweight, and maybe programmable
 56 | 
 57 | ----
 58 | 
 59 | 1964: RUNOFF
 60 | ------------
 61 | 
 62 | .. code:: roff
 63 | 
 64 |   .LINE LENGTH 60
 65 |   .LEFT MARGIN 0
 66 |   .PARAGRAPH 5
 67 |   Call us on our toll free number
 68 | 
 69 |   .CENTER
 70 |   1-800-555-5555
 71 | 
 72 |   and we will respond as soon as convenient.
 73 | 
 74 | ----
 75 | 
 76 | 1969: GML and 1986: SGML
 77 | ------------------------
 78 | 
 79 | .. code:: sgml
 80 | 
 81 |   <td> The Implication of SGML for the Preparation of Scientific
 82 |   Publications
 83 |   <au> Joan M. Smith
 84 |   <ad> <al> National Computing Centre, Oxford Road, Manchester M1 7ED
 85 |   <ab> The &SGML (SGML) is a draft international standard for publishing.
 86 |   ...
 87 |   <h1>Introduction
 88 |   <p> The official title of SGML, currently, is ISO/DIS 8879,
 89 |   <ci> Information Processing &end Text and Office Systems &end &SGML (SGML)
 90 |   </ci>. <ref> ISO/DIS 8879 <ci> Information Processing &end Text and Office
 91 |   Systems &end &SGML (SGML). ISO, Geneva (1985). </ref>
 92 |   ...
 93 |   <p>There are several points worthy of note here:
 94 |   <ul>
 95 |   <li> the normal publishing delay with ISO standards...
 96 |   ...
 97 |   </ul>
 98 | 
 99 | ----
100 | 
101 | SGML DTD
102 | --------
103 | 
104 | *DTD for a list:*
105 | 
106 | .. code:: DTD
107 | 
108 |   <!--      ELEMENT MIN CONTENT             >
109 |   <!ELEMENT list    - - (item)+             >
110 |   <!ELEMENT item    O O (#PCDATA, (list)*)  >
111 | 
112 | *and such a list:*
113 | 
114 | .. code:: sgml
115 | 
116 |   <list>
117 |   <item>First item</item>
118 |   <item>Second item</item>
119 |   <item>Last item</item>
120 |   </list>
121 | 
122 | ----
123 | 
124 | 1997: XML
125 | ---------
126 | 
127 |  "XML is an application profile of SGML"
128 | 
129 | ----
130 | 
131 | 1970s: roff, nroff, troff
132 | -------------------------
133 | 
134 | .. code:: roff
135 | 
136 |   .TH CORRUPT 1
137 |   .SH NAME
138 |   corrupt \- modify files by randomly changing bits
139 |   .SH SYNOPSIS
140 |   .B corrupt
141 |   [\fB\-n\fR \fIBITS\fR]
142 |   [\fB\-\-bits\fR \fIBITS\fR]
143 |   .IR file ...
144 |   .SH DESCRIPTION
145 |   .B corrupt
146 |   modifies files by toggling a randomly chosen bit.
147 |   .SH OPTIONS
148 |   .TP
149 |   .BR \-n ", " \-\-bits =\fIBITS\fR
150 |   Set the number of bits to modify.  Default is one bit.
151 | 
152 | ----
153 | 
154 | 1990: groff
155 | -----------
156 | 
157 | .. code:: roff
158 | 
159 |   ..INCLUDE mission-statement-strings.mom
160 |   .TITLE    "\*[Groff-Mission-Statement]
161 |   .SUBTITLE "\*[2014]
162 |   .INCLUDE  mission-statement-style.mom
163 |   .PP
164 |   As the most widely deployed implementation of troff in use today,
165 |   groff holds an important place in the Unix universe.  Frequently
166 |   and erroneously dismissed as a legacy program for formatting
167 |   Unix manuals (manpages), groff is in fact a sophisticated system
168 |   for producing high-quality typeset material, from business
169 |   correspondence to complex, technical reports and plate-ready books.
170 |   \*[BU3]With an impressive record for backward compatibility, it
171 |   continues to evolve and play a leading role in the development of
172 |   free typesetting software.
173 | 
174 | ----
175 | 
176 | 1977/1978: |TeX|
177 | ----------------
178 | 
179 | .. code:: tex
180 | 
181 |   \name{Name Redacted} wrote:
182 | 
183 |   \beginletter
184 |   Thoughts on ``Why I like children's books'':
185 | 
186 |   \beginlist
187 |   \item{\blob} They aren't afraid to show a sense of wonder.
188 |   \item{\blob} They aren't `duty bound' to include love interest for the
189 |   sake of it.
190 |   \item{\blob} They are rarely cynical, rarely bitter---but the best do
191 |   not avoid tragedy and truth.
192 |   \item{\blob} They are willing to teach the simple lessons of being
193 |   human---which adult books so often scorn, but which we all need to
194 |   learn and relearn.
195 |   \endlist
196 | 
197 | ----
198 | 
199 | 1983: |LaTeX|
200 | -------------
201 | 
202 | .. code:: latex
203 | 
204 |   \begin{center}
205 |   \rule{5in}{0.1mm}
206 |   \end{center}
207 | 
208 |   \section*{Captain Competent strikes again}
209 | 
210 |   The superhero is a familiar concept in comics, science
211 |   fiction and many other fields. However, I am more
212 |   interested in what might be called `the competent
213 |   hero'. This is a subtler form of protagonist---a
214 |   person who has attained {\em competence} in their
215 |   daily life.
216 | 
217 | ----
218 | 
219 | 1980: Scribe
220 | ------------
221 | 
222 | .. code:: scribe
223 | 
224 |     @Heading(The Beginning)
225 |     @Begin(Quotation)
226 |         Let's start at the very beginning, a @i(very good
227 |         place) to start
228 |     @End(Quotation)
229 | 
230 | *which can also be written:*
231 | 
232 | .. code:: scribe
233 | 
234 |     @Heading(The Beginning)
235 |     @(Quotation
236 |         Let's start at the very beginning, a @i(very good
237 |         place) to start
238 |     )
239 | 
240 | ----
241 | 
242 | 1987: TEI
243 | ---------
244 | 
245 | .. code:: XML
246 | 
247 |   <lg type="sestina">
248 |   <lg type="sestet" rhyme="ababab">
249 |   <l>I saw my soul at rest upon a
250 |                     <rhyme label="a" xml:id="A">day</rhyme></l>
251 |   <l>As a bird sleeping in the nest of
252 |                     <rhyme label="b" xml:id="B">night</rhyme>,</l>
253 |   <l>Among soft leaves that give the starlight
254 |                      <rhyme label="a" xml:id="C">way</rhyme></l>
255 |   <l>To touch its wings but not its eyes with
256 |                      <rhyme label="b" xml:id="D">light</rhyme>;</l>
257 |   <l>So that it knew as one in visions
258 |                      <rhyme label="a" xml:id="E">may</rhyme>,</l>
259 |   <l>And knew not as men waking, of
260 |                      <rhyme label="b" xml:id="F">delight</rhyme>.</l>
261 |   </lg>
262 | 
263 | ----
264 | 
265 | 1991: HTML
266 | ----------
267 | 
268 | .. code:: HTML
269 | 
270 |   <!DOCTYPE html>
271 |   <html>
272 |     <head>
273 |       <title>This is a title</title>
274 |     </head>
275 |     <body>
276 |       <p>Hello world!</p>
277 |     </body>
278 |   </html>
279 | 
280 | ----
281 | 
282 | 1991: Docbook
283 | -------------
284 | 
285 | .. code:: XML
286 | 
287 |   <?xml version="1.0" encoding="UTF-8"?>
288 |   <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
289 |   "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
290 |   <article>
291 |     <title>DocBook Tutorial</title>
292 |     <articleinfo>
293 |       <author>
294 |         <firstname>Adrian</firstname> <surname>Giurca</surname>
295 |       </author>
296 |       <date>April 5, 2005</date>
297 |     </articleinfo>
298 |     <section>
299 |       <title>What is DocBook ?</title>
300 |       <para>DocBook is an SGML dialect developed by O'Reilly and HaL
301 |         Computer Systems in 1991.</para>
302 |     </section>
303 |   </article>
304 | 
305 | ----
306 | 
307 | 1991: setext
308 | ------------
309 | 
310 | .. code:: reST
311 | 
312 |    This is the title. There can be only one.
313 |    =========================================
314 |      Body text must be indented by two spaces.
315 | 
316 |    A subheading
317 |    ------------
318 |      **Bold words** and ~italic~ are supported. _Underlined_words_ are
319 |      also supported. `Backquoted words` are not touched.
320 | 
321 |    > This text will be represented using a monospaced font.
322 | 
323 |    * This text will have a bullet mark before it.
324 | 
325 |    .. Two dots introduce text that can be ignored.
326 |    .. Two dots alone mean the logical end of text.
327 |    ..
328 | 
329 | ----
330 | 
331 | 1994/1995: wikiwikiweb
332 | ----------------------
333 | 
334 | .. code:: wiki
335 | 
336 |   Paragraphs are not indented.
337 | 
338 |   * This is a list item
339 |   ** This is a sub-list item
340 | 
341 |     Indented text is monospaced.
342 | 
343 |   We have ''emphasis'', '''bold''', '''''bold italic''''', and a
344 |   LinkToAnotherPage.
345 | 
346 |   But we can A''''''voidMakingAWikiLink.
347 | 
348 |   No HTML, tables, headers, maths, scripts.
349 |   No links within a page.
350 | 
351 | ----
352 | 
353 | 
354 | 1996: StructuredText
355 | --------------------
356 | 
357 | .. code:: reST
358 | 
359 |    This is a heading
360 | 
361 |      This is a paragraph. Body text is indented.
362 | 
363 |      - This is a list item. Words can be *emphasized*, _underlined_,
364 |      **strong** or 'inline' - yes, that's using single quotes [1].
365 | 
366 |      o This is a list item as well.
367 | 
368 |      This is a sub-heading
369 | 
370 |        Sub-section body text is indented even further. This
371 |        indented body text makes the sub-heading a heading.
372 | 
373 |    .. [1] Or we could use ``backquotes``.
374 | 
375 | ----
376 | 
377 | 2001/2002: reStructuredText
378 | ---------------------------
379 | 
380 | .. code:: reST
381 | 
382 |    This is a heading
383 |    =================
384 |    This is a paragraph. Body text is not indented.
385 | 
386 |      - This is a list item. Words can be *emphasized*, **strong** or
387 |        ``teletype`` - yes, that's paired backquotes [1]_.
388 |      - This is a list item as well.
389 | 
390 |        This is more of the second list item. It is indented appropriately.
391 | 
392 |    This is a sub-heading
393 |    ---------------------
394 |    Sub-section body text is not indented either.
395 | 
396 |    .. [1] Note the indentation inside the list item.
397 | 
398 | -----
399 | 
400 | 2002: Asciidoc
401 | --------------
402 | 
403 | .. There doesn't seem to be a Pygments mode for AsciiDoc
404 | 
405 | .. code:: reST
406 | 
407 |   = This is a title heading
408 |   This is a paragraph. Body text is not indented.
409 | 
410 |   - This is a list item. Words can be _italic_, *bold* or +mono+ - yes,
411 |     that's paired plus-signs.
412 |   - This is a list item as well.
413 |   +
414 |   This is more of the second list item. It is "`joined on`" by the
415 |   `+`.footnote:[Note the quotation marks around _joined on_.]
416 | 
417 |   == This is a sub-heading
418 |   Sub-section body text is not indented either.
419 | 
420 | ----
421 | 
422 | 2004: markdown
423 | --------------
424 | 
425 | .. code:: markdown
426 | 
427 |    # This is a heading
428 |    This is a paragraph. Body text is not indented.
429 | 
430 |    - This is a list item. Words can be *emphasized*, **strong** or
431 |    `inline` - that's single backquotes.
432 |    - This is a list item as well.
433 | 
434 |        This is more of the second list item. Its first line must be
435 |      indented by 4 spaces or a tab.
436 | 
437 |    ## This is a sub-heading
438 |    Sub-section body text is not indented either.
439 | 
440 |    (No footnotes. But <tt>HTML</tt> is allowed.)
441 | 
442 | ----
443 | 
444 | Fin
445 | ---
446 | 
447 | * 1960s TYPSET and RUNOFF, GML
448 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
449 | * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
450 | * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
451 | * 2000s reStructuredText, AsciiDoc, markdown
452 | 
453 | Written using reStructuredText_.
454 | 
455 | Converted to PDF slides using pandoc_ and beamer_.
456 | 
457 | Source and extended notes at https://github.com/tibs/markup-history
458 | 
459 | .. Since this version is to give to Write the Docs, I assume they know
460 | .. about the relevant website
461 | .. You may also be interested in Write the Docs: http://www.writethedocs.org/
462 | 
463 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
464 | 


--------------------------------------------------------------------------------
/assorted-text.txt:
--------------------------------------------------------------------------------
  1 | http://history-computer.com/Internet/Birth/Goldfarb.html
  2 | How I'm going to split the world
  3 | ================================
  4 | 
  5 | There are different sorts of markup, with different purposes, but I am going
  6 | to concentrate on three main types, which I shall categorise as:
  7 | 
  8 | 1. Presentational markup
  9 | 
 10 |    This uses markup to direct the presentation of the text, for instance as a
 11 |    man page, on a screen, or on a typeset page.
 12 | 
 13 |    Traditional examples are the ``*roff`` family (roff, nroff, troff, groff
 14 |    and the various sorts of RUNOFF) and the |TeX| family (|TeX|, |LaTeX|, etc.)
 15 | 
 16 | 2. Semantic markup
 17 | 
 18 |    This uses markup to add meaning to the text, typically by annotating
 19 |    textual elements to say what they are (e.g., part number, book title,
 20 |    address).
 21 | 
 22 |    Traditional examples are the markups described by SGML (or, lighter weight,
 23 |    XML), including Docbook.
 24 | 
 25 | 3. Readable plaintext
 26 | 
 27 |    This attempts to get some of the benefits of one of the other types
 28 |    (typically concentrating on presentation) whilst preserving the readability
 29 |    of the original text. Interestingly, these have been around about as long
 30 |    as the other forms, but are less talked about.
 31 | 
 32 |    The ur-language for this form is probably setext, but obvious examples
 33 |    include StructuredText, reStructuredText and markdown.
 34 | 
 35 |    The art of design of these markups is judging what capabilities are wanted
 36 |    - the more things the markup can represent, the more complex the
 37 |    restrictions on what may be typed as free text, and what has accidental
 38 |    meaning.
 39 | 
 40 |    .. note:: The classic aim is to be "close to what one would write in an
 41 |       email" - a stricture that meant more when emails could only contain
 42 |       ASCII text.
 43 | 
 44 |    .. note:: I think this is why some people object to reStructuredText but
 45 |       are happy with markdown. reStructuredText aims to provide a lot of
 46 |       capability (such that one rarely needs to stray into something like
 47 |       |TeX| or Docbook), whereas markdown puts that balance a lot closer to
 48 |       plain text.
 49 | 
 50 | .. note:: I think that means it is also sensible to separate out the three
 51 |    timelines. There will obviously have been cross-fertilisation, but it's
 52 |    probably much simpler not to mix them up, because that can lead to an
 53 |    artificial expectation of causation across the timelines, which I am
 54 |    suspicious of.
 55 | 
 56 |    (I'm not convinced the roffs and the SGMLs were well related in the early
 57 |    days, for instance. And that's irrespective of whether the different
 58 |    developers knew of each others work.)
 59 | 
 60 | Presentational markup
 61 | =====================
 62 | The early days
 63 | --------------
 64 | This started with output to teletype (underlining, bolding, and otherwise
 65 | overstruct characters) and to line printers. Eventually, output to
 66 | monotype/linotype/etc. got added in.
 67 | 
 68 | For instance: nroff/troff, DSR (Digital Standard Runnoff)
 69 | 
 70 | The need was to type basic alphanumerics and symbols (i.e., ASCII or EBCDIC)
 71 | but output to something with the ability to represent more. For teletypes,
 72 | this might just mean the use of the backspace character to allow overwriting
 73 | text - but doing that in the original text file would not necessarily be
 74 | portable or readable.
 75 | 
 76 | Needs:
 77 | 
 78 | * Use portable character sets (not necessarily only ASCII and EBCDIC!)
 79 | * Don't want to type in the "magic codes" to do unerlining, etc., especially
 80 |   as they're not necessarily going to be the same codes for different output
 81 |   devices.
 82 | 
 83 | Programmable markup
 84 | -------------------
 85 | 
 86 | .. note:: Wikipedia calls this "Procedural markup"
 87 | 
 88 | There is an important subset of presentation markup, which is actually a
 89 | progamming language that privides markup. The obvious examples are |TeX| and
 90 | Postscript (and to a lesser extent, PDF).
 91 | 
 92 | |TeX| is essentially a macro expansion language, and this means that the
 93 | (perhaps more familiar) |LaTeX| is written in |TeX| itself.
 94 | 
 95 | Postscript is perhaps not normally thought of as a markup lanugage,
 96 | but is essentially a Forth derivative that works on text to produce a
 97 | printable output.
 98 | 
 99 | As such, both of these languages can be used to do non-text processing as well,
100 | although perhaps not in a manner that feels natural (to their intent).
101 | 
102 | PDF incorporates a subset of Postscript, but is much more page oriented (pages are
103 | independent) and less general in its applicability, so is arguably not quite
104 | in our area of interest.
105 | 
106 | http://wiki.c2.com/?ForthPostscriptRelationship discusses whether Postscript
107 | *is a* Forth, or is just similar to Forth (basically, the latter seems more
108 | sensible).
109 | 
110 | Semantic markup
111 | ===============
112 | 
113 | .. note:: Wikipedia calls this Descriptive markup
114 | 
115 | * SGML (and DTDS)
116 | 
117 |   leading to:
118 | 
119 |   * HTML
120 |   * XML
121 |   * XHTML
122 |   * Docbook
123 | 
124 |   and so on.
125 | 
126 | (SGML originally derived from GML)
127 | 
128 | Readable plaintext
129 | ==================
130 | 
131 | .. note:: Wikipedia seems to put these together with such things as wiki
132 |    markup as Lightweight markup. I'd argue there's a difference between
133 |    lightweight markup and the subset therein which is readable, and it's that
134 |    latter subset I'm most interested in.
135 | 
136 | .. note:: It would be nice to get an actual timeline from setext to structured
137 |    text to reStructuredText and any other intermediaries.
138 | 
139 | setext -> structured text
140 | 
141 | The big ideas of reStructuredText:
142 | 
143 |   1. prioritise readability of the source text
144 |   2. not to specify the form of the output (i.e., don't just assume HTML)
145 |   3. be well specified
146 | 
147 | Other examples:
148 | 
149 | * markdown (I'd argue less readable, because it's meant to be slightly easier
150 |   to write, and it originally was designed for output to HTML, and it's
151 |   *definitely* not well specified)
152 | 
153 | * asciidoctor (how does this differ on those three axes?)
154 | 
155 | Talking points for the slideshow
156 | ================================
157 | 
158 | "Why markup languages are older than you think, and some of the major
159 | examples"
160 | 
161 | All four have different reasons for existing, but clearly influence each
162 | other.
163 | 
164 | *So*, for each pick a major example - perhaps:
165 | 
166 | * nroff/troff (different programs, but same input format - does *it* have a
167 |   name?)
168 | * SGML/HTML/XML and maybe a brief nod to Docbook
169 | * |TeX|/|LaTeX| (more people use |LaTeX| than bare |TeX|)
170 | * setext -> structured text -> reStructuredText
171 | 
172 | Want dates for each
173 | 
174 | Driving forces:
175 | 
176 | - I want portable documentation
177 | - I want good (but controllable) typesetting
178 | - I want to mark up the meaning of the elements of my text, for analysis
179 | - I want readable source
180 | 
181 | 
182 | Older fragments of a Timeline
183 | =============================
184 | need to put in setext, markdown, nroff/troff/groff, RUNOFF
185 | 
186 | * 1964 RUNOFF https://en.wikipedia.org/wiki/TYPSET_and_RUNOFF
187 | 
188 |   - also, the RUNOFF program (`wikipedia - Runoff`_)
189 | 
190 | * 1969 roff
191 | * nroff (newer roff) https://en.wikipedia.org/wiki/Nroff
192 | * troff (typesetter roff) https://en.wikipedia.org/wiki/Troff
193 | 
194 |   - in various versions, and with increasing capabilities. nroff basically
195 |     ignores what it doesn't understand when reading the same input.
196 | 
197 | * 1990s groff (GNU roff)
198 | 
199 | http://h20565.www2.hpe.com/hpsc/doc/public/display?docId=emr_na-c04623260 is
200 | the OpenVMS Digital Standard Runoff Reference Manual from May 1993.
201 | 
202 | and
203 | 
204 | * 1967 - GenCode, William W. Tunnicliffe ("generic coding") - publishing industry.
205 | * 1969 - GML, Charles Goldfarb
206 | * 1974 (is that date right?) - SGML
207 | * 1978 ?? - TeX
208 | * 1980 - Scribe, Brian Reid, doctoral thesis
209 | * 1984 ?? - LaTeX
210 | * 1986 - SGML ISO Standard ISO 8879
211 | * 1989 ?? - HTML
212 | * setext - introduced 1991
213 | * 1996 - XML
214 | * StructuredText - introduced through Zope
215 | * reStructuredText - 
216 | * MathML - 
217 | 
218 | .. _`wikipedia - Runoff`: https://en.wikipedia.org/wiki/Runoff_(program)
219 | 
220 | 
221 | 
222 | Mumblings
223 | =========
224 | 
225 | These may or may not get used.
226 | 
227 | 
228 | Readability versus writeability
229 | -------------------------------
230 | There is an obvious tradeoff to be made between how readable a format is, and
231 | how simple it is to write. For instance, delimiting headers by leading
232 | characters::
233 | 
234 |   # Header 1
235 |   ## Header 2
236 | 
237 | is much simpler than having to type underlines::
238 | 
239 |   Header 1
240 |   ========
241 | 
242 |   Header 2
243 |   --------
244 | 
245 | Also, having a pre-defined set of underlines (e.g., ``===`` always means title,
246 | ``---`` means subtitle, etc.) is easier to learn and easier to use than
247 | allowing any underlining choice (provided it is consistent within a document),
248 | but may be considered to remove the author's choice on which form of
249 | underlining reads best *in this particular document*.
250 | 
251 | As in so many things, the Zen of Python still has applicability - it is then
252 | left up to the reader how well it has been followed.
253 | 
254 | The advantages of having a competent specification
255 | --------------------------------------------------
256 | It is normally regarded as a good thing to have multiple implementations of a
257 | specification - not least because it helps to iron out misunderstandings of
258 | what that specification means. Standardisation can help to mediate that
259 | understanding (although not always as much as one might hope), and Python gets
260 | by quite well by just having people communicate a lot and having a reasonable
261 | test suite for the language.
262 | 
263 | It's not always an obviously good thing, though.
264 | 
265 | There are many forms of markdown, but the original implementation of markdown
266 | is essentially frozen, as is the original documentation, and that "definition"
267 | of markdown is both ambiguous, and does not address various tasks that people
268 | want to do. Nor is the original author willing to help with this situation [3]_.
269 | This means that different markdown implementations provide their
270 | own decisions on the ambiguous parts, and provide their own extensions.
271 | Unfortunately this means that markdown text is not necessarily portable
272 | between implementations. In practice, however, this probably doesn't matter
273 | much, as the use of markdown is often for documentation that belongs to a
274 | particular site or user environment, and interoperability within that
275 | site/environment is enough.
276 | 
277 | In contrast, reStructuredText is quite well specified (David Goodger having a
278 | background in SGML systems, after all). This means that the various
279 | implementations of reStructuredText can be specific about what they do or
280 | don't support, and in general interoperability should be better, or at least
281 | more predictable.
282 | 
283 | Incidentally, it probably also makes it possible to produce a general linter for
284 | reStructuredText - i.e., a program to inspect the text for errors before
285 | running it through docutils to produce output - which is harder to do in a
286 | portable manner for markdown, because there are so many markdowns.
287 | 
288 | .. [1] both not escaped in this text, of course
289 | .. [2] the answer is, of course, "whichever is suitable" / "whichever you
290 |    choose", although I would suggest that for a large public project (gov.uk,
291 |    documentation for the RaspberryPi) markdown should be adopted, as it is
292 |    simpler, whilst for more challenging uses (or people who prefer more
293 |    challenging markup), reStructuredText is good. And as reStructuredText
294 |    suggests that "if you need to do things it doesn't support, use something
295 |    else", then I think the same can apply to markdown and (perhaps) moving on
296 |    to reStructuredText.
297 | .. [3] whilst I personally find that hard to understand, it's not as if we're
298 |    *paying* anything for the privilege of using markdown, we're using
299 |    something given freely as it is/was.
300 | 
301 | 
302 | Comparisons
303 | -----------
304 | Comparing markdown, reStructuredText and AsciiDoc (to pick three).
305 | 
306 | *Is this section worth anything? I'm not actually convinced.*
307 | 
308 | NB: check whether AsciiDoctor also always goes through docbook
309 | 
310 |   ======================   ============  ====================     ========================
311 |   **Concept**              **markdown**  **reStructuredText**     **AsciiDoc**
312 |   ----------------------   ------------  --------------------     ------------------------
313 |   readability              a main aim    the main aim             a main aim
314 |   closely specified        no            yes                      yes
315 |   output to                various       various                  docbook and then various
316 |   inline HTML              yes           delimited [#a]_          delimited [#b]_
317 |   nested inline markup     ?             no                       yes
318 |   non-trivial list items   no            yes                      yes
319 |   extensible               no            directives               macros
320 |   conditional text         no            no                       no
321 |   executable text          no            no [#c]_                 yes
322 |   tables                   not standard  yes                      yes
323 |   ======================   ============  ====================     ========================
324 | 
325 | 
326 | .. [#a] reStructuredText allows the writer to add HTML via a directive,
327 |    but it will only be used if the output is to HTML.
328 | .. [#b] AsciiDoc produces HTML via Docbook, and Docbook provides a way of
329 |    including a file of raw HTML into the HTML output.
330 | .. [#c] this is a very conscious decision by reStructuredText
331 | 
332 | On lists
333 | --------
334 | Or, actually, treating text blocks as composable first class entities.
335 | 
336 | Why do so many markup creators believe that lists are just made up
337 | of list items with no internal structure? Do they really never want to
338 | put code into list items, or have more than one paragraph per item? Given
339 | the experience of the lengths people will go to in those wiki formats that
340 | are similarly crippled to make it *look* as if one can do these things,
341 | this would appear always to be a mistake. Back in the origianl wikiwikiweb,
342 | I think that it was quite deliberate - if one looks at the types of page
343 | being written in that wiki, there was no intent to have anything beyond a
344 | sort of "notation" page - it wasn't intended for writing whole documents.
345 | For other wikis, I suspect many have copied that limitation without
346 | thinking about the implications. For actual markup formats, though
347 | (expecially those targetting HTML, which is many of them), it's rather
348 | harder to understand the limitation.
349 | 
350 | .. vim: set filetype=rst tabstop=8  softtabstop=2 shiftwidth=2 expandtab:
351 | 


--------------------------------------------------------------------------------
/notes-per-slide-short.rst:
--------------------------------------------------------------------------------
  1 | Notes per slide
  2 | ===============
  3 | 
  4 | A history of markup languages
  5 | =============================
  6 | 
  7 |   By Tibs / Tony Ibbs
  8 | 
  9 |   This version for Write The Docs, Prague, 2018.
 10 | 
 11 |   Written using reStructuredText_.
 12 | 
 13 |   Converted to PDF slides using pandoc_ and beamer_.
 14 | 
 15 |   Source and extended notes at https://github.com/tibs/markup-history
 16 | 
 17 | .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 18 | .. _pandoc: https://pandoc.org
 19 | .. _beamer: https://github.com/josephwright/beamer
 20 | 
 21 | .. |TeX| replace:: :math:`\text{\TeX}`
 22 | 
 23 | .. |LaTeX| replace:: :math:`\text{\LaTeX}`
 24 | 
 25 | A summary of some of the more obvious bits of the history of document markup.
 26 | 
 27 | And only hitting the "high spots" for what I am talking about.
 28 | 
 29 | However, the github repository has the source for these slides, and also a set
 30 | of extended notes with links. I'll give the URL again at the end.
 31 | 
 32 | ----
 33 | 
 34 | Timeline
 35 | --------
 36 | 
 37 |   * 1960s TYPSET and RUNOFF, GML
 38 |   * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
 39 |   * 1980s |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
 40 |   * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, XML
 41 |   * 2000s reStructuredText, AsciiDoc, markdown
 42 | 
 43 | I'm ignoring anything that isn't just text (so, music, mathematics, diagrams,
 44 | bibliographies, indices, etc.).
 45 | 
 46 | Even so, this is clearly not all of the text markup formats there are, but
 47 | hopefully its a good survey.
 48 | 
 49 | There's a lot to cover, even so.
 50 | 
 51 | What's interesting, though, is that almost everything named is still in
 52 | use, in one form or another.
 53 | 
 54 | Note: I'm not going to follow a strict linear sequence in time, but instead
 55 | work partially by topic.
 56 | 
 57 | ----
 58 | 
 59 | The types of markup
 60 | -------------------
 61 | 
 62 |   Presentational or Semantic
 63 | 
 64 |   ...but also lightweight, and maybe programmable
 65 | 
 66 | *Presentational*: how the text should be presented, e.g., as a man page, on a
 67 | screen, or on a typeset page.
 68 | 
 69 | Even at the beginning of our timeline, people had access to typesetters, and
 70 | wanted to drive them.
 71 | 
 72 | Centering, right justification and so on are laborious, so worth
 73 | automating.
 74 | 
 75 | And presentation on different displays (or even line printers) may use
 76 | different techniques to produce effects such as bolding.
 77 | 
 78 | *Semantic*: marking up the meaning of the text.
 79 | 
 80 | One of the important early realisations was that even presentation benefits
 81 | from some degree of semantics - i.e., "heading", not "font X at size Y in
 82 | bold".
 83 | 
 84 | Indexing and creation of references is another sort of semantic markup of
 85 | presentationally marked documents.
 86 | 
 87 | But it can also be important to mark up the meaning of text for its own sake.
 88 | 
 89 | Subcategories, mainly of Presentational
 90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 91 | 
 92 | *Lightweight markup*: simple to type, and hopefully easier to read. Hence also
 93 | 
 94 | *Programmable markup*: markup with what is (essentially) a programming
 95 | language (wikipedia calls this "procedural" markup). For instance, |TeX|.
 96 | 
 97 | Obviously a markup may span categories.
 98 | 
 99 | ----
100 | 
101 | 1964: RUNOFF
102 | ------------
103 | 
104 |   .. code:: roff
105 | 
106 |     .LINE LENGTH 60
107 |     .LEFT MARGIN 0
108 |     .PARAGRAPH 5
109 |     Call us on our toll free number
110 | 
111 |     .CENTER
112 |     1-800-555-5555
113 | 
114 |     and we will respond as soon as convenient.
115 | 
116 | 1964 RUNOFF *Presentational*
117 | 
118 | Jerome H. Saltzer for CTSS (Compatible Time Sharing System)
119 | 
120 | Commands starting with a dot in the first column.
121 | 
122 | Commands could be abbreviated, e.g., ``.ls`` instead of ``.list``, and
123 | ``.le;`` instead of ``list element;``.
124 | 
125 | Inline commands shift the "case", for instance in and out of bold case.
126 | 
127 | Ported to BCPL and Multics. Ancestor to roff and thus, ultimately, all of
128 | the roff family.
129 | 
130 | In the 1980s/1990s I used Digital Standard Runoff, also a direct descendant.
131 | 
132 | This example is (more or less) from the original TYPSET/RUNOFF documentation.
133 | 
134 | ----
135 | 
136 | 1969: GML / 1986: SGML
137 | ----------------------
138 | 
139 |   *DTD for a list:*
140 | 
141 |   .. code:: DTD
142 | 
143 |     <!--      ELEMENT MIN CONTENT             >
144 |     <!ELEMENT list    - - (item)+             >
145 |     <!ELEMENT item    O O (#PCDATA, (list)*)  >
146 | 
147 |   *and such a list:*
148 | 
149 |   .. code:: sgml
150 | 
151 |     <list>
152 |     <item>First item</item>
153 |     <item>Second item</item>
154 |     <item>Last item</item>
155 |     </list>
156 | 
157 | 
158 | 1969 GML, 1986 SGML *Semantic* and *"meta"* (DTDs)
159 | 
160 | 1969 GML (Charles Goldfarb, Edward Mosher, Raymond Lorie - note the initials
161 | of the surnames) at IBM. 
162 | 
163 | 1986 [Standard] Generalised Markup Language.
164 | 
165 | The GML starter set was a set of macros for IBM Script.
166 | 
167 | A mechanism for *describing* markup languages. Use of the DTD.
168 | 
169 | Sensibly, SGML came with a "starter set" drafted by Joan Smith and
170 | Janet Vandore.
171 | 
172 | SGML uses DTDs (Document Type Definitions) to describe the set of
173 | markup declarations that form a *document type* (e.g., SGML itself, XML,
174 | HTML).
175 | 
176 | Shown is a DTD fragment for defining a simple list, and an example of the
177 | list structure described.
178 | 
179 | SGML allows the definition of elements that are implicitly closed by
180 | another element - e.g., <li> and <p> in HTML.
181 | 
182 | In our example::
183 | 
184 |     <!ELEMENT list - - (item)+ >
185 | 
186 | * The element being defined is ``list``.
187 | * The two hyphens indicate that both the start tag ``<list>`` and the end tag
188 |   ``</list>`` for this element are required.
189 | * The ``+`` means that there must be "at least one ``<item>`` element".
190 | 
191 | In::
192 | 
193 |   <!ELEMENT item O O (#PCDATA, (list)*)  >
194 | 
195 | * The two ``O`` ("oh", not "zero") characters mean that both the start and end
196 |   tags can be omitted.
197 | * The end of the specification tells us that an ``item`` may contain
198 |   ``PCDATA`` (text) or zero or more ``list`` elements.
199 | 
200 | XML
201 | ~~~
202 | 
203 | In 1997 XML arrives.
204 | 
205 |    "XML is an application profile of SGML"
206 | 
207 | It's a simpler subset of SGML, which makes parsers easier to write.
208 | 
209 | Other SGML based tools (TEI, Docbook, HTML itself) have generally moved
210 | towards using XML rather than SGML in their specification.
211 | 
212 | ----
213 | 
214 | 1970s: roff, nroff, troff, groff
215 | --------------------------------
216 | 
217 |   .. code:: roff
218 | 
219 |     .TH CORRUPT 1
220 |     .SH NAME
221 |     corrupt \- modify files by randomly changing bits
222 |     .SH SYNOPSIS
223 |     .B corrupt
224 |     [\fB\-n\fR \fIBITS\fR]
225 |     [\fB\-\-bits\fR \fIBITS\fR]
226 |     .IR file ...
227 |     .SH DESCRIPTION
228 |     .B corrupt
229 |     modifies files by toggling a randomly chosen bit.
230 |     .SH OPTIONS
231 |     .TP
232 |     .BR \-n ", " \-\-bits =\fIBITS\fR
233 |     Set the number of bits to modify.  Default is one bit.
234 | 
235 | 1970s \*roff *Presentational*. Still in use (as 1990: groff)
236 | 
237 | Started as a transliteration of the BCPL version of runoff, for UNIX,
238 | around 1970.
239 | 
240 | The example is a (fake) man page, using the ``man`` macro package from
241 | Lars Wirzenius' `Writing manual pages`_
242 | 
243 | * ``.TH`` = title
244 | * ``.SH`` = sub-heading
245 | * ``.B`` = bold
246 | * other font usages (e.g., normal font and underlining) are indicated by the
247 |   ``\f`` sequences.
248 | 
249 | .. _`Writing manual pages`: https://liw.fi/manpages/,
250 | 
251 | Whilst the roff family are not strictly speaking programmable as such, their
252 | use of macros means that in practice they are as capable as systems such as
253 | |TeX| (although I don't think that DSLs like |LaTeX| exist as-such).
254 | 
255 | ----
256 | 
257 | 1977/1978: |TeX| / 1983: |LaTeX|
258 | --------------------------------
259 | 
260 |   .. code:: latex
261 | 
262 |     \begin{center}
263 |     \rule{5in}{0.1mm}
264 |     \end{center}
265 | 
266 |     \section*{Captain Competent strikes again}
267 | 
268 |     The superhero is a familiar concept in comics, science
269 |     fiction and many other fields. However, I am more
270 |     interested in what might be called `the competent
271 |     hero'. This is a subtler form of protagonist---a
272 |     person who has attained {\em competence} in their
273 |     daily life.
274 | 
275 | The example is |LaTeX|, because that is more likely to be familiar to the
276 | audience, and most likely what they would use in preference to |TeX| itself.
277 | 
278 | 1977/1978 |TeX|
279 | 
280 | *Presentational with semantic leanings*. Programmable. Still in use.
281 | 
282 | Designed and mostly written by Donald Knuth.
283 | 
284 | Driven by the need to guarantee accurate typesetting of mathematics.
285 | 
286 | In serious use of |TeX|, one starts by defining lots of useful
287 | commands - although `the TeXbook`_ has many useful ideas one can copy.
288 | 
289 | .. _`The TeXbook`: http://www.ctex.org/documents/shredder/src/texbook.pdf
290 | 
291 | 
292 | 1983 |LaTeX| *Presentational*. Still in use.
293 | 
294 | Leslie Lamport.
295 | 
296 | |LaTeX| is essentially a DSL written in |TeX|. It's probably still
297 | the best known, but certainly not the only one.
298 | 
299 | I used to write plain |TeX|, but most people actually use |LaTeX|,
300 | which dates from about 1983/1984. |LaTeX| is probably still dominant in
301 | scientific and mathematical publishing.
302 | 
303 | This example is from the first edition of a fanzine I used to edit - all of
304 | the markup is provided for me by |LaTeX|, so I didn't need to define anything
305 | here.
306 | 
307 | ----
308 | 
309 | 1987: TEI
310 | ---------
311 | 
312 |   .. code:: XML
313 | 
314 |     <lg type="sestina">
315 |     <lg type="sestet" rhyme="ababab">
316 |     <l>I saw my soul at rest upon a
317 |        <rhyme label="a" xml:id="A">day</rhyme></l>
318 |     <l>As a bird sleeping in the nest of
319 |        <rhyme label="b" xml:id="B">night</rhyme>,</l>
320 |     <l>Among soft leaves that give the starlight
321 |        <rhyme label="a" xml:id="C">way</rhyme></l>
322 |     <l>To touch its wings but not its eyes with
323 |        <rhyme label="b" xml:id="D">light</rhyme>;</l>
324 |     <l>So that it knew as one in visions
325 |        <rhyme label="a" xml:id="E">may</rhyme>,</l>
326 |     <l>And knew not as men waking, of
327 |        <rhyme label="b" xml:id="F">delight</rhyme>.</l>
328 |     </lg>
329 | 
330 | 1987 TEI *Semantic*. Still in use today.
331 | 
332 | "The mission of the Text Encoding Initiative is to develop and maintain a
333 | set of high-quality guidelines for the encoding of humanities texts, and to
334 | support their use by a wide community of projects, institutions, and
335 | individuals"
336 | 
337 | Some mark up of the start of Swinburne's Sestina,
338 | taken from the poetry examples at `TEI By Example`_,
339 | showing the working of the ryhming scheme.
340 | 
341 | ``rhyme="ababab"`` and then on each line the rhyming word and which part (a,
342 | b) of the rhyming scheme it is.
343 | 
344 | (In the 16x9 version of this slide, I've set these far to the right, to make
345 | them more obvious.)
346 | 
347 | .. _`TEI by example`: http://teibyexample.org/examples/TBED04v00.htm
348 | 
349 | ----
350 | 
351 | 1991: HTML
352 | ----------
353 | 
354 |   .. code:: HTML
355 | 
356 |     <!DOCTYPE html>
357 |     <html>
358 |       <head>
359 |         <title>This is a title</title>
360 |       </head>
361 |       <body>
362 |         <p>Hello world!</p>
363 |       </body>
364 |     </html>
365 | 
366 | 1991 HTML *Presentational*. Still in use today (although rather altered).
367 | 
368 | Tim Berners-Lee, at CERN, specified HTML and wrote browser and server
369 | software in late 1990. The "HTML Tags" document was first mentioned on the
370 | internet in 1991.
371 | 
372 | HTML 2.0 was published as IETF RFC 1866 in 1995. There was no specification
373 | called "HTML 1".
374 | 
375 | HTML until HTML5 is an SGML document type - an SGML application.
376 | 
377 | Wikipedia says:
378 | 
379 |   "The HTML5 syntax is no longer based on SGML despite the similarity of its
380 |   markup. It has, however, been designed to be backward compatible with common
381 |   parsing of older versions of HTML. It comes with a new introductory line
382 |   that looks like an SGML document type declaration, ``<!DOCTYPE html>``, which
383 |   triggers the standards-compliant rendering mode."
384 | 
385 |   ----
386 | 
387 | 1991: Docbook
388 | -------------
389 | 
390 |   .. code:: XML
391 | 
392 |     <?xml version="1.0" encoding="UTF-8"?>
393 |     <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
394 |     "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
395 |     <article>
396 |      <title>DocBook Tutorial</title>
397 |      <articleinfo>
398 |       <author>
399 |        <firstname>Adrian</firstname> <surname>Giurca</surname>
400 |       </author>
401 |       <date>April 5, 2005</date>
402 |      </articleinfo>
403 |      <section>
404 |       <title>What is DocBook ?</title>
405 |       <para>DocBook is an SGML dialect developed by O'Reilly
406 |       and HaL Computer Systems in 1991.</para>
407 |      </section>
408 |     </article>
409 | 
410 | 1991 Docbook *Semantic*. Still in use today.
411 | 
412 | *(Same year as HTML)*
413 | 
414 | "A semantic markup language for technical documentation"
415 | 
416 | However, I think it is often "semantic" in the same way that |LaTeX| is
417 | "semantic" - often also for presentational purposes (but not *necessarily*).
418 | 
419 | Example of Docbook 4.3 from
420 | http://www.informatik.tu-cottbus.de/~giurca/tutorials/DocBook/index.htm
421 | 
422 | Before Docbook 5, an SGML language, defined by a DTD
423 | 
424 | DocBook 5 is an XML language, formally defined by a RELAX NG schema with
425 | integrated Schematron rules.
426 | 
427 | ----
428 | 
429 | 1991: setext
430 | ------------
431 | 
432 |   .. code:: reST
433 | 
434 |      This is the title. There can be only one.
435 |      =========================================
436 |        Body text must be indented by two spaces.
437 | 
438 |      A subheading
439 |      ------------
440 |        **Bold words** and ~italic~ are supported.
441 |        _Underlined_words_ are also supported.
442 |        `Backquoted words` are not touched.
443 | 
444 |      > This text will be represented using a monospaced font.
445 | 
446 |      * This text will have a bullet mark before it.
447 | 
448 |      .. Two dots introduce text that can be ignored.
449 |      .. Two dots alone mean the logical end of text.
450 |      ..
451 | 
452 | 1991 setext *Presentational*. Lightweight.
453 | 
454 | *(Same year as HTML and Docbook)*
455 | 
456 | *(This is the beginning of our look at lightweight markup formats)*
457 | 
458 | Ian Feldman, for use in writing the TidBITs electronic newsletter.
459 | 
460 | Partly a reaction to SGML. Clearly influential on all of the succeeding
461 | lightweight markups.
462 | 
463 | Note: the body text must be indented.
464 | 
465 | Multi-word italics (``~multiword~italics~``) appears to have been an
466 | extension. 
467 | 
468 | Underlining should really mean italics, following typewritten text
469 | conventions.
470 | 
471 | Two dots for comments or special meaning.
472 | 
473 | Unclear if lists actually were supported. Specification not very clear,
474 | specified by examples, not rigorous at all. Really just what he needed for his
475 | own purposes.
476 | 
477 |   (Links look very similar to one of the forms that reStructuredText supports)
478 | 
479 |   ----
480 | 
481 | 1994/1995: wikiwikiweb
482 | ----------------------
483 | 
484 |   .. code:: wiki
485 | 
486 |     Paragraphs are not indented.
487 | 
488 |     * This is a list item
489 |     ** This is a sub-list item
490 | 
491 |       Indented text is monospaced.
492 | 
493 |     We have ''emphasis'', '''bold''', '''''bold italic''''',
494 |     and a LinkToAnotherPage.
495 | 
496 |     But we can A''''''voidMakingAWikiLink.
497 | 
498 |     No HTML, tables, headers, maths, scripts.
499 |     No links within a page.
500 | 
501 | 1994/1995 wikiwikiweb *Presentational*
502 | 
503 | The first wiki, invented by Ward Cunningham
504 | 
505 | Like most wiki formats, specified by example, with no real rigour. However,
506 | I suspect this may have been done deliberately, to encourage learning by
507 | exploration.
508 | 
509 | I think that newlines within a paragraph are ignored, but it's hard  to
510 | tell.
511 | 
512 | The lack of capability is deliberate, aiming to promote a particular style
513 | of discourse:
514 | 
515 |    "This wiki is quite bare bones, and intentionally so. Less formatting
516 |    means you have to concentrate on saying things carefully and clearly.
517 |    Content over form."
518 | 
519 | Introduced CamelCasedWords as wiki links.
520 | 
521 | Single quotes - this really distressed me when I first came across it:
522 | 
523 | - 1 = single quote
524 | - 2 = emphasis
525 | - 3 = bold
526 | - 5 = emphasised bold (2+3)
527 | - 6 are used to stop a CamelCased word from being a WikiLink
528 | 
529 | Later wiki formats appear not to have understood *why* the design decisions
530 | were taken.
531 | 
532 | ----
533 | 
534 | 
535 | ----
536 | 
537 | 2001/2002: reStructuredText
538 | ---------------------------
539 | 
540 |   .. code:: reST
541 | 
542 |      This is a heading
543 |      =================
544 |      This is a paragraph. Body text is not indented.
545 | 
546 |        - This is a list item. Words can be *emphasized*,
547 |          **strong** or ``teletype`` - yes, that's paired
548 |          backquotes [1]_.
549 |        - This is a list item as well.
550 | 
551 |          This is more of the second list item. It is indented
552 |          appropriately.
553 | 
554 |      This is a sub-heading
555 |      ---------------------
556 |      Sub-section body text is not indented either.
557 | 
558 |      .. [1] Note the indentation inside the list item.
559 | 
560 | In part, a reaction to 1996 StructuredText which was created by Jim Fulton of
561 | Digital Creations (later Zope Foundation) for use in Zope, and which suffered
562 | from documentation by example and ambiguous markup.
563 | 
564 | 2001/2002 reStructuredText *Presentational*. Lightweight.
565 | 
566 | David Goodger had a professional background in SGML.
567 | 
568 | Original mailing of the idea to the Doc-Sig was in Nov 2000
569 | 
570 | * Readability is the main aim.
571 | * Output agnosticism is an important secondary aim.
572 | 
573 | Clearly influenced by setext (and StructuredText), but with more rigor.
574 | 
575 | Paragraphs do *not* need to be indented, but note how the text in list items
576 | follows the indentation of the text in the first line.
577 | 
578 | It is well specified, allowing other implementations which behave in the same way.
579 | 
580 | * < and > are not special - Guido wanted to be able to discuss XML
581 |   and suchlike without quoting stuff.
582 | * Similarly, it's not possible for underscores to be significant, as leading
583 |   and trailing underscores have meaning in Python.
584 | * Perhaps in part because of that, there is no way to specify underlined text,
585 |   which is a Good Thing.
586 | 
587 | Consciously designed to allow doing certain things but not others - basically,
588 | if a document is too complex for reStructuredText, use something like Docbook.
589 | 
590 | Sphinx was first introduced as a means of using reStructuredText to write
591 | the Python documenation, instead of |LaTeX|.
592 | 
593 | ----
594 | 
595 | 2002: Asciidoc
596 | --------------
597 | 
598 | .. There doesn't seem to be a Pygments mode for AsciiDoc
599 | 
600 |   .. code:: reST
601 | 
602 |     = This is a title heading
603 |     This is a paragraph. Body text is not indented.
604 | 
605 |     - This is a list item. Words can be _italic_, *bold* or
606 |      +mono+ - yes, that's paired plus-signs.
607 |     - This is a list item as well.
608 |     +
609 |     This is more of the second list item. It is "`joined on`"
610 |     by the `+`.footnote:[Note the quotation marks around
611 |     _joined on_.]
612 | 
613 |     == This is a sub-heading
614 |     Sub-section body text is not indented either.
615 | 
616 | 2002 Asciidoc *Presentational*. Lightweight.
617 | 
618 | Stuart Rackham
619 | 
620 | Aimed specifically as a lightweight way of producing docbook.
621 | 
622 | Producing docbook means that toolchains exist to produce almost anything else.
623 | 
624 | The original Asciidoc implementation was written in Python in 2002.
625 | 
626 | Asciidoctor came out in 2013, and is written in Ruby.
627 | 
628 | Well specified, allowing other implementations which behave in the same way.
629 | 
630 | Note the use of underlines to indicate emphasis, a nice look back to
631 | typewritten manuscripts.
632 | 
633 | Paired plus signs for monotyped text.
634 | 
635 | Use of a + sign to continue a list item into a second paragraph.
636 | 
637 | Nice (easy to type) way of distinguishing opening and closing quotes.
638 | 
639 | Footnotes done inline - less readable, but more convenient.
640 | 
641 | Note that headings can also be delimited with underlining characters, but that
642 | doesn't seem to be the normal convention (it's not what the current
643 | Asciidoctor documentation introduces, although https://asciidoclive.com
644 | still shows that style in its example).
645 | 
646 | ----
647 | 
648 | 2004: markdown
649 | --------------
650 | 
651 |   .. code:: markdown
652 | 
653 |      # This is a heading
654 |      This is a paragraph. Body text is not indented.
655 | 
656 |      - This is a list item. Words can be *emphasized*,
657 |      **strong** or `inline` - that's single backquotes.
658 |      - This is a list item as well.
659 | 
660 |          This is more of the second list item. Its first line
661 |        must be indented by 4 spaces or a tab.
662 | 
663 |      ## This is a sub-heading
664 |      Sub-section body text is not indented either.
665 | 
666 |      (No footnotes. But <tt>HTML</tt> is allowed.)
667 | 
668 | 2004 markdown *Presentation*. Lightweight.
669 | 
670 | John Gruber, collaborating with Aaron Swartz on the syntax
671 | 
672 | *So* nearly wonderful.
673 | 
674 | Yes, I know headings can be underline as well ("setext" style, as it terms
675 | it), but I've never seen anyone actually doing that.
676 | 
677 | * Aimed at producing HTML.
678 | 
679 |    From the syntax page: "Markdown’s syntax is intended for one purpose: to be
680 |    used as a format for *writing* for the web." Their emphasis.
681 | 
682 | * Poorly specified. Ambiguous.
683 | * Allows embedded HTML.
684 | * Most implementations extend it, incompatibly.
685 | 
686 | Very successful because (the most popular variants) hit a good compromise on
687 | the simplicity/capability curve.
688 | 
689 | Personally, I *think* that markdown would be improved a lot by just removing
690 | the ability to embed HTML.
691 | 
692 | Hopefully CommonMark_ will improve the situation - for instance,
693 | github-flavoured markdown is at least now based on CommonMark.
694 | 
695 | .. _CommonMark: http://commonmark.org/
696 | 
697 | (The CommonMark specification is rigorous, and well written, but inevitably
698 | very long, which rather undoes the perceived "simplicity" of markdown. Also,
699 | it is only really atttempting to specify the common ground of the markdown
700 | variants, and thus does not, for instance, include table.  
701 | 
702 | Note that it calls the underlined heading style "setext headings", which is
703 | nice.)
704 | 
705 | ----
706 | 
707 | Fin
708 | ---
709 | 
710 |   * 1960s TYPSET and RUNOFF, GML
711 |   * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
712 |   * 1980s |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
713 |   * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, XML
714 |   * 2000s reStructuredText, AsciiDoc, markdown
715 | 
716 |   Written using reStructuredText_.
717 | 
718 |   Converted to PDF slides using pandoc_ and beamer_.
719 | 
720 |   Source and extended notes at https://github.com/tibs/markup-history
721 | 
722 | Since this version of the talk is to be given to Write the Docs, I assume they
723 | already know about the Write the Docs website: http://www.writethedocs.org/
724 | 
725 | 
726 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
727 | 


--------------------------------------------------------------------------------
/notes-per-slide-long.rst:
--------------------------------------------------------------------------------
  1 | Notes per slide
  2 | ===============
  3 | 
  4 | A history of markup languages
  5 | =============================
  6 | 
  7 |   By Tibs / Tony Ibbs
  8 | 
  9 |   This version for the Cambridge Write The Docs meetup, Feb 2018
 10 | 
 11 |   Written using reStructuredText_.
 12 | 
 13 |   Converted to PDF slides using pandoc_ and beamer_.
 14 | 
 15 |   Source and extended notes at https://github.com/tibs/markup-history
 16 | 
 17 | .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 18 | .. _pandoc: https://pandoc.org
 19 | .. _beamer: https://github.com/josephwright/beamer
 20 | 
 21 | .. |TeX| replace:: :math:`\text{\TeX}`
 22 | 
 23 | .. |LaTeX| replace:: :math:`\text{\LaTeX}`
 24 | 
 25 | A summary of some of the more obvious bits of the history of document markup.
 26 | 
 27 | And only hitting the "high spots" for what I am talking about.
 28 | 
 29 | However, the github repository has the source for these slides, and also a set
 30 | of extended notes with links. I'll give the URL again at the end.
 31 | 
 32 | ----
 33 | 
 34 | Timeline
 35 | --------
 36 | 
 37 |   * 1960s TYPSET and RUNOFF, GML
 38 |   * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
 39 |   * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
 40 |   * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
 41 |   * 2000s reStructuredText, AsciiDoc, markdown
 42 | 
 43 | I'm ignoring anything that isn't just text (so, music, mathematics, diagrams,
 44 | bibliographies, indices, etc.).
 45 | 
 46 | Even so, this is clearly not all of the text markup formats there are, but
 47 | hopefully its a good survey.
 48 | 
 49 | There's a lot to cover, even so.
 50 | 
 51 | What's interesting, though, is that almost everything named is still in
 52 | use, in one form or another.
 53 | 
 54 | Note: I'm not going to follow a strict linear sequence in time, but instead
 55 | work partially by topic.
 56 | 
 57 | ----
 58 | 
 59 | The types of markup
 60 | -------------------
 61 | 
 62 |   Presentational or Semantic
 63 | 
 64 |   ...but also lightweight, and maybe programmable
 65 | 
 66 | *Presentational*: how the text should be presented, e.g., as a man page, on a
 67 | screen, or on a typeset page.
 68 | 
 69 | Even at the beginning of our timeline, people had access to typesetters, and
 70 | wanted to drive them.
 71 | 
 72 | Centering, right justification and so on are laborious, so worth
 73 | automating.
 74 | 
 75 | And presentation on different displays (or even line printers) may use
 76 | different techniques to produce effects such as bolding.
 77 | 
 78 | *Semantic*: marking up the meaning of the text.
 79 | 
 80 | One of the important early realisations was that even presentation benefits
 81 | from some degree of semantics - i.e., "heading", not "font X at size Y in
 82 | bold".
 83 | 
 84 | Indexing and creation of references is another sort of semantic markup of
 85 | presentationally marked documents.
 86 | 
 87 | But it can also be important to mark up the meaning of text for its own sake.
 88 | 
 89 | Subcategories, mainly of Presentational
 90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 91 | 
 92 | *Lightweight markup*: simple to type, and hopefully easier to read. Hence also
 93 | 
 94 | *Programmable markup*: markup with what is (essentially) a programming
 95 | language (wikipedia calls this "procedural" markup). For instance, |TeX|.
 96 | 
 97 | Obviously a markup may span categories.
 98 | 
 99 | ----
100 | 
101 | 1964: RUNOFF
102 | ------------
103 | 
104 |   .. code:: roff
105 | 
106 |     .LINE LENGTH 60
107 |     .LEFT MARGIN 0
108 |     .PARAGRAPH 5
109 |     Call us on our toll free number
110 | 
111 |     .CENTER
112 |     1-800-555-5555
113 | 
114 |     and we will respond as soon as convenient.
115 | 
116 | 1964 RUNOFF *Presentational*
117 | 
118 | Jerome H. Saltzer for CTSS (Compatible Time Sharing System)
119 | 
120 | Commands starting with a dot in the first column.
121 | 
122 | Commands could be abbreviated, e.g., ``.ls`` instead of ``.list``, and
123 | ``.le;`` instead of ``list element;``.
124 | 
125 | Inline commands shift the "case", for instance in and out of bold case.
126 | 
127 | Ported to BCPL and Multics. Ancestor to roff and thus, ultimately, all of
128 | the roff family.
129 | 
130 | In the 1980s/1990s I used Digital Standard Runoff, also a direct descendant.
131 | 
132 | This example is (more or less) from the original TYPSET/RUNOFF documentation.
133 | 
134 | ----
135 | 
136 | 1969: GML and 1986: SGML
137 | ------------------------
138 | 
139 | **Not in the shorter version**
140 | 
141 |   .. code:: sgml
142 | 
143 |     <td> The Implication of SGML for the Preparation of
144 |     Scientific Publications
145 |     <au> Joan M. Smith
146 |     ...
147 |     <ab> The &SGML (SGML) is a draft international standard
148 |     for publishing.
149 |     ...
150 |     <h1>Introduction
151 |     <p> The official title of SGML, currently, is ISO/DIS 8879,
152 |     <ci> Information Processing &end Text and Office Systems
153 |     &end &SGML (SGML) </ci>. <ref> ISO/DIS 8879 ... </ref>
154 |     ...
155 |     <p>There are several points worthy of note here:
156 |     <ul>
157 |     <li> the normal publishing delay with ISO standards...
158 |     ...
159 |     </ul>
160 | 
161 | 1969 GML, 1986 SGML *Semantic* and *"meta"* (DTDs)
162 | 
163 | 1969 GML (Charles Goldfarb, Edward Mosher, Raymond Lorie - note the initials
164 | of the surnames) at IBM. 
165 | 
166 | 1986 [Standard] Generalised Markup Language.
167 | 
168 | The example is actually SGML. It is transcribed from Figure 3 of the
169 | paper named. The ellipses are mine.
170 | 
171 | The GML starter set was a set of macros for IBM Script.
172 | 
173 | A mechanism for *describing* markup languages. Use of the DTD.
174 | 
175 | Sensibly, SGML came with a "starter set" drafted by Joan Smith and
176 | Janet Vandore.
177 | 
178 | Note how SGML allowed the
179 | definition of elements that were implicitly closed by another element -
180 | e.g., <li> and <p>
181 | 
182 | - <td> is the document title
183 | - <ad> is an address, <al> an address line
184 | - <ab> is the abstract
185 | - <ci> indicates a citation, which rendered as italics in the resulting paper.
186 | - <ref> marks up a Reference, collected for the section at the end of the document.
187 | - &SGML is an "entity reference" that expands to 'Standard Generalized
188 |   Markup Language' - we're familiar with things like &eacute; from HTML.
189 | 
190 | ----
191 | 
192 | SGML DTD
193 | --------
194 | 
195 |   *DTD for a list:*
196 | 
197 |   .. code:: DTD
198 | 
199 |     <!--      ELEMENT MIN CONTENT             >
200 |     <!ELEMENT list    - - (item)+             >
201 |     <!ELEMENT item    O O (#PCDATA, (list)*)  >
202 | 
203 |   *and such a list:*
204 | 
205 |   .. code:: sgml
206 | 
207 |     <list>
208 |     <item>First item</item>
209 |     <item>Second item</item>
210 |     <item>Last item</item>
211 |     </list>
212 | 
213 | SGML uses DTDs (Document Type Definitions) to describe the set of
214 | markup declarations that form a *document type* (e.g., SGML itself, XML,
215 | HTML).
216 | 
217 | Shown is a DTD fragment for defining a simple list, and an example of the
218 | list structure described.
219 | 
220 | SGML allows the definition of elements that were implicitly closed by
221 | another element - e.g., <li> and <p> in HTML.
222 | 
223 | In our example::
224 | 
225 |     <!ELEMENT list - - (item)+ >
226 | 
227 | * The element being defined is ``list``.
228 | * The two hyphens indicate that both the start tag ``<list>`` and the end tag
229 |   ``</list>`` for this element are required.
230 | * The ``+`` means that there must be "at least one ``<item>`` element".
231 | 
232 | In::
233 | 
234 |   <!ELEMENT item O O (#PCDATA, (list)*)  >
235 | 
236 | * The two ``O`` ("oh", not "zero") characters mean that both the start and end
237 |   tags can be omitted.
238 | * The end of the specification tells us that an ``item`` may contain
239 |   ``PCDATA`` (text) or zero or more ``list`` elements.
240 | 
241 | ----
242 | 
243 | 1997: XML
244 | ---------
245 | 
246 | **Not in the shorter version**
247 | 
248 |    "XML is an application profile of SGML"
249 | 
250 | 1997 XML (Extensible Markup Language) *Semantic*.
251 | 
252 | No example because there is no "default" XML - a schema is needed.
253 | 
254 | XML was compiled by a working group of eleven members, supported by a
255 | (roughly) 150-member Interest Group.
256 | 
257 | It's a simpler subset of SGML, which makes parsers easier to write.
258 | 
259 | Other SGML based tools (TEI, Docbook, HTML itself) have generally moved
260 | towards using XML rather than SGML in their specification.
261 | 
262 | ----
263 | 
264 | 1970s: roff, nroff, troff, groff
265 | --------------------------------
266 | 
267 |   .. code:: roff
268 | 
269 |     .TH CORRUPT 1
270 |     .SH NAME
271 |     corrupt \- modify files by randomly changing bits
272 |     .SH SYNOPSIS
273 |     .B corrupt
274 |     [\fB\-n\fR \fIBITS\fR]
275 |     [\fB\-\-bits\fR \fIBITS\fR]
276 |     .IR file ...
277 |     .SH DESCRIPTION
278 |     .B corrupt
279 |     modifies files by toggling a randomly chosen bit.
280 |     .SH OPTIONS
281 |     .TP
282 |     .BR \-n ", " \-\-bits =\fIBITS\fR
283 |     Set the number of bits to modify.  Default is one bit.
284 | 
285 | 1970s \*roff *Presentational*. Still in use (as 1990: groff)
286 | 
287 | Started as a transliteration of the BCPL version of runoff, for UNIX,
288 | around 1970.
289 | 
290 | The example is a (fake) man page, using the ``man`` macro package from
291 | Lars Wirzenius' `Writing manual pages`_
292 | 
293 | * ``.TH`` = title
294 | * ``.SH`` = sub-heading
295 | * ``.B`` = bold
296 | * other font usages (e.g., normal font and underlining) are indicated by the
297 |   ``\f`` sequences.
298 | 
299 | .. _`Writing manual pages`: https://liw.fi/manpages/,
300 | 
301 | ----
302 | 
303 | 1990: groff
304 | -----------
305 | 
306 | **Not in the shorter version**
307 | 
308 |   .. code:: roff
309 | 
310 |     ..INCLUDE mission-statement-strings.mom
311 |     .TITLE    "\*[Groff-Mission-Statement]
312 |     .SUBTITLE "\*[2014]
313 |     .INCLUDE  mission-statement-style.mom
314 |     .PP
315 |     As the most widely deployed implementation of troff in use
316 |     today, groff holds an important place in the Unix universe.
317 |     Frequently and erroneously dismissed as a legacy program
318 |     for formatting Unix manuals (manpages), groff is in fact a
319 |     sophisticated system for producing high-quality typeset
320 |     material, from business correspondence to complex,
321 |     technical reports and plate-ready books. \*[BU3]With an
322 |     impressive record for backward compatibility, it continues
323 |     to evolve and play a leading role in the development of
324 |     free typesetting software.
325 | 
326 | Some example groff (GNU troff) code.
327 | 
328 | Whilst the roff family are not strictly speaking programmable as such, their
329 | use of macros means that in practice they are as capable as systems such as
330 | |TeX| (although I don't think that DSLs like |LaTeX| exist as-such).
331 | 
332 | ----
333 | 
334 | 1977/1978: |TeX|
335 | ----------------
336 | 
337 |   .. code:: tex
338 | 
339 |     \name{Name Redacted} wrote:
340 | 
341 |     \beginletter
342 |     Thoughts on ``Why I like children's books'':
343 | 
344 |     \beginlist
345 |     \item{\blob} They aren't afraid to show a sense of wonder.
346 |     \item{\blob} They aren't `duty bound' to include love
347 |     interest for the sake of it.
348 |     \item{\blob} They are rarely cynical, rarely bitter---but
349 |     the best do not avoid tragedy and truth.
350 |     \item{\blob} They are willing to teach the simple lessons
351 |     of being human---which adult books so often scorn, but
352 |     which we all need to learn and relearn.
353 |     \endlist
354 | 
355 | 1977/1978 |TeX|
356 | 
357 | *Presentational with semantic leanings*. Programmable. Still in use.
358 | 
359 | Designed and mostly written by Donald Knuth.
360 | 
361 | Driven by the need to guarantee accurate typesetting of mathematics.
362 | 
363 | In serious use of |TeX|, one starts by defining lots of useful
364 | commands - although `the TeXbook`_ has many useful ideas one can copy.
365 | 
366 | In this example, `\item` is a standard definition, but all of the other
367 | commands starting with backslash were defined by my own macros.
368 | 
369 | .. _`The TeXbook`: http://www.ctex.org/documents/shredder/src/texbook.pdf
370 | 
371 | ----
372 | 
373 | 1983: |LaTeX|
374 | -------------
375 | 
376 | **Not in the shorter version**
377 | 
378 |   .. code:: latex
379 | 
380 |     \begin{center}
381 |     \rule{5in}{0.1mm}
382 |     \end{center}
383 | 
384 |     \section*{Captain Competent strikes again}
385 | 
386 |     The superhero is a familiar concept in comics, science
387 |     fiction and many other fields. However, I am more
388 |     interested in what might be called `the competent
389 |     hero'. This is a subtler form of protagonist---a
390 |     person who has attained {\em competence} in their
391 |     daily life.
392 | 
393 | 1983 |LaTeX| *Presentational*. Still in use.
394 | 
395 | Leslie Lamport.
396 | 
397 | |LaTeX| is essentially a DSL written in |TeX|. It's probably still
398 | the best known, but certainly not the only one.
399 | 
400 | I used to write plain |TeX|, but most people actually use |LaTeX|,
401 | which dates from about 1983/1984. |LaTeX| is probably still dominant in
402 | scientific and mathematical publishing.
403 | 
404 | This example is from the first edition of the same fanzine - all of the
405 | markup is provided for me by |LaTeX|, so I didn't need to define anything
406 | here.
407 | 
408 | ----
409 | 
410 | 1980: Scribe
411 | ------------
412 | 
413 |   .. code:: scribe
414 | 
415 |       @Heading(The Beginning)
416 |       @Begin(Quotation)
417 |           Let's start at the very beginning, a @i(very good
418 |           place) to start
419 |       @End(Quotation)
420 | 
421 |   *which can also be written:*
422 | 
423 |   .. code:: scribe
424 | 
425 |       @Heading(The Beginning)
426 |       @(Quotation
427 |           Let's start at the very beginning, a @i(very good
428 |           place) to start
429 |       )
430 | 
431 | 1980 Scribe *Presentational*
432 | 
433 | Described in Brian Reid's 1980 doctoral dissertation at Carnegie Mellon
434 | University. Lisp based.
435 | 
436 | Similar systems still appear to exist.
437 | 
438 | Note the two representations - the second one being more lisp-like.
439 | 
440 | ----
441 | 
442 | 1987: TEI
443 | ---------
444 | 
445 |   .. code:: XML
446 | 
447 |     <lg type="sestina">
448 |     <lg type="sestet" rhyme="ababab">
449 |     <l>I saw my soul at rest upon a
450 |        <rhyme label="a" xml:id="A">day</rhyme></l>
451 |     <l>As a bird sleeping in the nest of
452 |        <rhyme label="b" xml:id="B">night</rhyme>,</l>
453 |     <l>Among soft leaves that give the starlight
454 |        <rhyme label="a" xml:id="C">way</rhyme></l>
455 |     <l>To touch its wings but not its eyes with
456 |        <rhyme label="b" xml:id="D">light</rhyme>;</l>
457 |     <l>So that it knew as one in visions
458 |        <rhyme label="a" xml:id="E">may</rhyme>,</l>
459 |     <l>And knew not as men waking, of
460 |        <rhyme label="b" xml:id="F">delight</rhyme>.</l>
461 |     </lg>
462 | 
463 | 1987 TEI *Semantic*. Still in use today.
464 | 
465 | "The mission of the Text Encoding Initiative is to develop and maintain a
466 | set of high-quality guidelines for the encoding of humanities texts, and to
467 | support their use by a wide community of projects, institutions, and
468 | individuals"
469 | 
470 | Some mark up of the start of Swinburne's Sestina,
471 | taken from the poetry examples at `TEI By Example`_,
472 | showing the working of the ryhming scheme.
473 | 
474 | ``rhyme="ababab"`` and then on each line the rhyming word and which part (a,
475 | b) of the rhyming scheme it is.
476 | 
477 | (In the 16x9 version of this slide, I've set these far to the right, to make
478 | them more obvious.)
479 | 
480 | .. _`TEI by example`: http://teibyexample.org/examples/TBED04v00.htm
481 | 
482 | ----
483 | 
484 | 1991: HTML
485 | ----------
486 | 
487 |   .. code:: HTML
488 | 
489 |     <!DOCTYPE html>
490 |     <html>
491 |       <head>
492 |         <title>This is a title</title>
493 |       </head>
494 |       <body>
495 |         <p>Hello world!</p>
496 |       </body>
497 |     </html>
498 | 
499 | 1991 HTML *Presentational*. Still in use today (although rather altered).
500 | 
501 | Tim Berners-Lee, at CERN, specified HTML and wrote browser and server
502 | software in late 1990. The "HTML Tags" document was first mentioned on the
503 | internet in 1991.
504 | 
505 | HTML 2.0 was published as IETF RFC 1866 in 1995. There was no specification
506 | called "HTML 1".
507 | 
508 | HTML until HTML5 is an SGML document type - an SGML application.
509 | 
510 | Wikipedia says:
511 | 
512 |   "The HTML5 syntax is no longer based on SGML despite the similarity of its
513 |   markup. It has, however, been designed to be backward compatible with common
514 |   parsing of older versions of HTML. It comes with a new introductory line
515 |   that looks like an SGML document type declaration, ``<!DOCTYPE html>``, which
516 |   triggers the standards-compliant rendering mode."
517 | 
518 |   ----
519 | 
520 | 1991: Docbook
521 | -------------
522 | 
523 |   .. code:: XML
524 | 
525 |     <?xml version="1.0" encoding="UTF-8"?>
526 |     <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
527 |     "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
528 |     <article>
529 |      <title>DocBook Tutorial</title>
530 |      <articleinfo>
531 |       <author>
532 |        <firstname>Adrian</firstname> <surname>Giurca</surname>
533 |       </author>
534 |       <date>April 5, 2005</date>
535 |      </articleinfo>
536 |      <section>
537 |       <title>What is DocBook ?</title>
538 |       <para>DocBook is an SGML dialect developed by O'Reilly
539 |       and HaL Computer Systems in 1991.</para>
540 |      </section>
541 |     </article>
542 | 
543 | 1991 Docbook *Semantic*. Still in use today.
544 | 
545 | *(Same year as HTML)*
546 | 
547 | "A semantic markup language for technical documentation"
548 | 
549 | However, I think it is often "semantic" in the same way that |LaTeX| is
550 | "semantic" - often also for presentational purposes (but not *necessarily*).
551 | 
552 | Example of Docbook 4.3 from
553 | http://www.informatik.tu-cottbus.de/~giurca/tutorials/DocBook/index.htm
554 | 
555 | Before Docbook 5, an SGML language, defined by a DTD
556 | 
557 | DocBook 5 is an XML language, formally defined by a RELAX NG schema with
558 | integrated Schematron rules.
559 | 
560 | ----
561 | 
562 | 1991: setext
563 | ------------
564 | 
565 |   .. code:: reST
566 | 
567 |      This is the title. There can be only one.
568 |      =========================================
569 |        Body text must be indented by two spaces.
570 | 
571 |      A subheading
572 |      ------------
573 |        **Bold words** and ~italic~ are supported.
574 |        _Underlined_words_ are also supported.
575 |        `Backquoted words` are not touched.
576 | 
577 |      > This text will be represented using a monospaced font.
578 | 
579 |      * This text will have a bullet mark before it.
580 | 
581 |      .. Two dots introduce text that can be ignored.
582 |      .. Two dots alone mean the logical end of text.
583 |      ..
584 | 
585 | 1991 setext *Presentational*. Lightweight.
586 | 
587 | *(Same year as HTML and Docbook)*
588 | 
589 | *(This is the beginning of our look at lightweight markup formats)*
590 | 
591 | Ian Feldman, for use in writing the TidBITs electronic newsletter.
592 | 
593 | Partly a reaction to SGML. Clearly influential on all of the succeeding
594 | lightweight markups.
595 | 
596 | Note: the body text must be indented.
597 | 
598 | Multi-word italics (``~multiword~italics~``) appears to have been an
599 | extension. 
600 | 
601 | Underlining should really mean italics, following typewritten text
602 | conventions.
603 | 
604 | Two dots for comments or special meaning.
605 | 
606 | Unclear if lists actually were supported. Specification not very clear,
607 | specified by examples, not rigorous at all. Really just what he needed for his
608 | own purposes.
609 | 
610 |   (Links look very similar to one of the forms that reStructuredText supports)
611 | 
612 |   ----
613 | 
614 | 1994/1995: wikiwikiweb
615 | ----------------------
616 | 
617 |   .. code:: wiki
618 | 
619 |     Paragraphs are not indented.
620 | 
621 |     * This is a list item
622 |     ** This is a sub-list item
623 | 
624 |       Indented text is monospaced.
625 | 
626 |     We have ''emphasis'', '''bold''', '''''bold italic''''',
627 |     and a LinkToAnotherPage.
628 | 
629 |     But we can A''''''voidMakingAWikiLink.
630 | 
631 |     No HTML, tables, headers, maths, scripts.
632 |     No links within a page.
633 | 
634 | 1994/1995 wikiwikiweb *Presentational*
635 | 
636 | The first wiki, invented by Ward Cunningham
637 | 
638 | Like most wiki formats, specified by example, with no real rigour. However,
639 | I suspect this may have been done deliberately, to encourage learning by
640 | exploration.
641 | 
642 | I think that newlines within a paragraph are ignored, but it's hard  to
643 | tell.
644 | 
645 | The lack of capability is deliberate, aiming to promote a particular style
646 | of discourse:
647 | 
648 |    "This wiki is quite bare bones, and intentionally so. Less formatting
649 |    means you have to concentrate on saying things carefully and clearly.
650 |    Content over form."
651 | 
652 | Introduced CamelCasedWords as wiki links.
653 | 
654 | Single quotes - this really distressed me when I first came across it:
655 | 
656 | - 1 = single quote
657 | - 2 = emphasis
658 | - 3 = bold
659 | - 5 = emphasised bold (2+3)
660 | - 6 are used to stop a CamelCased word from being a WikiLink
661 | 
662 | Later wiki formats appear not to have understood *why* the design decisions
663 | were taken.
664 | 
665 | ----
666 | 
667 | 1996: StructuredText
668 | --------------------
669 | 
670 |   .. code:: reST
671 | 
672 |      This is a heading
673 | 
674 |        This is a paragraph. Body text is indented.
675 | 
676 |        - This is a list item. Words can be *emphasized*,
677 |        _underlined_, **strong** or 'inline' - yes, that's
678 |        using single quotes [1].
679 | 
680 |        o This is a list item as well.
681 | 
682 |        This is a sub-heading
683 | 
684 |          Sub-section body text is indented even further. This
685 |          indented body text makes the sub-heading a heading.
686 | 
687 |      .. [1] Or we could use ``backquotes``.
688 | 
689 | 1996 StructuredText *Presentational*. Lightweight.
690 | 
691 | Created by Jim Fulton of Digital Creations (later Zope Foundation) for use
692 | in Zope.
693 | 
694 | Specified by example, somewhat ambiguously.
695 | 
696 | Clearly influenced by setext.
697 | 
698 | Significant indentation - good idea in a programming language, not so much
699 | when writing plain text.
700 | 
701 | A heading is a heading because it is followed by a non-heading (!)
702 | 
703 | Single quotes or doubled backquotes for "inline" text.
704 | 
705 | Footnotes are fairly simple. Note the use of two dots to introduce the
706 | actual footnote.
707 | 
708 | All block entities must be separated by blank lines. That includes list items.
709 | 
710 | Note that "o" can be a list delimiter - regarded as a serious ambiguity.
711 | 
712 | Links are done as::
713 | 
714 |     visit the "Python website" :http://www.python.org/.
715 | 
716 | i.e., quoted text followed by a colon and then a URL.
717 | 
718 | ----
719 | 
720 | 2001/2002: reStructuredText
721 | ---------------------------
722 | 
723 |   .. code:: reST
724 | 
725 |      This is a heading
726 |      =================
727 |      This is a paragraph. Body text is not indented.
728 | 
729 |        - This is a list item. Words can be *emphasized*,
730 |          **strong** or ``teletype`` - yes, that's paired
731 |          backquotes [1]_.
732 |        - This is a list item as well.
733 | 
734 |          This is more of the second list item. It is indented
735 |          appropriately.
736 | 
737 |      This is a sub-heading
738 |      ---------------------
739 |      Sub-section body text is not indented either.
740 | 
741 |      .. [1] Note the indentation inside the list item.
742 | 
743 | 2001/2002 reStructuredText *Presentational*. Lightweight.
744 | 
745 | David Goodger had a professional background in SGML.
746 | 
747 | Original mailing of the idea to the Doc-Sig was in Nov 2000
748 | 
749 | * Readability is the main aim.
750 | * Output agnosticism is an important secondary aim.
751 | 
752 | Clearly influenced by setext and StructuredText, but with more rigor.
753 | 
754 | It is well specified, allowing other implementations which behave in the same way.
755 | 
756 | * < and > are not special - Guido wanted to be able to discuss XML
757 |   and suchlike without quoting stuff.
758 | * Similarly, it's not possible for underscores to be significant, as leading
759 |   and trailing underscores have meaning in Python.
760 | * Perhaps in part because of that, there is no way to specify underlined text,
761 |   which is a Good Thing.
762 | 
763 | In contrast to StructuredText:
764 | 
765 | * Body text isn't indented (what makes sense for programming languages is
766 |   irritating for text), but things must line up when appropriate (see the
767 |   lists).
768 | * "o" is not allowed as a list delimiter, as it is too ambiguous.
769 | 
770 | Consciously designed to allow doing certain things but not others - basically,
771 | if a document is too complex for reStructuredText, use something like Docbook.
772 | 
773 | Sphinx was first introduced as a means of using reStructuredText to write
774 | the Python documenation, instead of |LaTeX|.
775 | 
776 | ----
777 | 
778 | 2002: Asciidoc
779 | --------------
780 | 
781 | .. There doesn't seem to be a Pygments mode for AsciiDoc
782 | 
783 |   .. code:: reST
784 | 
785 |     = This is a title heading
786 |     This is a paragraph. Body text is not indented.
787 | 
788 |     - This is a list item. Words can be _italic_, *bold* or
789 |      +mono+ - yes, that's paired plus-signs.
790 |     - This is a list item as well.
791 |     +
792 |     This is more of the second list item. It is "`joined on`"
793 |     by the `+`.footnote:[Note the quotation marks around
794 |     _joined on_.]
795 | 
796 |     == This is a sub-heading
797 |     Sub-section body text is not indented either.
798 | 
799 | 2002 Asciidoc *Presentational*. Lightweight.
800 | 
801 | Stuart Rackham
802 | 
803 | Aimed specifically as a lightweight way of producing docbook.
804 | 
805 | Producing docbook means that toolchains exist to produce almost anything else.
806 | 
807 | The original Asciidoc implementation was written in Python in 2002.
808 | 
809 | Asciidoctor came out in 2013, and is written in Ruby.
810 | 
811 | Well specified, allowing other implementations which behave in the same way.
812 | 
813 | Note the use of underlines to indicate emphasis, a nice look back to
814 | typewritten manuscripts.
815 | 
816 | Paired plus signs for monotyped text.
817 | 
818 | Use of a + sign to continue a list item into a second paragraph.
819 | 
820 | Nice (easy to type) way of distinguishing opening and closing quotes.
821 | 
822 | Footnotes done inline - less readable, but more convenient.
823 | 
824 | Note that headings can also be delimited with underlining characters, but that
825 | doesn't seem to be the normal convention (it's not what the current
826 | Asciidoctor documentation introduces, although https://asciidoclive.com
827 | still shows that style in its example).
828 | 
829 | ----
830 | 
831 | 2004: markdown
832 | --------------
833 | 
834 |   .. code:: markdown
835 | 
836 |      # This is a heading
837 |      This is a paragraph. Body text is not indented.
838 | 
839 |      - This is a list item. Words can be *emphasized*,
840 |      **strong** or `inline` - that's single backquotes.
841 |      - This is a list item as well.
842 | 
843 |          This is more of the second list item. Its first line
844 |        must be indented by 4 spaces or a tab.
845 | 
846 |      ## This is a sub-heading
847 |      Sub-section body text is not indented either.
848 | 
849 |      (No footnotes. But <tt>HTML</tt> is allowed.)
850 | 
851 | 2004 markdown *Presentation*. Lightweight.
852 | 
853 | John Gruber, collaborating with Aaron Swartz on the syntax
854 | 
855 | *So* nearly wonderful.
856 | 
857 | Yes, I know headings can be underline as well ("setext" style, as it terms
858 | it), but I've never seen anyone actually doing that.
859 | 
860 | * Aimed at producing HTML.
861 | 
862 |    From the syntax page: "Markdown’s syntax is intended for one purpose: to be
863 |    used as a format for *writing* for the web." Their emphasis.
864 | 
865 | * Poorly specified. Ambiguous.
866 | * Allows embedded HTML.
867 | * Most implementations extend it, incompatibly.
868 | 
869 | Very successful because (the most popular variants) hit a good compromise on
870 | the simplicity/capability curve.
871 | 
872 | Personally, I *think* that markdown would be improved a lot by just removing
873 | the ability to embed HTML.
874 | 
875 | Hopefully CommonMark_ will improve the situation - for instance,
876 | github-flavoured markdown is at least now based on CommonMark.
877 | 
878 | .. _CommonMark: http://commonmark.org/
879 | 
880 | (The CommonMark specification is rigorous, and well written, but inevitably
881 | very long, which rather undoes the perceived "simplicity" of markdown. Also,
882 | it is only really atttempting to specify the common ground of the markdown
883 | variants, and thus does not, for instance, include table.  
884 | 
885 | Note that it calls the underlined heading style "setext headings", which is
886 | nice.)
887 | 
888 | ----
889 | 
890 | Fin
891 | ---
892 | 
893 |   * 1960s TYPSET and RUNOFF, GML
894 |   * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
895 |   * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, SGML, TEI
896 |   * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, StructuredText, XML
897 |   * 2000s reStructuredText, AsciiDoc, markdown
898 | 
899 |   Written using reStructuredText_.
900 | 
901 |   Converted to PDF slides using pandoc_ and beamer_.
902 | 
903 |   Source and extended notes at https://github.com/tibs/markup-history
904 | 
905 | Since this version of the talk is to be given to Write the Docs, I assume they
906 | already know about the Write the Docs website: http://www.writethedocs.org/
907 | 
908 | 
909 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
910 | 


--------------------------------------------------------------------------------
/markup-history-extended-notes.rst:
--------------------------------------------------------------------------------
   1 | =============================
   2 | A history of markup languages
   3 | =============================
   4 | 
   5 | By Tibs / Tony Ibbs
   6 | 
   7 | .. note:: These are the extended notes to go with the slideshow, together
   8 |    with links which I hope will be useful, and perhaps act as a start on
   9 |    finding out more about markup languages.
  10 | 
  11 | .. We can represent TeX and LaTeX as simple text:
  12 | 
  13 | .. |TeX| replace:: TeX
  14 | 
  15 | .. |LaTeX| replace:: LaTeX
  16 | 
  17 | .. contents::
  18 | 
  19 | Introduction
  20 | ============
  21 | 
  22 | We've always added markup to text.
  23 | 
  24 | When writing by hand, we underline to indicate emphasis.
  25 | 
  26 | Typewritten manuscripts would similarly use underlining (of various sorts) to
  27 | indicate titles, emphasis, and so on.
  28 | 
  29 | Play scripts use various abbreviations and conventions to distinguish dialogue,
  30 | effects and stage arrangements.
  31 | 
  32 | This "history" (or "opinionated overview") will hopefully serve as a starting
  33 | point for finding out more about markup languages, why they exist and what a
  34 | wide range of possibilities they represent.
  35 | 
  36 | I'm taking "markup language" to mean a way of marking up plain text so it can
  37 | be turned into something more interesting (for instance, output to a
  38 | typesetter), or so it can be analysed more easily.
  39 | 
  40 | Interestingly, almost all of the markup formats I'm going to discuss are still
  41 | in use today.
  42 | 
  43 | .. note:: Basically, these notes are a summary of some of the more obvious
  44 |    bits of the history of document markup. It's the sort of stuff that one can
  45 |    find with a little bit of memory and some googling. That means that there
  46 |    is doubtless interesting stuff I've missed, and there is also bound to be
  47 |    *exciting* work going on **right now** that is not mentioned anywhere here
  48 |    - for instance, I think Pollen_ looks quite interesting.
  49 | 
  50 | .. _Pollen: http://docs.racket-lang.org/pollen/
  51 | 
  52 | Types of markup
  53 | ===============
  54 | 
  55 | It is common to distiguish two main ways of marking up text:
  56 | 
  57 | * Semantic - what it means
  58 | * Presentational - how it should be shown
  59 | 
  60 | Semantic markup is intended to give more information about the meaning of the
  61 | text. This may be an end in and of itself, for reasons as disparate as
  62 | allowing extraction of information about aeroplane parts or determining the
  63 | parts of speech in a corpus.
  64 | 
  65 | Presentational markup indicates how the text should be presented, for instance
  66 | as a man page, or printed using a typesetter.
  67 | 
  68 |   (Even at the beginning of our timeline, people had access to typesetters, and
  69 |   wanted to drive them.)
  70 | 
  71 | These two aren't necessarily entirely distinct, though: one of the important
  72 | early realisations was that presentational markup benefits from some degree of
  73 | semantics. So, for instance, it is more useful to say "heading", than
  74 | "bold font X at size Y".
  75 | 
  76 | We can also separate out two other types of markup
  77 | 
  78 | * Lightweight markup us designed to be simple to type, and hopefully easier to
  79 |   read.
  80 | 
  81 | * Programmable markup (wikipedia calls this "procedural") is actually merging
  82 |   a programming language with the text. The best know of these is |TeX|.
  83 | 
  84 | Things I'm ignoring
  85 | ===================
  86 | 
  87 | I'm ignoring anything that isn't just text, so:
  88 | 
  89 | * Music
  90 | * Mathematics
  91 | * Pictures/diagrams/graphs
  92 | * Bibliographies and indices
  93 | * All sorts of other things
  94 | 
  95 | Further, there are many more markup formats than I discuss here (for instance,
  96 | and perhaps unsurprisingly, people have been inventing "easier" ways to write
  97 | HTML documents since the early days of HTML).
  98 | 
  99 | My own experience
 100 | =================
 101 | I believe I first used a markup language when writing up my final year
 102 | Computer Science project, in 1981. This would have been a Cambridge written
 103 | format that ran on the local mainframe.
 104 | 
 105 | Later on, at work, I came across DEC's RUNOFF, which became Digital Standard
 106 | Runoff (DSR). In the 1980s I wrote a partial bibliography of Joan Aiken using
 107 | DSR, but unfortunately no longer have the original sources, as I converted it
 108 | to HTML.
 109 | 
 110 | HTML I wrote almost from its inception - back then it was quite common to
 111 | write HTML by hand (it was a much simpler thing than it is today).
 112 | 
 113 | I first wrote |TeX| at work as well, and introduced the use of |LaTeX| for our
 114 | in-house API documentation. Personally, I preferred |TeX| to |LaTeX|, but
 115 | realise I was in the minority.
 116 | 
 117 | When Python converted its documentation from |LaTeX|, I originally thought
 118 | this was a bad idea, as clearly (!) anyone could learn |LaTeX| (which was
 119 | originally used, before the adoption of reStructuredText). It was explained to
 120 | me, though, that the problem wasn't that people couldn't learn |LaTeX|, it was
 121 | that they'd look at it and say "I don't *want* to learn that, I can't see why
 122 | I should". Which made me change my mind.
 123 | 
 124 | Nowadays, reStructuredText is my "how to write text" format for almost all
 125 | my own purposes, and like everyone I can also write markdown when necessary
 126 | (although not with any great understanding of its edge cases).
 127 | 
 128 | A timeline
 129 | ==========
 130 | 
 131 | * 1964 TYPSET and RUNOFF
 132 | * 1967 William Tunincliffe: "The separation of the information content of
 133 |   documents from their format". Goldfarb credits him with starting the generic
 134 |   coding movement (i.e., the idea of using descriptive tags like "heading"
 135 |   rather than "format-17") with this presentation given at a meeting of the
 136 |   Canadian Government Printing Office in September 1967
 137 | * 1969 GML (Goldfarb, Mosher, Lorie) at IBM
 138 | * "1970s" roff, script, runoff, document
 139 | * 1976 nroff and troff (Ossanna)
 140 | * 1978 bib and refer
 141 | * 1977/1978 |TeX| and Metafont ("classic" version, written in SAIL, Knuth and others)
 142 | * 1978-1980 Scribe (Reid)
 143 | * 1982 |TeX| and Metafont in WEB/Pascal
 144 | * 1983-1985 |LaTeX| (Lamport)
 145 | * 1984 Postscript (`Wikipedia on PostScript`_ has 1982-1984)
 146 | * 1986 ISO standard SGML (although the first working draft was in 1980)
 147 | * 1987 TEI 
 148 | * 1991 Tim Berners-Lee wrote the "HTML Tags" document, proposing what was
 149 |   essentially HTML, built on SGML
 150 | * 1989-1991 HTML and HTTP (Berners-Lee)
 151 | * 1991 setext, (Feldman) for use in the TidBITS electronic newsletter
 152 | * 1991 Docbook
 153 | * 1993 PDF (Adobe Systems)
 154 | * 1994/1995 WikiWikiWeb (Cunningham) the first wiki
 155 | * 1994 Perl 5.000 introduces POD
 156 | * 1995 Java appears, and with it javadoc
 157 | * 1996 StructuredText (Fulton, Zope Corporation / Digital Creations)
 158 | * 1997 XML
 159 | * 2000 Digital Creations begins development of StructuredTextNG
 160 | * 2000 First draft of reStructuredText spec posted to Doc-Utils SIG (Goodger)
 161 | * 2001-2002 reStructuredText and Docutils
 162 | * 2001-2005 DITA
 163 | * 2002 PEP 287 "reStructuredText Standard Docstring Format"
 164 | * 2002 AsciiDoc (Rackham)
 165 | * 2004 markdown (Gruber and Swartz)
 166 | * 2013 Asciidoctor (Waldron and others)
 167 | 
 168 | Various sources were used in creating the timeline, but a special mention has
 169 | to go to `25 Years of |TeX| and METAFONT\: Looking Back and Looking
 170 | Forward`_, and of course to Wikipedia.
 171 | 
 172 | General
 173 | =======
 174 | These are some interesting general links.
 175 | 
 176 | * `Wikipedia on Markup Language`_ - In general, this is a good place to start.
 177 |   See the taxonomy of (three) types therein, and the history section.
 178 | * `Wikipedia List of document markup languages`_ - always fun to look through.
 179 |   Notice how several of the "Well-known document markup languages" are
 180 |   essentially HTML variants.
 181 | * `Charles Goldfarb — the Godfather of Markup Languages`_, Georgi Dalako,
 182 |   undated. A quick introduction to one of the important influences on this
 183 |   field.
 184 | * `Don Knuth's homepage`_, the homepage of Dona;d E. Knuth, Professor Emeritus
 185 |   at Stanford University. There are so many reasons to browse these pages.
 186 | * `An informal look into the history of digital typography`_, David Walden, 2016.
 187 |   This is a good introduction, starting with letter presses and moving on into
 188 |   the digital world. Read it for a look at where markup came from, and what it
 189 |   is driving.
 190 | * `From boiling lead and black art\: An essay on the history of mathematical typography`_,
 191 |   Eddie Smith, 2017, is a lovely article on mathematical typesetting, from the
 192 |   invention of the printing press to |TeX|.
 193 | 
 194 | .. _`Wikipedia on Markup Language`: https://en.wikipedia.org/wiki/Markup_language
 195 | .. _`Wikipedia List of document markup languages`: https://en.wikipedia.org/wiki/List_of_document_markup_languages
 196 | .. _`Charles Goldfarb — the Godfather of Markup Languages`: http://history-computer.com/Internet/Birth/Goldfarb.html
 197 | .. _`Don Knuth's homepage`: http://www-cs-faculty.stanford.edu/~knuth/
 198 | .. _`An informal look into the history of digital typography`: http://www.tug.org/tug2016/walden-digital.pdf
 199 | .. _`From boiling lead and black art\: An essay on the history of mathematical typography`: http://www.practicallyefficient.com/2017/10/13/from-boiling-lead-and-black-art.html
 200 | 
 201 | * `Wikipedia on docstrings`_. My memory is that Python docstrings were
 202 |   inspired by the existence of docstrings in Emacs Lisp. This wikipedia page
 203 |   gives examples from several different programming languages.
 204 | * `Docstring Convention: Python vs Emacs Lisp`_, Xah Lee, 2014. This compares
 205 |   the difference in how one is meant to write good dosctrings in the two
 206 |   different programming languages.
 207 | 
 208 | .. _`Wikipedia on docstrings`: https://en.wikipedia.org/wiki/Docstring
 209 | .. _`Docstring Convention: Python vs Emacs Lisp`: http://xahlee.info/comp/python_vs_elisp_docstring_convention.html
 210 | 
 211 | * `SGML and PDF--Why We Need Both`_, Bill Kasdorf, Volume 3, Issue 4: *Moving
 212 |   from Print to Electronic Publishing*, June, 1998. This essentially talks about the
 213 |   difference between semantic and presentational representation. I'm not sure
 214 |   that it would occur to anyone now-a-days to ask the question this article
 215 |   proposes, but the answer is definitely still valuable.
 216 |   
 217 | .. _`SGML and PDF--Why We Need Both`: https://quod.lib.umich.edu/j/jep/3336451.0003.406?view=text;rgn=main
 218 | 
 219 | RUNOFF and its descendants
 220 | ==========================
 221 | 
 222 | :1964 RUNOFF: *Presentational*
 223 | :1970s \*roff: *Presentational*. Still in use.
 224 | :1990 groff: *Presentational*. Still in use.
 225 | 
 226 | RUNOFF
 227 | ------
 228 | The original RUNOFF and TYPSET were written by Jerome H. Saltzer for CTSS_
 229 | (Compatible Time Sharing System). Between them, they provided simple text
 230 | layout and pagination, including right justification.
 231 | 
 232 | This example is (more or less) from the original TYPSET/RUNOFF documentation:
 233 | 
 234 | .. code:: roff
 235 | 
 236 |   .LINE LENGTH 60
 237 |   .LEFT MARGIN 0
 238 |   .PARAGRAPH 5
 239 |   Call us on our toll free number
 240 | 
 241 |   .CENTER
 242 |   1-800-555-5555
 243 | 
 244 |   and we will respond as soon as convenient.
 245 | 
 246 | Commands start with a dot in the first column - this makes sense as it's not
 247 | usual to start a line of English text with a dot.
 248 | 
 249 | Commands could be abbreviated, which would have been important with the
 250 | keyboards in use at the time. Inline commands can be used to shift the "case",
 251 | for instance in and out of bold case.
 252 | 
 253 | The following is an example of Digital Standard Runoff (DSR), showing that the
 254 | name had an enduring meaning. I used to use DSR on VMS in the 1980s/90s.
 255 | 
 256 | .. code:: roff
 257 | 
 258 |     .TITLE A simpler DSR example
 259 |     .CHAPTER This is a chapter
 260 | 
 261 |     This is the first paragraph.
 262 |     .LIST
 263 |     .LIST ELEMENT;This is a list element. We have *bold\* and &underline\&.
 264 |     .LIST ELEMENT;This is another list element. I like interrobangs ?%!
 265 |     .END LIST
 266 | 
 267 | Abbreviated forms are still available, e.g., ``.ls`` instead of
 268 | ``.list``, and ``.le;`` instead of ``list element;``.
 269 | 
 270 | RUNOFF was ported to BCPL and Multics, and became the ancestor to roff and
 271 | thus, ultimately, all of the roff family.
 272 | 
 273 | The roffs
 274 | ---------
 275 | 
 276 | roff started as a transliteration of the BCPL version of runoff, for UNIX,
 277 | around 1970.
 278 | 
 279 | The roff family are typically used with macro processors, allowing more domain
 280 | specific commands to be converted into the actual roff commands. This means
 281 | that the system as a whole can be regarded as essentially programmable,
 282 | even though the roff program itself is not.
 283 | 
 284 | The example given here (from Lars Wirzenius' `Writing manual pages`_)
 285 | is a (fake) man page, using the ``man`` macro package:
 286 | 
 287 | .. code:: roff
 288 | 
 289 |   .TH CORRUPT 1
 290 |   .SH NAME
 291 |   corrupt \- modify files by randomly changing bits
 292 |   .SH SYNOPSIS
 293 |   .B corrupt
 294 |   [\fB\-n\fR \fIBITS\fR]
 295 |   [\fB\-\-bits\fR \fIBITS\fR]
 296 |   .IR file ...
 297 |   .SH DESCRIPTION
 298 |   .B corrupt
 299 |   modifies files by toggling a randomly chosen bit.
 300 |   .SH OPTIONS
 301 |   .TP
 302 |   .BR \-n ", " \-\-bits =\fIBITS\fR
 303 |   Set the number of bits to modify.  Default is one bit.
 304 | 
 305 | In this example, ``.TH`` = title, ``.SH`` = sub-heading, ``.B`` = bold, other
 306 | font usages (e.g., normal font and underlining) are indicated by the ``\f``
 307 | sequences.
 308 | 
 309 | Today, the dominant roff program is probably ``groff``, or GNU roff. Here is
 310 | an example of groff:
 311 | 
 312 | .. code:: roff
 313 | 
 314 |   ..INCLUDE  mission-statement-strings.mom
 315 |   .TITLE    "\*[Groff-Mission-Statement]
 316 |   .SUBTITLE "\*[2014]
 317 |   .INCLUDE  mission-statement-style.mom
 318 |   .PP
 319 |   As the most widely deployed implementation of troff in use today,
 320 |   groff holds an important place in the Unix universe.  Frequently
 321 |   and erroneously dismissed as a legacy program for formatting
 322 |   Unix manuals (manpages), groff is in fact a sophisticated system
 323 |   for producing high-quality typeset material, from business
 324 |   correspondence to complex, technical reports and plate-ready books.
 325 |   \*[BU3]With an impressive record for backward compatibility, it
 326 |   continues to evolve and play a leading role in the development of
 327 |   free typesetting software.
 328 | 
 329 | Interesting links:
 330 | 
 331 | * `Wikipedia on TYPSET and RUNOFF`_
 332 | * CTSS_ (the Compatible Time Sharing System) which is the machine on which the
 333 |   first RUNOFF ran.
 334 | * `Wikipedia on Runoff`_
 335 | * `Wikipedia on roff`_
 336 | * `Wikipedia on nroff`_ ("newer roff")
 337 | * `Wikipedia on troff`_ ("typesetter roff")
 338 | * `Wikipedia on groff`_ ("GNU troff")
 339 | * A repository of `Historical documents from classical RUNOFF and files using the RUNOFF language`_
 340 | * The `OpenVMS Digital Standard Runoff Reference Manual`_ from May 1993.
 341 | * The manpage ``ROFF(7)``: `roff - concepts and history
 342 |   of roff typesetting`_, part of the `groff`_ distribution. It has an overview
 343 |   of the history of the roffs, and a summary of how they work.
 344 | * `History of UNIX Manpages`_, Kristaps Dzonsons, 2011. The history of the
 345 |   UNIX manpage "based on source code, manuals, and first-hand accounts".
 346 |   Also traces the naming of programs RUNOFF through roff, SCRIPT, compose,
 347 |   roff (a different thing), nroff and so on.
 348 | * The Groff_ manual
 349 | * `Groff and mom\: an overview`_, Peter Schaffer, 2017
 350 | * Mom_, macros for GNU troff, Peter Schaffter. mom is a flexible typesetting
 351 |   and document formatting package that allows you to create high-quality
 352 |   Portable Document Format (.pdf) or PostScript (.ps) files. It is a macro set
 353 |   that sits on top of groff_.
 354 | * `Writing manual pages`_, Lars Wirzenius, 2016
 355 | * From `Unix history`_, `William Stewart`_, 1996-2014:V
 356 | 
 357 |     In the spring of 1971, the interest in Unix began to grow, so instead of
 358 |     writing a new text-processing system as originally proposed, Thompson and
 359 |     Ritchie translated the existing "roff" text formatter from the PDP-7 to the
 360 |     PDP-11 and made it available to the Patent department on their new Unix
 361 |     system. This practical success helped convince Bell Labs of the value of
 362 |     Unix, and shortly thereafter they bought the team one of the first, powerful
 363 |     PDP-11/45 minicomputers to continue their development. A series of
 364 |     progressively better "editions" of Unix were then released.
 365 | 
 366 | .. _`Wikipedia on TYPSET and RUNOFF`: https://en.wikipedia.org/wiki/TYPSET_and_RUNOFF
 367 | .. _CTSS: https://en.wikipedia.org/wiki/Compatible_Time-Sharing_System
 368 | .. _`Historical documents from classical RUNOFF and files using the RUNOFF language`: https://github.com/bwarken/RUNOFF_historical/
 369 | .. _`Wikipedia on Runoff`: https://en.wikipedia.org/wiki/Runoff_(program)
 370 | .. _`Wikipedia on roff`: https://en.wikipedia.org/wiki/Roff_(computer_program)
 371 | .. _`Wikipedia on nroff`: https://en.wikipedia.org/wiki/Nroff
 372 | .. _`Wikipedia on troff`: https://en.wikipedia.org/wiki/Troff
 373 | .. _`Wikipedia on groff`: https://en.wikipedia.org/wiki/Groff_(software)
 374 | .. _`roff - concepts and history of roff typesetting`: https://linux.die.net/man/7/roff
 375 | .. _`OpenVMS Digital Standard Runoff Reference Manual`: http://h20565.www2.hpe.com/hpsc/doc/public/display?docId=emr_na-c04623260  
 376 | .. _`Writing manual pages`: https://liw.fi/manpages/
 377 | .. _`History of UNIX Manpages`: http://manpages.bsd.lv/history.html
 378 | .. _Groff: http://www.gnu.org/software/groff/
 379 | .. _`Groff and mom\: an overview`: https://www.gnu.org/software/groff/groff-and-mom.pdf
 380 | .. _mom: http://www.schaffter.ca/mom/
 381 | .. _`Unix history`: https://www.livinginternet.com/i/iw_unix_dev.htm 
 382 | .. _`William Stewart`: http://williamstewart.com/
 383 | 
 384 | .. note:: Also, preceding RUNOFF, in 1963, there is `TJ-2`_:
 385 | 
 386 |       TJ-2 (Type Justifying Program) was published by Peter Samson in May 1963
 387 |       and is thought to be the first page layout program. ...  TJ-2 was
 388 |       succeeded by TYPSET and RUNOFF, a pair of complementary programs written
 389 |       in 1964 for the CTSS operating system. TYPSET and RUNOFF soon evolved
 390 |       into runoff for Multics, which was in turn ported to Unix in the 1970s as
 391 |       roff.
 392 | 
 393 |    -- from the wikipedia page
 394 | 
 395 |    .. _`TJ-2`: `Wikipedia on TJ-2`_
 396 |    .. _`Wikipedia on TJ-2`: https://en.wikipedia.org/wiki/TJ-2
 397 | 
 398 | GML and SGML and XML
 399 | ====================
 400 | 
 401 | :1969 GML: *Semantic* and *meta*
 402 | :1986 SGML: *Semantic* and *meta* (DTDs)
 403 | :1997 XML: *Semantic* and *meta* (various schema languages)
 404 | 
 405 | GML
 406 | ---
 407 | 
 408 | 1969 GML
 409 | 
 410 | GML stood for Generalized Markup Language, but also for the initials of the
 411 | surnames of its inventors (Charles Goldfarb, Edward Mosher, Raymond Lorie).
 412 | 
 413 | It was intended to be a mechanism for *describing* markup languages, rather
 414 | than a markup language itself.
 415 | 
 416 | Here is an example of GML, from `The Roots of SGML -- A Personal
 417 | Recollection`_ by Charles F. Goldfarb. It uses the "starter set", implemented
 418 | using macros in IBM's Script_:
 419 | 
 420 | .. code::
 421 | 
 422 |   :h1.Chapter 1:  Introduction
 423 |   :p.GML supported hierarchical containers, such as
 424 |   :ol
 425 |   :li.Ordered lists (like this one),
 426 |   :li.Unordered lists, and
 427 |   :li.Definition lists
 428 |   :eol.
 429 |   as well as simple structures.
 430 |   :p.Markup minimization (later generalized and formalized in SGML),
 431 |   allowed the end-tags to be omitted for the "h1" and "p" elements.
 432 | 
 433 | SGML
 434 | ----
 435 | SGML is an ISO standard: "ISO 8879:1986 Information processing – Text and
 436 | office systems – Standard Generalized Markup Language (SGML)". The `wikipedia
 437 | page on SGML`_ gives more information on the standard and its related
 438 | standards.
 439 | 
 440 | .. _`wikipedia page on SGML`: `Wikipedia on SGML`_
 441 | 
 442 | SGML uses DTDs (Document Type Definitions) to describe the set of
 443 | markup declarations that form a *document type* (e.g., SGML itself, XML,
 444 | HTML).
 445 | 
 446 | Shown is a DTD fragment for defining a simple list:
 447 | 
 448 | .. code:: DTD
 449 | 
 450 |   <!--      ELEMENT MIN CONTENT             >
 451 |   <!ELEMENT list    - - (item)+             >
 452 |   <!ELEMENT item    O O (#PCDATA, (list)*)  >
 453 | 
 454 | and an example of the list structure described:
 455 | 
 456 | .. code:: XML
 457 | 
 458 |   <list>
 459 |   <item>First item</item>
 460 |   <item>Second item</item>
 461 |   <item>Last item</item>
 462 |   </list>
 463 | 
 464 | .. note:: SGML (like GML before it) allows the definition of elements that
 465 |     were implicitly closed by another element - e.g., <li> and <p> in HTML.
 466 | 
 467 |     In our example::
 468 | 
 469 |         <!ELEMENT list - - (item)+ >
 470 | 
 471 |     * The element being defined is ``list``.
 472 |     * The two hyphens indicate that both the start tag ``<list>`` and the end tag
 473 |       ``</list>`` for this element are required.
 474 |     * The ``+`` means that there must be "at least one ``<item>`` element".
 475 | 
 476 |     In::
 477 | 
 478 |       <!ELEMENT item O O (#PCDATA, (list)*)  >
 479 | 
 480 |     * The two ``O`` ("oh", not "zero") characters mean that both the start and end
 481 |       tags can be omitted.
 482 |     * The end of the specification tells us that an ``item`` may contain
 483 |       ``PCDATA`` (text) or zero or more ``list`` elements.
 484 | 
 485 | Sensibly, SGML also came with a "starter set", drafted by Joan Smith and
 486 | Janet Vandore.
 487 | 
 488 | The following example of SGML, using that starter set, is transcribed from
 489 | Figure 3 of the paper named in the example. The ellipses are mine.
 490 | 
 491 | .. code:: XML
 492 | 
 493 |   <td> The Implication of SGML for the Preparation of Scientific Publications
 494 |   <au> Joan M. Smith
 495 |   <ad>
 496 |   <al> National Computing Centre, Oxford Road, Manchester M1 7ED
 497 |   <ab> The &SGML (SGML) is a draft international standard for publishing.
 498 |   ...
 499 |   <h1>Introduction
 500 |   <p> The official title of SGML, currently, is ISO/DIS 8879,
 501 |   <ci> Information Processing &end Text and Office Systems &end &SGML (SGML)
 502 |   </ci>. <ref> ISO/DIS 8879 <ci> Information Processing &end Text and Office
 503 |   Systems &end &SGML (SGML). ISO, Geneva (1985). </ref>
 504 |   ...
 505 |   <p>There are several points worthy of note here:
 506 |   <ul>
 507 |   <li> the normal publishing delay with ISO standards...
 508 |   ...
 509 |   </ul>
 510 | 
 511 | where:
 512 | 
 513 |   - ``<td>`` is the document title
 514 |   - ``<ad>`` is an address, <al> an address line
 515 |   - ``<ab>`` is the abstract
 516 |   - ``<ci>`` indicates a citation, which rendered as italics in the resulting paper.
 517 |   - ``<ref>`` marks up a Reference, collected for the section at the end of the document.
 518 |   - ``&SGML`` is an "entity reference" that expands to 'Standard Generalized
 519 |     Markup Language'. You may be familiar with entity references from things
 520 |     like ``&eacute;`` in HTML.
 521 |   - ``<li>`` and ``<p>`` are implicitly closed by following elements.
 522 | 
 523 | An SGML document must declares a DOCTYPE to say what DTD it is conforming to.
 524 | The following example should look very familiar:
 525 | 
 526 | .. code:: html
 527 | 
 528 |   <!DOCTYPE html>
 529 |   <html>
 530 |     <head>
 531 |       <title>This is a title</title>
 532 |     </head>
 533 |     <body>
 534 |       <p>Hello world!</p>
 535 |     </body>
 536 |   </html>
 537 | 
 538 | Interesting links:
 539 | 
 540 | * `Wikipedia on GML`_
 541 | * `Wikipedia on SCRIPT`_
 542 | * `Wikipedia on SGML`_
 543 | * `Wikipedia on Document Type Definition`_ (i.e., DTD)
 544 | * Use of GML (specifically, the starter set) is described by:
 545 | 
 546 |   * `GML Starter Set User's Guide`_, IBM 1980, 1991
 547 |   * `GML Starter Set Reference`_, IBM 1980, 1991
 548 | 
 549 | * `The Implications of SGML for the Preparation of Scientific Publications`_,
 550 |   Joan Smith, *The Computer Journal*, Volume 29, Issue 3, 1 January 1986,
 551 |   Pages 193-200. This is the paper from which my SGML example is taken.
 552 | * W3C_ `HTML 4.01 Specification`_, section 3 `On SGML and HTML`_
 553 | * `Guidelines for Writing SGML DTDs (Draft)`_, Sandra A. Mamrak, 1989.
 554 | * `The SGML History Niche`_, Charles F. Goldfarb, 2002/2003. Some personal
 555 |   recollections by Goldfarb, all of which are well worth reading.
 556 | 
 557 | .. _`The Roots of SGML -- A Personal Recollection`: http://www.sgmlsource.com/history/roots.htm
 558 | .. _`Wikipedia on GML`: https://en.wikipedia.org/wiki/IBM_Generalized_Markup_Language
 559 | .. _Script: `Wikipedia on SCRIPT`_
 560 | .. _`Wikipedia on SGML`: https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language
 561 | .. _`Wikipedia on Document Type Definition`: https://en.wikipedia.org/wiki/Document_type_definition
 562 | .. _`GML Starter Set User's Guide`: http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/dsm04m00/CCONTENTS
 563 | .. _`GML Starter Set Reference`: http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/dsm05m00/CCONTENTS
 564 | .. _`Wikipedia on SCRIPT`: https://en.wikipedia.org/wiki/SCRIPT_(markup)
 565 | .. _`The Implications of SGML for the Preparation of Scientific Publications`: https://academic.oup.com/comjnl/article-lookup/doi/10.1093/comjnl/29.3.193
 566 | 
 567 | .. _`The SGML History Niche`: http://www.sgmlsource.com/history/index.htm, six
 568 |    articles by Charles F. Goldfarb, 2002 (and earlier)
 569 | 
 570 | .. _W3C: https://www.w3.org/
 571 | .. _`HTML 4.01 Specification`: https://www.w3.org/TR/html4/cover.html
 572 | .. _`On SGML and HTML`: https://www.w3.org/TR/html4/intro/sgmltut.html
 573 | .. _`Guidelines for Writing SGML DTDs (Draft)`: http://www.tei-c.org/Vault/ML/mlw01.htm
 574 | 
 575 | XML
 576 | ---
 577 | 
 578 | XML (Extensible Markup Language) was compiled by a working group of eleven
 579 | members, supported by a (roughly) 150-member Interest Group. It's
 580 | specification is managed by the W3C_.
 581 | 
 582 | Whilst XML is not itself of direct interest as a markup language, it is
 583 | important because it is *used* as the basis for many markup formats.
 584 | 
 585 | XML is a subset of SGML (wikipedia: "XML is an application profile of SGML").
 586 | In particular, it is much simpler than SGML, which makes parsers easier to
 587 | write. Many SGML based tools (TEI, Docbook, HTML itself) have generally moved
 588 | towards using XML rather than SGML in their specification.
 589 | 
 590 | There is no example for XML because there is no "starter set" for XML.
 591 | 
 592 | Interesting links:
 593 | 
 594 | * `Wikipedia on XML`_ is a good overview, and includes discussion of
 595 |   various schema and validation mechanisms.
 596 | * `XML Information`_  is a nested set of pages (I assume course notes).
 597 |   Constituent topics are "What is Markup?", "Schemas" and "Special Characters
 598 |   and Unicode". Author presumably Beck, undated.
 599 | * `Is there a difference between SGML DTDs and XML DTDs?`_ is from the "Schemas"
 600 |   section of the above.
 601 | * `XML People`_ is an article by Tim Bray, originally writing in 1998, and
 602 |   republished in 2008. It describes the genesis of XML and the people (and
 603 |   organisations) involved.
 604 | 
 605 | .. _`Wikipedia on XML`: https://en.wikipedia.org/wiki/XML
 606 | .. _`XML Information`: https://www.ncbi.nlm.nih.gov/staff/beck/xml/index.html
 607 | .. _`Is there a difference between SGML DTDs and XML DTDs?`: https://www.ncbi.nlm.nih.gov/staff/beck/xml/schemas/II-C.html
 608 | .. _`XML People`: http://www.tbray.org/ongoing/When/200x/2008/02/10/XML-People
 609 | 
 610 | |TeX| and |LaTeX|
 611 | =================
 612 | 
 613 | :1977/1978 |TeX|: *Presentational with semantic leanings*. Programmable. Still in use.
 614 | :1983 |LaTeX|: *Presentational*. Still in use.
 615 | 
 616 | |TeX|
 617 | -----
 618 | 
 619 | |TeX| was designed and mostly written by Donald Knuth, driven by the need to
 620 | guarantee accurate typesetting of mathematics.
 621 | 
 622 | Here is an example from a fanzine I used to edit (name redacted because I
 623 | don't know if they'd want it used in an example like this!):
 624 | 
 625 | .. code:: TeX
 626 | 
 627 |   \name{Name Redacted} wrote:
 628 | 
 629 |   \beginletter
 630 |   Thoughts on ``Why I like children's books'':
 631 | 
 632 |   \beginlist
 633 | 
 634 |   \item{\blob} They aren't afraid to show a sense of wonder.
 635 | 
 636 |   \item{\blob} They aren't `duty bound' to include love interest for the sake of
 637 |   it.
 638 | 
 639 |   \item{\blob} They are rarely cynical, rarely bitter---but the best do not avoid
 640 |   tragedy and truth.
 641 | 
 642 |   \item{\blob} They are willing to teach the simple lessons of being human---which
 643 |   adult books so often scorn, but which we all need to learn and relearn.
 644 | 
 645 |   \endlist
 646 | 
 647 | In serious use of |TeX|, one starts by defining lots of useful
 648 | commands - although `the TeXbook`_ has many useful ideas one can copy.
 649 | 
 650 | In this example, only the ``\item`` was predefined for me.
 651 | 
 652 | .. _`The TeXbook`: http://www.ctex.org/documents/shredder/src/texbook.pdf
 653 | 
 654 | |LaTeX|
 655 | -------
 656 | 
 657 | Most people don't write |TeX| itself, they use |LaTeX| (1984) or one of the
 658 | other markup languages written in |TeX|. |LaTeX| in particular is still
 659 | dominant in scientific and mathematical publishing.
 660 | 
 661 | Here is an example of |LaTeX|:
 662 | 
 663 | .. code:: TeX
 664 | 
 665 |    \beginsection
 666 |    A new section
 667 | 
 668 |    Paragraphs are separated by blank lines. `Quotation marks' differ. {\it
 669 |    Italics are done so}. Equations are important, and can be inline:
 670 |    $$|y - z| < \epsilon$$. Hyphen (-), ranges (1--4) and dashes (---) are all
 671 |    distinct.
 672 | 
 673 |    However, more people use systems {\it written} in \TeX, such as \LaTeX,
 674 |    because they provide ready-made support for most document elements.
 675 | 
 676 |    \bye
 677 | 
 678 | And an example from the first issue of the aforementioned fanzine (before I
 679 | switched from |LaTeX| back to |TeX|):
 680 | 
 681 | .. code:: TeX
 682 | 
 683 |   \begin{center}
 684 |   \rule{5in}{0.1mm}
 685 |   \end{center}
 686 | 
 687 |   \section*{Captain Competent strikes again}
 688 | 
 689 |   The superhero is a familiar concept in comics, science fiction and many other
 690 |   fields. However, I am more interested in what might be called `the competent
 691 |   hero'. This is a subtler form of protagonist---a person who has attained
 692 |   {\em competence} in their daily life.
 693 | 
 694 | * `25 Years of |TeX| and METAFONT\: Looking Back and Looking Forward`_:
 695 |   TUG’2003 Keynote Address, Nelson H. F. Beebe. Including sections on "What
 696 |   did |TeX| do right" and "What did |TeX| do wrong".
 697 | * `Wikipedia on SAIL`_
 698 | * `SAIL Tutorial`_, Nancy W. Smith, 1976
 699 | 
 700 | .. _`25 Years of |TeX| and METAFONT\: Looking Back and Looking Forward`: http://www.math.utah.edu/~beebe/talks/2003/tug2003/tug2003-keynote.pdf
 701 | .. _SAIL: `Wikipedia on SAIL`_
 702 | .. _`Wikipedia on SAIL`: https://en.wikipedia.org/wiki/SAIL_(programming_language)
 703 | .. _`SAIL Tutorial`: http://i.stanford.edu/pub/cstr/reports/cs/tr/76/575/CS-TR-76-575.pdf
 704 | 
 705 | The history
 706 | -----------
 707 | 
 708 |    Donald Knuth, a professor of computer science at Stanford University, was
 709 |    writing a projected seven-volume survey entitled The Art of Computer
 710 |    Programming. Volume 3 was published in 1973, composed with Monotype. By
 711 |    then, computer science had advanced to the point where a revised edition
 712 |    of volume 2 was in order but Monotype composition was no longer possible.  The galleys returned to Knuth by his publisher were photocomposed. Knuth
 713 |    was distressed: the results looked so awful that it discouraged him from
 714 |    wanting to write any more. But an opportunity presented itself in the
 715 |    form of the emerging digital output devices—images of letters could be
 716 |    constructed of zeros and ones. This was something that he, as a computer
 717 |    scientist, understood. Thus began the development of TeX.
 718 |   
 719 |  From `Communication of Mathematics with TeX`_, Barbara Beeton and Richard
 720 |  Palais, from "Visible Language" Volume 50 Issue 2, archived on the `Author
 721 |  Resource Center`_ page of the `American Mathematical Society` (AMS).
 722 | 
 723 | |TeX| (and Metafont) were originally written in SAIL_.  
 724 | In 1982, |TeX| was re-written in Pascal, using the WEB `literate programming`_
 725 | system.
 726 | 
 727 | .. _`literate programming`: `Wikipedia on literate programming`_
 728 | 
 729 | .. _`Communication of Mathematics with TeX`: http://www.ams.org/publications/authors/Communication_of_Mathematics_with_TEX.pdf
 730 | .. _`American Mathematical Society`: http://www.ams.org/home/page
 731 | .. _`Author Resource Center`: http://www.ams.org/publications/authors/authors
 732 | 
 733 | There are many interesting articles about |TeX| and its world, many from the
 734 | various |TeX| user group (TUGs).
 735 | 
 736 | Some interesting links:
 737 | 
 738 | * `Wikipedia on |TeX|`_
 739 | * `Wikipedia on WEB`_
 740 | * `Wikipedia on Literate programming`_
 741 | * `Wikipedia on Donald Knuth`_
 742 | * `Knuth's home page`_.  If you don't know about Knuth, it's worth following
 743 |   him up - he has done amazing things.
 744 | 
 745 | .. _`Wikipedia on |TeX|`: https://en.wikipedia.org/wiki/TeX
 746 | .. _`Wikipedia on WEB`: https://en.wikipedia.org/wiki/WEB
 747 | .. _`Wikipedia on Literate programming`: https://en.wikipedia.org/wiki/Literate_programming
 748 | .. _`Wikipedia on Donald Knuth`: https://en.wikipedia.org/wiki/Donald_Knuth
 749 | .. _`Knuth's home page`: http://www-cs-faculty.stanford.edu/~knuth/
 750 | 
 751 | 
 752 | * `An overview of |TeX|, its children and their friends...`_, Arno Trautman,
 753 |   2016
 754 | * `TeX family tree with timeline?`_, 2016, a question on https://tex.stackexchange.com
 755 |    
 756 | * `A Brief History of LaTeX`_, 1998, an email by 'I Find Karma' on the `FoRK Archive`_
 757 | * `How (La)TeX changed the face of Mathematics`_, an E-interview with Leslie
 758 |   Lamport, 2000
 759 | * `The (La)TeX project: A case study of open source software`, Alexandre Gaudeul, 2003
 760 | * `A brief history of TeX, volume II`_, Arthur Reutenauer, 2007. This is a
 761 |   successor article to `A Brief History of TeX`_, Philip Taylor 1995. Taylor's
 762 |   article also talks about Postscript, HTML, PDF and other matters.
 763 | 
 764 | .. _`An overview of |TeX|, its children and their friends...`: https://github.com/alt/tex-overview "An overview of |TeX|, its children
 765 | .. _`TeX family tree with timeline?`: https://tex.stackexchange.com/questions/42594/tex-family-tree-with-timeline
 766 | .. _`A Brief History of LaTeX`: http://www.xent.com/FoRK-archive/feb98/0307.html
 767 | .. _`FoRK Archive`: http://www.xent.com/FoRK-archive/
 768 | .. _`How (La)TeX changed the face of Mathematics`: https://www.microsoft.com/en-us/research/wp-content/uploads/2016/12/TeX-changed-the-face-of-Mathematics.pdf
 769 |  .. _`The (La)TeX project: A case study of open source software`: http://tug.org/TUGboat/tb24-1/gaudeul.pdf
 770 | .. _`A brief history of TeX, volume II`: http://www.tug.org/TUGboat/tb29-1/tb91reutenauer.pdf
 771 | .. _`A Brief History of TeX`: https://tug.org/TUGboat/tb17-4/tb53tayl.pdf
 772 | 
 773 | 
 774 | Choosing |TeX| or troff
 775 | =======================
 776 | 
 777 | .. _`TeX/troff/typesetting markups`: http://minnie.tuhs.org/pipermail/tuhs/2017-April/009638.html ::
 778 | 
 779 | `TeX/troff/typesetting markups`_ is an email conversation from 2017 comparing
 780 | use of |TeX| and troff::
 781 | 
 782 |   [TUHS] TeX/troff/typesetting markups - Re: SunOS 4 documentation
 783 |   Toby Thain toby at telegraphics.com.au
 784 |   Sun Apr 16 01:09:15 AEST 2017
 785 | 
 786 |       Previous message (by thread): [TUHS] TeX/troff/typesetting markups - Re: SunOS 4 documentation
 787 |       Next message (by thread): [TUHS] TeX/troff/typesetting markups - SunOS 4 documentation
 788 |       Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
 789 | 
 790 |   On 2017-04-15 10:23 AM, Michael Kerpan wrote:
 791 |   > Comparing documents produced by Heirloom troff and modern versions of
 792 |   > LaTeX, I just can't see a huge difference. The main thing TeX has going
 793 |   > for it is LyX, which makes composing documents a whole lot more
 794 |   > comfortable for folks raised on WYSIWYG. If a tool like that was
 795 |   > available for troff...
 796 | 
 797 |   I'm not only talking about the _output_. But my intention isn't to 
 798 |   denigrate troff but to show that they are completely different animals. 
 799 |   A glance through the TeXbook would confirm.
 800 | 
 801 |   TeX is a complete domain-specific language, page model, and runtime 
 802 |   environment (without even discussing its layered frameworks like LaTeX). 
 803 |   I admit it took me a few weeks or months of study back in the late 1980s 
 804 |   to understand this distinction; previously I had been using a 
 805 |   troff-level markup (perhaps even troff-inspired) on Mac called 
 806 |   "JustText", which generated PostScript of course.
 807 | 
 808 |   One _can_ typeset books in both troff and TeX, but that doesn't make 
 809 |   them at all equivalent. The process and possibilities are different. For 
 810 |   example, that simple task of producing two different output formats from 
 811 |   the same manuscript, that I mentioned upthread, is made possible by TeX 
 812 |   macros. But the sophistication of its page model is also required for 
 813 |   any nontrivial layout, table, diagram, math, or just typographic 
 814 |   refinement.
 815 | 
 816 |   Some projects _have_ tried to replace TeX. 
 817 |   https://tex.stackexchange.com/questions/120271/alternatives-to-latex
 818 | 
 819 |   --------
 820 | 
 821 |   Clem Cole clemc at ccc.com
 822 |   Sun Apr 16 01:27:49 AEST 2017
 823 | 
 824 |       Previous message (by thread): [TUHS] TeX/troff/typesetting markups - SunOS 4 documentation
 825 |       Next message (by thread): [TUHS] TeX/troff/typesetting markups - Re: SunOS 4 documentation
 826 |       Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
 827 | 
 828 |   On Fri, Apr 14, 2017 at 6:24 PM, Toby Thain <toby at telegraphics.com.au>
 829 |   wrote:
 830 |   >
 831 |   >
 832 |   > No matter how far you tart up the former, Troff and TeX just aren't
 833 |   > playing the same ballgame.
 834 | 
 835 | 
 836 |   Toby - that's a tad inflammatory - at least to my American sensibilities.
 837 |   Saying one or the other has been "dressed up" (using a derogatory term or
 838 |   not) is to me the same as the vi/emacs wars or rugby/American Football
 839 |   argument.   Some people like the taste of one, others do not, and thank
 840 |   goodness we have choices.   I've used the afore mentioned systems (and
 841 |   played the games too at a fairly high level in my day); and frankly it is a
 842 |   matter if taste.  They all have their place.
 843 | 
 844 |   If you grew up with an affinity for one, you are more likely to find it
 845 |   more comfortable for your needs.  I find a TeX just as ugly and unreadable
 846 |   as  the runoff family with troff is a member.   It's just a different view
 847 |   of beauty.  Frankly, Brian Reid's Scribe on the "Twinex" and VMS was the
 848 |   "best" document product system I ever really used (for those that do not
 849 |   know, LaTex was an attempt to bring Scribe-like functions into TeX).    But
 850 |   as Brian Kernighan points out in his "Page Makeup" paper, even Scribe had
 851 |   some flaws (it's too bad Scribe seems to have been lost to IP and source
 852 |   issues - I've often wonder how it would have played out in the modern
 853 |   world).
 854 | 
 855 |   Anyway - it fine to say you don't like troff - please feel free to suggest
 856 |   that you don't think that it can be made to your style/preferences.   But
 857 |   please don't sling to many insults as the truth is, that troff is still
 858 |   useful to many people and a lot people do still like it.
 859 | 
 860 |   In my own case, I'll use TeX if a colleague wants too, but I'm a fair bit
 861 |   faster with troff than almost any other doc prep system for any document of
 862 |   almost any size; but particularly when the documents get large such as
 863 |   book.   But that's me; although I note it is also a lot of other people.
 864 |   As Brian points out, many of the Pearson and Wiley texts use troff; and of
 865 |   course you have to note that my old deskmate, Tim O'Reilly founded his
 866 |   empire on it 😂 (I still have a copy of the his original style manual they
 867 |   wrote for the Masscomp engineers and doc writers in the mid 80s).
 868 |   Clem
 869 | 
 870 | Personally, my conclusion would be the opposite, as I think |TeX| being a
 871 | language (albeit a macro language, with the problems that is recognised as
 872 | entailing) is a big benefit. But it's an interesting comparison, nonetheless.
 873 | 
 874 | Scribe
 875 | ======
 876 | 
 877 | :1980 Scribe: *Presentational*
 878 | 
 879 | Scribe was another influential early markup language [#]_,
 880 | described in Brian Reid's 1980 doctoral dissertation
 881 | `Scribe\: A Document Specification Language and its Compiler`_,
 882 | at Carnegie Mellon
 883 | University.
 884 | 
 885 | .. [#] Lamport explicitly acknowledges its influence on |LaTeX|.
 886 | 
 887 | An example:
 888 | 
 889 | .. code::
 890 | 
 891 |     @Heading(The Beginning)
 892 |     @Begin(Quotation)
 893 |         Let's start at the very beginning, a @i(very good place) to start
 894 |     @End(Quotation)
 895 | 
 896 | which can also be written in a more LISP-like style:
 897 | 
 898 | .. code::
 899 | 
 900 |     @Heading(The Beginning)
 901 |     @(Quotation
 902 |         Let's start at the very beginning, a @i(very good place) to start
 903 |     )
 904 | 
 905 | * `Wikipedia on Scribe`_
 906 | * `Scribe\: A Document Specification Language and its Compiler`_, Brian Reid's
 907 |   1980 doctoral dissertation at Carnegie Mellon University.
 908 |  
 909 |   .. note:: My first quick scan suggests that this is well worth reading. NB:
 910 |      It mentions |TeX| and EQN (the roff-related tool for equations) as
 911 |      influences.
 912 | 
 913 | * `Scribe\: Introductory User's Manual`_, First Edition, Brian K. Reid, 1978
 914 | * Scriba_ is "a markup format similar to Scribe", with last commit in 2015. It
 915 |   references Skribilo_ and scribble_ as being similar.
 916 | * I think one might argue Pollen_ follows in the same footsteps, although it's
 917 |   not clear from it's documentation if the author is aware of Scribe_.
 918 | * The markup described in `This is Scribe!`_ (Manuel Serrano and Erick
 919 |   Gallesio, 2002)  appears to be entirely unrelated.
 920 | 
 921 | .. _`Wikipedia on Scribe`: https://en.wikipedia.org/wiki/Scribe_(markup_language)
 922 | .. _`Scribe\: A Document Specification Language and its Compiler`: http://reports-archive.adm.cs.cmu.edu/anon/scan/CMU-CS-81-100.pdf
 923 | .. _`Scribe\: Introductory User's Manual`: http://bitsavers.informatik.uni-stuttgart.de/pdf/cmu/scribe/Scribe_Introductory_Users_Manual_Jul78.pdf
 924 | .. _Scriba: https://github.com/CommonDoc/scriba
 925 | .. _Skribilo: http://www.nongnu.org/skribilo/
 926 | .. _scribble: http://quickdocs.org/scribble/
 927 | .. _`This is Scribe!`: http://www-sop.inria.fr/members/Manuel.Serrano/scribe/doc/scribe.html
 928 | 
 929 | TEI
 930 | ===
 931 | :1987 TEI: *Semantic*. Still in use today.
 932 | 
 933 | "The mission of the Text Encoding Initiative is to develop and maintain a
 934 | set of high-quality guidelines for the encoding of humanities texts, and to
 935 | support their use by a wide community of projects, institutions, and
 936 | individuals"
 937 | 
 938 | Some mark up of the start of Swinburne's Sestina,
 939 | taken from the poetry examples at `TEI By Example`_,
 940 | showing the working of the ryhming scheme:
 941 | 
 942 | .. code:: XML
 943 | 
 944 |   <lg type="sestina">
 945 |   <lg type="sestet" rhyme="ababab">
 946 |   <l>I saw my soul at rest upon a <rhyme label="a" xml:id="A">day</rhyme></l>
 947 |   <l>As a bird sleeping in the nest of <rhyme label="b" xml:id="B">night</rhyme>,</l>
 948 |   <l>Among soft leaves that give the starlight <rhyme label="a" xml:id="C">way</rhyme></l>
 949 |   <l>To touch its wings but not its eyes with <rhyme label="b" xml:id="D">light</rhyme>;</l>
 950 |   <l>So that it knew as one in visions <rhyme label="a" xml:id="E">may</rhyme>,</l>
 951 |   <l>And knew not as men waking, of <rhyme label="b" xml:id="F">delight</rhyme>.</l>
 952 |   </lg>
 953 | 
 954 | We can see it declaring the rhyme scheme, ``rhyme="ababab"``, and then on each
 955 | line the rhyming word and which part (a, b) of the rhyming scheme it is.
 956 | 
 957 | .. _`TEI by example`: http://teibyexample.org/examples/TBED04v00.htm
 958 | 
 959 | TEI and its use is a whole field of study I haven't even started - I shan't
 960 | attempt to be able to do it justice here.
 961 | 
 962 | Interesting links:
 963 | 
 964 | * `Wikipedia on Text Encoding Initiative`_
 965 | * `TEI\: Text Encoding Initiative`_ (homepage), and some of the things there:
 966 | 
 967 |   * `The TEI Archive`_ 1988-1999 articles on the Text Encoding Initiative, with
 968 |     a link to another part for 1987-1988
 969 |   * `A Bibliography of Publications Related to the Text Encoding Initiative`_,
 970 |     ...-2013, which are not just related to TEI itself
 971 | 
 972 | * `The TEI and XML`_, from "What is the Text Encoding Initiative?", Lou
 973 |   Burnard, OpenEdition Press, 2014
 974 | * `The TEI By Example Project`_ "offers a series of freely
 975 |   available online tutorials walking individuals through the different stages
 976 |   in marking up a document in TEI (Text Encoding Initiative)."
 977 | 
 978 | .. _`Wikipedia on Text Encoding Initiative`: https://en.wikipedia.org/wiki/Text_Encoding_Initiative
 979 | .. _`TEI\: Text Encoding Initiative`: http://www.tei-c.org/index.xml
 980 | .. _`The TEI Archive`: http://www.tei-c.org/Vault/
 981 | .. _`A Bibliography of Publications Related to the Text Encoding Initiative`: http://www.tei-c.org/Support/Learn/tei_bibliography.xml
 982 | .. _`The TEI and XML`: http://books.openedition.org/oep/680
 983 | .. _`The TEI By Example Project`: http://teibyexample.org/
 984 | 
 985 | Postscript
 986 | ==========
 987 | 
 988 | :1984 PostScript: Entirely *Presentational*, still in use.
 989 | :1993 PDF: Entirely *Presentational*, still in use.
 990 | 
 991 | It's probably worth mentioning PostScript briefly, even though it was not
 992 | intended to be written by people (although I've seen it done).
 993 | 
 994 | An example from wikipedia:
 995 | 
 996 | .. code:: postscript
 997 | 
 998 |    %!PS
 999 |    /Courier             % name the desired font
1000 |    20 selectfont        % choose the size in points and establish 
1001 |                         % the font as the current one
1002 |    72 500 moveto        % position the current point at 
1003 |                         % coordinates 72, 500 (the origin is at the 
1004 |                         % lower-left corner of the page)
1005 |    (Hello world!) show  % stroke the text in parentheses
1006 |    showpage             % print all on the page
1007 | 
1008 | PDF then uses PostScript to describe each page - it is even further from a
1009 | human-writable markup.
1010 | 
1011 | * `Wikipedia on PostScript`_
1012 | * `Wikipedia on PDF`_
1013 | * The WikiWikiWeb_ article `Forth Postscript Relationship`_ discusses whether
1014 |   Postscript *is a* Forth, or is just similar to Forth (basically, the latter
1015 |   seems more sensible).
1016 | 
1017 | .. _`Wikipedia on PostScript`: https://en.wikipedia.org/wiki/PostScript
1018 | .. _`Forth Postscript Relationship`: http://wiki.c2.com/?ForthPostscriptRelationship
1019 | 
1020 | .. _`Wikipedia on PDF`: https://en.wikipedia.org/wiki/Portable_Document_Format
1021 | 
1022 | HTML
1023 | ====
1024 | 
1025 | :1991 HTML: *Presentational*. Still in use today (although rather altered).
1026 | 
1027 | Tim Berners-Lee, at CERN, specified HTML and wrote browser and server
1028 | software in late 1990. The "HTML Tags" document was first mentioned on the
1029 | internet in 1991.
1030 | 
1031 | HTML 2.0 was published as IETF RFC 1866 in 1995
1032 | 
1033 | HTML (at least until HTML5) was an SGML application - hence the specification
1034 | of its DOCTYPE:
1035 | 
1036 | .. code:: HTML
1037 | 
1038 |   <!DOCTYPE html>
1039 |   <html>
1040 |     <head>
1041 |       <title>This is a title</title>
1042 |     </head>
1043 |     <body>
1044 |       <p>Hello world!</p>
1045 |     </body>
1046 |   </html>
1047 | 
1048 | There's not a lot of discussion of HTML here, as I'm not (in this context)
1049 | especially interested in HTML-as-markup, and it's really a specialism of its
1050 | own, with its own consideration and politics (and considerable text about it
1051 | on the internet).
1052 | 
1053 | Some links:
1054 | 
1055 | * `Wikipedia on HTML`_
1056 | * `The Evolution of Web Documents`_, Dan Connolly, Rohit Khare, and Adam
1057 |   Rifkin, 1997. HTML, SML, SGML.
1058 | * `XML People`_, Tim Bray, 1998 (republished 2008). A look at the people who
1059 |   influenced development of XML
1060 | *  `A brief history of markup`_, Jeremy Keith, 2010. From HTML 2.0 through XHTML to HTML5.
1061 | * https://www.ukessays.com/essays/information-technology/the-history-of-markup-languages-information-technology-essay.php
1062 | 
1063 | .. _`Wikipedia on HTML`: https://en.wikipedia.org/wiki/HTML
1064 | .. _`The Evolution of Web Documents`: https://www.xml.com/pub/a/w3j/s3.connolly.html
1065 | .. _`XML People`: http://www.tbray.org/ongoing/When/200x/2008/02/10/XML-People
1066 | .. _`A brief history of markup`: https://alistapart.com/article/a-brief-history-of-markup
1067 | 
1068 | * `A Brief History of Markup`_, Jeremy Keith, 2010, HTML and its friends
1069 | * `A Brief History of Markup Languages`_, Melody Smith, 2012, again HTML and
1070 |   W3C
1071 | * `The Evolution of Web Documents`_: The Ascent of XML, Dan Connolly, Rohit
1072 |   Khare, Adam Rifkin, 1997
1073 | 
1074 | .. _`A Brief History of Markup`: https://alistapart.com/article/a-brief-history-of-markup
1075 | .. _`A Brief History of Markup Languages`: http://taxodiary.com/2012/12/a-brief-history-of-markup-languages/
1076 | .. _`The Evolution of Web Documents`: https://www.xml.com/pub/a/w3j/s3.connolly.html
1077 | 
1078 | Docbook
1079 | =======
1080 | 
1081 | :1991 Docbook: *Semantic*. Still in use today.
1082 | 
1083 | Docbook dates from the same year as HTML.
1084 | 
1085 | Docbook is "a semantic markup language for technical documentation".
1086 | However, I think it is often "semantic" in the same way that |LaTeX| is
1087 | "semantic", i.e., used for mainly presentational purposes.
1088 | 
1089 | An example of Docbook 4.3 from
1090 | http://www.informatik.tu-cottbus.de/~giurca/tutorials/DocBook/index.htm
1091 | 
1092 | .. code:: XML
1093 | 
1094 |   <?xml version="1.0" encoding="UTF-8"?>
1095 |   <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
1096 |   "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
1097 |   <article>
1098 |     <title>DocBook Tutorial</title>
1099 |     <articleinfo>
1100 |       <author>
1101 |         <firstname>Adrian</firstname>
1102 |         <surname>Giurca</surname>
1103 |       </author>
1104 |       <date>April 5, 2005</date>
1105 |     </articleinfo>
1106 |     <section>
1107 |       <title>What is DocBook ?</title>
1108 |       <para>DocBook is an SGML dialect developed by O'Reilly and HaL Computer
1109 |       Systems in 1991.
1110 |       </para>
1111 |     </section>
1112 |   </article>
1113 | 
1114 | Before Docbook 5, it was an SGML language, defined by a DTD.
1115 | 
1116 | DocBook 5 is an XML language, formally defined by a RELAX NG schema with
1117 | rule-based validation for some constraints using Schematron.
1118 | 
1119 | An example of Docbook 5 (taken from wikipedia):
1120 | 
1121 | .. code:: XML
1122 | 
1123 |    <?xml version="1.0" encoding="UTF-8"?>
1124 |    <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
1125 |      <title>Very simple book</title>
1126 |      <chapter xml:id="chapter_1">
1127 |        <title>Chapter 1</title>
1128 |        <para>Hello world!</para>
1129 |        <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
1130 |      </chapter>
1131 |      <chapter xml:id="chapter_2">
1132 |        <title>Chapter 2</title>
1133 |        <para>Hello again, world!</para>
1134 |      </chapter>
1135 |    </book>
1136 | 
1137 | Some links:
1138 | 
1139 | * `Wikipedia on DocBook`_
1140 | * `The DocBook Project`_ on Sourceforge
1141 | * `DocBook.org`_ is the homepage for both "DocBook: The Definitive Guide" and
1142 |   "DocBook Publishers: The Definitive Guide". Both are by Norman Walsh, and
1143 |   both are available free online from this page, in their various versions,
1144 |   specific to different versions of DocBook itself.
1145 | 
1146 |   "DocBook 5: The Definitive Guide", Norman Walsh, O'Reilly Media, 2010, is
1147 |   the current published version of the book.
1148 | 
1149 | * `Overview of the DocBook format`_ at https://workaround.org/ is a quick
1150 |   introduction to DocBook
1151 | 
1152 | .. _`Wikipedia on DocBook`: https://en.wikipedia.org/wiki/DocBook
1153 | .. _`The DocBook Project`: http://docbook.sourceforge.net/
1154 | .. _`DocBook.org`: http://docbook.org/
1155 | .. _`Overview of the DocBook format`: https://workaround.org/docbook/
1156 | 
1157 | DITA
1158 | ====
1159 | 
1160 | :2001/2005 DITA: *Semantic* and *Presentational*, still in use.
1161 | 
1162 | DITA, the "Darwin Information Typing Architecture", appears to be a semantic
1163 | (maps and topics) technical documentation format, with a basic vocabulary
1164 | modeled on HTML. A quick look around for information about it suggested that
1165 | people are keen to write markdown and then convert to DITA, rather than
1166 | writing it directly.
1167 | 
1168 | An example from `DITA for the impatient`_:
1169 | 
1170 | .. code:: xml
1171 | 
1172 |   <topic id="docbook_or_dita">
1173 |     <title>DITA or DocBook?</title>
1174 | 
1175 |     <shortdesc>Both DITA and DocBook are both mature, feature rich, document types,
1176 |     so which one to choose?</shortdesc>
1177 | 
1178 |     <body>
1179 |       <p>DocBook 5 is a mature document type. It is well-documented (DocBook:
1180 |       The Definitive Guide, DocBook XSL: The Complete Guide), featuring decent
1181 |       XSL stylesheets allowing conversion to a variety of formats, based on the
1182 |       best schema technologies: RELAX NG and Schematron.</p>
1183 | 
1184 |       <p>DITA concepts (topics, maps, specialization, etc) have an immediate
1185 |       appeal to the technical writer, making this document type more attractive
1186 |       than DocBook. However the DocBook vocabulary is comprehensive and very
1187 |       well thought out. So choose DITA if its technical vocabulary is
1188 |       sufficiently expressive for your needs or if, anyway, you intend to
1189 |       specialize DITA.</p>
1190 |     </body>
1191 | 
1192 |     <related-links>
1193 |       <link format="html" href="http://www.docbook.org/" scope="external">
1194 |         <linktext>DocBook 5</linktext>
1195 |       </link>
1196 | 
1197 |       <link format="html"
1198 |             href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita"
1199 |             scope="external">
1200 |         <linktext>DITA</linktext>
1201 |       </link>
1202 |     </related-links>
1203 |   </topic>
1204 | 
1205 | * `Wikipedia on DITA`_
1206 | * `What is DITA?` at xml.com. This suggests that "DITA's closest peer is
1207 |   DocBook, which is also designed primarily for technical documentation".
1208 | * `DITA for the impatient`_
1209 | * `DITA: Specializations (task, concept, reference)`_ gives a flavour of
1210 |   what DITA is about.
1211 | 
1212 | .. _`Wikipedia on DITA`: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
1213 | .. _`What is DITA?`: https://www.xml.com/articles/2017/01/19/what-dita/
1214 | .. _`DITA for the impatient`: http://www.xmlmind.com/tutorials/DITA/
1215 | .. _`DITA: Specializations (task, concept, reference)`: https://idratherbewriting.com/specializations/
1216 | 
1217 | Wikiwikiweb
1218 | ===========
1219 | 
1220 | :1994/1995 wikiwikiweb: *Presentational*
1221 | 
1222 | Wikiwikiweb was the first wiki, invented by Ward Cunningham.
1223 | 
1224 | .. Pygments doesn't seem to have a lexer for wiki text. Not entirely
1225 | .. surprising given the lack of any consistency between them.
1226 | 
1227 | .. code::
1228 | 
1229 |   Paragraphs are not indented.
1230 | 
1231 |   * This is a list item
1232 |   ** This is a sub-list item
1233 | 
1234 |     Indented text is monospaced.
1235 | 
1236 |   We have ''emphasis'', '''bold''', '''''bold italic''''', and a LinkToAnotherPage.
1237 | 
1238 |   But we can A''''''voidMakingAWikiLink.
1239 | 
1240 |   No HTML, tables, headers, maths, scripts. No links within a page.
1241 | 
1242 | Apart from introducing the whole idea of wikis, it is perhaps most notable for
1243 | the use of CamelCasedWords as wiki links.
1244 | 
1245 | Single quotes are used, oddly (and indeed this really distressed me when I
1246 | first came across it):
1247 | 
1248 | - 1 = single quote
1249 | - 2 = emphasis
1250 | - 3 = bold
1251 | - 5 = emphasised bold (2+3)
1252 | - 6 are used to stop a CamelCased word from being a WikiLink
1253 | 
1254 | Like most wiki formats, specified by example, with no real rigour. However,
1255 | I suspect this may have been done deliberately, to encourage learning by
1256 | exploration.
1257 | 
1258 | I think that newlines within a paragraph are ignored, but it's hard  to
1259 | tell from the documentation, and the original Wikiwikiweb is now frozen.
1260 | 
1261 | Cunningham wrote:
1262 | 
1263 |    "This wiki is quite bare bones, and intentionally so. Less formatting
1264 |    means you have to concentrate on saying things carefully and clearly.
1265 |    Content over form."
1266 | 
1267 | This lack of capability led to a particular and characteristic type of
1268 | discussion, which makes WikiWikiWeb pages very recognisable.
1269 | 
1270 | Later wiki formats appear not to have understood *why* the design decisions
1271 | were taken, and have mostly had ungainly markups. The adoption of (some form
1272 | of) markdown in many current wikis is thus a good thing.
1273 | 
1274 | (One of my pet hates with wiki markups is treating a list as composed only
1275 | of single-block list items - i.e., there can be no internal block structure
1276 | to a list in most wikis. That means you cannot, for instance, do:
1277 | 
1278 | .. code::
1279 | 
1280 |     * This is a list item
1281 | 
1282 |        Which is continued into a second paragraph.
1283 | 
1284 |        And contains an example:
1285 | 
1286 |        {example}
1287 |        Some example text.
1288 |        {/example}
1289 | 
1290 | Such a restriction made sense in the original wikiwikweb, where the idea
1291 | was to keep the text structure very simple, but it doesn't fare well when
1292 | trying to discuss technical matters, which is what many modern wikis are
1293 | used for. Thus users end up forcing the formatting to give something that
1294 | *looks like* the semantics they want, even to the extent of "drawing"
1295 | list item enumeration markers by hand.)
1296 | 
1297 | Some links:
1298 | 
1299 | * WikiWikiWeb_ itself (now readonly).
1300 | * `Wikipedia on Wiki`_ talks about wiki pages themselves.
1301 | * `Wikipedia on WikiWikiWeb`_ talks about the first wiki. I don't particularly
1302 |   propose to talk about the (many) ways of marking up wiki text here. However,
1303 |   `Text Formatting Rules`_ is the page on wikiwikiweb about the markup it
1304 |   supported. It really did use differing numbers of single quotes to mean
1305 |   different sorts of markup. And inline meaningful tabs. Which is why I don't
1306 |   want to talk about it.
1307 | * `Wiki Wiki Hypercard`_ is an interesting note on the influence of
1308 |   HyperCard on WikiWikiWeb
1309 | 
1310 | .. _WikiWikiWeb: http://wiki.c2.com/
1311 | .. _`Wikipedia on Wiki`: https://en.wikipedia.org/wiki/Wiki
1312 | .. _`Wikipedia on WikiWikiWeb`: https://en.wikipedia.org/wiki/WikiWikiWeb.
1313 | .. _`Text formatting rules`: http://wiki.c2.com/?TextFormattingRules
1314 | .. _`Wiki Wiki Hypercard`: http://acroom.wikity.cc/wiki-wiki-hypercard
1315 | 
1316 | 
1317 | Programming language internal documentation
1318 | ===========================================
1319 | API documentation in programming languages is its own distinct problem domain.
1320 | 
1321 | Here we consider two of the more important examples, POD (from Perl) and
1322 | javadoc (from Java). Both of these are the dominant API documentation
1323 | mechanisms for their respective languages.
1324 | 
1325 | POD
1326 | ---
1327 | 
1328 | :1994 POD: *Presentational*. Still in use today.
1329 | 
1330 | Perl's POD (or Plain Old Documentation)
1331 | 
1332 | .. code:: perl
1333 | 
1334 |   =pod
1335 | 
1336 |   =head1 DESCRIPTION
1337 | 
1338 |   This is not I<really> representative of POD usage.
1339 | 
1340 |   =over 2
1341 | 
1342 |   =item This is a list item.
1343 | 
1344 |   =item This is another list item.
1345 | 
1346 |   =back
1347 | 
1348 |   =cut
1349 | 
1350 | This was introduced the same year as wikiwikweb
1351 | 
1352 | It is an example of markup to a specific purpose, and clearly very successful.
1353 | 
1354 | Note that the blank lines are required around the POD commands.
1355 | 
1356 | I don't think you can do multi-paragraph list items. The POD definitions
1357 | contains ambuguities, although how to handle some of them is explained in
1358 | the POD documentation.
1359 | 
1360 | * `The Timeline of Perl and its Culture`_ explains that POD was introduced in
1361 |   1995 at the same time as Perl 5.001. This is a very nice brief history of
1362 |   the significant events in Perl, from the 1960s to 2002, with links at the
1363 |   end.
1364 | * perlpodspec_ is the format specification and notes for Perl's Plain Old
1365 |   Documentation.
1366 | 
1367 | .. _`The Timeline of Perl and its Culture`: http://history.perl.org/PerlTimeline.html
1368 | .. _perlpodspec: https://perldoc.perl.org/perlpodspec.html
1369 | 
1370 | javadoc
1371 | -------
1372 | 
1373 | :1995 javadoc: *Presentational*. Still in use today.
1374 | 
1375 | 
1376 | .. code:: java
1377 | 
1378 |   /**
1379 |    * Short one line description.
1380 |    * <p>
1381 |    * Longer description. If there were any, it would be here.
1382 |    * <p>
1383 |    * And even more explanations to follow in consecutive
1384 |    * paragraphs separated by HTML paragraph breaks.
1385 |    *
1386 |    * @param  variable Description text text text.
1387 |    * @return Description text text text.
1388 |    */
1389 |   public int methodName (...) {
1390 |       // ...
1391 |   }
1392 | 
1393 | The java toolchain understands how to extract javadoc and produce HTML API
1394 | documentation from it. As well as the ``@param`` style annotations, it may
1395 | also contain HTML, although the javadoc specification has never specified what
1396 | subset of HTML it allows [#]_.
1397 | 
1398 | .. [#] Perhaps it is better now-a-days, but somehow I doubt it.
1399 | 
1400 | * `Wikipedia on Javadoc`_
1401 | 
1402 | .. _`Wikipedia on Javadoc`: https://en.wikipedia.org/wiki/Javadoc
1403 | 
1404 | Lightweight markup
1405 | ==================
1406 | 
1407 | With the exception of wikiwikiweb, all of the markups we have looked at so far
1408 | introduce significant extra text into the actual document being written. This
1409 | can distract from the actual writing of the document. As a consequence, the
1410 | idea of *lightweight markup* arose, partly as a result of seeing what people
1411 | would write in emails (which back then were plain text only) to convey
1412 | presentational ideas.
1413 | 
1414 | There is, of course, a trade-off between keeping the markup light and
1415 | unintrusive, and adding more capabilities to it. Quite often the lightweight
1416 | markup chosen by an individual reflects where on that spectrum they are
1417 | comfortable.
1418 | 
1419 | setext
1420 | ======
1421 | 
1422 | :1991 setext: *Presentational*. Lightweight.
1423 | 
1424 | 1991 was the same year as HTML and Docbook.
1425 | 
1426 | setext was invented by Ian Feldman as an alternative to RTF and SGML. He used
1427 | it to format the electronic newsletter TidBITS_ ("Apples news for the rest of
1428 | us") from issue 100 - before that the magazine was distributed as a HyperCard_
1429 | stack. 
1430 | 
1431 | An example, excerpted from a document called `"Why setext"`_:
1432 | 
1433 | .. Unsurprisingly, there isn't a Pygments highlighter for setext
1434 | 
1435 | .. code:: reST
1436 | 
1437 |   Why setext?
1438 |   -----------
1439 | 
1440 |     I agree that FAQ's would best be written in something like setext_.
1441 |     Why?  Because this document is written in setext and it includes
1442 |     the ability to embed HTML hypertext links without being obnoxious.
1443 | 
1444 |     As you can see it's easy to write setext documents, and as Edward
1445 |     pointed out, it uses existing text conventions for **bold** and _italic_
1446 |     words and titles.
1447 | 
1448 |   .. _setext http://www.bsdi.com/setext/
1449 |   ..
1450 | 
1451 | The specification of the format was by example, spread over several documents,
1452 | and is not entirely clear. It probaly evolved over time according to the
1453 | author's needs.
1454 | 
1455 | Body text must be indented by two spaces.
1456 | 
1457 | Using underlines to indicate italics (``_italic_``) is suggestive of the use
1458 | of underlining in typewritten manuscripts to mean that the relevant text should
1459 | be set using an italic font.
1460 | 
1461 | Two dots were used for comments or special meaning.
1462 | 
1463 | It is not clear if lists were actually supported.
1464 | 
1465 | Here is another example (I hope I've got the syntax correct):
1466 | 
1467 | .. code:: reST
1468 | 
1469 |    This is the title. There can be only one.
1470 |    =========================================
1471 |      Body text must be indented by two spaces.
1472 | 
1473 |    A subheading
1474 |    ------------
1475 |      **Bold words** and ~italic~ are supported (although ~multiword~italics~
1476 |      seems to have been an extension). _Underlined_words_ are also supported.
1477 |      `Backquoted words` are not touched.
1478 | 
1479 |    > This text will be represented using a monospaced font.
1480 | 
1481 |    * This text will have a bullet mark before it.
1482 | 
1483 |    .. Two dots introduce text that can be ignored, and two dots alone mean
1484 |    .. the logical end of text
1485 |    ..
1486 | 
1487 | * `Wikipedia on setext`_ 
1488 | * The `docutils`_ site holds a `Setext Documents Mirror`_ which preserves copies
1489 |   of some of the setext documentation.
1490 | * The `wayback machine`_ also has some `setext documents`_
1491 | 
1492 | .. _TidBits: http://tidbits.com/
1493 | .. _HyperCard: https://en.wikipedia.org/wiki/HyperCard
1494 | .. _`Wikipedia on setext`: https://en.wikipedia.org/wiki/Setext
1495 | .. _`docutils`: http://docutils.sourceforge.net/
1496 | .. _`wayback machine`: https://web.archive.org
1497 | .. _`Setext Documents Mirror`: http://docutils.sourceforge.net/mirror/setext.html
1498 | .. _`setext documents`: https://web.archive.org/web/20010424104701/http://www.bsdi.com/setext/
1499 | .. _`"Why setext"`: http://docutils.sourceforge.net/mirror/setext/why_setext.etx.txt
1500 | 
1501 | 
1502 | Python's Doc-SIG
1503 | ================
1504 | Python's Doc-SIG was started to look at documentation matters for Python, and
1505 | in particular had two main interests - how to write the text in docstrings,
1506 | and how to write "external" documentation.
1507 | 
1508 | For docstrings, it was a perceived wisdom that one had to be able to mark up
1509 | the names of function arguments, variable names and so on, so that tools could
1510 | use this information for some unspecified purpose. And in fact, there were
1511 | systems that *did* do exactly that - Zope_ being an example, where typing
1512 | information was taken from the docstring.
1513 | 
1514 | .. note:: It's not clear when docstrings_ were invented. I believe that Python
1515 |    took the idea from Lisp, and specifically from Emacs Lisp. Of course, the
1516 |    nice thing about docstrings is that they are part of the program data, so
1517 |    they can be inspected and manipulated like the rest of Python code.
1518 | 
1519 |    `This article`_ from 2013 is an interesting comparison of how to write Python
1520 |    vs Emacs Lisp docstrings.
1521 | 
1522 | .. _docstrings: `Wikipedia on docstrings`_
1523 | .. _`this article`: `Docstring Convention: Python vs Emacs Lisp`_
1524 | 
1525 | There was also a feeling that this was a generally good thing to do -
1526 | contrasting the relaxed way one might write::
1527 | 
1528 |     The arguments are:
1529 |     - 'first' which must give the person's "first" name
1530 |     - 'last' which must give their "last" name
1531 |     'first' and 'last' should be interpreted when possible as if they were
1532 |     "christian" and "surname" (or family name) respectively.
1533 | 
1534 |     A hash made from those two components will be returned.
1535 | 
1536 | rather than a more formal (and invented - not an actual markup language)
1537 | approach like::
1538 | 
1539 |     @param[string] first: the person's "first" name
1540 |     @param[string] last: the person's "last" name
1541 |     @return[integer] a hash made from those two components
1542 | 
1543 |     'first' and 'last' should be interpreted when possible as if they were
1544 |     "christian" and "surname" (or family name) respectively.
1545 | 
1546 | .. note:: Interestingly, later on the requirement to formally document one's
1547 |    arguments in a docstring has tended to go away, replaced by informal
1548 |    documentation, and, if one must, use of the 'mypy_' style annotation in the
1549 |    code itself. I think there are interesting cultural reasons for this, and
1550 |    in part it allows one to not bother documenting function arguments whose
1551 |    intent is entirely obvious from their use and name.
1552 | 
1553 | .. _mypy: http://mypy-lang.org/
1554 | .. _zope: `Wikipedia on Zope`_
1555 | .. _`Wikipedia on Zope`: https://en.wikipedia.org/wiki/Zope
1556 | 
1557 | StructuredText
1558 | ==============
1559 | 
1560 | :1996 StructuredText: *Presentational*. Lightweight.
1561 | 
1562 | StructuredText was created by Jim Fulton of Digital Creations (later Zope
1563 | Foundation) for use in Zope_.
1564 | 
1565 | It was clearly influenced by setext, although much extended.
1566 | 
1567 | For instance:
1568 | 
1569 | .. code:: reST
1570 | 
1571 |    This is a heading
1572 | 
1573 |      This is a paragraph. Body text is indented.
1574 | 
1575 |      - This is a list item. Words can be *emphasized*, _underlined_,
1576 |      **strong** or 'inline' - yes, that's using single quotes [1].
1577 | 
1578 |      o This is a list item as well. Each list item must be separated by a
1579 |      blank line from other entities.
1580 | 
1581 |      This is a sub-heading
1582 | 
1583 |        Sub-section body text is indented even further. We know the sub-header
1584 |        is such because it is followed by this indented text.
1585 | 
1586 |    .. [1] Or we could use ``backquotes``.
1587 | 
1588 | It retains the idea of significant indentation, although in an extended form.
1589 | I think it is now agreed that this is a good idea in a programming language,
1590 | but not so much when writing plain text.
1591 | 
1592 | A heading is a heading because it is followed by a non-heading(!).
1593 | 
1594 | Footnotes are fairly simple to write. Note the use of two dots to introduce the
1595 | actual footnote.
1596 | 
1597 | All block entities must be separated by blank lines.
1598 | 
1599 | Note that "o" can be a list delimiter - this was regarded as a serious
1600 | ambiguity, especially when writing Spanish, where "o" is a valid word.
1601 | 
1602 | Links are done as::
1603 | 
1604 |     visit the "Python website" :http://www.python.org/.
1605 | 
1606 | i.e., quoted text followed by a colon and then a URL.
1607 | 
1608 | The StructuredText documentation was much better than that for setext, but
1609 | still relied on example rather than specification, and left important
1610 | ambiguities.
1611 | 
1612 | Some links:
1613 | 
1614 | * `MoinMoin on StructuredText`_ is a short summary of StructuredText
1615 | * `Jim Fulton`_'s `Older Projects`_ page has a section on his
1616 |   StructuredText work:
1617 | 
1618 |     In 1996, I created StructuredText as a light weight text markup for
1619 |     generating various forms of documentation, especially HTML documents. It
1620 |     was inspired by Setext. Like Python, it used indentation to provide
1621 |     document structure.
1622 | 
1623 |     StructuredText was widely used in the Python, and especially in the Zope
1624 |     community for a few years. The extensive use of indentation was eventually
1625 |     recognized as a mistake.
1626 | 
1627 |     StructuredText was ultimately replaced by the superior ReStructuredText.
1628 | 
1629 | .. _`MoinMoin on StructuredText`: https://moinmo.in/StructuredText
1630 | .. _`Jim Fulton`: http://jimfulton.info/
1631 | .. _`Older Projects`:  http://jimfulton.info/site/older-projects.html
1632 | 
1633 | * `An Introduction to Structured Text`_, Paul Everitt, undated.
1634 | * `zope.structuredtext`_ on github
1635 |   https://github.com/zopefoundation/zope.structuredtext
1636 |   is an implementation of a StructuredText parser, and appears to be the best
1637 |   source of examples.
1638 | 
1639 | StructuredTextNG was an attempt to refactor StructuredText, but a final
1640 | specification and implementation were never completed. I did make an attempt,
1641 | at `StructuredTextNG - Format`_, to work out what it was meant to be, but the
1642 | need for this was superceded by later work, and in particular by
1643 | reStructuredText.
1644 | 
1645 | .. _`StructuredTextNG - Format`: http://www.tibsnjoan.co.uk/docutils/STNG-format.html
1646 | 
1647 | Whilst StructuredText was not perfect, it was very influential in the Python
1648 | world, and I think that the dissatisfaction with it showed how close it came
1649 | to being the right system. It is significant that reStructuredText uses that
1650 | name.
1651 | 
1652 | * `Problems with StructuredText`_ is David Goodger's analysis of the problem.V
1653 | 
1654 | .. _`An Introduction to Structured Text`: http://old.zope.org/Documentation/Articles/STX/
1655 | .. _`zope.structuredtext`: https://github.com/zopefoundation/zope.structuredtext
1656 | .. _`Problems with StructuredText`: http://docutils.sourceforge.net/docs/dev/rst/problems.html
1657 | 
1658 | reStructuredText
1659 | ================
1660 | 
1661 | :2001/2002 reStructuredText: *Presentational*. Lightweight.
1662 | 
1663 | reStructuredText was designed by David Goodger, who also wrote the original
1664 | implementation.  I think it is significant that Daivd had a professional
1665 | background in SGML.  In particular, it meant that he used very keen judgement
1666 | to decide what capabilities should be included, and what not.
1667 | 
1668 | reStructuredText was, of course, explicitly influenced by both setext and
1669 | StructuredText, but with more rigor.
1670 | 
1671 | The main aims of reStructuredText are to be:
1672 | 
1673 | * readable
1674 | * output agnostic
1675 | * well specified
1676 |   
1677 | Being readable means that the actual marked up text, as written, is a first
1678 | class document. As far as I know, reStructuredText is the only lightweight
1679 | markup with this aim, and it aligns well with Python's own philosophy that
1680 | readability comes first. It does, of course, mean that sometimes it is a
1681 | little harder to *write* reStructuredText, but that is regarded as an
1682 | acceptable cose.
1683 | 
1684 | .. note:: The `reStructuredText specification`_ is itself written in
1685 |    reStructuredText, which is not surprising, but importantly it is also
1686 |    intended to be readable in that form.
1687 | 
1688 | Being output agnostic means that it does not have to worry about fitting
1689 | itself to HTML, PDF, Docbook or any other particular output engine.
1690 | 
1691 | Finally, being well specified makes it possible to work out if a document is
1692 | valid, and also facilitates writing other implementations.
1693 | 
1694 | .. note:: I'm particularly fond of the implementation in VimL, the programming
1695 |    language within the Vim editor.
1696 | 
1697 | For instance, here is text similar to the StructuredText example, but in
1698 | reStructuredText:
1699 | 
1700 | .. code:: reST
1701 | 
1702 |    This is a heading
1703 |    =================
1704 | 
1705 |    This is a paragraph. Body text is not indented.
1706 | 
1707 |      - This is a list item. Words can be *emphasized*, **strong** or
1708 |        ``inline`` - yes, that's paired backquotes [1]_.
1709 |      - This is a list item as well. We can't use "o" as a list delimiter,
1710 |        as it is too ambiguous. We don't need blank lines between list items.
1711 | 
1712 |    This is a sub-heading
1713 |    ---------------------
1714 | 
1715 |    Sub-section body text is not indented either. What makes sense for
1716 |    programming languages is irritating for text.
1717 | 
1718 |    .. [1] Lines after the first line of a list item must be indented appropriately.
1719 | 
1720 | Body text isn't indented, but things must line up when appropriate (see the lists).
1721 | 
1722 | Double backquotes are used for inline text because single backquotes are used
1723 | for grouping, for instance in specifying links:
1724 | 
1725 | .. code:: reST
1726 | 
1727 |   Section One
1728 |   ===========
1729 | 
1730 |   `This is a link to something external`_ and this is a link to this section,
1731 |   `Section One`_.
1732 | 
1733 |   .. _`This is a link to something external`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
1734 | 
1735 | Being able to name links but put the URL outside the actual text is part of
1736 | reStructuredText's attempt to foster readability.
1737 | 
1738 | Given its intended use in the Python world, where ``__init__`` is a thing, the
1739 | underscore character is *not* overloaded for any special purpose.
1740 | 
1741 | It was also a design consideration that < and > are not special, as
1742 | programmers often use these in text (specifically, when writing about HTML or
1743 | XML).
1744 | 
1745 | reStructuredText isn't perfect - for instance, the various forms of inline
1746 | markup (``*..*``, ``**..``, etc.) cannot, at time of writing, be nested - but
1747 | I find that it is a good solution for most purposes when I just want to write
1748 | text, and perhaps convert it to another format.
1749 | 
1750 | * `Wikipedia on reStructuredText`_
1751 | * `reStructuredText specification`_
1752 | * 2012 `An Introduction to reStructuredText`_, David Goodger. This also
1753 |   includes David's recounting of its history, which I'd say is accurate if a
1754 |   little too modest.
1755 | 
1756 |   It's also worth looking at:
1757 | 
1758 |   * `A Record of reStructuredText Syntax Alternatives`_, David Goodger, 2012 -
1759 |     i.e.. the roads not taken, and why not.
1760 |   * `Problems With StructuredText`_, David Goodger, 2012 - yes, the project
1761 |     acknowledges various known shortcomings.
1762 | 
1763 | * Sphinx_ was first introduced as a means of using reStructuredText to write
1764 |   the Python documenation, instead of |LaTeX|.
1765 | * `Kernel documentation with Sphinx`_, part 1 of an `LWN.net`_ article from
1766 |   2016, on how the Linux Kernel documentation is now using reStructuredText
1767 |   and Sphinx
1768 | * `CMake 3.0.0 Release Notes`_: CMake has also moved to reStructuredText and
1769 |   Sphinx
1770 | 
1771 | .. _`Wikipedia on reStructuredText`: https://en.wikipedia.org/wiki/ReStructuredText
1772 | .. _`reStructuredText specification`: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
1773 | .. _`An Introduction to reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
1774 | .. _`A Record of reStructuredText Syntax Alternatives`: http://docutils.sourceforge.net/docs/dev/rst/alternatives.html
1775 | .. _`Problems With StructuredText`: http://docutils.sourceforge.net/docs/dev/rst/problems.html
1776 | .. _Sphinx: http://www.sphinx-doc.org/
1777 | .. _`Kernel documentation with Sphinx`: https://lwn.net/Articles/692704/
1778 | .. _`LWN.net`: https://lwn.net/
1779 | .. _`CMake 3.0.0 Release Notes`:  https://cmake.org/cmake/help/v3.0/release/3.0.0.html
1780 | 
1781 | AsciiDoc
1782 | ========
1783 | 
1784 | :2002 AsciiDoc: *Presentational*. Lightweight.
1785 | :2013 Asciidoctor: newer AsciiDoc toolchain.
1786 | 
1787 | AsciiDoc was originally written by Stuart Rackham. It is 
1788 | aimed specifically as a lightweight way of producing docbook.
1789 | 
1790 | Of course, producing docbook means that toolchains exist to produce almost
1791 | anything else.
1792 | 
1793 | The original Asciidoc implementation was written in Python in 2002.
1794 | 
1795 | Asciidoctor_ came out in 2013, and is written in Ruby.
1796 | 
1797 | AsciiDoc is well specified, allowing other implementations which behave in the
1798 | same way.
1799 | 
1800 | The AsciiDoc user guide says:
1801 | 
1802 |   AsciiDoc is a plain text human readable/writable document format that can be
1803 |   translated to DocBook or HTML using the asciidoc(1) command. You can then
1804 |   either use asciidoc(1) generated HTML directly or run asciidoc(1) DocBook
1805 |   output through your favorite DocBook toolchain or use the AsciiDoc a2x(1)
1806 |   toolchain wrapper to produce PDF, EPUB, DVI, LaTeX, PostScript, man page,
1807 |   HTML and text formats.
1808 | 
1809 | An example:
1810 | 
1811 | .. There doesn't seem to be a Pygments highlighter for DocBook
1812 | 
1813 | .. code:: reST
1814 | 
1815 |    Top level heading
1816 |    =================
1817 |    Or, alternatively, that could have been += Top level heading =+.
1818 |    Sub-heading
1819 |    -----------
1820 |    Like |TeX|, open and closing quote marks don't match, so instead one uses
1821 |    `single' or ``double'' quoting. This means that both 'this' and _that_ can
1822 |    be used to emphasize text. *strong* text and +monospaced+ text are also
1823 |    available.
1824 | 
1825 |    Listing blocks are one type of DelimitedBlock - there are several more:
1826 |    ---------------------------
1827 |    #include <stdio.h>
1828 |    ---------------------------
1829 | 
1830 |    * List items
1831 |    +
1832 |    can continue into another paragraph, but it must be explicitly joined on.
1833 | 
1834 | Here is an example similar to the setext example:
1835 | 
1836 | .. code:: reST
1837 | 
1838 |   = This is a title heading
1839 | 
1840 |   This is a paragraph. Body text is not indented.
1841 | 
1842 |   - This is a list item. Words can be _italic_, *bold* or
1843 |    +mono+ - yes, that's paired plus-signs.
1844 |   - This is a list item as well. We don't need blank lines between list items.
1845 |   +
1846 |   This is more of the second list item. It is "`joined on`" by the
1847 |   `+`.footnote:[Note the quotation marks around _joined on_.]
1848 | 
1849 |   == This is a sub-heading
1850 | 
1851 |   Sub-section body text is not indented either. What makes sense for
1852 |   programming languages is irritating for text.
1853 | 
1854 | Note the use of underlines to indicate emphasis, again looking back to the
1855 | meaning of underlining in typewritten manuscripts.
1856 | 
1857 | Paired plus signs are used for monotyped text, freeing up other quotation
1858 | marks for other uses.
1859 | 
1860 | AsciiDoc has a distinctive solution to continuing body elements such as lists,
1861 | using a + sign to continue a list item into a second paragraph.
1862 | 
1863 | The use of ``"\``` and ``\`"`` to indicate explicit opening and closing quotes
1864 | is nice.
1865 | 
1866 | Note that footnotes are written inline - this is less readable (in the
1867 | original asciidoc), but more convenient to write, and doesn't require the
1868 | author worrying about what footnore marker to use.
1869 | 
1870 | Headings can also be delimited in "setext" style, with underlining
1871 | characters, but that doesn't seem to be the normal convention (although
1872 | https://asciidoclive.com still shows that style in its example).
1873 | 
1874 | Some links:
1875 | 
1876 | * `Wikipedia on AsciiDoc`_
1877 | * AsciiDoc_ homepage
1878 | * AsciiDoctor_ - "Asciidoctor is a fast text processor and publishing toolchain
1879 |   for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other
1880 |   formats."
1881 | * `What is AsciiDoc? Why do we need it?`_, which also includes a list of
1882 |   organisations using it.
1883 | * `AsciiDoc Syntax Quick Reference`_
1884 | * `AsciiDoc Writer's Guide`_
1885 | 
1886 | .. _`Wikipedia on AsciiDoc`: https://en.wikipedia.org/wiki/AsciiDoc
1887 | .. _AsciiDoc: http://asciidoc.org/
1888 | .. _AsciiDoctor: http://asciidoctor.org/
1889 | .. _`AsciiDoc User Guide`: http://asciidoc.org/userguide.html
1890 | .. _`What is AsciiDoc? Why do we need it?`: http://asciidoctor.org/docs/what-is-asciidoc/
1891 | .. _`AsciiDoc Syntax Quick Reference`: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
1892 | .. _`AsciiDoc Writer's Guide`: http://asciidoctor.org/docs/asciidoc-writers-guide/
1893 | 
1894 | The tradeoffs made for a particular form of lightweight markup are always very
1895 | personal - one person's just-simple-enough is another person's step too far.
1896 | This means that developers keep trying to come up with a form of markup that
1897 | suits *their* sweet spot. Markup to fit their individual needs and wants.
1898 | 
1899 | So it shouldn't be a surprise that when I gave a lightning talk on "which
1900 | should I use, reStructuredText or Markdown?" I got a couple of people
1901 | asking afterwards why I hadn't talked about AsciiDoc. The answer was, in fact,
1902 | mostly ignorance on my part. There are many lightweight markup formats, and I
1903 | just hadn't realised how much use is made of AsciiDoc, and in particular of
1904 | the Asciidoctor system.
1905 | 
1906 | The `AsciiDoc User Guide`_ seems comprehensive and to define the markup well.
1907 | It is clear that its ambitions are much more complex than those of
1908 | reStructuredText - it clearly aims to support a substantial portion of
1909 | docbook, whilst remaining (more) readable.
1910 | 
1911 | I'd say it's definitely further away from "looking like an email", but this
1912 | makes sense as its ambitions are greater.
1913 | 
1914 | .. note:: Jonathan Corbet did look at using AsciiDoc for the kernel
1915 |   documentation, but Sphinx appears to have been a main contributor to the
1916 |   decision to use reStructuredText instead. However, the article at
1917 |   `Kernel documentation with Sphinx`_ explaining the decision does have a
1918 |   decent summary of AsciiDoc
1919 | 
1920 |     The AsciiDoc format, ... is semantically equivalent to DocBook XML, with
1921 |     the DocBook constructs expressed in terms of lightweight markup. AsciiDoc
1922 |     is easier for humans to read and write than XML, but since it is designed
1923 |     to translate to DocBook, it fits nicely in front of an existing DocBook
1924 |     toolchain. The original Python AsciiDoc tool has been around for a long
1925 |     time, but has been superseded by a Ruby reimplementation called
1926 |     Asciidoctor in recent years. 
1927 | 
1928 | Markdown
1929 | ========
1930 | 
1931 | :2004 markdown: *Presentation*. Lightweight.
1932 | 
1933 | Markdown was originally written by John Gruber, collaborating with Aaron
1934 | Swartz on the syntax.
1935 | 
1936 | It was explicitly aimed at being an easier way to write HTML:
1937 | 
1938 |    From the syntax page: "Markdown’s syntax is intended for one purpose: to be
1939 |    used as a format for *writing* for the web." Their emphasis.
1940 | 
1941 | It has suffered from an ambiguous specification and first implementation, and
1942 | the fact that the original author does not wish these to be corrected.
1943 | 
1944 | However, despite this, it has been immensely successful, suggesting that there
1945 | is a clear niche for a markup format at just about its (perceived) level of
1946 | complexity, and I myself recommend its use when reStructuredText is not
1947 | appropriate.
1948 | 
1949 | Here is the equivalent of our setext example:
1950 | 
1951 | .. There doesn't seem to be a Pygments highlighter for markdown
1952 | 
1953 | .. code:: reST
1954 | 
1955 |    # This is a heading
1956 | 
1957 |    This is a paragraph. Body text is not indented.
1958 | 
1959 |    - This is a list item. Words can be *emphasized*, **strong** or
1960 |    `inline` - that's single backquotes.
1961 |    - This is a list item as well. We don't need blank lines between list items.
1962 | 
1963 |        This is more of the second list item. It's first line must be indented
1964 |      by 4 spaces or a tab.
1965 | 
1966 |    ## This is a sub-heading
1967 | 
1968 |    Sub-section body text is not indented either. What makes sense for
1969 |    programming languages is irritating for text.
1970 | 
1971 |    (We don't do footnotes, but you can include <tt>HTML</tt>.)
1972 | 
1973 | Actually, headings can be specified with underlining as well (setext style),
1974 | but I've never seen anyone actually doing that.
1975 | 
1976 | And here is a more specific example:
1977 | 
1978 | .. code:: reST
1979 | 
1980 |    # A first-level header
1981 | 
1982 |    * Lists work as you might expect.
1983 |    * This is an unnumbered list.
1984 | 
1985 |      Multiple paragraphs are allowed per list item, which is good.
1986 |    Although the indentation doesn't need to be kept consistent after
1987 |    the first line.
1988 | 
1989 |    ## A sub heading
1990 | 
1991 |    > A blockquote.
1992 |    >
1993 |    > 1. The first line of a blockquoted list.
1994 | 
1995 |    Blocks of code must be indented by four spaces:
1996 | 
1997 |        so this is code
1998 | 
1999 |    and `inline code` can be done as well.
2000 | 
2001 | It's not well defined whether a blank line is needed before a list - that is,
2002 | whether::
2003 | 
2004 |   This paragraph has a hyphen starting its next line
2005 |   - does that constitute the start of a list item?
2006 | 
2007 | and it is specified that::
2008 | 
2009 |   1986. What a great season.
2010 | 
2011 | does start a numbered list item, so would need to be written as::
2012 | 
2013 |   1986\. What a great season.
2014 | 
2015 | The problems of markdown are, in the end:
2016 | 
2017 | * The amibiguous specification means that different implementations
2018 |   have different interpretations of markdown. Bugs in the original
2019 |   implementation mean that it's not possible to refer to that for
2020 |   arbitration.
2021 | * Markdown as originally specified is generally regarded as being a little
2022 |   *too* unambitious, and thus most of the implementations also include (often
2023 |   incompatible) extensions.
2024 | 
2025 | Thus it's not really sufficient to say one is using markdown, one has also to
2026 | say which dialect (e.g., github markdown) one is using.
2027 | 
2028 | Personally, I also think it is a problem that it allows embedded HTML
2029 | (although not specifying *what* HTML), and that means that, in order to keep
2030 | writing it reasonably simple, it has to try to "guess" an author's intent when
2031 | they use characters that might conceivably be HTML and not plain text.
2032 | 
2033 | .. note:: Would markdown be hurt **in any real way** by just removing the
2034 |    ability to embed HTML?
2035 | 
2036 | Hopefully CommonMark_ will improve the situation - for instance,
2037 | github-flavoured markdown is at least now based on CommonMark.
2038 | 
2039 | .. _CommonMark: http://commonmark.org/
2040 | .. _`CommonMark specification`: http://spec.commonmark.org/
2041 | 
2042 | The `CommonMark specification`_ is rigorous, and well written, but inevitably
2043 | very long, which rather undoes the perceived "simplicity" of markdown. Also,
2044 | it is only really atttempting to specify the common ground of the markdown
2045 | variants, and thus does not, for instance, include table.  
2046 | 
2047 | Note that it calls the underlined heading style "setext headings", which is
2048 | nice.
2049 | 
2050 |   CommonMark is very explicit (!) about how HTML may be included into its
2051 |   documents: https://spec.commonmark.org/0.28/#html-block
2052 | 
2053 |     Note that the CommonMark spec quotes the later purpose for markdown,
2054 |     readability, and not its original purpose of being an easier way to write
2055 |     HTML.
2056 | 
2057 |   The rules are bit complicated, but quite explicit, which is good, and appear
2058 |   always to require an opening ``<HTML-tag>`` and a closing matching ``<HTML-tag>``
2059 |   (where "``<HTML-tag>``" is my term - there must be a better way to describe
2060 |   that - entity?).
2061 | 
2062 |     https://spec.commonmark.org/0.28/#raw-html explains exactly how it
2063 |     recognises those ``<any-old-text>`` strings. It still means one has to
2064 |     escape thing like <this> to use them in mark[whatever], though. So one
2065 |     has to backtick escape it (https://spec.commonmark.org/0.28/#code-spans), or
2066 |     use https://spec.commonmark.org/0.28/#backslash-escapes as in the example of
2067 |     ``\<br/> not a tag``.
2068 | 
2069 |   Although it still has https://spec.commonmark.org/0.28/#entity-references but
2070 |   at least it's explicit that this is ``&`` plus an allowed entity reference
2071 |   name plus ``;``, which is reasonably deterministic (even if it relies on
2072 |   external documentation to say what entity references exist!).
2073 | 
2074 |   And finally, https://spec.commonmark.org/0.28/#textual-content says:
2075 | 
2076 |     Any characters not given an interpretation by the above rules will be parsed
2077 |     as plain textual content.
2078 | 
2079 |   which I still find itchy.
2080 | 
2081 | Markdown claims to be both easy-to-read and easy-to-write - i.e., the
2082 | `original introduction to markdown`_ said:
2083 | 
2084 |       Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
2085 |       you to write using an easy-to-read, easy-to-write plain text format, then
2086 |       convert it to structurally valid XHTML (or HTML).
2087 | 
2088 | The `original article on markdown's syntax`_ clarifies that a bit:
2089 | 
2090 |       Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
2091 | 
2092 |       Readability, however, is emphasized above all else. A Markdown-formatted
2093 |       document should be publishable as-is, as plain text, without looking like
2094 |       it’s been marked up with tags or formatting instructions. While Markdown’s
2095 |       syntax has been influenced by several existing text-to-HTML filters —
2096 |       including Setext, atx, Textile, reStructuredText, Grutatext, and EtText —
2097 |       the single biggest source of inspiration for Markdown’s syntax is the format
2098 |       of plain text email.
2099 | 
2100 | Personally, I think that doesn't recognise the tension between easy-to-read
2101 | and easy-to-write (they're not entirely compatible).
2102 | 
2103 | For interest, here are links to the sources mentioned:
2104 | 
2105 |     * `setext`_
2106 |     * `atx`_ - appears very simple, not very sophisticated
2107 |     * Textile_ - shortcuts for HTML
2108 |     * reStructuredText_
2109 |     * Grutatxt_ - appears to date from 2000 onwards. Simple but ambiguous
2110 |       documentation.
2111 |     * EtText_ - explicitly influenced by setext_, wikiwikiweb_, txt2html,
2112 |       Userland's Frontier, and StructuredText_.
2113 | 
2114 | .. _setext: `setext documents mirror`_
2115 | 
2116 | Of those, I think only reStructuredText_ has a decent definition. Also,
2117 | compared with the others (i.e., not reStructuredText), I think markdown looks
2118 | not too bad!
2119 | 
2120 | I'm surprised that AsciiDoc_ isn't mentioned in the influences.
2121 | 
2122 | Other links:
2123 | 
2124 | * `Wikipedia on markdown`_
2125 | * CommonMark_ is an attempt to provide a well-specified successor form of
2126 |   markdown. The page explains the problem they're trying to solve well. It was
2127 |   initially to be called "Standard Markdown", but that led to problems, as
2128 |   documented at `Standard Markdown is now Common Markdown`_, and hence the
2129 |   name change.
2130 | 
2131 | * Note that the IETF `RFC 7763: The text/markdown Media Type`_ (from 2016)
2132 |   explicitly says, in section 1.1:
2133 | 
2134 |       [MDSYNTAX] explicitly rejects the notion of validity: there is no such
2135 |       thing as "invalid" Markdown.
2136 | 
2137 |   which one might, perhaps, find distressing.
2138 | 
2139 | * Various people have written articles on the shortcomings of markdown. For
2140 |   instance:
2141 | 
2142 |   * `Why You Shouldn’t Use “Markdown” for Documentation`_, Eric Holscher, 2016
2143 |   * `markdown considered harmful (or perhaps just a loved but irritating old uncle)`_,
2144 |     bowerbird intelligentleman, 2013 (although he still likes markdown, despite
2145 |     the problems). This is also an interesting history of why markdown is where
2146 |     it is today (or, anyway, when the author was writing). He goes on to propose
2147 |     "Zen markup language" - see `beyond markdown, part 1`_, 2014 - although I
2148 |     don't know if it has ever materialised beyond the articles.
2149 |   * `Why Markdown is not my favourite language`_ (from 2012) shares many of my
2150 |     grumbles about markdown, gives a reasoned look at reStructuredText, and
2151 |     decides that actually the best hope is actually Creole_. Unfortunately, I
2152 |     don't think there's been much adoption of Creole.
2153 | 
2154 | In 2017, GitHub produced announced `A formal spec for GitHub Flavored
2155 | Markdown`_, which can be found at `GitHub Flavored Markdown Spec`_. Sensibly,
2156 | it's an extension of CommonMark_.
2157 | 
2158 | .. _atx: http://www.aaronsw.com/2002/atx/
2159 | .. _Textile: http://www.booked.net/textism.html
2160 | .. _Grutatxt: http://triptico.com/software/grutatxt.html
2161 | .. _EtText: http://ettext.taint.org/doc/
2162 | .. _`Wikipedia on markdown`: https://en.wikipedia.org/wiki/Markdown
2163 | .. _`original introduction to markdown`: https://daringfireball.net/projects/markdown/a
2164 | .. _`original article on markdown's syntax`: https://daringfireball.net/projects/markdown/syntax
2165 | .. _CommonMark: http://commonmark.org/
2166 | .. _`Standard Markdown is now Common Markdown`: https://blog.codinghorror.com/standard-markdown-is-now-common-markdown/
2167 | .. _`RFC 7763: The text/markdown Media Type`: https://tools.ietf.org/html/rfc7763
2168 | .. _`Why You Shouldn’t Use “Markdown” for Documentation`: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
2169 | .. _`markdown considered harmful (or perhaps just a loved but irritating old uncle)`: https://medium.com/the-bower/markdown-considered-harmful-495ccfe24a52
2170 | .. _`beyond markdown, part 1`: https://medium.com/the-bower/beyond-markdown-part-1-2300665659f7
2171 | .. _`Why Markdown is not my favourite language`: http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/
2172 | .. _Creole: http://www.wikicreole.org/
2173 | .. _`A formal spec for GitHub Flavored Markdown`: https://github.blog/2017-03-14-a-formal-spec-for-github-flavored-markdown/
2174 | .. _`GitHub Flavored Markdown Spec`: https://github.github.com/gfm/
2175 | 
2176 | Some more comparisons
2177 | =====================
2178 | 
2179 | * `Why we need constrainable lightweight markup languages`_, Mark Baker, 2016,
2180 |   and sam_ (Semantic Authoring Markdown), his proposed solution (still under
2181 |   active development)
2182 | * `Common markup for Markdown and reStructuredText`_, Alexander Dupuy, 2017 -
2183 |   an attempt to describe the commonality between the two markups, so that text
2184 |   can be written to satisfy both.
2185 | * `reStructuredText vs Markdown for documentation`_, Victor Zverovich, 2016 -
2186 |   a short comparison.
2187 |   
2188 | .. _`Why we need constrainable lightweight markup languages`:  http://everypageispageone.com/2016/06/05/why-we-need-constrainable-lightweight-markup-languages/
2189 | .. _sam: https://github.com/mbakeranalecta/sam
2190 | .. _`Common markup for Markdown and reStructuredText`: https://gist.github.com/dupuy/1855764
2191 | .. _`reStructuredText vs Markdown for documentation`:  http://zverovich.net/2016/06/16/rst-vs-markdown.html
2192 | 
2193 | Other lightweight markups
2194 | =========================
2195 | A very scattershot section.
2196 | 
2197 | `Org-Mode Is One of the Most Reasonable Markup Language to Use for Text`_,
2198 | Karl Voit, 2017. Emacs org-mode considered as a general markup language
2199 | 
2200 | .. _`Org-Mode Is One of the Most Reasonable Markup Language to Use for Text`: http://karl-voit.at/2017/09/23/orgmode-as-markup-only/
2201 | 
2202 | I don't really discuss org-mode as a markup format because it is so
2203 | Emacs-specific. It appears to be defined by its usage, without separating out
2204 | in a clear fashion the underlying text representation.
2205 | 
2206 | Pollen_, a lightweight programmable markup written in Racket_, Matthew
2207 | Butterick, 2017. I admit to finding this quite interesting - in some ways it
2208 | can be seen as a re-imagining of |TeX|.
2209 | 
2210 | .. _Pollen: http://docs.racket-lang.org/pollen/
2211 | .. _Racket: https://racket-lang.org/
2212 | 
2213 | `A Brief History of the Development of SMDL and HyTime`_. OK, just one link
2214 | to an article about marking up music. Although I actually find Lilypond_
2215 | (1996 and later) more interesting. Which is a second.
2216 | 
2217 | .. _`A Brief History of the Development of SMDL and HyTime`: http://www.sgmlsource.com/history/hthist.htm
2218 | .. _Lilypond: http://lilypond.org/
2219 | 
2220 | `Mathematical Markup Language (MathML™) 1.01 Specification`_ of the W3C_
2221 | Mathematical Markup Language. The Introduction_ gives its history and
2222 | background.
2223 | 
2224 | .. _`Mathematical Markup Language (MathML™) 1.01 Specification`: https://www.w3.org/TR/REC-MathML/
2225 | .. _`Introduction`: https://www.w3.org/TR/REC-MathML/chapter1.html
2226 | 
2227 | HAML_ (HTML Abstract Markup Language) is an attempt to make "beautiful HTML
2228 | markup". It is especially used in the Ruby on Rails world. One of the
2229 | maintainers is `Takashi Kokubun`_ from Arm Treasure Data, who has also written
2230 | hamlit_, which is a high performance implementation.
2231 | 
2232 | .. _HAML: http://haml.info/
2233 | .. _`Takashi Kokubun`: https://github.com/k0kubun
2234 | .. _hamlit: https://github.com/k0kubun/hamlit
2235 | 
2236 | Fin
2237 | ===
2238 | 
2239 | * 1960s TYPSET and RUNOFF, GML
2240 | * 1970s roff, runoff, nroff/troff, |TeX| in SAIL
2241 | * 1980s Scribe, |TeX| in WEB/Pascal, |LaTeX|, PostScript, SGML, TEI
2242 | * 1990s groff, HTML, setext, Docbook, WikiWikiWeb, POD, javadoc, StructuredText, XML
2243 | * 2000s reStructuredText, AsciiDoc, markdown
2244 | 
2245 | This document was written using reStructuredText_.
2246 | 
2247 | The source for this and the corresponding slide show can be found at
2248 | https://github.com/tibs/markup-history
2249 | 
2250 | You may also be interested in Write the Docs: http://www.writethedocs.org/
2251 | 
2252 | .. vim: set filetype=rst tabstop=8 softtabstop=2 shiftwidth=2 expandtab:
2253 | 


--------------------------------------------------------------------------------