diff --git a/Pillar/Pillar.pillar b/Pillar/Pillar.pillar new file mode 100644 index 0000000..67e806a --- /dev/null +++ b/Pillar/Pillar.pillar @@ -0,0 +1,521 @@ +!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/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://www.cheatography.com/benjaminvanryseghem/cheat-sheets/pillar* + + +The contributors are: + +- *Benjamin van Ryseghem>http://benjamin.vanryseghem.com* did everything on the *Mardown>http://daringfireball.net/projects/markdown/* exporter and its *GitHub Markdown>https://help.github.com/articles/github-flavored-markdown* little brother; +- *Benjamin van Ryseghem>http://benjamin.vanryseghem.com* also worked on the command-line interface, the STON configuration interpreter and many other stuff; +- Ben Coman made annotated paragraphs work; +- *Guillermo Polito>http://playingwithobjects.wordpress.com* fixed a bug; +- *Lukas Renggli>http://www.lukas-renggli.ch* created *Pier>http://piercms.com* a long time ago from which Pillar's document model, parser and many unit tests are coming; +- *Stéphane Ducasse>http://stephane.ducasse.free.fr* provided continuous feedback from the beginning of the project and got the original idea; +- *Damien Cassou>http://damiencassou.seasidehosting.st* for everything else :-). + ++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/DamienCassou/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://github.com/DamienCassou/pillar-documentation* +- *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 download Pillar. For that, I recommend executing *this script>https://raw2.github.com/SquareBracketAssociates/PharoForTheEnterprise-english/master/download.sh* in the base directory. + +Then, you can check everything is working fine by creating a ==first.pier== 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.pier' > 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 + + + + No title + [...] + + +
+

Hello World

+
+ [...] + + +]]] + +!!!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 write a 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). Create your first ==pillar.conf== file: + +[[[language=ston +{ + "title" : "My first document while reading the 5 minutes Pillar tutorial" +} +]]] + +When you compile using the same command line, + +[[[language=bash +./pillar export --to=html first.pier > first.html +]]] + +you should now get a web page with a title: + +[[[language=html + + + + My first document while reading the 5 minutes Pillar tutorial + +]]] + +!!!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 + + + + {{{title}}} + + +
+ {{{content}}} +
+ + + +]]] + +Then, you need to reference this template from your configuration file. So, edit your ==pillar.conf== configuration file: + +[[[language=ston +{ + "title" : "My first document while reading the 5 minutes Pillar tutorial", + "configurations" : { + "html" : { + "template" : "myhtml.template", + "outputType" : #html + } + } +} +]]] + +Now, compile ==first.pier== + +[[[language=bash +./pillar export --to=html first.pier > first.html +]]] + +to generate a ==first.html== that will contain: + +[[[language=html + + + + My first document while reading the 5 minutes Pillar tutorial + + +
+

Hello World

+
+ + + +]]] + +This concludes our 5 minutes tutorial. + +!!Writing Pillar documents + +@writing + +In this section we show how to write Pillar documents by presenting 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. + +!!!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 that is not visible in the output. + +@@todo this is a todo annotation + +!!!Lists + +!!!!Unordered lists + +[[[ +-A block of lines, +-where each line starts with ==-== +-is transformed to a bulleted list, where each line is an entry. +]]] + +generates + +-A block of lines, +-where each line starts with ==-== +-is transformed to a bulleted list, where each line is an entry. + +!!!!Ordered lists + +[[[ +#A block of lines, +#where each line starts with ==#== +#is transformed to an ordered list, where each line is an entry. +]]] + +generates + +#A block of lines, +#where each line starts with ==#== +#is transformed to an ordered list, where each line is an entry. + +!!!!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""== +-To make something ''italic'', write ==\''italic''== +-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 + + + + {{{title}}} + + + + + + + + + + +
+ {{{content}}} +
+ + + + + + + +]]] + +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 +]]] diff --git a/Pillar/figures/esug-logo.jpg b/Pillar/figures/esug-logo.jpg new file mode 100644 index 0000000..ebb8add Binary files /dev/null and b/Pillar/figures/esug-logo.jpg differ diff --git a/Pillar/figures/pier-logo.png b/Pillar/figures/pier-logo.png new file mode 100644 index 0000000..18cab88 Binary files /dev/null and b/Pillar/figures/pier-logo.png differ diff --git a/Pillar/figures/voyageDocExample-small.png b/Pillar/figures/voyageDocExample-small.png new file mode 100644 index 0000000..46f5c93 Binary files /dev/null and b/Pillar/figures/voyageDocExample-small.png differ diff --git a/Pillar/figures/voyageDocExample.png b/Pillar/figures/voyageDocExample.png new file mode 100644 index 0000000..30274cd Binary files /dev/null and b/Pillar/figures/voyageDocExample.png differ diff --git a/pillar.conf b/pillar.conf index 9ac3128..84f8869 100644 --- a/pillar.conf +++ b/pillar.conf @@ -25,7 +25,8 @@ } }, "inputFiles" : [ - "Copyright/License.pier", + "Copyright/License.pier", "Zinc/Zinc.pier" + "Pillar/Pillar.pillar", ] }