Pillar: One Format to Rule them All

PillarOne Format to Rule Them All!

Cyril Ferlicot-Delbecque, Damien Cassou

http://www.smalltalkhub.com/#!/~Pier/Pillar

1

What is Pillar ?

What is Pillar ? 2

Problem

We want more documentationWe want many formats

I pdfI htmlI epub

We do not want to rewrite everythingWe want it simple

If you want them to RTFM,make a better FM.

What is Pillar ? 3

Currently

LaTeXI ComplicatedI Hard to find an errorI Hard to convert in HTML

MarkdownI IncompleteI Incompatible implementation

What is Pillar ? 4

Currently

LaTeXI ComplicatedI Hard to find an errorI Hard to convert in HTML

MarkdownI IncompleteI Incompatible implementations

What is Pillar ? 5

Our Solution: Pillar

One input, many outputsI HTMLI LaTeXI TextI Markdown

Textual syntaxI No need for a specific editor

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

Our Solution: Pillar

Extracted from Pier

Now Pier needs Pillar

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

Current Uses

Current Uses 8

PillarHub by Mike Filonov.

Current Uses 9

http://pillarhub.pharocloud.com/

Current Uses http://pillarhub.pharocloud.com/ 10

Books


Current Books

Updated Pharo by ExamplePharo for the Enterprise


Presentations


Presentations

This presentation itself is written in Pillar.


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+



Created by Guillermo Polito and StephaneDucasseGenerate static website with PillarMany templatesExamples

I Ecstatic (guillep.github.io/ecstatic)I

I


http://guillep.github.io/ecstatic



I Ecstatic (guillep.github.io/ecstatic)I DBXTalk (guillep.github.io/DBXTalk)I



http://guillep.github.io/DBXTalk



I Ecstatic (guillep.github.io/ecstatic)I DBXTalk (guillep.github.io/DBXTalk)I Personal pages as tinchodias.github.io



http://guillep.github.io/DBXTalk

http://tinchodias.github.io


Current Uses http://guillep.github.io/ecstatic 20

Documentation renderer

Prototype by Kasper Osterbye

Current Uses http://guillep.github.io/ecstatic 21

Begin a Documentation with Pillar

Begin a Documentation with Pillar 22

Simple Example

1 https://raw.githubusercontent.com/pillar-markup/book-skeleton/master/download.sh

2 echo "!Hello World" > Example.pillar3 ./pillar export - -to=html - -outputFile=Example.html Example.pillar


https://raw.githubusercontent.com/pillar-markup/book-skeleton/master/download.sh

https://raw.githubusercontent.com/pillar-markup/book-skeleton/master/download.sh

Use Your Own Templates

One default template by exporterPossibility to create your own templatePossibility to use meta-data in thetemplate

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


Configuration: pillar.conf

Configure your exports with a simple fileSTON syntaxCan contain

I Export configurationI Sub configurationsI 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"

}}

}’


Text Editor Plugins

You can find Pillarplugin for:

I EmacsI VimI TextMateI Atom


https://github.com/pillar-markup/pillar-mode

https://github.com/cdlm/vim-pillar

https://github.com/Uko/Pillar.tmbundle

https://github.com/Uko/language-pillar

How Pillar Works

How Pillar Works 28

Parse

.PillarPRDocumentParser

PRDocument

PRHeader

PRText

PRParagraph

PRText

PRFigure

Example.pillar

!Hello WorldI am an example +>file://figures/fig.png+

How Pillar Works 29

Transformation

PRDocument

PRHeader

PRText

PRParagraph

PRText

PRFigure

PRSectionTransformer

PRDocument

PRHeader

PRText

PRSection

PRParagraph

PRText

PRFigure

Example.pillar

!Hello WorldI am an example +>file://figures/fig.png+

How Pillar Works 30

Export

PRDocument

PRHeader

PRText

PRSection

PRParagraph

PRText

PRFigure

PRLaTeXWriter

PRHTMLWriter

PRTextWriter

.pdf

.html

.txt

pdflatex

.tex

How Pillar Works 31

Phases System

PRCreationPhase PRParsingPhase PRTransformingPhase

transformerScriptEvaluatortransformerSection

PRExportingPhase

nil

A collection of input files

A collection of PRDocuments

A collection of transformed PRDocuments

Exported files

How Pillar Works 32

Easy Extension

Easy Extension 33

Adding an Exporter

Write a format from a document modelJust write a visitor for the documentCheck your exporter with tests

Easy Extension 34

Adding an Annotation

Syntax extension pointCan take parameters

I Describe your parameters withMagritte

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


PRAbstractAnnotation subclass: #MyNewAnnotationinstanceVariableNames: ’’classVariableNames: ’’category: ’Pillar−Model−Document’

Easy Extension 36



MyNewAnnotation class>>#tag^ #myTag

Easy Extension 37



MyNewAnnotation class>>#tag^ #myTag

MyNewAnnotation>>#descriptionWidth<magritteDescription>^ MANumberDescription new

accessor: #width;required: true;min: 0 max: 100;yourself

Easy Extension 38

Adding a Transformer

Transform a documentI Visit the document to transform it

Basic transformers structure exist

Easy Extension 39


PRNodeTransformer subclass: #PRFileInclusioninstanceVariableNames: ’’classVariableNames: ’’category: ’Pillar−Model−Transformer’

Easy Extension 40


PRNodeTransformer subclass: #PRFileInclusioninstanceVariableNames: ’’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


You can:I Define a priorityI Define a keyword to disable a transformerI 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

Conclusion

Conclusion 43

Conclusion

One Format to Rule Them AllEasy to extendsFuture Work

I Improve the Pharo rendererI An Epub and a DocBook exporter

would be great.I We have a large TODO list

Conclusion 44

Annexes

Annexes 45

Partial Diagram of Pillar

PRCocoonConfiguration

exportPRDocument

PRDocumentParser

parse(aFile):aDocument

PRDocumentItem

acceptVisitor(aVisitor)

PRHeader PRParagraph PRTextPRDocumentWriter

write(aDocument)

PRVisitor

visit(aDocument)visitHeader(aHeader)visitParagraph(aParagraph)visitText(aText)

PRHTMLWriter

*

PRLaTeXWriter

PREmptyParagraph

PRPhaserexport()

PRPhaseactionOn(input):outputtransform(input):output

n

Annexes 46

Sequence Diagram

a PRHTMLWriter a PRHeader a PRText a PRScript

accept: self

start: aDocumentvisit: 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 findu titre

accept: self

visitScript: self

Ici le script s'écrit

a PRDocument

children

PRItem Collection

Annexes 47

Moose analysis of Pillar

Annexes 48

Non Exhaustive Syntax of Pillar

Annexes 49

Pillar: One Format to Rule them All

Technology

Transcript of Pillar: One Format to Rule them All