Pillar: One Format to Rule them All
First Name: Cyril
Last Name: Ferlicot
Type: Talk
Video: https://www.youtube.com/watch?v=3EdSENvCmjg
Abstract: 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, the Updated Pharo by Example book, and many other
texts. 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 configuration file;
- support of templates using the Mustache templating engine;
- syntax-highlighting of generated code blocks;
- configurable numbering of section titles and figures;
- ...
Bio: Cyril Ferlicot-Delbecque is a student at the French University of Lille 1. He follows a course to get a Master’s degree in Business Informatics. He is currently doing an internship in the RMoD research group at INRIA Lille and he is working on Pillar.
Damien Cassou received his PhD degree in Computer Science from the
University of Bordeaux, France. He is working as associate professor
(maître de conférences) at the University of Lille, France, and is a
member of the RMod research group (Inria, CRIStAL). He is currently working on dynamic programming languages (most notably around traits and modules) and software engineering (mainly tools for developers). Damien has co-organized many events (including ECOOP'14 and several ESUGs), wrote several books, and is an active member of the Smalltalk and Emacs-Lisp communities.
3. Problem
We want more documentation
We want many formats
pdf
html
epub
We do not want to rewrite everything
We want it simple
If you want them to RTFM,
make a better FM.
What is Pillar ? 3
6. Our Solution: Pillar
One input, many outputs
HTML
LaTeX
Text
Markdown
Textual syntax
No need for a specific editor
!Example
This is an example of a Pillar file.
*Link>http://www.smalltalkhub.com/*
- Unordered Item
- Unordered Item
# Ordered Item
# Ordered Item
|!Language |!Coolness
|Smalltalk | Hypra cool
|Java | baaad
+ Figure !>file://path.png|width=80+
What is Pillar ? 6
7. Our Solution: Pillar
Extracted from Pier
Now Pier needs Pillar
!Example
This is an example of a Pillar file.
*Link>http://www.smalltalkhub.com/*
- Unordered Item
- Unordered Item
# Ordered Item
# Ordered Item
|!Language |!Coolness
|Smalltalk | Hypra cool
|Java | baaad
+ Figure !>file://path.png|width=80+
What is Pillar ? 7
15. Ecstatic: Static Websites
!Ecstatic
Ecstatic is a static web-site generator engine written entirely in
+Pharo>http://www.pharo.org+.
The Ecstatic engine generates html from the markup language Pillar.
Ecstatic is based on the following principles:
- Ease of use
- Fast feedback
- Extensible
+Getting started>getting_started.pillar+
Current Uses http://pillarhub.pharocloud.com/ 15
17. Ecstatic: Static Websites
Created by Guillermo Polito and Stephane
Ducasse
Generate static website with Pillar
Many templates
Examples
Ecstatic (guillep.github.io/ecstatic)
Current Uses http://pillarhub.pharocloud.com/ 17
18. Ecstatic: Static Websites
Created by Guillermo Polito and Stephane
Ducasse
Generate static website with Pillar
Many templates
Examples
Ecstatic (guillep.github.io/ecstatic)
DBXTalk (guillep.github.io/DBXTalk)
Current Uses http://pillarhub.pharocloud.com/ 18
19. Ecstatic: Static Websites
Created by Guillermo Polito and Stephane
Ducasse
Generate static website with Pillar
Many templates
Examples
Ecstatic (guillep.github.io/ecstatic)
DBXTalk (guillep.github.io/DBXTalk)
Personal pages as tinchodias.github.io
Current Uses http://pillarhub.pharocloud.com/ 19
24. Use Your Own Templates
One default template by exporter
Possibility to create your own template
Possibility to use meta-data in the
template
’<!DOCTYPE html>
<html lang="en">
<head>
<title>{{{title}}}</title>
<link rel="stylesheet" href="http://yandex.st/
highlightjs/8.0/styles/default.min.css">
</head>
<body>
<h1>{{{subtitle}}}</h1>
<div class="container">
{{{content}}}
</div>
</body>
</html>’
Begin a Documentation with Pillar 24
25. Configuration: pillar.conf
Configure your exports with a simple file
STON syntax
Can contain
Export configuration
Sub configurations
Meta-data
’{
"inputFiles": [ "Pillar.pillar" ],
"outputFile": "Pillar.tex",
"author":"Damien Cassou, Cyril Ferlicot",
"title": "Pillar",
"configurations": {
"beamer":{
"template" : "slides.beamer.template",
}
"beamer2":{
"outputType": #beamer,
"template":"slides.beamer2.template"
}
}
}’
Begin a Documentation with Pillar 25
26. Text Editor Plugins
You can find Pillar
plugin for:
Emacs
Vim
TextMate
Atom
Begin a Documentation with Pillar 26
27. Text Editor Plugins
You can find Pillar
plugin for:
Emacs
Vim
TextMate
Atom
Begin a Documentation with Pillar 27
32. Phases System
PRCreationPhase PRParsingPhase PRTransformingPhase
transformerScriptEvaluator
transformerSection
PRExportingPhase
nil
A collection of
input files
A collection of
PRDocuments
A collection of
transformed PRDocuments
Exported files
How Pillar Works 32
34. Adding an Exporter
Write a format from a document model
Just write a visitor for the document
Check your exporter with tests
Easy Extension 34
35. Adding an Annotation
Syntax extension point
Can take parameters
Describe your parameters with
Magritte
Work well with transformers
Examples:
Include a Pillar file
${inputFile:folder/file.pillar}$
Define boundaries of a Slide
${slide:title=title of the slide}$
Divide into columns
${column:width=50}$
Easy Extension 35
41. Adding a Transformer
PRNodeTransformer subclass: #PRFileInclusion
instanceVariableNames: ’’
classVariableNames: ’’
category: ’Pillar−Model−Transformer’
PRFileInclusion>>#visitInputFileAnnotation: anInputFileAnnotation
"I load the file and if the file exist I replace the node of the annotation by the content of the file."
| file |
file := anInputFileAnnotation fileWithConfiguration: self configuration.
file exists
ifTrue: [ self replace: (anInputFileAnnotation parseFile: file withConfiguration: self configuration) children ]
ifFalse: [ anInputFileAnnotation errorFileNotFound: file ]
Easy Extension 41
42. Adding a Transformer
You can:
Define a priority
Define a keyword to disable a transformer
Generate documentation of the transformer
PRTransformingPhase>>#transformerInputFileOn: aCollection
<pillarTransformer: 1 key: ’fileInclusion’ documentation:
’I visit a document and transform an ==inputFile== annotation into the content of the file.’>
aCollection
do: [ :each |
PRFileInclusion new
configuration: self configuration;
start: each ]
Easy Extension 42
44. Conclusion
One Format to Rule Them All
Easy to extends
Future Work
Improve the Pharo renderer
An Epub and a DocBook exporter
would be great.
We have a large TODO list
Conclusion 44
47. Sequence Diagram
a PRHTMLWriter a PRHeader a PRText a PRScript
accept: self
start: aDocument
visit: aDocument
visitDocument: aDocument
visitDocumentGroup: aDocument
visitHeader: self
accept: self
Ici le titre commence
à s'écrire.
visitText: self
Ici le contenu du
titre s'écrit
Puis il écrit la fin
du titre
accept: self
visitScript: self
Ici le script s'écrit
a PRDocument
children
PRItem Collection
Annexes 47
