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
