Pillar.pillar

{
    "metadata" : {
        "title": "Documenting and Presenting with Pillar",
        "attribution": "Damien Cassou, Cyril Ferlicot Delbecque, Yann Dubois and Thibault Arloing"
    },
    "headingLevelOffset":2
}
@cha:pillar


This chapter describes Pillar version 4.0. It may be work with Pillar 5.0 and 6.0. The current version of Pillar is Pillar 7.0. An up to date documentation is available at *http://books.pharo.org*.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>http://www.esug.org*.


!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 *@voyageDocExample* shows the HTML version of chapter *@cha:voyage*.

+An example Pillar output>file://figures/voyageDocExample-small.png|label=voyageDocExample|width=60+

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 *@cha:ston*) and Mustache templates (see chapter *@cha:mustache*).
- many tests with good coverage (94% with more than a 2100 executed tests), which are regularly run by a *continuous integration job>https://ci.inria.fr/pharo-contribution/job/Pillar*
- a command-line interface and dedicated plugins for several text editors: *Emacs>https://github.com/pillar-markup/pillar-mode*, *Vim>https://github.com/cdlm/vim-pillar*, *TextMate>https://github.com/Uko/Pillar.tmbundle*, and *Atom>https://github.com/Uko/language-pillar*
- a *cheat sheet>http://pillarhub.pharocloud.com/hub/pillarhub/pillarcheatsheet*


!!Pillar Users
@pillarUSERS

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*).


!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.

[[[language=bash
mkdir mydocument
cd mydocument
]]]

!!Installing and Exporting your First Document

The use of pillar is possible on all platform supported by Pharo. In fact Pillar is executed on top of Pharo 

so you can use Pillar on Linux, MacOSX, Windows.


!!!Pillar installation on Windows

Windows is not able to deals with .sh and makefile script natively, so we have to install Pillar manually or install *https://www.cygwin.com/* which provides functionality similar to a Linux distribution.

If you decide to install cygwin you should be able to follow the Mac OS X / Linux installation section otherwise you can follow the next steps.


If you don't have Pharo you can get it here : *http://files.pharo.org/platform/Pharo5.0-win.zip*

Then download and extract the content of Pillar-deployment.zip in the Pharo directory.

*https://ci.inria.fr/pharo-contribution/job/Pillar/PHARO=50,VERSION=stable,VM=vm/lastSuccessfulBuild/artifact/Pillar-deployment.zip*


-Let's create an html document example :

Create for instance welcome.pillar file. You can place it in your Pharo directory and fill in this code example
[[[
{
	"metadata": {
			"title":"My first document while reading the 5 minutes Pillar tutorial"
	},
	"outputDirectory" : "book-result"
}
!Hello World
]]]

We would like pillar to generate a json file which will be used by a generation template.
Maj + right click in the Pharo directory and open a terminal and paste this command to generate the json file.

[[[
Pharo.exe Pillar.image pillar export --to=html --outputFile=welcome welcome.pillar
]]]

This command starts Pharo with Pillar image and trigger the pillar handler. Then it specifies the exportation as html and the output file as welcome. The .html.json will be appended automatically to the end of the filename so welcome.pillar.json will be created and placed in book-result folder (you can specify the outputDirectory in the command or in the .pillar file and this is the same for other attributes like outputFile).
The last argument is the path of the input file.

Then we have to create a template, for instance let's create welcome.html.template in the Pharo directory and fill in this template example :
[[[
<!DOCTYPE html>
<html lang="en">
	<head>
		<title>{{{title}}}</title>
	</head>

	<body>
		<div class="container">
			{{{content}}}
		</div>
	</body>
</html>
]]]

This latest command let us make the html document thanks by the json and template files.
Each attribute in the template will be replaced by its value in the json file.

[[[
Pharo.exe Pillar.image mustache --data=book-result/welcome.html.json --template=welcome.html.template
]]]

You can check the result in the stdout file which is placed in the Pharo directory

-Exportation in latex
The procedure is the same with other kind of document. This is an another example with latex

In this example we show how to add a bibliography and how to export the result as pdf with pdflatex provided by (MiKTeX distribution)

Let's set some attributes (title, content) in testLatex.pillar for instance

[[[
{
    "metadata": {
      "title":"My latex bibliography test with Pillar !"
    }
}

my bibliography test
{{{latex: \bibliographystyle{abbrv}
\bibliography{rmod}
}}}
]]]

We create testLatex.tex.json with the following command

[[[
Pharo.exe Pillar.image pillar export --to=latex --outputFile=testLatex testLatex.pillar
]]]

Then, let's create the template in testLatex.latex.template file for instance

[[[
\documentclass{article}

\begin{document}

Cite : first \cite{ref}, second \cite{ref2}, third \cite{ref3}.

{{{content}}}

\end{document}
]]]

We generate the document in the stdout file with the following command

[[[
Pharo.exe Pillar.image mustache --data=testLatex.tex.json --template=testLatex.latex.template
]]]

Create a bibliography if it doesn't exists and place it in the Pharo directory. In our example this is rmod.bib file

Then, link the bibliography with the latex document
[[[
bibtex stdout
]]]

Create your pdf
[[[
pdflatex stdout
]]]


!!!Pillar installation on Mac OS X / Linux

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.


[[[language=bash
wget https://raw.githubusercontent.com/pillar-markup/pillar/master/download.sh
chmod +x download.sh
./download.sh
]]]


[[[language=bash
wget https://raw.githubusercontent.com/pillar-markup/pillar/master/download.sh
bash download.sh
]]]

[[[language=bash
curl https://raw.githubusercontent.com/pillar-markup/pillar/master/download.sh | bash
]]]



Then, you can load an archetype (see Section *@archetypes*) with command:

[[[language=bash
./pillar archetype welcome
]]]

Now you can just compile the welcome file

[[[
make build/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>
]]]


!!! Creating a first page
You can create a first page naemd ==first.pillar== file with this content:

[[[language=pillar
!Hello World
]]]

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

[[[language=bash
make build/first.html
]]]

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

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

!!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:

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

!Hello World
]]]

When you compile using the same command line,

[[[language=bash
make build/first.html
]]]

you should now get a web page with a title:

[[[language=html
<!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 *@configuring* for more information about the configuration file). Create your
first ==pillar.conf== file:

[[[language=ston
{
   "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==.

!!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
*@templating* for more information about templating). You must write such template in its own file, e.g., ==myhtml.template==:

[[[language=html
<!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==:

[[[language=bash
HTMLTEMPLATE = myhtml.template
]]]

Now, write your name in ==first.pillar== :

[[[language=pillar
{
   "metadata":{
     "author": "Damien Cassou"
    }
}

!Hello World
]]]

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

[[[language=ston
{
  "metadata":{
    "title":"My first document from pillar.conf",
    "year":"2016"
  }
}
]]]

Finally, compile ==first.pillar== one last time

[[[language=bash
make book-result/first.html
]]]

to generate a file containing:

[[[language=html
<!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 *@cha:mustache*. 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.

@archetypes

!!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 :

[[[language=bash
./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>https://github.com/pillar-markup/Pillar-Archetype*.

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

!Writing Pillar Documents

@writing

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>http://pillarhub.pharocloud.com/hub/pillarhub/pillarcheatsheet* and even download and print it.

!!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 *@cha:ston*).
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,

[[[language=pillar
{
   "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
*@templating* for more information about templating). Only keys in the ==metadata== field can be referenced in the template.

!!Chapters & Sections

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

@chapterAndSections

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: *@chapterAndSections*.

!!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,

[[[language=pillar
@@note this is a note annotation.
]]]

generates

@@note this is a note annotation.

And,

[[[language=pillar
@@todo this is a todo annotation
]]]

generates a todo annotation

@@todo 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:

[[[language=javascript
// 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:

[[[language=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;
}
]]]

!!Lists

!!!Unordered Lists

[[[language=pillar
-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

!!!Ordered Lists

[[[language=pillar
#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

!!!Definition Lists

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

[[[language=pillar
;blue
:color of the sky
;red
:color of the fire
]]]

generates

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

!!!List Nesting

[[[language=pillar
-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.
-#Thus, a line starting with ==-#==
-#is an element of a bulleted list that is part of an ordered list.

!!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\__==

!!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=pillar
|!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.

[[[language=pillar
||centered||!centered header||centered
|{ left |} right || center
]]]

generates

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

!!Links

!!!Internal Links and Anchors
@anchorName

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: *@anchorName*.

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).

!!!External Links

To create links to external resources, use the ==\*Pharo>http://pharo.org/\*== syntax which is rendered as *Pharo>http://pharo.org/*. The same syntax can also represent email addresses: write ==\*damien@cassou.me\*== to get *damien@cassou.me*.

!!!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>wikipedia:Pharo*.
To specify a language, you can use the ==\*Wikipedia Pharo>wikipedia:Pharo|lang=en\*== syntax which is rendered as *Wikipedia Pharo>wikipedia:Pharo|lang=en*

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

!!Pictures

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

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

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

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

!!Scripts
@scripts

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

= [[[
= foo bar
= ]]]

generates

[[[
foo bar
]]]

!!! 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 *@script1* (this reference is produced with ==\*@script1\*==).

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

!!! Syntax Highlighting
@sec:syntaxHighlighting

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

[[[eval=true
| languages |
stream nextPutAll: '@@note The currently supported languages are '.
languages := PRRealScriptLanguage withAllConcreteClasses collect: #standardName.
languages asStringOn: stream delimiter: ', ' last: ' and '
]]]

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

!!! 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

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

!!! 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.

!!! 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:

[[[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=='.
]]]

For example section *@configParameters* of this chapter is generated.

!!Structures

You can create structures to render all structures with the same name as the same object.
Structures use the scripts syntax (see *@scripts*) 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

!!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. Here is an example of how you can add a LaTeX equation to your Pillar document:

= {{{
= \begin{equation}
=    \label{eq:1}
=    \frac{1+\sqrt{2}}{2}
= \end{equation}
= }}}

""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.

!!Annotations

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

[[[language=pillar
${tag:parameter=value|parameter2=value2}$
]]]

!!! 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:

[[[language=pillar
${inputFile:test.pillar}$

${inputFile:chapter2/chapter2.pillar}$
]]]

!!! 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:note=Some Explanation for Foo}$
]]]

@@note Support for footnotes is not activated by default. You must add a ''"PRFootnoteTransformer"'' plugin to your ==pillar.conf== file. See Section *@sec:Citations* for example.

!!!Citations
@sec: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}==

@@note Support for citations is not activated by default. You must add a ''"PRCitationTransformer"'' plugin to your ==pillar.conf== file:

[[[
{
    "title": "Your Awesome Title",
    "attribution": "John Doe and Jane Doe",
    "series": "Square Bracket tutorials",
    "keywords": "Nice Keyword, Catchy Keyword",
    "newLine": #unix,
    "latexWriter": #'latex:sbabook',
    "plugins": [
      "PRCitationTransformer",
      "PRFootnoteTransformer"],
    "bibFile": "others.bib",
    "htmlWriter": #html 
}
]]]

@@todo á vérifier

!!! Slide Annotation
@sec:slide

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:

[[[language=pillar
${slide:title=My slide|label=sld:mySlide}$
]]]

!!! 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:

[[[language=pillar
${columns}$
   ${column:width=60}$
      bla
   ${column:40}$
      bla
${endColumns}$
]]]

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

!!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

!!Commented Lines

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

!!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:

[[[eval=true
| characters |
characters := (PRPillarGrammar markups inject: Set new into: [ :chars :markup | chars addAll: markup. chars]) copyWithout: Character space.
stream nextPutAll: '[[['; cr.
characters do: [:char | stream nextPut: char] separatedBy: [ stream nextPutAll: ', ' ].
stream cr; nextPutAll: ']]]'; cr.
]]]

! Configuring your Output
@configuring

In this section we show how to configure the export.

!! Configuration File

Pillar exporting mechanism can be configured using *STON>http://smalltalkhub.com/#!/~SvenVanCaekenberghe/STON* (see chapter @ston), a lightweight, text-based, human-readable data
interchange format (similar to the popular *JSON>http://www.json.org*). Configuration is done either in ==pillar.conf== or at the beginning of Pillar files.

!! Configuration Parameters
@configParameters

[[[eval=true
CCDocumentationGeneration of: PRPillarConfiguration on: stream.
]]]

! Templating
@templating

Pillar generates json as output so you can use a templating engine to tweak Pillar output. Pillar comes with the Mustache templating engine (see chapter *@cha:mustache*).
This means you can specify a preamble and postamble for your document. Here is an example HTML template using Mustache:

[[[language=html
<!DOCTYPE html>
<html lang="en">
   <head>
      <title>{{{title}}}</title>
   </head>
   <body>
      <div class="container">
         {{{content}}}
      </div>
   </body>
</html>
]]]

In this example, we can see the use of ==\{\{\{title\}\}\}== and ==\{\{\{content\}\}\}== to refer to the title of the document and its actual content (the one
exported from Pillar). You have to put such a template in a dedicated file (named ==chapter.html.template== for example) and reference this file from the
==HTMLTEMPLATE== variable in the ==Makefile==. Then when you will compile in HTML, the ==Makefile== will use this template.

You can also use ==mustache== alone with command:

[[[language=bash
./mustache --data=file.html.json --template=myhtml.template > file.html
]]]

! Command-Line Interface
@commandLineInterface

In this section we show how to use the Pillar command-line interface.

One of the basic uses of the command line is:

[[[language=bash
$ ./pillar export --to=latex PharoSound.pillar
]]]

[[[eval=true
stream nextPutAll: 'You can select an export type with the parameter ==-\-to==. The possible exports are: '.
(PRDocumentWriter withAllConcreteClasses collect: #writerName) asStringOn: stream delimiter: ', ' last: ' and '.
stream nextPutAll: '.'
]]]

The ==Makefile== will create a symbolic link named ==root== referencing the output directory into each directory containing output files.
You can use this symbolic link to reference files in specified in the ==support== collection.

! Pillar from Pharo

Pillar has a document model (the root of which being ==PRDocument==), a parser (==PRPillarParser==) and several export types (subclasses of ==PRDocumentWriter==) implemented as visitors over the document model.
Pillar also has phases (subclasses of ==PRPhase==) that take a document model as input and produce a modified document model as output.

!! How to Create a Pillar Document

It is possible to create a Pillar document by parsing a string or by instantiating the document model.

Creating a document by parsing a ==String== requires using the ==PRPillarParser==:

[[[
| wiki |
wiki := '!My Document'.
PRPillarParser parse: wiki
]]]

Or from a file:
[[[
PRPillarParser parse: (FileSystem workingDirectory / 'foo.pillar') readStream
]]]

You can also instantiate the document model, one node after the other, starting with ==PRDocument== and adding sub-instances of ==PRDocumentItem==:

[[[
| document title figure|
document := PRDocument new.
title := PRHeader new
   level: 1;
   add: (PRText content: 'foo');
   yourself.
figure := PRFigure new
   add: (PRText content: 'Alias');
   reference: 'file://test.png';
   yourself.
document add: title; add: figure.
]]]

!! How to Export a Document

Once you have your document, you may want to export it. But exporting, there's an optional step: transforming your document.
A transformer is an abstraction that visits a document and changes it. For instance, ==PRScriptEvaluator== replaces a script with ==eval=true==
 by the result of its evaluation. Exporting is done with a subclass of ==PRDocumentWriter==, like this:

[[[
PRHTMLWriter write: document
]]]

To specify export parameters (see above for a comprehensive list), you may want to use a configuration.

[[[
| configuration |
configuration := PRPillarConfiguration new.
configuration outputType: PRHTMLWriter.
PRExportPhase executeOn: { document } with: configuration.
]]]

! Conclusion

Pillar is still in active development because authors keep writing new documents. Because Pillar's source code is of great quality (mainly due to Lukas Renggli), features can be added easily by new developers. Pillar is different from competition thanks to its notion of project that allows managing multiple files coherently.

% Local Variables:
% compile-command: "cd .. && ./pillar export --to=\"LaTeX by chapter\" PillarChap/Pillar.pillar && bash pillarPostExport.sh"
% End: