Collaborative and automated writing of papers and reports
Here we will look at markup languages used for writing texts as well as at online tools to do the writing and command line tools which do format transformations and typesetting. Finally, we will look at one aspect of open access, particularly licensing, i.e. what can happen with the paper after it is published.
Markdown is a way how include things such a headings and lists into a documents while still keeping it as a simple text file. Generally speaking, Markdown is a markup language like HTML but simpler (and also less powerful).
In Authorea, go to Insert -> Markdown and type or copy paste there the following text:
# This is a heading This is *emphasis*. * This is a list. * Of different items.
To practice Markdown, we will use online editor Dillinger (which can be used for free online and is also open source):
Markdown with Pandoc
Markdown is a simple markup language for include formatting into a plain text document. Pandoc is a conversion tool which can convert Markdown files and many other files into other formats.
Pandoc is licensed under GNU GPL.
To see the format conversions without installing Pandoc use the Try Pandoc! service.
reStructuredText with Sphinx/Docutils
reStructuredText is an plain text markup syntax similar to aforementioned Markdown. It is often used for software documentation, for example in Python docstrings. reStructuredText is, unlike Markdown, designed for extensibility for specific application domains. reStructuredText is applicable to non-trivial cases like LaTeX, but still striving to keep simple syntax like Markdown.
Docutils is an open-source text processing system for processing plain text into formats, such as HTML, LaTeX, man-pages, open-document or XML. Docutils processes reStructuredText and can be used from command line or as a Python package. Another software which can process reStructuredText in a similar manner is Pandoc.
Sphinx is a tool that creates documentation from reStructuredText sources. It is used for Python documentation and it is universal enough to be used for software projects in general. The output formats include HTML, LaTeX (for printable PDF versions), ePub, and more. Sphinx uses the Docutils to parse the reStructuredText.
Sphinx is licensed under BSD and Docutils are placed into public domain.
Authorea is freemium cloud platform for writing scientific articles. Markdown is one way to author text in Authorea. Optionally, try writing a document at:
Note: When creating account or article on Authorea, use your institutional (NCSU) email, but don't send announcement about it to all people in the institution (which is something Authorea may do by default if you won't say no!).
LaTeX is markup language, typesetting software, and software ecosystem.
Go through a dedicated page (that's required).
Open access and licenses
Although open access independent from the tools discussed above, it often comes into play together. For example, many papers at arXiv are typesetted (and presumably prepared) using LaTeX and Authorea offers a pre-print service. Here we will discuss a specific and key aspect of open access which is licensing.
Publishing an article as open access is usually achieved by licensing it using one of the Creative Commons licenses.
For example, MDPI uses CC BY (Creative Commons Attribution License). In a description of an article MDPI says:
This is an open access article distributed under the Creative Commons Attribution License which permits unrestricted use, distribution, and reproduction in any medium, provided the original work is properly cited. (CC BY 4.0).
CC BY is also used, for example, by PLOS and it is the most common license used for open access articles.
Another license commonly used for open access articles is CC BY-NC (Creative Commons Attribution-NonCommercial License) sometimes combined also with ND (NoDerivatives) part (CC BY-NC-ND or CC BY-ND) preventing commercial use and modifications. What that exactly means in each particular case is often hard to determine [Redhead, 2012], but it is clear that these licenses doen't fulfill the Open Definition:
Open means anyone can freely access, use, modify, and share for any purpose (subject, at most, to requirements that preserve provenance and openness).
The "preservation of provenance" part is for example the attribution in CC BY and the "preservation of openness" part can be found for example in CC BY-SA (Creative Commons Attribution-ShareAlike License). CC BY-SA is sometimes used for open access articles and is quite commonly used in general, for example at Wikipedia. The CC BY-SA license requires that the derived works are distributed only under the same or similar license.
Creative Common licenses have both "human-readable summaries" ("plain English") and a full legal language license documents.
- Markdown in Authorea (recording from the class, 4 mins)
- Working with references in Authorea (recording from the class, 10 mins)
- Open Access and Creative Commons Licenses (recording from the class, 13 mins)
- Open definition is about freedoms (recording from the class, 3 mins)
- Is open a reaction to proprietary? (recording from the class, 3 mins)
- Creative Commons & Copyright Info
- Freemium (Wikipedia)
- Gratis versus libre (Wikipedia)
- Markdown (Original Daring Fireball document)
- In the beginning, there is Markdown
- Creative Commons Licenses (About The Licenses)
- Writing Technical Papers with Markdown
- reStructuredText Primer for Sphinx
- Differencees between reStructuredText, Docutils, and Sphinx
- reStructuredText vs Markdown for documentation
- Herb, Ulrich (2014). Total numbers and shares of Open Access Journals using Creative Commons licenses as listed by the Directory of Open Access Journals; ZENODO; DOI: 10.5281/zenodo.8327
- The Open Definition (accessed: 2017-08-22)
- Claire Redhead. 2012. Why CC-BY? URL: https://oaspa.org/why-cc-by/ (accessed: 2017-08-22)
Follow the Assignment in the LaTeX part.