Pillar Book Tester

Hello everyone!

I am currently in an internship within the RMoD team and would like to present my work. My internship subject was the following: “How to test documents (books, slides) written in Pillar?”. Let me first introduce Pillar then what I managed to implement and what is left to do.

 

-What is Pillar? 

 

Pillar is a markup syntax and associated tools to write and generate documentation, books, slide-based presentations or websites. Pillar syntax is similar to Markdown’s one but its emphasis is stressed on publishing to different formats/languages (Markdown, html, LateX, pdf).

 

-What does it mean to ‘test a book’?

--      Display code within the book

Pillar syntax allows you to write codeblocks, showing a part of code. The inside of a codeblock allows one to display any part of code you might want to. For example:

[[[

YourClass >> yourMethod

^ ‘bla’

]]]

This codeblock presents a method definition, the other two possible codeblocks are the following: 

          Class definition

[[[

Object subclass: #YourClass

            instanceVariableNames: ''

            classVariableNames: ''

            package: YourPackage'

]]]

          Example

[[[

1+1

>>> 2

]]]

 

--      How to test it?

The use of ‘>>>’ and parameters in the codeblock will help us to test the code within it. The BookTester will turn examples into tests.

 

Testing examples: 

[[[testcase=true

3+4                              becomes       self assert: (3+4) equals: 7

>>>7

]]]

Testing methodDefinitions and classDefinitions:

 

Testing method or class definitions resumes is the same as testing if the compilation of the method does not raise any error. It can help make sure your book is up to date with the latest Pharo version. Those tests are done the same way as testing an example: stating methodDefinition=true or classDefinition=true as code block parameters will make them elible for tests. Now, we are adding more features to code block or Pillar to help book writers.

 

-Additional Features

In Pillar, several annotations can be used for different purposes like including columns/tables/citations/figures/links…

 

--       Loading code: loader

${loader:account=QDucasse|project=TestBook|tag=Chapter1}$

allows you to load the github project as it was in the commit tagged Chapter1. This will help you test every chapter of your code with its current progression and also allow you to test the objects you are defining in your book.

-       Executing Tests: run

${run:testClass=YourClassTest}$ runs the test defined in the class testClass. And of course this testClass can be  

Other annotations have been added to help you write your book:

-       Display a class definition: showClass:

${showClass:className=YourClass}$ displays a codeblock with the class definition within it

This helps you quickly include a class definition you want to display in your book. Combined with the loader it means that the code can be the source of your book.

 

-       Display a method definition: showMethod:

${showMethod:className=YourClass|methodName=yourMethod}$ will display a codeblock with the method definition within it

This helps you quickly include a method definition you want to display in your book.

 

-       Screenshot: 

${showMethod:packageName=yourPackage|className=YourClass|methodName=yourMethod|caption|width|label}$

saves a screenshot of a Calypso browser open at the selected package, class and method and includes it in both your book (using the designated Pillar figure reference) and the figures subfolder in the pillar book folder (saved as PNG).

-Future objectives

 

One of the future improvements would be to make everyone able to write examples and test them in the comments of method definitions. It is already partially possible “3+4 >>> 7” will be highlighted differently and if printed will display “7->7”. However, an automation or UI improvement would be nice.

I hope this gave you the will to write something you had in mind. Are there any books you want to try the tools on? Feel free to ask !

Quentin Ducasse