New subject: [Pharo-dev] Pillar 0.56 : New features, new syntax

22 May 2015

Hello,
today I created the version 0.56 of Pillar and with this version we'll
need to do some changes, sorry.

The first change is the numerator. The old numerator was too limited,
so i changed it. Now if you put different files into the pillar.conf
the numerator will not be reset at each files.
The parameters 'startNumberingAtHeaderLevel:' and
'stopNumberingAtHeaderLevel:' are replace by 'level1:',
'level2:',
'level3:', 'level4:', 'level5:'.
For now they can take 3 sub-parameters: 'numbering', 'size' and
'renderAs'.

numbering: a boolean that say if this header level need to be take in
account by the numerator.
size: the number of level we want to render. You can put numbering at
true and size at 0 if you want your numerator to be reset at a level
without rendering the number of this level.
renderAs: can be number, roman, letter or upperLetter.

Example:

pillar.conf:
{
    'level1': {
        'numbering': true,
        'size': 1,
        'renderAs': 'roman'
    },
    'level2': {
        'numbering': true,
        'size': 2,
        'renderAs': 'number'
    },
    'level3': {
        'numbering': true,
        'size': 1,
        'renderAs': 'upperLetter'
    },
    'level4': {
        'numbering': true,
        'size': 2,
        'renderAs': letter
    },
    'level5': {
        'numbering': false
    },

}

document.pillar:

! Example
!! Introduction
!!! Beginning
!!! Example - Intro
!!!! Example 1
!!!! Example 2
!!!!! With X
!!!!! With Y
!! Explanation

Result:
I. Example
I.1. Introduction
A. Beginning
B. Example - Intro
B.a. Example 1
B.b. Example 2
With X
With Y
I.2. Explanation

In the future we could also add feature like 'delimiter'.

The second main change is the Internal Links.
Now when you want to reefer to an anchor, a figure or a script you'll
need to use *@anchor* instead of *anchor*.
I'm sorry for that but that's the easiest way to implement the
inter-files links.

And so the last main change is the Inter-files links !
Imagine you're writing a book.
You have a directory 'Chapter1' which contains the file
'chapter1.pillar' and a directory 'Chapter2' with a file
'chapter2.pillar'.

If you want to make a reference to the chapter 1 in the chapter 2 you
can create an interfile link you can now use the syntax:

*../Chapter1/chapter1.pillar*

But be careful ! Remember that pillar can export in different format.
And you can export a group of file as separate output files or as one
file.
So if you don't use an Alias your link will not be render if you
export as one output file in LaTeX. And if you export in LaTeX or HTML
or Markdown as one output file and you don't have an anchor on your
link, the link will be vanish.

So I recommend to use inter file links like this:

*Chapter 1>../Chapter1/chapter1.pillar@cha:chapter1*

when cha:chapter1 is an anchor you need to create at the beginning of
the chapter 1.

I already changed the links on Enterprise Pharo (you can find a table
with the list of the inter-files links on the README.md)

On last thing for the people who write book for SquareBracketAssociates:
It would be good to have some conventions, so if you create anchors
use this form :
@sec:nameOfSection for a section
@cha:nameOfTheChapter for a title of chapter
@fig:nameOfFigure for a figure
@spt:nameOfTheScript for a script

-- 
Cheers
Cyril Ferlicot