Pillar 0.56 : New features, new syntax

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

Cyril,

Hi.
We used '@' because Pier used it this way. I'm afraid that if we
change the character that will break Pier.
But if you write *Chapter 1>../Chapter1/chapter1.pillar@cha:chapter1*
and export in HTML you'll get
<a href="../Chapter1/chapter1.html#cha:chapter1"> I. Chapter 1 </a>

On 23 May 2015 at 08:44, Norbert Hartl <[hidden email]> wrote:


--
Cheers
Cyril Ferlicot

Cyril, thanks for doing all of this, but now the links seem to be broken, at least for the html export on my machine. :-( I am working on the Fuel chapter, and I see that inter-file links are broken in the first paragraph, and intra-file links are broken e.g. figure 6.1. Example of changes to a class.

Could you have a look? The pillar file is in github, the Fuel.pillar.html result of ./compile.sh is here:
https://dl.dropboxusercontent.com/u/31426460/Fuel.pillar.html

Thanks in advance!



---> Save our in-boxes! http://emailcharter.org <---

Johan Fabry   -   http://pleiad.cl/~jfabry
PLEIAD lab  -  Computer Science Department (DCC)  -  University of Chile

Hi,
2 possibility:
- You have an old version of Pillar
- You check the wrong file.

With the version 0.47 of Pillar we changed the way files was generated.
Before if you had a file foo.pillar exported foo.pillar.html
but since the version 0.47 you get foo.html only.

So check if you have a file "Fuel.html" and if you don't have it just
execute ./download.sh before the ./compile.sh

You should get that :
https://ci.inria.fr/pharo-contribution/view/Books/job/EnterprisePharoBook/lastSuccessfulBuild/artifact/Fuel/Fuel.html

:)

On 25 May 2015 at 03:10, Johan Fabry <[hidden email]> wrote:


--
Cheers
Cyril Ferlicot

Aah silly me, I still had the old version of Pillar. Many apologies!

Now it works, but I found a bug: do a find for  ‘shown in Section 5.3.3’ in the same html file. The section title there is V.3.C. So it should say ‘shown in Section V.3.C.’, right?



---> Save our in-boxes! http://emailcharter.org <---

Johan Fabry   -   http://pleiad.cl/~jfabry
PLEIAD lab  -  Computer Science Department (DCC)  -  University of Chile

No problem! Think like this happen easily.

Yeah that's right. I think I know where is the error. I'll correct
that tomorrow if I have time.
Thank you for your feedback!

On 25 May 2015 at 04:03, Johan Fabry <[hidden email]> wrote:


--
Cheers
Cyril Ferlicot