Structured Commons

Summary

The content of the following sections can be summarized as follows:

• prefer document sources when computing fingerprints and citing new or existing works;
• publish document sources (eg. TeX) alongside their presentation formats (eg. HTML, PDF, EPUB) and indicate clearly which source format is used, eg. via file name extensions or user instructions;
• do not under-estimate the importance of long-term durability, a requirement not commonly honored by popular word processing software;
• acknowledge and do not under-estimate the recent (2005-2015) user demand for markup languages that enable fast adoption, fast editing and fast reading in source form, eg. rST or Markdown.

This SCEP is only applicable to Structured Common objects that primarily consist of written text, ie. NOT data sets, images, program source code, program executables, virtual machine images, etc.

Source formats and citation network

It is possible to integrate printable PDFs in the Structured Commons network directly; ie., compute fingerprints of PDF files directly and/or cite works via their PDF fingerprints. However, the Structured Commons model strongly encourages authors to publish their document sources as well.

This requirement is already prevalent in online document libraries, either from established academic publishers or in open repositories like arXiv [3]. Moreover, once authors take the habit to publish document sources alongside other presentation formats, it becomes possible to make fingerprints independent from document representation.

This in turn enables authors to (re-)generate alternate representations of a document after it has been published, without breaking the existing fingerprint-based citations from other works.

Support for multiple source formats

There currently exist multiple workflows and tools used by scientific authors to prepare documents prior to publication. Anecdotically, this diversity is maintained and usually polarised by conflicting requirements between the authors’ desire for a WYSIWYG editing interface and the field’s requirement for high-quality print typesetting and long-term portability of document formats; the conflict is epitomized by this common question from graduate students worldwide: "should I use Word or LaTeX to write my thesis?"

For various reasons, some of which detailed below, this controversy may be soon resolved for scientific works by a common shift away from word processors, towards standard-based and document-centric workflows using multiple editing tools simultaneously—including but not limited LaTeX, and also newer "lightweight" markup formats like rST or Markdown.

Nevertheless, this SCEP acknowledges that both technology and user preferences will continue to evolve over time, and thus that the Structured Common model should not restrict users to a single source format or technology.

Choice of markup languages

This SCEP recommends the following prioritization of criteria when considering multiple candidate markup languages for a new Structured Commons documents, in decreasing priority order:

1. standardisation: how well-specified is the markup language, how many different implementations exist that have a common interpretation of the markup language, and how likely will it be possible to re-implement tools from format specifications long after current implementations have been lost.
2. semantic transparency: how much does the markup syntax suggest the semantic role of annotated content elements.
3. readability in source form: how much can still be learn and understood from a document source if all knowledge about the format and document processing machinery has been lost.

Criterion #1 promotes all standard-based workflows and formats (eg. LaTeX, rST, Markdown, HTML, etc) over implementation-based workflows and formats (eg. OOXML, OXF, etc.), because program-centric environments have only poorly/partially standardized interchange formats, and it is thus unlikely that documents can be recovered from sources after current implementations fall out of use.

Criterion #2 promotes pre-structured markup languages like LaTeX, rST, Markdown or HTML compared to general markup languages like XML, where markup tags can be inscrutable without access to an externally provided schema, or print-oriented typesetting languages like Troff, where markup tags specify layout and typography instead of semantics.

Criterion #3 promotes "transparent" markup languages like rST, Markdown or Org-mode, where the source form of a document is usually also conveniently readable, compared to command-based or tag-based languages like LaTeX, texinfo or HTML which require preprocessing/interpretation to become conveniently readable.

Other criteria to further discriminate between alternatives are intendedly not covered by this SCEP, in order to:

1. acknowledge possibly diverging preferences by research field or user community.
2. acknowledge the evolution of markup languages and technology over time, in particular regarding their support for "specialized features" (eg. inline mathematical formulas), integration as inline comments in programming languages, support by popular editor programs, etc.

See also Example markup languages below.

History of source document formats

Historically, the following requirements have motivated major technology shifts by authors, ie. situations where authors willfully decided to adapt their workflow and working style and accept/adopt new tools and technology for source documents, even sometimes at the cost of a partial feature loss from their existing habits and expectations:

Source formats vs. requirements

The following table illustrates how technology has evolved to respond to the requirements stated above over time:

At the time of this writing, word processors are coming out of fashion for scientific works in favor of markup languages, with LaTeX historically prevalent in mathematics, logics and computer science.

LaTeX vs. other markup languages

LaTeX is commonly advertised to new scientific scholars as the go-to markup language suitable for academic publishing. LaTeX particularly contrasts with most word processing software with its long history of technical stability, reliability and typeset output quality, and these differences is commonly used as "selling point".

However, all users, including new authors, teachers of LaTeX and existing LaTeX users, should consider how LaTeX may not fully cater for recent requirements from both authors and readers:

• client-side interpretation: LaTeX still has only limited support for web and e-book publishing; in particular, its underlying TeX engine is designed to position words on a page, not organize text in semantic groups suitable for re-formatting in different ways by different readers.
• learning curve: LaTeX presents an extremely steep learning curve to new authors, which opposes a significant threshold to adoption.
• lightweight implementation: LaTeX requires access to a working LaTeX typesetting infrastructure, including a relatively large software and data base (hundreds of megabytes), to "interpret" source documents to a format understandable by humans.

In contrast, the new generation of "lightweight markup formats" pionereed by Wikipedia (Wiki markup), Web fora (Markdown) and inline source code documentation (rST, AsciiDoc) is tailored to these new requirements without sacrificing the other advantages of LaTeX compared to word processors.

In short, this SCEP recommends scientific authors to consider alternate source markup languages for new works, tailored to contemporary user expectations, without sacrificing the Structured Commons vision: long-term document durability.

Example markup languages

The following table summarizes a few markup languages in common use at the time of this writing (2014). This table is provided for informational use only. This SCEP does not endorse nor promote any of these languages and associated technologies.

In the table above,

• "Strong support for print" indicates native features for controlling the formatting of print outputs, including paper format and page layout.
• "Strong support for math" indicates native support for mathematical formula’s, including superscripts (x²), subscripts (f₀), and general use mathematical symbols (eg. infinity ∞, pi π, sum ∑, implication  ⇒ , algebraic sets ℝ).
• "Strong support for tables" indicates native support for tabular data, including row headers, text alignment within cells and merging of adjacent cells.

See also

• Wikipedia’s comparison of Lightweight markup languages
• Wikipedia’s Comparison of document markup languages
• The C2 WikiWikiWeb’s page on Text Filters
• Pandoc, a universal markup format converter