Cite this lesson as: Deutsch, J. L., & Author, S. (2015). Authoring Lessons. In J. L. Deutsch (Ed.), Geostatistics Lessons. Retrieved from http://geostatisticslessons.com/lessons/creatinglessons
Authoring Lessons
Jared Deutsch
University of Alberta
Second Author
School of Rocks
September 30, 2015
Learning Objectives
- Identify and apply the correct syntax and format for authoring lessons for publication in Geostatistics Lessons
- Include figures, references, and equations using the markdown format
- Build an HTML draft of your lesson using the standalone compiler with pandoc
Introduction
Geostatistics Lessons is not a website that explains fundamental geostatistical principles in a series of lessons. There are many classes, short courses, academic papers, and books (Chilès & Delfiner, 2009; Goovaerts, 1997; Pyrcz & Deutsch, 2014; Rossi & Deutsch, 2013, and others) on geostatistics which are an excellent resource for learning and reviewing the details of specific subjects. Instead of covering the same ground as these textbooks in Geostatistics Lessons, the focus of Lessons is on when to apply different techniques, how to make informed modeling decisions, and how to apply these models for better decision making with uncertainty. The goal is to provide an open transparent disclosure of best practices in a series of lessons which is freely and easily accessible with online browsing at GeostatisticsLessons.com and offline reference in the form of lesson PDFs.
This dual format is achieved by authoring lessons using the widely used markdown format for lessons. This short demonstrative lesson covers the basics of authoring lessons and serves as a starting point for lesson authors to format their own lessons. The inclusion of figures, equations, tables, and references are all covered in this lesson.
Authoring lessons
Lessons are authored in markdown format, specifically the markdown syntax used by pandoc. A complete reference guide to pandoc markdown is available online. Markdown is a plain text formatting language, with many similarities to LaTex, but much simpler and may easily be converted to a wide range of formats. A limited set of html and LaTex may be included directly in the markdown; however, as the lessons are compiled to both PDF and html formats, not all html and LaTex code may be validly used in a lesson. Standards such as equations, links, code segments, citations, figures, tables, and lists all may be incorporated.
Equations
Equations are rendered for the web using MathJax, and for PDF using LaTex typesetting. The lessons are written in markdown using standard LaTex equation formatting. If the lesson author uses MathType, MathType can directly produce the correct LaTex formatting for copying into the text file. For example, an equation is expressed in markdown as:
$$\overline{\gamma}(V,v)=\frac{1}{|V||v|}\int_V\int_v\gamma(x-y)dxdy$$
When rendered online or in PDF, it appears as: \[ \overline{\gamma}(V,v) = \frac{1}{|V||v|} \int_V \int_v \gamma(x-y) dx dy \] Equations may also be included inlined using standard LaTex syntax, such as this equation \(\gamma(\mathbf{h}) = 0.2 + 0.8 C(\mathbf{h})\). In markdown, this equation is expressed as:
$\gamma(\mathbf{h}) = 0.2 + 0.8 C(\mathbf{h})$
Since dollar signs are used to signal equations, dollar signs should be escaped in the markdown to avoid accidentally typesetting as an equation!
Citations
Citations are included using a separate bibtex file. Citations are referenced using syntax very close to LaTex. A single work may be cited, such as this one: (Journel & Huijbregts, 1978).
...such as this one: [@journel1978]
Alternatively multiple works, such as standard geostatistical texts may be cited together as (Chilès & Delfiner, 2009; Goovaerts, 1997; Pyrcz & Deutsch, 2014; Rossi & Deutsch, 2013).
... together as [@chiles2009; @goovaerts1997; @pyrcz2014; @rossi2013]
The references are included in a BibTex file, with text in standard BibTex format, such as this citation for Geostatistical Reservoir Modeling:
@book{pyrcz2014,
title={Geostatistical reservoir modeling},
author={Pyrcz, Michael J and Deutsch, Clayton V},
year={2014},
publisher={Oxford university press}
}
BibTex formatted citations, such as the one above, may be downloaded from Google Scholar using the Cite functionality. Reference managers such as Mendeley and EndNote are also capable of exporting BibTex formatted citations. Publishers, such as Elsevier and Springer, also include BibTex export functionality. References are automatically included at the end of the lesson where the statement appears in the markdown text:
# References
Figures
Figures may be included in lessons with mouseover text for html rendering and captions. An example figure is included.
Figures are included using an exclamation point to signal that a link is a figure as:
![This is the caption for a figure.](domain.png "This...")
The html version of the lesson will put the figure where it appears in the markdown. The PDF version will include the figure at a reasonable point near to the original location using LaTex to dictate figure location.
Code snippets
Code snippets may be included where text has 4 spaces at the beginning of the line, such as:
pandoc testlesson.txt --latex-engine=xelatex -o testlesson.PDF
pandoc testlesson.txt -s --mathjax -o testlesson.html
Lists
Lists may be included with either bullets as unordered lists:
- Item one
- SubItem one
- SubItem two
- Item two
or as numbered lists:
- First item
- Second item
- Third item
The syntax for these lists is:
- Item one
- Item two
1. First item
2. Second item
Tables
Tables may be included with content right aligned, left aligned, centered, or with default ordering. A table including all formats is written:
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Table: Demonstration of simple table syntax.
and rendered as:
Right | Left | Center | Default |
---|---|---|---|
12 | 12 | 12 | 12 |
123 | 123 | 123 | 123 |
1 | 1 | 1 | 1 |
Lesson files
Three types of file compose a lesson: a .txt file containing the lesson in markdown format, a .bib file containing the bibtex formatted bibliography and any figures. For this lesson, the source files are:
authoringlessons.txt
authoringlessons.bib
domain.png
geometvision.png
Lesson metadata
At the top of every lesson is metadata in the form of YAML (YAML Ain’t Markup Language) at the of the text file. This specifies the lesson title, authoring date, lesson classification (ie: Methodology, Variograms,…) and lesson authors. A portion of the YAML for this lesson is:
---
title: Authoring Lessons
date: September 30, 2015
author:
- name: Jared Deutsch
affiliation: University of Alberta
- name: Second Author
affiliation: School of Rocks
...
Standalone Compilation
Provided with this lesson is a small directory which includes the tools to generate a standalone html document which can be downloaded from: https://resmodsol.nyc3.digitaloceanspaces.com/standalone.zip. This is useful for ensuring that the markdown is entered in the correct format, and for previewing what the lesson will look like online. The directory includes the following:
standalone/
pandoc/
pandoc.exe - Used to compile the markdown
pandoc-citeproc.exe - A filter used to format citations
template/
apa.csl - APA format for pandoc-citeproc
html.template - The template for pandoc
style.css - The cascading stylesheet for the html
makelesson.bat - Windows script to compile the document
makelesson.sh - Unix script to compile the document
lesson.txt - The lesson source
lesson.bib - Citations in bibtex format
*.png - Include any figures in this directory
The command in the makelesson script assumes this directory structure and file names, so it is best to simply edit the files directly.
Summary
The markdown format used in the authoring of lessons for Geostatistics Lessons is straight forward, and requires no special software to author. If the author has any questions regarding the markdown syntax, please contact the editor or editorial board for Geostatistics Lessons.
References
Chilès, J.-P., & Delfiner, P. (2009). Geostatistics: Modeling spatial uncertainty (Vol. 497). John Wiley & Sons.
Goovaerts, P. (1997). Geostatistics for natural resources evaluation. Oxford university press.
Journel, A. G., & Huijbregts, Ch. J. (1978). Mining geostatistics (p. 600). Blackburn Press.
Pyrcz, M. J., & Deutsch, C. V. (2014). Geostatistical reservoir modeling. Oxford university press.
Rossi, M. E., & Deutsch, C. V. (2013). Mineral resource estimation. Springer Science & Business Media.