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,
Am 22.05.2015 um 23:12 schrieb Cyril Ferlicot <cyril.ferlicot@gmail.com>:
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.
why @? It is about links and how to point to a fragment inside a resource. This already exists and is called fragment identifier http://en.wikipedia.org/wiki/Fragment_identifier <http://en.wikipedia.org/wiki/Fragment_identifier> You do it by using # the separate the resource and the fragment in an URI. '../chapters/chapter1.pillar#section1' is complete valid URI and the way to go. Can you change that? Norbert
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 <norbert@hartl.name> wrote:
Cyril,
Am 22.05.2015 um 23:12 schrieb Cyril Ferlicot <cyril.ferlicot@gmail.com>:
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.
why @? It is about links and how to point to a fragment inside a resource. This already exists and is called fragment identifier
http://en.wikipedia.org/wiki/Fragment_identifier
You do it by using # the separate the resource and the fragment in an URI.
'../chapters/chapter1.pillar#section1'
is complete valid URI and the way to go. Can you change that?
Norbert
-- Cheers Cyril Ferlicot
This might be a case where is reasonable for both to be valid: @ for backward compatibility # for compatibility with internet conventions cheers -ben On Sat, May 23, 2015 at 8:36 PM, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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 <norbert@hartl.name> wrote:
Cyril,
Am 22.05.2015 um 23:12 schrieb Cyril Ferlicot <cyril.ferlicot@gmail.com :
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.
why @? It is about links and how to point to a fragment inside a resource. This already exists and is called fragment identifier
http://en.wikipedia.org/wiki/Fragment_identifier
You do it by using # the separate the resource and the fragment in an URI.
'../chapters/chapter1.pillar#section1'
is complete valid URI and the way to go. Can you change that?
Norbert
-- Cheers Cyril Ferlicot
Am 23.05.2015 um 17:59 schrieb Ben Coman <btc@openinworld.com>:
This might be a case where is reasonable for both to be valid: @ for backward compatibility # for compatibility with internet conventions
Agreed, if there isn't special semantics for @ in pillar then it should be changed. It is less confusing and less error prone using #. Norbert
cheers -ben
On Sat, May 23, 2015 at 8:36 PM, Cyril Ferlicot <cyril.ferlicot@gmail.com <mailto:cyril.ferlicot@gmail.com>> wrote: 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 <norbert@hartl.name <mailto:norbert@hartl.name>> wrote:
Cyril,
Am 22.05.2015 um 23:12 schrieb Cyril Ferlicot <cyril.ferlicot@gmail.com <mailto:cyril.ferlicot@gmail.com>>:
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.
why @? It is about links and how to point to a fragment inside a resource. This already exists and is called fragment identifier
http://en.wikipedia.org/wiki/Fragment_identifier <http://en.wikipedia.org/wiki/Fragment_identifier>
You do it by using # the separate the resource and the fragment in an URI.
'../chapters/chapter1.pillar#section1'
is complete valid URI and the way to go. Can you change that?
Norbert
-- Cheers Cyril Ferlicot
Now, is pier evolving? because i'd also accept a solution where either - pier extends pillar to use @ - pier uses a freezed version of pillar and new releases of pillar are not backward compatible El dom., 24 de may. de 2015 a la(s) 11:38 a. m., Norbert Hartl < norbert@hartl.name> escribió:
Am 23.05.2015 um 17:59 schrieb Ben Coman <btc@openinworld.com>:
This might be a case where is reasonable for both to be valid: @ for backward compatibility # for compatibility with internet conventions
Agreed, if there isn't special semantics for @ in pillar then it should be changed. It is less confusing and less error prone using #.
Norbert
cheers -ben
On Sat, May 23, 2015 at 8:36 PM, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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 <norbert@hartl.name> wrote:
Cyril,
Am 22.05.2015 um 23:12 schrieb Cyril Ferlicot <cyril.ferlicot@gmail.com :
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.
why @? It is about links and how to point to a fragment inside a resource. This already exists and is called fragment identifier
http://en.wikipedia.org/wiki/Fragment_identifier
You do it by using # the separate the resource and the fragment in an URI.
'../chapters/chapter1.pillar#section1'
is complete valid URI and the way to go. Can you change that?
Norbert
-- Cheers Cyril Ferlicot
Ben Coman <btc@openinworld.com> 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
Am 26.05.2015 um 11:03 schrieb Damien Cassou <damien.cassou@inria.fr>:
Ben Coman <btc@openinworld.com> 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 @?
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
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!
On May 22, 2015, at 18:12, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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
---> 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/la... :) On 25 May 2015 at 03:10, Johan Fabry <jfabry@dcc.uchile.cl> wrote:
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!
On May 22, 2015, at 18:12, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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
---> Save our in-boxes! http://emailcharter.org <---
Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile
-- 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?
On May 24, 2015, at 22:17, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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/la...
:)
---> 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 <jfabry@dcc.uchile.cl> wrote:
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?
On May 24, 2015, at 22:17, Cyril Ferlicot <cyril.ferlicot@gmail.com> wrote:
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/la...
:)
---> Save our in-boxes! http://emailcharter.org <---
Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile
-- Cheers Cyril Ferlicot
participants (6)
-
Ben Coman -
Cyril Ferlicot -
Damien Cassou -
Guillermo Polito -
Johan Fabry -
Norbert Hartl