Smalltalk › Pharo › Pharo Smalltalk Users

including Pillar in Pharo image by default

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

36 messages Options

Peter Uhnak

including Pillar in Pharo image by default

Hi,

I would like to propose including Pillar in the Pharo image by default.

My reasoning:

Since we are moving to git, and most people will use github, gitlab, and the likes, it is expected to include a README.md file (or possibly more extensive documentation) alongside the code.

Which means that people will (and are) writing the README mostly by hand, which of course is problematic, as e.g. code snippets can get deprecated, screenshots become outdated, etc.

As Pillar tries to address these problems, it would make sense to me to include Pillar in the image by default, as anyone using git (which eventually should be everyone) will most likely benefit from writing their documentation in Pillar.
Similarly using Pillar would open an avenue to provide the documentation in-image, e.g. one exporter for html/markdown, and another one for Pharo's Help system.

I could, of course, install Pillar every time, but considering thats extra effort and in the extra time I can fix the issues by hand, I don't have such an incentive to use Pillar for this.

Questions & Problems:

I don't know by how much would pillar increase the image size. Perhaps there could be (a) "lightweight Pillar" (that would include just pillar & markdown exporter), or (b) we would have different images for different uses.

By different images I mean something along the lines of
a) developer image - meant to be directly used by developers to create their software
b) production image - as a foundation for running systems / users

Does this make sense?

Peter

CyrilFerlicot

Re: including Pillar in Pharo image by default

Le 11/08/2017 à 18:52, Peter Uhnak a écrit :

> Hi,
>
> I would like to propose including Pillar in the Pharo image by default.
>
> My reasoning:
>
> Since we are moving to git, and most people will use github, gitlab, and the likes, it is expected to include a README.md file (or possibly more extensive documentation) alongside the code.
>
> Which means that people will (and are) writing the README mostly by hand, which of course is problematic, as e.g. code snippets can get deprecated, screenshots become outdated, etc.
>
> As Pillar tries to address these problems, it would make sense to me to include Pillar in the image by default, as anyone using git (which eventually should be everyone) will most likely benefit from writing their documentation in Pillar.
> Similarly using Pillar would open an avenue to provide the documentation in-image, e.g. one exporter for html/markdown, and another one for Pharo's Help system.
>
> I could, of course, install Pillar every time, but considering thats extra effort and in the extra time I can fix the issues by hand, I don't have such an incentive to use Pillar for this.
>
> Questions & Problems:
>
> I don't know by how much would pillar increase the image size. Perhaps there could be (a) "lightweight Pillar" (that would include just pillar & markdown exporter), or (b) we would have different images for different uses.
>
> By different images I mean something along the lines of
> a) developer image - meant to be directly used by developers to create their software
> b) production image - as a foundation for running systems / users
>
> Does this make sense?
>
> Peter
>

Hi,

I know that Stephane want to includes a light version of Pillar in the
image.

Currently he is working on a way to remove Magritte dependency from
Pillar. Another step would be to get a minimal parser not relying on
PetitParser. This parser would parse only a subset of the Pillar syntax
that can be used for writing class comments. If this subset is defined
(I we have the list of all Document Items we want to understand), I can
give a try to make this light parse.

--
Cyril Ferlicot
https://ferlicot.fr

http://www.synectique.eu
2 rue Jacques Prévert 01,
59650 Villeneuve d'ascq France

signature.asc (836 bytes) Download Attachment

Stephane Ducasse-3

Re: including Pillar in Pharo image by default

In reply to this post by Peter Uhnak

Let us rephrase it:

- I would like to have a mini pillar with a simplified model and visitor
to display class comments.

- then think about Pharo 70 as the core and birth of a new generation of imageS

I will restart to revisit Pillar once I'm done with the Lecture at Prague.

Stef

On Fri, Aug 11, 2017 at 6:52 PM, Peter Uhnak <[hidden email]> wrote:

Stephane Ducasse-3

Re: including Pillar in Pharo image by default

In reply to this post by CyrilFerlicot

Tx cyril

For class comment I image that we want

!

-
-
*url*
and bold
[[[

]]]

Did I miss something.

Stef

On Fri, Aug 11, 2017 at 6:57 PM, Cyril Ferlicot D.
<[hidden email]> wrote:

> Le 11/08/2017 à 18:52, Peter Uhnak a écrit :
>> Hi,
>>
>> I would like to propose including Pillar in the Pharo image by default.
>>
>> My reasoning:
>>
>> Since we are moving to git, and most people will use github, gitlab, and the likes, it is expected to include a README.md file (or possibly more extensive documentation) alongside the code.
>>
>> Which means that people will (and are) writing the README mostly by hand, which of course is problematic, as e.g. code snippets can get deprecated, screenshots become outdated, etc.
>>
>> As Pillar tries to address these problems, it would make sense to me to include Pillar in the image by default, as anyone using git (which eventually should be everyone) will most likely benefit from writing their documentation in Pillar.
>> Similarly using Pillar would open an avenue to provide the documentation in-image, e.g. one exporter for html/markdown, and another one for Pharo's Help system.
>>
>> I could, of course, install Pillar every time, but considering thats extra effort and in the extra time I can fix the issues by hand, I don't have such an incentive to use Pillar for this.
>>
>> Questions & Problems:
>>
>> I don't know by how much would pillar increase the image size. Perhaps there could be (a) "lightweight Pillar" (that would include just pillar & markdown exporter), or (b) we would have different images for different uses.
>>
>> By different images I mean something along the lines of
>> a) developer image - meant to be directly used by developers to create their software
>> b) production image - as a foundation for running systems / users
>>
>> Does this make sense?
>>
>> Peter
>>
>
> Hi,
>
> I know that Stephane want to includes a light version of Pillar in the
> image.
>
> Currently he is working on a way to remove Magritte dependency from
> Pillar. Another step would be to get a minimal parser not relying on
> PetitParser. This parser would parse only a subset of the Pillar syntax
> that can be used for writing class comments. If this subset is defined
> (I we have the list of all Document Items we want to understand), I can
> give a try to make this light parse.
>
> --
> Cyril Ferlicot
> https://ferlicot.fr
>
> http://www.synectique.eu
> 2 rue Jacques Prévert 01,
> 59650 Villeneuve d'ascq France
>

CyrilFerlicot

Re: including Pillar in Pharo image by default

Le 11/08/2017 à 19:09, Stephane Ducasse a écrit :

> Tx cyril
>
> For class comment I image that we want
>
> !
>
> -
> -
> *url*
> and bold
> [[[
>
> ]]]
>
> Did I miss something.
>
> Stef
>
>
>

We might want to add some syntax only for class comment and not Pillar
itself. For example to be able to reference a class in Pharo and get a
link to the class during the rendering.

I think that we might also want the formats (bold, etc) and the ordered
list.

--
Cyril Ferlicot
https://ferlicot.fr

http://www.synectique.eu
2 rue Jacques Prévert 01,
59650 Villeneuve d'ascq France

signature.asc (836 bytes) Download Attachment

CyrilFerlicot

Re: including Pillar in Pharo image by default

Le 11/08/2017 à 19:12, Cyril Ferlicot D. a écrit :
>
> We might want to add some syntax only for class comment and not Pillar
> itself. For example to be able to reference a class in Pharo and get a
> link to the class during the rendering.
>
> I think that we might also want the formats (bold, etc) and the ordered
> list.
>

I just saw that you said bold after sending…

--
Cyril Ferlicot
https://ferlicot.fr

http://www.synectique.eu
2 rue Jacques Prévert 01,
59650 Villeneuve d'ascq France

signature.asc (836 bytes) Download Attachment

Stephane Ducasse-3

Re: including Pillar in Pharo image by default

Cyril

the ** can be used to point to another class for example acting as a ref.

Stef

On Fri, Aug 11, 2017 at 7:15 PM, Cyril Ferlicot D.
<[hidden email]> wrote:

> Le 11/08/2017 à 19:12, Cyril Ferlicot D. a écrit :
>>
>> We might want to add some syntax only for class comment and not Pillar
>> itself. For example to be able to reference a class in Pharo and get a
>> link to the class during the rendering.
>>
>> I think that we might also want the formats (bold, etc) and the ordered
>> list.
>>
>
> I just saw that you said bold after sending…
>
> --
> Cyril Ferlicot
> https://ferlicot.fr
>
> http://www.synectique.eu
> 2 rue Jacques Prévert 01,
> 59650 Villeneuve d'ascq France
>

CyrilFerlicot

Re: including Pillar in Pharo image by default

Le 11/08/2017 à 19:19, Stephane Ducasse a écrit :
> Cyril
>
> the ** can be used to point to another class for example acting as a ref.
>
> Stef
>
>

I though it would be kept for real links to web urls.

--
Cyril Ferlicot
https://ferlicot.fr

http://www.synectique.eu
2 rue Jacques Prévert 01,
59650 Villeneuve d'ascq France

signature.asc (836 bytes) Download Attachment

Peter Uhnak

Re: including Pillar in Pharo image by default

In reply to this post by Stephane Ducasse-3

What I meant is that I have a readme, e.g. https://github.com/OpenPonk/xmi , which contains

* Pharo code examples
* images
* References to Pharo code (class names, etc.)

But if the code changes (renames, API changes, different UI), I have to manually update the README.
There is also no way for me to validate the examples, etc and see if anything is broken.

Peter

On Fri, Aug 11, 2017 at 06:58:50PM +0200, Stephane Ducasse wrote:

> Let us rephrase it:
>
> - I would like to have a mini pillar with a simplified model and visitor
> to display class comments.
>
> - then think about Pharo 70 as the core and birth of a new generation of imageS
>
> I will restart to revisit Pillar once I'm done with the Lecture at Prague.
>
> Stef
>
> On Fri, Aug 11, 2017 at 6:52 PM, Peter Uhnak <[hidden email]> wrote:
> > Hi,
> >
> > I would like to propose including Pillar in the Pharo image by default.
> >
> > My reasoning:
> >
> > Since we are moving to git, and most people will use github, gitlab, and the likes, it is expected to include a README.md file (or possibly more extensive documentation) alongside the code.
> >
> > Which means that people will (and are) writing the README mostly by hand, which of course is problematic, as e.g. code snippets can get deprecated, screenshots become outdated, etc.
> >
> > As Pillar tries to address these problems, it would make sense to me to include Pillar in the image by default, as anyone using git (which eventually should be everyone) will most likely benefit from writing their documentation in Pillar.
> > Similarly using Pillar would open an avenue to provide the documentation in-image, e.g. one exporter for html/markdown, and another one for Pharo's Help system.
> >
> > I could, of course, install Pillar every time, but considering thats extra effort and in the extra time I can fix the issues by hand, I don't have such an incentive to use Pillar for this.
> >
> > Questions & Problems:
> >
> > I don't know by how much would pillar increase the image size. Perhaps there could be (a) "lightweight Pillar" (that would include just pillar & markdown exporter), or (b) we would have different images for different uses.
> >
> > By different images I mean something along the lines of
> > a) developer image - meant to be directly used by developers to create their software
> > b) production image - as a foundation for running systems / users
> >
> > Does this make sense?
> >
> > Peter
> >
>

abergel

Re: including Pillar in Pharo image by default

In reply to this post by Peter Uhnak

The idea is neat! Usually, I write my README.md through the interface of GitHub. But indeed, if Git and inline documentation are central to Pharo, then having a mini-pillar in the base image would make sense.

Anyway, Pillar definitely needs to be improved. Everything that goes in that direction is welcome!

Cheers,

Alexandre

--
_,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
Alexandre Bergel http://www.bergel.eu
^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.

On Aug 11, 2017, at 12:52 PM, Peter Uhnak <[hidden email]> wrote:

Hi,

I would like to propose including Pillar in the Pharo image by default.

My reasoning:

Since we are moving to git, and most people will use github, gitlab, and the likes, it is expected to include a README.md file (or possibly more extensive documentation) alongside the code.

Which means that people will (and are) writing the README mostly by hand, which of course is problematic, as e.g. code snippets can get deprecated, screenshots become outdated, etc.

As Pillar tries to address these problems, it would make sense to me to include Pillar in the image by default, as anyone using git (which eventually should be everyone) will most likely benefit from writing their documentation in Pillar.
Similarly using Pillar would open an avenue to provide the documentation in-image, e.g. one exporter for html/markdown, and another one for Pharo's Help system.

I could, of course, install Pillar every time, but considering thats extra effort and in the extra time I can fix the issues by hand, I don't have such an incentive to use Pillar for this.

Questions & Problems:

I don't know by how much would pillar increase the image size. Perhaps there could be (a) "lightweight Pillar" (that would include just pillar & markdown exporter), or (b) we would have different images for different uses.

By different images I mean something along the lines of
a) developer image - meant to be directly used by developers to create their software
b) production image - as a foundation for running systems / users

Does this make sense?

Peter

EstebanLM

Re: including Pillar in Pharo image by default

In reply to this post by CyrilFerlicot

hi,

On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email]> wrote:

Another step would be to get a minimal parser not relying on
PetitParser.

Let’s think differently: why not to include a tiny PetitParser?

Then we can think on:

- pillar sintax (better than just a restricted version)

- simplify other “small parsers” that are already on the image.

- we provide a tool to o cool stuff (instead relying as always in regexp, etc.)

cheers,

Esteban

EstebanLM

Re: including Pillar in Pharo image by default

On 11 Aug 2017, at 21:10, Esteban Lorenzano <[hidden email]> wrote:

hi,

On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email]> wrote:

Another step would be to get a minimal parser not relying on
PetitParser.

Let’s think differently: why not to include a tiny PetitParser?
Then we can think on:

- pillar sintax (better than just a restricted version)

*syntax*… sorry for spanish intromission ;)

btw… not just outside the image (as readme). There was a prototype about rich text (using pillar, of course) for class comments.

Esteban

- simplify other “small parsers” that are already on the image.
- we provide a tool to o cool stuff (instead relying as always in regexp, etc.)

cheers,
Esteban

Peter Uhnak

Re: including Pillar in Pharo image by default

On Fri, Aug 11, 2017 at 09:14:01PM +0200, Esteban Lorenzano wrote:

>
> > On 11 Aug 2017, at 21:10, Esteban Lorenzano <[hidden email]> wrote:
> >
> > hi,
> >
> >> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email] <mailto:[hidden email]>> wrote:
> >>
> >> Another step would be to get a minimal parser not relying on
> >> PetitParser.
> >
> > Let’s think differently: why not to include a tiny PetitParser?
> > Then we can think on:
> >
> > - pillar sintax (better than just a restricted version)
> *syntax*… sorry for spanish intromission ;)
>
> btw… not just outside the image (as readme).

Yes, one of the points I want is to have the readme available in Pharo's Help Browser with rich content.

Peter

Tim Mackinnon

Re: including Pillar in Pharo image by default

If we are considering this, might we take the hard decision to actually support proper markdown (or even kramdown if we need more control).

Pillar is a weird variant that isn't like everyone else - so i always have to think about how to do formatting.

I know it's not nice, and lots of things are done in pillar - but could we convert them to be like everyone else? The readme.md that Peter is talking about is gfm markdown.'

Tim

Sent from my iPhone

> On 11 Aug 2017, at 20:24, Peter Uhnak <[hidden email]> wrote:
>
>> On Fri, Aug 11, 2017 at 09:14:01PM +0200, Esteban Lorenzano wrote:
>>
>>> On 11 Aug 2017, at 21:10, Esteban Lorenzano <[hidden email]> wrote:
>>>
>>> hi,
>>>
>>>> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email] <mailto:[hidden email]>> wrote:
>>>>
>>>> Another step would be to get a minimal parser not relying on
>>>> PetitParser.
>>>
>>> Let’s think differently: why not to include a tiny PetitParser?
>>> Then we can think on:
>>>
>>> - pillar sintax (better than just a restricted version)
>> *syntax*… sorry for spanish intromission ;)
>>
>> btw… not just outside the image (as readme).
>
> Yes, one of the points I want is to have the readme available in Pharo's Help Browser with rich content.
>
> Peter
>

Offray Vladimir Luna Cárdenas-2

Re: including Pillar in Pharo image by default

Hi,

I would go both suggestions of including both support for PetitParser
(Esteban's ) and Markdown (Tim's) . Having our own syntax for
documentation would make us more insular. In the same way that support
for Git is strategical in wider acceptance and visibility (even if we
use other DVCS like Fossil with Iceberg) in the coding front, support
for Markdown is similar in the documentation front. Pandoc's Markdown
has all features for professional book/thesis/article like documents
already and Markdown is widely used (like Git) in the code documentation

Cheers,

Offray

On 11/08/17 15:14, Tim Mackinnon wrote:

> If we are considering this, might we take the hard decision to actually support proper markdown (or even kramdown if we need more control).
>
> Pillar is a weird variant that isn't like everyone else - so i always have to think about how to do formatting.
>
> I know it's not nice, and lots of things are done in pillar - but could we convert them to be like everyone else? The readme.md that Peter is talking about is gfm markdown.'
>
> Tim
>
> Sent from my iPhone
>
>> On 11 Aug 2017, at 20:24, Peter Uhnak <[hidden email]> wrote:
>>
>>> On Fri, Aug 11, 2017 at 09:14:01PM +0200, Esteban Lorenzano wrote:
>>>
>>>> On 11 Aug 2017, at 21:10, Esteban Lorenzano <[hidden email]> wrote:
>>>>
>>>> hi,
>>>>
>>>>> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email] <mailto:[hidden email]>> wrote:
>>>>>
>>>>> Another step would be to get a minimal parser not relying on
>>>>> PetitParser.
>>>> Let’s think differently: why not to include a tiny PetitParser?
>>>> Then we can think on:
>>>>
>>>> - pillar sintax (better than just a restricted version)
>>> *syntax*… sorry for spanish intromission ;)
>>>
>>> btw… not just outside the image (as readme).
>> Yes, one of the points I want is to have the readme available in Pharo's Help Browser with rich content.
>>
>> Peter
>>
>
>

Peter Uhnak

Re: including Pillar in Pharo image by default

In reply to this post by Tim Mackinnon

A long time issue with Markdown was that there was no standardization (and when I used Pillar's MD export ~2 years ago it didn't work well).

However CommonMark ( http://spec.commonmark.org/0.28/ ) has become the de-facto standard, so it would make sense to support it bidirectionally with Pillar.

> The readme.md that Peter is talking about is gfm markdown

Well, technically it is just a CommonMark, as I am not using any github extensions.
(Github uses CommonMarks and adds just couple small extensions.)

Peter

Tim Mackinnon

Re: including Pillar in Pharo image by default

Of course, I/we recognise and appreciate all the work that's gone into docs in pillar - but I think it should be reasonably straightforward to write a converter as it is pretty closely related from what I have seen.

So I don't make the suggestion flippantly, and would want to help write a converter and get us to a common ground where we can differentiate on the aspects where we can excel.

Tim

Sent from my iPhone

> On 11 Aug 2017, at 23:21, Peter Uhnak <[hidden email]> wrote:
>
> A long time issue with Markdown was that there was no standardization (and when I used Pillar's MD export ~2 years ago it didn't work well).
>
> However CommonMark ( http://spec.commonmark.org/0.28/ ) has become the de-facto standard, so it would make sense to support it bidirectionally with Pillar.
>
>> The readme.md that Peter is talking about is gfm markdown
>
> Well, technically it is just a CommonMark, as I am not using any github extensions.
> (Github uses CommonMarks and adds just couple small extensions.)
>
> Peter
>

Tudor Girba-2

Re: including Pillar in Pharo image by default

In reply to this post by EstebanLM

Hi,

I would very much like this path. What would constitute tiny?

Cheers,
Doru

> On Aug 11, 2017, at 9:10 PM, Esteban Lorenzano <[hidden email]> wrote:
>
> hi,
>
>> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email]> wrote:
>>
>> Another step would be to get a minimal parser not relying on
>> PetitParser.
>
> Let’s think differently: why not to include a tiny PetitParser?
> Then we can think on:
>
> - pillar sintax (better than just a restricted version)
> - simplify other “small parsers” that are already on the image.
> - we provide a tool to o cool stuff (instead relying as always in regexp, etc.)
>
> cheers,
> Esteban

--
www.tudorgirba.com
www.feenk.com

"Beauty is where we see it."

EstebanLM

Re: including Pillar in Pharo image by default

> On 12 Aug 2017, at 12:46, Tudor Girba <[hidden email]> wrote:
>
> Hi,
>
> I would very much like this path. What would constitute tiny?

no idea, we need to think on it :)
but I see no point in create a new (even small) parser/scanner each time we need one. At the end you have several small parsers that repeat always same process when PetitParser is good for most of our problems (and if you need to improve it. you can always load PP compiler, etc.).

Esteban

>
> Cheers,
> Doru
>
>
>> On Aug 11, 2017, at 9:10 PM, Esteban Lorenzano <[hidden email]> wrote:
>>
>> hi,
>>
>>> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email]> wrote:
>>>
>>> Another step would be to get a minimal parser not relying on
>>> PetitParser.
>>
>> Let’s think differently: why not to include a tiny PetitParser?
>> Then we can think on:
>>
>> - pillar sintax (better than just a restricted version)
>> - simplify other “small parsers” that are already on the image.
>> - we provide a tool to o cool stuff (instead relying as always in regexp, etc.)
>>
>> cheers,
>> Esteban
>
> --
> www.tudorgirba.com
> www.feenk.com
>
> "Beauty is where we see it."
>
>
>
>
>

EstebanLM

Re: including Pillar in Pharo image by default

and btw, this kind of threads belongs to pharo-dev, not to pharo-users :)

Esteban

> On 12 Aug 2017, at 16:35, Esteban Lorenzano <[hidden email]> wrote:
>
>
>> On 12 Aug 2017, at 12:46, Tudor Girba <[hidden email]> wrote:
>>
>> Hi,
>>
>> I would very much like this path. What would constitute tiny?
>
> no idea, we need to think on it :)
> but I see no point in create a new (even small) parser/scanner each time we need one. At the end you have several small parsers that repeat always same process when PetitParser is good for most of our problems (and if you need to improve it. you can always load PP compiler, etc.).
>
> Esteban
>
>>
>> Cheers,
>> Doru
>>
>>
>>> On Aug 11, 2017, at 9:10 PM, Esteban Lorenzano <[hidden email]> wrote:
>>>
>>> hi,
>>>
>>>> On 11 Aug 2017, at 18:57, Cyril Ferlicot D. <[hidden email]> wrote:
>>>>
>>>> Another step would be to get a minimal parser not relying on
>>>> PetitParser.
>>>
>>> Let’s think differently: why not to include a tiny PetitParser?
>>> Then we can think on:
>>>
>>> - pillar sintax (better than just a restricted version)
>>> - simplify other “small parsers” that are already on the image.
>>> - we provide a tool to o cool stuff (instead relying as always in regexp, etc.)
>>>
>>> cheers,
>>> Esteban
>>
>> --
>> www.tudorgirba.com
>> www.feenk.com
>>
>> "Beauty is where we see it."
>>
>>
>>
>>
>>
>