Pillar update (for broken links)

Pillar.pillar

{{title: Pillar}}

!Documenting your Project with Pillar

!!Introduction

*Pillar>http://www.smalltalkhub.com/#!/~Pier/Pillar* is a markup syntax and associated tools to write and generate documentation and books. Pillar is currently used to write the *Enterprise Pharo book>https://ci.inria.fr/pharo-contribution/job/PharoForTheEnterprise* and other projects (see Section *pillarUSERS*). The Pillar screenshot below (see Figure *voyageDocExample*) shows a part of the *Voyage documentation>https://github.com/SquareBracketAssociates/PharoForTheEnterprise-english/blob/master/MigratedToOtherPlaces/Voyage/Voyage.pier* generated by Pillar.

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

Pillar has many features:
- simple markup syntax with references, tables, pictures, captions...);
- export to HTML, LaTeX, Markdown and Pillar itself;
- customization of the export through a dedicated *STON>http://smalltalkhub.com/#!/~SvenVanCaekenberghe/STON* configuration file;
- support of templates using the *Mustache>http://smalltalkhub.com/#!/~NorbertHartl/Mustache* templating engine;
- syntax-highlighting of generated code blocks (not yet in LaTeX);
- configurable numbering of section titles and figures;
- ...

Pillar has also:
- a 5-minutes tutorial
- a documentation (in progress)
- a good test coverage (95% with more than a 1150 executed tests)
- a *continuous integration job>https://ci.inria.fr/pharo-contribution/job/Pillar*
- a command-line interface
- several existing use cases (see Section *pillarUSERS*)
- a *cheat sheet>http://pillarhub.pharocloud.com/hub/pillarhub/pillarcheatsheet*


The original author of Pillar and current main contributor is *Damien Cassou>http://damiencassou.seasidehosting.st*.

The past contributors are Ben Coman, Stéphane Ducasse, Guillermo Polito, Lukas Renggli (original author of Pier from which Pillar has been extracted) and Benjamin van Ryseghem.

+This project is sponsored by ESUG: *http://www.esug.org*>file://figures/esug-logo.jpg|width=20|label=esugsponsoring+


!!!Editors

These editors have dedicated plugins for Pillar:

- *Emacs>https://github.com/pillar-markup/pillar-mode*
- *Vim>https://github.com/cdlm/vim-pillar*
- *TextMate>https://github.com/Uko/Pillar.tmbundle*
- *Atom>https://github.com/Uko/language-pillar*

!!!Pillar users

@pillarUSERS

Pillar is used in several projects. You can have a look at these projects for real use cases of Pillar.

- *the Enterprise Pharo book>https://ci.inria.fr/pharo-contribution/job/PharoForTheEnterprise/*
- *the Updated Pharo by Example>https://github.com/SquareBracketAssociates/UpdatedPharoByExample*
- *the Pharo Laser Game Tutorial>https://github.com/SquareBracketAssociates/PharoLaserGameTutorial*
- *the Pharo Web Stack>https://github.com/SquareBracketAssociates/PharoWebStack*
- *the Marina CMS>https://github.com/tide-framework/marina*
- *the PillarHub open-access shared blog>http://pillarhub.pharocloud.com*
- *the Pier CMS>http://piercms.com*
- *the Pillar documentation itself>https://ci.inria.fr/pharo-contribution/job/EnterprisePharoBook/lastSuccessfulBuild/artifact/PillarChap/*
- *the Spec documentation>https://github.com/SpecForPharo/documentation*
- *the Pharo sound tutorial>https://github.com/xmessner/PharoSoundTutorial*

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

You first need to get Pillar. For that, I recommend *downloading executing this script>https://raw.githubusercontent.com/pillar-markup/book-skeleton/master/download.sh* in the base directory.

Then, you can check everything is working fine by creating a ==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
./pillar export --to='html' 'first.pillar' > first.html
]]]

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

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

!!!Configuring a document

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

[[[language=pillar
{{title: My first document while reading the 5 minutes Pillar tutorial}}
!Hello World
]]]

When you compile using the same command line,

[[[language=bash
./pillar export --to=html first.pillar > 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>http://smalltalkhub.com/#!/~SvenVanCaekenberghe/STON* format (see Section *configuring* for more information about the configuration file). Create your first ==pillar.conf== file:

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

Meta-information specified in Pillar files take precedence over configuration in the ==pillar.conf== file.

!!!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, you need to reference this template from your configuration file. So, edit your ==pillar.conf== configuration file:

[[[language=ston
{
   "year" : 2014,
    "configurations" : {
        "html" : {
            "template" : "myhtml.template",
            "outputType" : #html
        }
     }
}
]]]

Now, add your name to ==first.pillar== :

[[[language=pillar
{{title: My first document while reading the 5 minutes Pillar tutorial}}
{{author: Damien Cassou}}
!Hello World
]]]

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

[[[language=bash
./pillar export --to=html first.pillar > first.html
]]]

to generate a ==first.html== that will contain:

[[[language=html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My first document while reading the 5 minutes Pillar tutorial</title>
  </head>
  <body>
    <div class="container">
      <h1>Hello World</h1>
    </div>
    <footer>
      <p>Damien Cassou, 2014</p>
    </footer>
  </body>
</html>
]]]

Look at how the HTML template references ==title==, ==author== and ==year==. This variables are referenced by enclosing them in 3 curly braces. The templating engine that transforms your templates in documents is *Mustache>http://smalltalkhub.com/#!/~NorbertHartl/Mustache*. As you can see, I decided to put the author and title of the document in the ==first.pillar== file whereas the year is specified in ==pillar.conf==: this is arbitrary and you can do whatever suits you best, the only difference being that the ==pillar.conf== file applies to all Pillar files of the project.

This concludes our 5 minutes tutorial.

!!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://www.cheatography.com/benjaminvanryseghem/cheat-sheets/pillar* and even download and print it.

!!!Meta-information

Meta-information of a particular file is written at the start of the file between 2 curly braces. A meta-information starts with a word acting as a key, is followed by a colon ==:==, and finishes with a string acting as the value. For example, the following file,

[[[language=pillar
{{title: My first document while reading the 5 minutes Pillar tutorial}}
{{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). As of today, the only meaningful key is ==next== which references the next pillar file in a sequence: this is useful to present a ==next== link to navigate between pages in a project. This ==next== meta-information is automatically filled by the system so you can just use it in your template: the default order comes from the ==inputFiles== configuration parameter of the ==pillar.conf== file. You can override it in your own document as any other meta-information.

!!!Chapters & Sections

A line starting with ==!== becomes a chapter 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 a line with ==\@@== followed by either ==todo== or ==note==. For example,

[[[
@@note this is a note annotation.
]]]

generates

@@note this is a note annotation.

And,

[[[
@@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, annotated paragraphs 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

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

[[[
#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:

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

generates

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

!!!!List nesting

[[[
-Lists can also be nested.
-#Thus, a line starting with ==-#==
-#is an element of a bulleted 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 sugar for font 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 off the lines with ==|== and separate the elements with ==|==s. 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||centered
|{ left |} right || center
]]]

generates

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

!!!!External Links

To create links to externals resources, use the ==\*Pharo>http://pharo-project.org/\*== syntax which is rendered as *Pharo>http://pharo-project.org/*.

!!!Pictures

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

[[[
+Caption of the picture>file://figures/pier-logo.png|width=50|label=pierLogo+
]]]

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

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

!!!Scripts

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

= [[[
=     foo bar
= ]]]

generates

[[[
foo bar
]]]

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

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

This script can then be referenced with ==\*script1\*== (produces *script1*). Specifying the language (here ==Smalltalk==) will give you syntax highlighting.

!!!Raw

If you want to include raw text into a page you must enclose it in =={{{== and ==}}}==, otherwise Pier ensures that text appears as you type it.

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 now only LaTeX, HTML and Markdown are supported). For example, the following shows a formula, either using LaTeX or an image depending on the kind of export.

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


This results in

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

!!!Preformatted (less used)

To create a preformatted block, begin each line with ==\===. A preformatted block uses equally spaced text so that spacing is preserved.

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

!! Configuring your output

@configuring

In this section we show how to configure the export from the Pillar files.

!!! Configuration file

Pillar exporting mechanism can be configured using *STON>http://smalltalkhub.com/#!/~SvenVanCaekenberghe/STON*, a lightweight, text-based, human-readable data interchange format (similar to the popular *JSON>http://www.json.org*.

!!! Configuration parameters

[[[language=Smalltalk|eval=true
| writeConfigurationParameter |
writeConfigurationParameter := [: pragma | | methodWithDefaultValue methodComment |
methodComment := [ :aMethod |
    aMethod comment
        ifNil: [ 'uncommented' ]
        ifNotNil: [ :comment | comment trimBoth: [ :c | c = $" ] ] ].
methodWithDefaultValue := pragma methodClass >> (#default , pragma selector capitalized) asSymbol.
stream
    nextPutAll: '!!!! ' , pragma selector;
    lf;
    nextPutAll: '@sec:confParam:', pragma selector;
    lf;
    nextPutAll: (methodComment value: pragma method);
    lf;
    lf;
    nextPutAll: ';Default value';
    lf;
    nextPutAll: ':';
    nextPutAll:
            (methodWithDefaultValue comment
                    ifNotNil: [ methodComment value: methodWithDefaultValue ]
                    ifNil: [
                        methodWithDefaultValue isQuick
                            ifTrue: [ '==', methodWithDefaultValue ast statements first value formattedCode, '==' ]
                            ifFalse: [ 'uncommented' ] ]);
    lf;
    lf
    ].

((Pragma allNamed: #pillarConfigurationParameter in: PRExportConfiguration) sort: [ :p1 :p2 | p1 selector < p2 selector ])
        do: [ :pragma | writeConfigurationParameter value: pragma ]

]]]

!! Templating
@templating

Pillar comes with the *Mustache>http://smalltalkhub.com/#!/~NorbertHartl/Mustache* templating engine. This means you can specify a preamble and postamble for your document. Here is an example (bootrap-based) HTML template using Mustache:

[[[language=html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>{{{title}}}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
    <link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.3/css/bootstrap-theme.min.css" rel="stylesheet">
    <link rel="stylesheet" href="http://yandex.st/highlightjs/8.0/styles/default.min.css">
    <script src="http://yandex.st/highlightjs/8.0/highlight.min.js"></script>

    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
    <![endif]-->
  </head>
  <body>

    <div class="container">
      {{{content}}}
    </div>

    <script src="https://code.jquery.com/jquery.js"></script>
    <script src="http://netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
  </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 template configuration parameter (see *sec:confParam:template*).

!! Command-line interface
@commandLineInterface

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

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