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

Ben Coman <[hidden email]> writes:

> This might be a case where is reasonable for both to be valid:
>   @ for backward compatibility
>    # for compatibility with internet conventions

- Pillar is not an Internet-related tool. It produces HTML, but not only:
  Pillar produces LaTeX and Markdown and we plan to make it support
  Docbook. For example, LaTeX uses \ref to represent anchors, should
  Pillar use \ref instead of @?

- Creating anchors in the document is done through the @@ syntax. As a
  result, both links and anchors use the same character. Switching to #
  for links only would break this similarity. Switching to # for both
  links and anchors would break even more document and website (but I
  think that's ok).

Breaking backward compatibility is ok, but we should pay attention when
we do it.

--
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

No, of course not. I see an URI as good and common known abstraction to reference resources. It is useful regardless how you access different resources and that is what are the semantics behind the anchor and the reference.

> - Creating anchors in the document is done through the @@ syntax. As a
>  result, both links and anchors use the same character. Switching to #
>  for links only would break this similarity. Switching to # for both
>  links and anchors would break even more document and website (but I
>  think that's ok).
>
> Breaking backward compatibility is ok, but we should pay attention when
> we do it.
>
As it was proposed already there could be a time where both would work. So this is not an argument.

I can see that the meaning of an anchor or a reference in pillar can exceed the semantics of an URI. In this case it wouldn't be a good idea to use URI syntax. But I doubt this will be the case. So I'm opting for a format that is commonly known and that enables URI aware software not be mislead by a format.

Norbert