Documenting and Presenting with Pillar

Damien Cassou, Cyril Ferlicot Delbecque, Yann Dubois and Thibault Arloing

This chapter describes Pillar version 4.0. The original author of Pillar and current maintainer is Damien Cassou. Many people have also contributed: Ben Coman, Stéphane Ducasse, Guillermo Polito, Lukas Renggli (original author of Pier from which Pillar has been extracted), Benjamin van Ryseghem, Cyril Ferlicot-Delbecque, Thibault Arloing and Yann Dubois. Pillar is sponsored by ESUG.

1. Introduction

Pillar (hosted at http://www.smalltalkhub.com/#!/~Pier/Pillar) is a markup syntax and associated tools to write and generate documentation, books (such as this one) and slide-based presentations. The Pillar screenshot in Figure 0.1 shows the HTML version of chapter .

Pillar has many features, helpful tools, and documentation:

simple markup syntax with references, tables, pictures, captions, syntax-highlighted code blocks;
export documents to HTML, LaTeX, Markdown, AsciiDoc, ePuB and Pillar itself, and presentations to Beamer and Deck.js;
customization of the export through a dedicated STON configuration file (see chapter ) and Mustache templates (see chapter ).
many tests with good coverage (94% with more than a 2100 executed tests), which are regularly run by a continuous integration job
a command-line interface and dedicated plugins for several text editors: Emacs, Vim, TextMate, and Atom
a cheat sheet

1.1. Pillar Users

This book was written in Pillar. If you want to see how Pillar is used, have a look at its source code (http://books.pharo.org/enterprise-pharo/), or check the following other real-world projects:

the Updated Pharo by Example book (https://github.com/SquareBracketAssociates/UpdatedPharoByExample),
the Pharo MOOC - Massive open online course (https://github.com/SquareBracketAssociates/PharoMooc ,
the PillarHub open-access shared blog (http://pillarhub.pharocloud.com).

2. 5 Minutes Tutorial

In this section we give the basic steps to get you started with your first Pillar document and exports. You first need to create a base directory inside which we will put all your text, configuration files, and Pillar itself.

mkdir mydocument
cd mydocument

2.1. Installing and Exporting your First Document

You first need to get Pillar. For that, we recommend downloading and executing the script available at https://raw.githubusercontent.com/pillar-markup/pillar/master/download.sh in the base directory if you are on an Unix environment.

wget https://raw.githubusercontent.com/pillar-markup/pillar/master/download.sh
chmod +x download.sh
./download.sh

Then, you can load an archetype (see Section 2.3) with command:

./pillar archetype welcome

Now you can just compile the welcome file

make book-result/welcome.html

You can see the result of the compilation as follow:

more welcome.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My first document while reading the 5 minutes Pillar tutorial</title>
  </head>
  <body>
    <div class="container">
    <section>
<h1>1. Hello World</h1>
</section>
    </div>
  </body>
</html>

2.1.1. Changing the output folder

You have the possibility to rename the directory in which your files will be exported. To do that you have to change the OUTPUTDIRECTORY variable in the Makefile:

OUTPUTDIRECTORY = result

Then, you can check everything is working fine by creating a first.pillar file with this content:

!Hello World

And finally compiling it from a terminal (see Section 6 for more information about the command-line interface).

make result/first.html

Pay attention if you did not change the output directory you should use:

make book-result/first.html

This should generate a first.html file you can open in a web browser. The content of this file will be something like:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title></title>
  </head>
  <body>
    <div class="container">
      <section>
        <h1>1. Hello World</h1>
      </section>
    </div>
  </body>
</html>

2.2. Configuring a Document

As you can see, there is no document title in the generated first.html file. This is because we did not specify any. To specify a title, we have to add it with a configuration at the beginning of the first.pillar file:

{
   "metadata": {
     "title": "My first document while reading the 5 minutes Pillar tutorial"
    }
}

!Hello World

When you compile using the same command line,

make result/first.html

you should now get a web page with a title:

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>My first document while reading the 5 minutes Pillar tutorial</title>
   </head>

Another way to achieve the same is to use a dedicated configuration file. This configuration is typically named pillar.conf and is written in the STON format (see Section 4 for more information about the configuration file). Create your first pillar.conf file:

{
   "metadata": {
     "title" : "My first document from pillar.conf"
    }
}

Meta-information specified in Pillar files take precedence over configuration in the pillar.conf file. To see the new title, you thus have to remove the one in first.pillar.

2.3. Exporting a Different Content Using a Template

If you want to tweak the content of the exported file, for example to reference your CSS or to add a footer, you need to create your own template (see Section 5 for more information about templating). You must write such template in its own file, e.g., myhtml.template:

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>{{{title}}}</title>
   </head>
   <body>
      <div class="container">
         {{{content}}}
      </div>
      <footer>
         <p>{{author}}, {{year}}</p>
      </footer>
   </body>
</html>

Then, to use this template, you need to replace the HTMLTEMPLATE variable in the Makefile. So, edit your Makefile:

HTMLTEMPLATE = myhtml.template

Now, write your name in first.pillar :

{
   "metadata":{
     "author": "Damien Cassou"
    }
}

!Hello World

You can also write the year in the pillar.conf file:

{
  "metadata":{
    "title":"My first document from pillar.conf",
    "year":"2016"
  }
}

Finally, compile first.pillar one last time

make book-result/first.html

to generate a file containing:

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>My first document from pillar.conf</title>
   </head>
   <body>
      <div class="container"> [...]
         <h1>Hello World</h1>
      </div>
      <footer>
         <p>Damien Cassou, 2016</p>
      </footer>
   </body>
</html>

Look at how the HTML template (myhtml.template) references title, author and year. These variables are referenced by enclosing them in 3 curly braces. The templating engine that transforms your templates in documents is Mustache (see chapter . As you can see, I decided to put the author of the document in the first.pillar file whereas the year and title are specified in pillar.conf: this is arbitrary and you can do whatever suits you best: the differences being that the pillar.conf file applies to all Pillar files of the project and that file meta-information takes precedence.

This concludes our 5 minutes tutorial.

2.4. Archetype - A Pillar skeleton maker

An archetype is a project skeleton to well begin a pillar project. In an archetype you have all the files you will need and an example.

Basically you have:

Makefile
pillar.conf
templates
... with some differences between archetypes

To download a new archetype, launch this command :

./pillar archetype <archetypeName>

Here is the list of the current archetypes :

book
presentation
welcome

Pay attention that you may have to restart from a fresh folder when you change project style.

You can help us by creating your own archetype on the Github Project.

To add an archetype, just create the file tree and put an empty file ".keep" in empty folders.

3. Writing Pillar Documents

In this section we show how to write Pillar documents by presenting the Pillar syntax. You might want to have a look at the cheat sheet and even download and print it.

3.1. Meta-Information

Meta-information of a particular file is written at the start of the file between curly braces using the STON syntax (see chapter ). A meta-information starts with a word between quotation marks acting as a key, is followed by a colon :, and finishes with a value. For example, the following Pillar file,

{
   "metadata":{
     "title": "My first document from pillar.conf",
     "author": "Damien Cassou"
    }
}

!Hello World

represents a Pillar document with the title and author set. You can use whatever keys you like. Use them by referencing them in templates (see section 5 for more information about templating). Only keys in the metadata field can be referenced in the template.

3.2. Chapters & Sections

A line starting with ! represents a heading. Use multiple ! to create sections and subsections.

To refer to a section or chapter, put an anchor (equivalent to \label{chapterAndSections} in Latex) using the @chapterAndSections syntax on a separate line. Then, when you want to link to it (equivalent to \ref{chapterAndSections} in Latex), use the *@chapterAndSections* syntax. Anchors are invisible and links will be rendered as: 3.2.

3.3. Paragraphs and Framed Paragraphs

An empty line starts a new paragraph.

An annotated paragraph starts with @@ followed by a keyword such as todo and note. For example,

@@note this is a note annotation.

generates

this is a note annotation.

And,

@@todo this is a todo annotation

generates a todo annotation

this is a todo annotation

The annotation (e.g., todo and note) can be any word that is meaningful to the author. In HTML, an annotated paragraph triggers the generation of a paragraph with the annotation as the paragraph class. In LaTeX, an environment with the annotation name is generated. In HTML, you can tweak the output to make it look nice, for example with such JavaScript code:

// Wraps paragraphs with class pClass inside a div and adds an H4 element with pTitle.
function transformAnnotatedParagraphs(pClass, pTitle) {
   $("p." + pClass).wrap( "<div class='annotated-paragraph "
         + pClass + "' />" ).prepend("<h4>"+ pTitle +"</h4>");
}

transformAnnotatedParagraphs("note", "Note");
transformAnnotatedParagraphs("todo", "To do");

Above code will prepend the titles "Note" and "To do" to the @@note and @@todo paragraphs. You can make that looks nice using a little bit of CSS:

.annotated-paragraph {
   margin: 20px 0;
   padding: 15px 30px 15px 15px;
   border-left: 5px solid #eee;
}

.annotated-paragraph h4 {
   margin-top: 0;
}

.annotated-paragraph p:last-child {
   margin-bottom: 0;
}

.note {
   background-color: #f0f7fd;
   border-color: #d0e3f0;
}

.note h4 {
   color: #3a87ad;
}

.todo {
   background-color: #dff0d8;
   border-color: #d6e9c6;
}

.todo h4 {
   color: #3c763d;
}

3.4. Lists

3.4.1. Unordered Lists

-A block of lines,
-where each line starts with ==-==
-is transformed to a bulleted list

generates

A block of lines,
where each line starts with -
is transformed to a bulleted list

3.4.2. Ordered Lists

#A block of lines,
#where each line starts with ==#==
#is transformed to an ordered list

generates

A block of lines,
where each line starts with #
is transformed to an ordered list

3.4.3. Definition Lists

Definition lists (aka. description lists) are lists with labels:

;blue
:color of the sky
;red
:color of the fire

generates

blue: color of the sky
red: color of the fire

3.4.4. List Nesting

-Lists can also be nested.
-#Thus, a line starting with ==-#==
-#is an element of an unordered list that is part of an ordered list.

generates

Lists can also be nested.
1. Thus, a line starting with -#
2. is an element of a bulleted list that is part of an ordered list.

3.5. Formatting

There is some syntax for text formatting:

To make something bold, write ""bold"" (with 2 double quotes)
To make something italic, write ''italic'' (with 2 single quotes)
To make something monospaced, write ==monospaced==
To make something ~~strikethrough~~, write --strikethrough--
To make something _subscript, write @@subscript@@
To make something ^superscript, write ^^superscript^^
To make something underlined, write __underlined__

3.6. Tables

To create a table, start the lines with | and separate the elements with |. Each new line represents a new row of the table. Add a single ! to let the cell become a table heading.

|!Language |!Coolness
|Smalltalk | Hypra cool
|Java | baaad

Language	Coolness
Smalltalk	Hypra cool
Java	baaad

The contents of cells can be aligned left, centered or aligned right by using |{, || or |} respectively.

||centered||!centered header||centered
|{ left |} right || center

generates

centered	centered header	centered
left	right	center

3.7. Links

3.7.1. Internal Links and Anchors

To put an anchor (equivalent to \label in Latex), use the @anchorName syntax on a separate line. Then, when you want to link to it (equivalent to \ref in Latex), use the *@anchorName* syntax. Anchors are invisible and links will be rendered as: 3.7.1.

To create a link to an other pillar file, use the *Alias>path.pillar@anchorName*. The Alias and the anchor are optional but you will need them in some cases (for example if you have an inter-file link and you export in LaTeX, or if you have an inter-file link and you export all your file in the same html file).

3.7.2. External Links

To create links to external resources, use the *Pharo>http://pharo.org/* syntax which is rendered as Pharo. The same syntax can also represent email addresses: write *[email protected]* to get [email protected].

3.7.3. Semantic Links

Semantic links are a way to simplify links to standard websites such as Wikipedia and Youtube.

To create semantic links ressources, use the *Wikipedia Pharo>wikipedia:Pharo* syntax which is rendered as Wikipedia Pharo. To specify a language, you can use the *Wikipedia Pharo>wikipedia:Pharo|lang=en* syntax which is rendered as Wikipedia Pharo

Same for Youtube links : *Youtube Pharo>youtube:KDvNuOjdjY4*, the result is : Youtube Pharo.

3.8. Pictures

To include a picture, use the syntax +caption>file://filename|parameters+:

+Caption of the picture>file://figures/pharo-logo.png|width=50|label=pharoLogo+

generates Figure 0.2 (this reference has been generated using *@pharoLogo*).

0.2. This is the caption of the picture

3.9. Scripts

Use scripts when you want to add code blocks to your document.

[[[
foo bar
]]]

generates

foo bar

3.9.1. Script with a Label or Caption

If you want either a label (to reference the script later) or a caption (to give a nice title to the script), write the following:

[[[label=script1|caption=My script that works|language=smalltalk
self foo bar
]]]

which produces script 0.1 (this reference is produced with *@script1*).

self foo bar

0.1. My script that works

3.9.2. Syntax Highlighting

To specify the syntax a script is written in, you need to use the language parameter. For example on 0.1 we used the smalltalk value for the language parameter.

The currently supported languages are bash, css, html, http, json, javascript, pillar, sql, ston, shellcommands and smalltalk

If you don't want syntax highlighting for a particular script, specify no language as value to the language parameter.

3.9.3. Script with Line Numbers

If you need to explain a long piece of code, you may want a script to have line numbers:

[[[lineNumber=true
self foo bar.
self bar foo.
]]]

produces

1	self foo bar.
2	self bar foo.

3.9.4. Script from an External File

If you want you can also include a script from a external file. For example if you have a file `myProject.html` and you want to take the code from line 15 to line 45, instead of copy/pasting the code you can use:

[[[language=html|fromFile=myProject.html|firstLine=15|lastLine=45
]]]

The firstLine and lastLine parameters are optional.

3.9.5. Generate a Part of your Document with a Script

If you want you can also evaluate a script to generate a part of your document. For example if you write a project's documentation and want to give some metrics about its code, you can write something like this:

[[[eval=true
| packages classes |
packages := RPackageOrganizer default packages select: [ :each |
               each name includesSubstring: 'Pillar' ].
classes := packages flatCollect: [ :each | each classes ].
stream
   nextPutAll: 'The Pillar project contains:';
   lf;
   nextPutAll: '- ==';
   print: packages size;
   nextPutAll: ' packages==.';
   lf;
   nextPutAll: '- ==';
   print: classes size;
   nextPutAll: ' classes=='.
]]]

will generate:

The Pillar project contains:

29 packages.
359 classes

For example section 4.2 of this chapter is generated.

3.10. Structures

You can create structures to render all structures with the same name as the same object. Structures use the scripts syntax (see 3.9) with a particular parameter structure

[[[structure=exercise
{
  "question":"What is the answer to life, the universe and everything ?",
  "answer":"42"
}
]]]

There is two kind of structures for the moment:

exercise, rendered as a definition list
city, rendered as a table
country, rendered as a table

3.11. Raw

If you want to include raw text into a page you must enclose it between {{{ and }}}, otherwise Pillar ensures that text appears as you type it which might require transformations.

A good practice is to always specify for which kind of export the raw text must be outputted by starting the block with {{{latex: or {{{html:. For example, the following shows a formula, either using LaTeX or plain text depending on the kind of export.

{{{latex:
\begin{equation}
   \label{eq:1}
   \frac{1+\sqrt{2}}{2}
\end{equation}
}}}
{{{html:
(1+sqrt(2)) / 2
}}}

Take care: avoid terminating the verbatim text with a } as this will confuse the parser. So, don't write ~~{{{\begin{scriptsize}}}}~~ but {{{\begin{scriptsize} }}} instead.

3.12. Annotations

Annotations are the Pillar way to have extensible syntax. An annotation has this syntax:

${tag:parameter=value|parameter2=value2}$

3.12.1. InputFile Annotation

You can include a file into another pillar file. The inputFile annotation takes as parameter the path of the file relative to baseDirectory (if you don't change the base directory, it is your working directory). In this example, 2 files are included:

${inputFile:test.pillar}$

${inputFile:chapter2/chapter2.pillar}$

3.12.2. Footnotes Annotation

You can add footnotes to explain or annotate words. The footnotes annotation takes as parameter the note which will appear at the end of the document. In this example, one footnote is added.

Foo${footnote:Some Explanation for Foo}$

3.12.3. Citations

Citations are only available for LaTeX. You can add citations to your document to reference an element in a LaTeX bibliography. The cite annotationtakes as parameter the key of the reference in the bibliography.

${cite:reference}$

The exemple above wil render as cite{reference}

If you want to use other type of citations like citep or citet, please overwrite the command in your LaTeX template: renewcommand{cite}{citep}

á vérifier

3.12.4. Slide Annotation

This annotation is used to create slides structure for a beamer or a deck.js export. The parameter title is required. The label parameter can be used to reference this slide in another slide:

${slide:title=My slide|label=sld:mySlide}$

3.12.5. Columns

With Pillar you can put text and other contents in columns. To do that, you need to delimit an environment with the columns and endColumns annotations. Then you can create columns with the column annotation. The column annotation takes 1 required parameter: the width of the column. Here is an example:

${columns}$
   ${column:width=60}$
      bla
   ${column:40}$
      bla
${endColumns}$

The column annotations currently works only for the beamer, HTML and Deck.js export.

3.13. Preformatted (less used)

To create a preformatted block, begin each line with =. A preformatted block uses equally spaced text so that spacing is preserved. In general you should prefer scripts over preformatted blocks.

= this is preformatted text
= this line as well

3.14. Commented Lines

Lines that start with a % are considered comments and will not be rendered in the resulting document.

3.15. Escaping Characters

Special characters (e.g., + and *) must be escaped with a backslash: to get a +, you actually have to write \+. The list of characters to escape is:

^, _, :, ;, =, @, {, |, !, ", #, $, %, ', *, +, [, -

4. Configuring your Output

In this section we show how to configure the export.

4.1. Configuration File

Pillar exporting mechanism can be configured using STON (see chapter @ston), a lightweight, text-based, human-readable data interchange format (similar to the popular JSON). Configuration is done either in pillar.conf or at the beginning of Pillar files.

4.2. Configuration Parameters

baseDirectory

Indicate where to look for files.

Default value: The current working directory

configurations

Each configuration can define several sub configurations, each of which inherits the properties of its parent.

Default value: A dictionary of default configurations from the exporters.

defaultExporters

Collection of exporters to use when none is explicitely specified. You can specify the exporter you want through the --to= command-line argument.

Default value: By default only the text exporter is enabled.

defaultScriptLanguage

Indicate the language in scripts when none is specified. This language is used for syntax highlighting. The currently supported languages are bash, css, html, http, json, javascript, pillar, sql, ston, shellcommands and smalltalk.

Default value: An unspecified language

disabledPhases

Collection of phases that Pillar should ignore.

For exemple, a value of ["scriptEvaluator", "section", "transform"] will disable script evaluation (useful when security is important), sectioning (useful when generating HTML 4) and the transform phases (i.e. all the transformers) .

Default value: By default the collection is empty, i.e., all phases are active.

headingLevelOffset

Indicate how to convert from the level of a Pillar heading to the level of heading in your exported document. For example, a headingLevelOffset of 3 converts a 1st level Pillar heading to an <h4> in HTML.

Default value: 0

inputFile

The Pillar file that must be exported. You can also specify an input file at the end of the command-line interface.

Default value: nil

level1

Configure how headers at level 1 will be rendered. Value must be a dictionnary. These keys are recognized:

numbering: a boolean indicating if headers at this level must be numbered
size: a positive number indicating how many parent levels should be visible in the number: e.g., if 2, the parent header's number and the current header's number will be shown (must be lower than or equal to 1)
renderAs: a string indicating how the numbering is done (must be one of "number", "roman", "letter" or "upperLetter")