Commit 64e25dc3 authored by Joel Ostblom's avatar Joel Ostblom

Clarify what plain text and markdown are

parent ba12c94e
......@@ -179,49 +179,52 @@ researcher's institution can't afford a license, the text of that document will
be inaccessible.
More commonly, if one finds a document written using an older version of the
software (e.g. `.doc` vs `.docx`), there is no guarantee it can be opened in the
new version of the software. Documents can only be opened by people who can
afford to purchase the products sold by the vendor. Opening the same document in
different versions of the same software or on different computers could render
different results (such as when opening a Windows PowerPoint presentation on a
Mac). Storing either data or manuscripts in such formats means that they can be
lost forever or could be inaccessible to certain groups of people. In contrast,
writing in an open, text-based source format means that the document can be
opened by anyone with access to a computer or mobile device.
There are several plain-text "[markup language]" formates, such as [LaTeX] or
[HTML]. However, there are major drawbacks to these "languages", including the
difficulty and effort required to learn them. Luckily, there is the
[Markdown] format which is simple to learn and to use. Since Markdown is just
plain text, changes can also be easily tracked using [Git] and collaboration can
happen on [GitHub] or [GitLab]. There are also promising online text editors
emerging which support Markdown with track changes to ease the transition for
those not wanting to learn GitHub, e.g. Authorea. Plus, when using
[Pandoc Markdown], the document can be converted to a large range of output
formats, including Word `.docx`, beautifully typeset [LaTeX] PDFs, or web friendly
[HTML] files. Markdown also has features typically required of scientific
writing such as citation and bibliography insertion (including plain text
formats such as [BibTeX]). Taken together Markdown is a simple, powerful plain
text format that ensures documents will stick around well into the future.
software (e.g. `.doc` vs `.docx`), there is no guarantee it can be opened in
the new version of the software. Opening the same document in different
versions of the same software or on different computers could render different
results (such as when opening a Windows PowerPoint presentation on a Mac).
Documents can only be opened by people who can afford to purchase the products
sold by the vendor. Storing either data or manuscripts in such formats means
that they can be lost forever or could be inaccessible to certain groups of
people. In contrast, writing in an open, text-based source format means that
the document can be opened by anyone with access to a computer or mobile
device.
Open, text-based formats are commonly referred to as plain text documents.
Although plain text itself cannot be formatted into headings, bold font, etc;
the addition of text-based markup, such as `*` or `[bold]` surrounding a word,
enables text editors to display plain text as formatted documents. There are
several plain-text "[markup language]", such as [LaTeX] or [HTML], but many of
these have verbose markup that make them inefficient to type and difficult to
learn. [Markdown] is a markup language that was designed from markup
conventions used over email so it is simple to learn and easy to type. A flavor
of Markdown called [Pandoc Markdown]) is specialized on scholarly communication
and support features required in scientific writing such as automatic figure
referencing, in text citations, and bibliography insertion (including plain
text formats such as [BibTeX]). [Pandoc Markdown] documents can also be
converted to a large range of output formats, including Word `.docx`,
beautifully typeset [LaTeX] PDFs, or web friendly [HTML] files. [R Markdown] is
an extension of [Pandoc Markdown] that allows R and Python code to be executed
within and inserted into a document, increasing document-level reproducibility.
Since Markdown is just plain text, changes can be easily tracked using [Git]
and collaboration can happen on [GitHub] or [GitLab]. There are also promising
online text editors emerging which support Markdown with track changes to ease
the transition for people used to conventional word processors, e.g. [Authorea]
and [Stencila]. Taken together the Markdown format is an open plain text format
that is accessible and usable on all operating systems, has an active community
of users, is well maintained and documented (e.g. the [Pandoc Markdown] manual
or the [R Markdown Book]), can be converted in a wide range of document types
(see the [Pandoc Markdown] about page for examples), is designed for simplicity
and readability, and has flavors dedicated to scholarly communication.
[HTML]: https://en.wikipedia.org/wiki/HTML
[LaTeX]: https://www.latex-project.org/
[markup language]: https://en.wikipedia.org/wiki/Markup_language
[Markdown]: https://en.wikipedia.org/wiki/Markdown
[BibTeX]: https://en.wikipedia.org/wiki/BibTeX
TODO: Determine if there is a "Python Markdown" available
The Markdown format is open source, is simple plain text (accessible and usable
on all operating systems and versions), has an active community of users, is
well maintained and documented (e.g. the [Pandoc Markdown] or the [R Markdown
Book]), can be converted in a wide range of document types (see the [Pandoc
Markdown] about page for examples), is designed for simplicity and readability.
For R based projects, use [R Markdown], an extension of Markdown that allows R
code to be executed within and inserted into a document, increasing
document-level reproducibility. [RStudio] offers a great environment to write R
Markdown.
[Authorea]: https://www.authorea.com/
[Stencila]: https://stenci.la/
[R Markdown Book]: https://bookdown.org/yihui/rmarkdown/
#### Dissemination phase
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment