Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Dimitris Chloupis]

I remember my 10 year self struggling learning to code basic back in 1988
on an Amstrad CPC 6128 with Locomotive Basic that required entering line
numbers before the code statement. IDEs , code editors and what else were
unheard of for me at least and even if they did exist would be nowhere near
the budget of a 10 year old.

Nowdays we have a ton of options, easy access to it, its free , its open
source, insanely powerful and even documented. You can even find Youtube
tutorials if too lazy to read text and also a ton of examples and snippets
to get you started.

I agree 1000% with your argument that "batteries included" version is super
important, its one of the major reason why Python exploded in popularity.

But yeah I turn to Hulk every time I hear these dreaded 3 words "too many
options". I am willing to endure this hell of too many options and even
pray it gets much much worse. But then it may be just me :)

On Thu, Aug 17, 2017 at 5:50 PM Dimitris Chloupis 
wrote:

> On Thu, Aug 17, 2017 at 4:25 PM Esteban Lorenzano 
> wrote:
>
>> hi Dimitris (good to see you around ;) ),
>>
>>
> Not going anywhere , just taking a break from Pharo :)
>
>
>> thing is… we want to improve our tools.
>>
>> great
>
>
>> And improve tools sometime means to add stuff (I’m not very happy with it
>> either, I would like to remove more than what I add, but it is like that).
>> For example, if we want to have good class comments, we need some markup
>> format, then the best thing we have is pillar and then we need a parser and
>> then the easiest to use thing we have is petit parser.
>>
>
> Yeah.. about that. See the issue is exactly what you just mentioned ,
> improvement. Sometimes improving makes things worse. Markdown class
> comments is an excellent example of this. You do the logical thing and
> offer markdown for class comments , you make the image more complex by
> adding a feature the average user would need but you greatly improve your
> ability for class comments.
>
> But your average user does not even bother adding one line comment on the
> main class what are the chances that will use markdown ? I am willing to
> bet big money on "close to zero chance". Hence you end up making things
> actually worse by adding code that your user wont use and instead
> increasing the complexity and his motivation to explore and fall in love
> with your project.
>
>
>> Which means we will need an image that have a core PetitParser and a
>> basic Pillar… so we can have proper documentation. Of course, maybe the
>> full pillar is too much (as it is the full petit parser, probably) so we
>> need to think carefully what we put inside and what we left outside. Same
>> is with everything: why to put athens, or glamour, or X, Y, Z. (things that
>> few people use, but are very important for our echosystem in general).
>>
>
> Well if few people use them, how they are important to your ecosystem ? If
> you talking about dependencies then that means the ecosystem is deeply
> flawed and we go back to the modularity question. I fail to see how Athens
> is important to the Pharo ecosystem , apart from Roassal people I have not
> seen anyone else using it consistently.
>
> If you were talking about the UFFI I would agree 100% but I cannot agree
> by any means that Athens is so important for Pharo that must be included in
> the image. By the way I am a graphics guy so biased in favour of Athens.
>
>
>>
>>
> Now, along with this “bloating” movements, that adds more elements to the
>> system and because of that increases essential complexity, we are working
>> on the other direction: bootstrapping and modularising Pharo so in the near
>> future (it should be done for P7 or as late to P8) you will be able to
>> create an image with the elements you want.
>>
>> Another thing we need to work on (but that’s in part documentation and in
>> part modifications to be done) we need to work on overall
>> availability/comprehensibility of the system.
>>
>> So… we need to continue adding things, in order to continue improving. We
>> also need to remove a lot of things that are duplicated or obsolete.
>> Pharo will always be “the deliverable we make” (including all things we
>> officially support as “part of it”)… but we are making possible that
>> everybody can also do “the Pharo they want”.
>>
>
> I can understand having a Parser in image to parse Pharo syntax and other
> things, big thumbs up for that I think that would justify the inclusion for
> the average user. Parsing and dealing with text is a big deal afterall.
>
> I am ok with offering a minimal image and not being the default one. As
> long it exists I am happy.
>

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Dimitris Chloupis]

On Thu, Aug 17, 2017 at 4:25 PM Esteban Lorenzano 
wrote:

> hi Dimitris (good to see you around ;) ),
>
>
Not going anywhere , just taking a break from Pharo :)


> thing is… we want to improve our tools.
>
> great


> And improve tools sometime means to add stuff (I’m not very happy with it
> either, I would like to remove more than what I add, but it is like that).
> For example, if we want to have good class comments, we need some markup
> format, then the best thing we have is pillar and then we need a parser and
> then the easiest to use thing we have is petit parser.
>

Yeah.. about that. See the issue is exactly what you just mentioned ,
improvement. Sometimes improving makes things worse. Markdown class
comments is an excellent example of this. You do the logical thing and
offer markdown for class comments , you make the image more complex by
adding a feature the average user would need but you greatly improve your
ability for class comments.

But your average user does not even bother adding one line comment on the
main class what are the chances that will use markdown ? I am willing to
bet big money on "close to zero chance". Hence you end up making things
actually worse by adding code that your user wont use and instead
increasing the complexity and his motivation to explore and fall in love
with your project.


> Which means we will need an image that have a core PetitParser and a basic
> Pillar… so we can have proper documentation. Of course, maybe the full
> pillar is too much (as it is the full petit parser, probably) so we need to
> think carefully what we put inside and what we left outside. Same is with
> everything: why to put athens, or glamour, or X, Y, Z. (things that few
> people use, but are very important for our echosystem in general).
>

Well if few people use them, how they are important to your ecosystem ? If
you talking about dependencies then that means the ecosystem is deeply
flawed and we go back to the modularity question. I fail to see how Athens
is important to the Pharo ecosystem , apart from Roassal people I have not
seen anyone else using it consistently.

If you were talking about the UFFI I would agree 100% but I cannot agree by
any means that Athens is so important for Pharo that must be included in
the image. By the way I am a graphics guy so biased in favour of Athens.


>
>
Now, along with this “bloating” movements, that adds more elements to the
> system and because of that increases essential complexity, we are working
> on the other direction: bootstrapping and modularising Pharo so in the near
> future (it should be done for P7 or as late to P8) you will be able to
> create an image with the elements you want.
>
> Another thing we need to work on (but that’s in part documentation and in
> part modifications to be done) we need to work on overall
> availability/comprehensibility of the system.
>
> So… we need to continue adding things, in order to continue improving. We
> also need to remove a lot of things that are duplicated or obsolete.
> Pharo will always be “the deliverable we make” (including all things we
> officially support as “part of it”)… but we are making possible that
> everybody can also do “the Pharo they want”.
>

I can understand having a Parser in image to parse Pharo syntax and other
things, big thumbs up for that I think that would justify the inclusion for
the average user. Parsing and dealing with text is a big deal afterall.

I am ok with offering a minimal image and not being the default one. As
long it exists I am happy.

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[p...@highoctane.be]

Got an architecture discussion with a client this morning and a lot of pain
they face is that there are too many choices out there on some platforms.

A batteries included distro with one good framework doing its thing nicely
if really a good thing to have.

It reduces the amount of choice and thus allows to focus on the business
problem instead of diving into endless technical discussions.

Phil

On Thu, Aug 17, 2017 at 3:32 PM, Esteban Lorenzano 
wrote:

>
> On 17 Aug 2017, at 15:24, Esteban Lorenzano  wrote:
>
> hi Dimitris (good to see you around ;) ),
>
> thing is… we want to improve our tools.
>
> And improve tools sometime means to add stuff (I’m not very happy with it
> either, I would like to remove more than what I add, but it is like that).
> For example, if we want to have good class comments, we need some markup
> format, then the best thing we have is pillar and then we need a parser and
> then the easiest to use thing we have is petit parser.
>
> Which means we will need an image that have a core PetitParser and a basic
> Pillar… so we can have proper documentation. Of course, maybe the full
> pillar is too much (as it is the full petit parser, probably) so we need to
> think carefully what we put inside and what we left outside. Same is with
> everything: why to put athens, or glamour, or X, Y, Z. (things that few
> people use, but are very important for our echosystem in general).
>
>
> a corollary of this is that, if we think well and we include the correct
> addition, then it’s exponential (having a real parser inside can easy a lot
> of developments, and can also lead to better tools).
>
>
> Now, along with this “bloating” movements, that adds more elements to the
> system and because of that increases essential complexity, we are working
> on the other direction: bootstrapping and modularising Pharo so in the near
> future (it should be done for P7 or as late to P8) you will be able to
> create an image with the elements you want.
>
> Another thing we need to work on (but that’s in part documentation and in
> part modifications to be done) we need to work on overall
> availability/comprehensibility of the system.
>
> So… we need to continue adding things, in order to continue improving. We
> also need to remove a lot of things that are duplicated or obsolete.
> Pharo will always be “the deliverable we make” (including all things we
> officially support as “part of it”)… but we are making possible that
> everybody can also do “the Pharo they want”.
>
> cheers,
> Esteban
>
> On 17 Aug 2017, at 14:01, Dimitris Chloupis  wrote:
>
> Is it really necessary ?
>
> I am more a modular guy , I would love to get an image that 0.1% the size
> of the current one and offer me a convenient package manager to install the
> tools I like.
>
> I have used Pillar ALOT probably more than any other Pharo library because
> I was doing Pharo documentation stuff.
> I have even used Pillar to build my website , yeah I know that is not the
> pupose of Pillar but with some modification and the addition of a tool I
> created (Octopus) it help me generate some portion of the website via
> mustache.
>
> Do I want Pillar in ? Nope
>
> Already the System Browser looks like a monster ready to eat you alive, I
> think we need to make the image a lot less threatening especially for
> newcomers. There is such thing as too much info.
>
> Pillar is in the Package Browser you just click and install it if you dont
> mind the wait because its a rather big install.
>
> On Thu, Aug 17, 2017 at 11:27 AM Peter Uhnak  wrote:
>
>> Even though I've initiated this discussion I kind of stopped reading
>> because everyone started discussing completely unrelated things...
>>
>> The initial point was "we are using github/gitlab more and more, lets
>> leverage it more"
>>
>> New, lets separate the concepts at play here...
>>
>> "Pillar - document model" - the workhorse of pillar and (imho) the most
>> important part of it, and also the part I am interested in being included.
>> Because then I can generate the document directly without using any
>> syntax...
>>
>> "Pillar - syntax" - we can have endless arguments whether the syntax is
>> good or bad, and imho that should be a separate discussion unrelated to the
>> Pillar inclusion
>>
>> "Markdown for unrelated usecases" - whether you can or cannot write your
>> thesis in markdown is really irelevant here
>>
>> "Markdown - export" - there will always be different variants and
>> extensions for Markdown, simply because the sites using markdown offer
>> different capabilities.
>>
>> Therefore the first focus should be on the most impact/effort ratio,
>> which is CommonMark (basically the only meaningful Markdown specification),
>> and GFM (which is a CommonMark with added tables and strikethrough).
>>
>> Adding support for more extensive export support, whether code related
>> (e.g. GitLab), or code unrelated (writing a thesis) should be a future
>> discussion, it is not relevant or too e

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

> On 17 Aug 2017, at 15:24, Esteban Lorenzano  wrote:
> 
> hi Dimitris (good to see you around ;) ),
> 
> thing is… we want to improve our tools. 
> 
> And improve tools sometime means to add stuff (I’m not very happy with it 
> either, I would like to remove more than what I add, but it is like that). 
> For example, if we want to have good class comments, we need some markup 
> format, then the best thing we have is pillar and then we need a parser and 
> then the easiest to use thing we have is petit parser.
> 
> Which means we will need an image that have a core PetitParser and a basic 
> Pillar… so we can have proper documentation. Of course, maybe the full pillar 
> is too much (as it is the full petit parser, probably) so we need to think 
> carefully what we put inside and what we left outside. Same is with 
> everything: why to put athens, or glamour, or X, Y, Z. (things that few 
> people use, but are very important for our echosystem in general).

a corollary of this is that, if we think well and we include the correct 
addition, then it’s exponential (having a real parser inside can easy a lot of 
developments, and can also lead to better tools).

> 
> Now, along with this “bloating” movements, that adds more elements to the 
> system and because of that increases essential complexity, we are working on 
> the other direction: bootstrapping and modularising Pharo so in the near 
> future (it should be done for P7 or as late to P8) you will be able to create 
> an image with the elements you want.
> 
> Another thing we need to work on (but that’s in part documentation and in 
> part modifications to be done) we need to work on overall 
> availability/comprehensibility of the system.
> 
> So… we need to continue adding things, in order to continue improving. We 
> also need to remove a lot of things that are duplicated or obsolete. 
> Pharo will always be “the deliverable we make” (including all things we 
> officially support as “part of it”)… but we are making possible that 
> everybody can also do “the Pharo they want”. 
> 
> cheers, 
> Esteban
> 
>> On 17 Aug 2017, at 14:01, Dimitris Chloupis > > wrote:
>> 
>> Is it really necessary ?
>> 
>> I am more a modular guy , I would love to get an image that 0.1% the size of 
>> the current one and offer me a convenient package manager to install the 
>> tools I like. 
>> 
>> I have used Pillar ALOT probably more than any other Pharo library because I 
>> was doing Pharo documentation stuff. 
>> I have even used Pillar to build my website , yeah I know that is not the 
>> pupose of Pillar but with some modification and the addition of a tool I 
>> created (Octopus) it help me generate some portion of the website via 
>> mustache. 
>> 
>> Do I want Pillar in ? Nope
>> 
>> Already the System Browser looks like a monster ready to eat you alive, I 
>> think we need to make the image a lot less threatening especially for 
>> newcomers. There is such thing as too much info. 
>> 
>> Pillar is in the Package Browser you just click and install it if you dont 
>> mind the wait because its a rather big install. 
>> 
>> On Thu, Aug 17, 2017 at 11:27 AM Peter Uhnak > > wrote:
>> Even though I've initiated this discussion I kind of stopped reading because 
>> everyone started discussing completely unrelated things...
>> 
>> The initial point was "we are using github/gitlab more and more, lets 
>> leverage it more"
>> 
>> New, lets separate the concepts at play here...
>> 
>> "Pillar - document model" - the workhorse of pillar and (imho) the most 
>> important part of it, and also the part I am interested in being included. 
>> Because then I can generate the document directly without using any syntax...
>> 
>> "Pillar - syntax" - we can have endless arguments whether the syntax is good 
>> or bad, and imho that should be a separate discussion unrelated to the 
>> Pillar inclusion
>> 
>> "Markdown for unrelated usecases" - whether you can or cannot write your 
>> thesis in markdown is really irelevant here
>> 
>> "Markdown - export" - there will always be different variants and extensions 
>> for Markdown, simply because the sites using markdown offer different 
>> capabilities.
>> 
>> Therefore the first focus should be on the most impact/effort ratio, which 
>> is CommonMark (basically the only meaningful Markdown specification), and 
>> GFM (which is a CommonMark with added tables and strikethrough).
>> 
>> Adding support for more extensive export support, whether code related (e.g. 
>> GitLab), or code unrelated (writing a thesis) should be a future discussion, 
>> it is not relevant or too effortful right now.
>> 
>> "Markdown - import" - I would love to be able to write markdown and have it 
>> imported into the Pillar document model, however that is imho moot point 
>> right now, as it can always be added later
>> 
>> 
>> To summarize:
>> 
>> * primary
>> * include pillar document model
>> 

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

hi Dimitris (good to see you around ;) ),

thing is… we want to improve our tools. 

And improve tools sometime means to add stuff (I’m not very happy with it 
either, I would like to remove more than what I add, but it is like that). For 
example, if we want to have good class comments, we need some markup format, 
then the best thing we have is pillar and then we need a parser and then the 
easiest to use thing we have is petit parser.

Which means we will need an image that have a core PetitParser and a basic 
Pillar… so we can have proper documentation. Of course, maybe the full pillar 
is too much (as it is the full petit parser, probably) so we need to think 
carefully what we put inside and what we left outside. Same is with everything: 
why to put athens, or glamour, or X, Y, Z. (things that few people use, but are 
very important for our echosystem in general).

Now, along with this “bloating” movements, that adds more elements to the 
system and because of that increases essential complexity, we are working on 
the other direction: bootstrapping and modularising Pharo so in the near future 
(it should be done for P7 or as late to P8) you will be able to create an image 
with the elements you want.

Another thing we need to work on (but that’s in part documentation and in part 
modifications to be done) we need to work on overall 
availability/comprehensibility of the system.

So… we need to continue adding things, in order to continue improving. We also 
need to remove a lot of things that are duplicated or obsolete. 
Pharo will always be “the deliverable we make” (including all things we 
officially support as “part of it”)… but we are making possible that everybody 
can also do “the Pharo they want”. 

cheers, 
Esteban

> On 17 Aug 2017, at 14:01, Dimitris Chloupis  wrote:
> 
> Is it really necessary ?
> 
> I am more a modular guy , I would love to get an image that 0.1% the size of 
> the current one and offer me a convenient package manager to install the 
> tools I like. 
> 
> I have used Pillar ALOT probably more than any other Pharo library because I 
> was doing Pharo documentation stuff. 
> I have even used Pillar to build my website , yeah I know that is not the 
> pupose of Pillar but with some modification and the addition of a tool I 
> created (Octopus) it help me generate some portion of the website via 
> mustache. 
> 
> Do I want Pillar in ? Nope
> 
> Already the System Browser looks like a monster ready to eat you alive, I 
> think we need to make the image a lot less threatening especially for 
> newcomers. There is such thing as too much info. 
> 
> Pillar is in the Package Browser you just click and install it if you dont 
> mind the wait because its a rather big install. 
> 
> On Thu, Aug 17, 2017 at 11:27 AM Peter Uhnak  > wrote:
> Even though I've initiated this discussion I kind of stopped reading because 
> everyone started discussing completely unrelated things...
> 
> The initial point was "we are using github/gitlab more and more, lets 
> leverage it more"
> 
> New, lets separate the concepts at play here...
> 
> "Pillar - document model" - the workhorse of pillar and (imho) the most 
> important part of it, and also the part I am interested in being included. 
> Because then I can generate the document directly without using any syntax...
> 
> "Pillar - syntax" - we can have endless arguments whether the syntax is good 
> or bad, and imho that should be a separate discussion unrelated to the Pillar 
> inclusion
> 
> "Markdown for unrelated usecases" - whether you can or cannot write your 
> thesis in markdown is really irelevant here
> 
> "Markdown - export" - there will always be different variants and extensions 
> for Markdown, simply because the sites using markdown offer different 
> capabilities.
> 
> Therefore the first focus should be on the most impact/effort ratio, which is 
> CommonMark (basically the only meaningful Markdown specification), and GFM 
> (which is a CommonMark with added tables and strikethrough).
> 
> Adding support for more extensive export support, whether code related (e.g. 
> GitLab), or code unrelated (writing a thesis) should be a future discussion, 
> it is not relevant or too effortful right now.
> 
> "Markdown - import" - I would love to be able to write markdown and have it 
> imported into the Pillar document model, however that is imho moot point 
> right now, as it can always be added later
> 
> 
> To summarize:
> 
> * primary
> * include pillar document model
> * include pillar syntax (as an import format)
> * add CommonMark+GFM export
> * secondary
> * discuss Pillar syntax if needed (in a _new_ thread)
> * discuss Markdown parser / importing CommonMark into Pillar model
> * any other discussion not pertinent here should go elsewhere
> 
> Peter
> 
> 
> On Wed, Aug 16, 2017 at 06:05:29PM +0200, Esteban Lorenzano wrote:
> > Hi,
> >
> > In general (you

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Dimitris Chloupis]

Is it really necessary ?

I am more a modular guy , I would love to get an image that 0.1% the size
of the current one and offer me a convenient package manager to install the
tools I like.

I have used Pillar ALOT probably more than any other Pharo library because
I was doing Pharo documentation stuff.
I have even used Pillar to build my website , yeah I know that is not the
pupose of Pillar but with some modification and the addition of a tool I
created (Octopus) it help me generate some portion of the website via
mustache.

Do I want Pillar in ? Nope

Already the System Browser looks like a monster ready to eat you alive, I
think we need to make the image a lot less threatening especially for
newcomers. There is such thing as too much info.

Pillar is in the Package Browser you just click and install it if you dont
mind the wait because its a rather big install.

On Thu, Aug 17, 2017 at 11:27 AM Peter Uhnak  wrote:

> Even though I've initiated this discussion I kind of stopped reading
> because everyone started discussing completely unrelated things...
>
> The initial point was "we are using github/gitlab more and more, lets
> leverage it more"
>
> New, lets separate the concepts at play here...
>
> "Pillar - document model" - the workhorse of pillar and (imho) the most
> important part of it, and also the part I am interested in being included.
> Because then I can generate the document directly without using any
> syntax...
>
> "Pillar - syntax" - we can have endless arguments whether the syntax is
> good or bad, and imho that should be a separate discussion unrelated to the
> Pillar inclusion
>
> "Markdown for unrelated usecases" - whether you can or cannot write your
> thesis in markdown is really irelevant here
>
> "Markdown - export" - there will always be different variants and
> extensions for Markdown, simply because the sites using markdown offer
> different capabilities.
>
> Therefore the first focus should be on the most impact/effort ratio, which
> is CommonMark (basically the only meaningful Markdown specification), and
> GFM (which is a CommonMark with added tables and strikethrough).
>
> Adding support for more extensive export support, whether code related
> (e.g. GitLab), or code unrelated (writing a thesis) should be a future
> discussion, it is not relevant or too effortful right now.
>
> "Markdown - import" - I would love to be able to write markdown and have
> it imported into the Pillar document model, however that is imho moot point
> right now, as it can always be added later
>
>
> To summarize:
>
> * primary
> * include pillar document model
> * include pillar syntax (as an import format)
> * add CommonMark+GFM export
> * secondary
> * discuss Pillar syntax if needed (in a _new_ thread)
> * discuss Markdown parser / importing CommonMark into Pillar model
> * any other discussion not pertinent here should go elsewhere
>
> Peter
>
>
> On Wed, Aug 16, 2017 at 06:05:29PM +0200, Esteban Lorenzano wrote:
> > Hi,
> >
> > In general (you all know me), I have the policy of “do not go alien just
> because” which means we do not need to reinvent the wheel all the time and
> we need to stick with what is already there and known (I have pushed many
> changes in pharo following this direction, iceberg being just the latest),
> but we need to keep also the basis of what we are (which means: when we
> need to stay alien, we need to embrace it too).
> >
> > Said that: while I would LOVE to have a markdown compatible format, the
> amount of effort put on pillar to make it *what we need* and is a format
> used not just for doing README.md but to write books, etc., then replacing
> it would be complicated.
> >
> > but… I think we can do pillar syntax more “markdown alike” (and we can
> even have a stripped-pillar with would be even more like md), I would
> salute such change.
> >
> > cheers,
> > Esteban
> >
> >
> > > On 15 Aug 2017, at 19:23, Eliot Miranda 
> wrote:
> > >
> > >
> > >
> > > On Aug 15, 2017, at 7:25 AM, Ben Coman  b...@openinworld.com>> wrote:
> > >
> > >>
> > >>
> > >> On Tue, Aug 15, 2017 at 12:54 AM, Esteban A. Maringolo <
> emaring...@gmail.com > wrote:
> > >> You hit several birds with one single mail.
> > >>
> > >> 2017-08-14 13:34 GMT-03:00 Tim Mackinnon  tim@testit.works>>:
> > >> > Jimmie et al. nicely reasoned arguments - and Doru's point about
> controlling
> > >> > the syntax is an interesting one that I hadn’t thought about.
> > >> >
> > >> > Personally, I find having too many similar syntax’s confusing -
> contributing
> > >> > to things is hard enough - having to remember that its !! Instead
> of ## and
> > >> > “” instead of ** is just frustrating for me.
> > >>
> > >> +1
> > >>
> > >> Not only for docs, most platforms like Slack/Discord share the syntax,
> > >> so now I'm getting "muscle memory" when typing literals using the
> > >> backtick (`) character, quoting with > or pasting sni

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Peter Uhnak]

Even though I've initiated this discussion I kind of stopped reading because 
everyone started discussing completely unrelated things...

The initial point was "we are using github/gitlab more and more, lets 
leverage it more"

New, lets separate the concepts at play here...

"Pillar - document model" - the workhorse of pillar and (imho) the most 
important part of it, and also the part I am interested in being included. 
Because then I can generate the document directly without using any syntax...

"Pillar - syntax" - we can have endless arguments whether the syntax is good or 
bad, and imho that should be a separate discussion unrelated to the Pillar 
inclusion

"Markdown for unrelated usecases" - whether you can or cannot write your thesis 
in markdown is really irelevant here

"Markdown - export" - there will always be different variants and extensions 
for Markdown, simply because the sites using markdown offer different 
capabilities.

Therefore the first focus should be on the most impact/effort ratio, which is 
CommonMark (basically the only meaningful Markdown specification), and GFM 
(which is a CommonMark with added tables and strikethrough).

Adding support for more extensive export support, whether code related (e.g. 
GitLab), or code unrelated (writing a thesis) should be a future discussion, it 
is not relevant or too effortful right now.

"Markdown - import" - I would love to be able to write markdown and have it 
imported into the Pillar document model, however that is imho moot point right 
now, as it can always be added later


To summarize:

* primary
* include pillar document model 
* include pillar syntax (as an import format)
* add CommonMark+GFM export
* secondary
* discuss Pillar syntax if needed (in a _new_ thread)
* discuss Markdown parser / importing CommonMark into Pillar model
* any other discussion not pertinent here should go elsewhere

Peter


On Wed, Aug 16, 2017 at 06:05:29PM +0200, Esteban Lorenzano wrote:
> Hi, 
> 
> In general (you all know me), I have the policy of “do not go alien just 
> because” which means we do not need to reinvent the wheel all the time and we 
> need to stick with what is already there and known (I have pushed many 
> changes in pharo following this direction, iceberg being just the latest), 
> but we need to keep also the basis of what we are (which means: when we need 
> to stay alien, we need to embrace it too).
> 
> Said that: while I would LOVE to have a markdown compatible format, the 
> amount of effort put on pillar to make it *what we need* and is a format used 
> not just for doing README.md but to write books, etc., then replacing it 
> would be complicated. 
> 
> but… I think we can do pillar syntax more “markdown alike” (and we can even 
> have a stripped-pillar with would be even more like md), I would salute such 
> change.
> 
> cheers,
> Esteban
> 
> 
> > On 15 Aug 2017, at 19:23, Eliot Miranda  wrote:
> > 
> > 
> > 
> > On Aug 15, 2017, at 7:25 AM, Ben Coman  > > wrote:
> > 
> >> 
> >> 
> >> On Tue, Aug 15, 2017 at 12:54 AM, Esteban A. Maringolo 
> >> mailto:emaring...@gmail.com>> wrote:
> >> You hit several birds with one single mail.
> >> 
> >> 2017-08-14 13:34 GMT-03:00 Tim Mackinnon  >> >:
> >> > Jimmie et al. nicely reasoned arguments - and Doru's point about 
> >> > controlling
> >> > the syntax is an interesting one that I hadn’t thought about.
> >> >
> >> > Personally, I find having too many similar syntax’s confusing - 
> >> > contributing
> >> > to things is hard enough - having to remember that its !! Instead of ## 
> >> > and
> >> > “” instead of ** is just frustrating for me.
> >> 
> >> +1
> >> 
> >> Not only for docs, most platforms like Slack/Discord share the syntax,
> >> so now I'm getting "muscle memory" when typing literals using the
> >> backtick (`) character, quoting with > or pasting snippets using ```
> >> 
> >> +1.  So I've posted this before...
> >>   
> >> https://www.joelonsoftware.com/2000/06/03/strategy-letter-iii-let-me-go-back/
> >>  
> >> 
> >> describing that "The only strategy in getting people to switch to your 
> >> product is to eliminate barriers"
> >> 
> >> But more... the best reason for Pillar to support a Markdown-ish syntax, 
> >> is that when we scratch-our-own-itch (nominally for Pillar) to build the 
> >> best damn markup-editor ever (because we can!) - if this happened to 
> >> support Markdown it can draw in Markdown-non-Pharo users (because its the 
> >> best editor ever!). Those users later want to make modifications, and now 
> >> have a *reason* to learn Pharo... ahHaA! now you see the cunning plan...
> >> 
> >> So don't just promote to people "hey come and play with this cool toy of 
> >> ours (Pharo)."
> >> Instead give them a toy they *already-want* (Markdown editor) and then 
> >> when they

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

Hi, 

In general (you all know me), I have the policy of “do not go alien just 
because” which means we do not need to reinvent the wheel all the time and we 
need to stick with what is already there and known (I have pushed many changes 
in pharo following this direction, iceberg being just the latest), but we need 
to keep also the basis of what we are (which means: when we need to stay alien, 
we need to embrace it too).

Said that: while I would LOVE to have a markdown compatible format, the amount 
of effort put on pillar to make it *what we need* and is a format used not just 
for doing README.md but to write books, etc., then replacing it would be 
complicated. 

but… I think we can do pillar syntax more “markdown alike” (and we can even 
have a stripped-pillar with would be even more like md), I would salute such 
change.

cheers,
Esteban


> On 15 Aug 2017, at 19:23, Eliot Miranda  wrote:
> 
> 
> 
> On Aug 15, 2017, at 7:25 AM, Ben Coman  > wrote:
> 
>> 
>> 
>> On Tue, Aug 15, 2017 at 12:54 AM, Esteban A. Maringolo > > wrote:
>> You hit several birds with one single mail.
>> 
>> 2017-08-14 13:34 GMT-03:00 Tim Mackinnon > >:
>> > Jimmie et al. nicely reasoned arguments - and Doru's point about 
>> > controlling
>> > the syntax is an interesting one that I hadn’t thought about.
>> >
>> > Personally, I find having too many similar syntax’s confusing - 
>> > contributing
>> > to things is hard enough - having to remember that its !! Instead of ## and
>> > “” instead of ** is just frustrating for me.
>> 
>> +1
>> 
>> Not only for docs, most platforms like Slack/Discord share the syntax,
>> so now I'm getting "muscle memory" when typing literals using the
>> backtick (`) character, quoting with > or pasting snippets using ```
>> 
>> +1.  So I've posted this before...
>>   
>> https://www.joelonsoftware.com/2000/06/03/strategy-letter-iii-let-me-go-back/
>>  
>> 
>> describing that "The only strategy in getting people to switch to your 
>> product is to eliminate barriers"
>> 
>> But more... the best reason for Pillar to support a Markdown-ish syntax, is 
>> that when we scratch-our-own-itch (nominally for Pillar) to build the best 
>> damn markup-editor ever (because we can!) - if this happened to support 
>> Markdown it can draw in Markdown-non-Pharo users (because its the best 
>> editor ever!). Those users later want to make modifications, and now have a 
>> *reason* to learn Pharo... ahHaA! now you see the cunning plan...
>> 
>> So don't just promote to people "hey come and play with this cool toy of 
>> ours (Pharo)."
>> Instead give them a toy they *already-want* (Markdown editor) and then when 
>> they want to change the batteries, they *need* to use our special 
>> screwdriver (Pharo). 
> 
> +1!
> 
>> 
>> cheers -ben
>>  
>> 
>> > Sure, maybe we were first with Pillar, but for me, lots of programming is 
>> > in
>> > other languages, and I use Smalltalk where I can, and a hybrid of multiple
>> > languages and projects is often the reality - so a lowest common 
>> > denominator
>> > of Markdown is just easier. The fact that we are quite close to what our
>> > colleagues in other languages use (regardless of what Python has chosen), 
>> > is
>> > quite interesting.
>> 
>> This helps building "bridges" with other communities. 
>>  
>> 
>> 
>> 
>>  
>> 
>> The language as a means of exchange is always the lowest common denominator.
>> As long as it's "efficient enough" then I vote to use what other
>> communities use.
>> 
>> > That said, if the community wants to stick to its gun’s thats fine - I will
>> > probably still investigate how to use Commonmark for myself, and will still
>> > contribute to Pillar docs where I can (and curse history) - but I think we
>> > are long better off trying to join emerging standards where we can
>> > particularly if they aren’t our core language thing. And it just makes it
>> > less frictionless for ourselves and newcomers.
>> 
>> The "Not Invented Here" syndrome is strong among Smalltalkers, it's
>> important to be aware of this bias and think more than once whether
>> eating our own dogfood adds value to the core of what Pharo brings.
>> 
>> I think we missed some good years fighting with our own SCM and in the
>> end git (or any other file based SCM) prevailed, even when it has
>> limitations.
>> 
>> Pareto (80-20) for everything non-core business should be a guide.
>> 
>> > Of course, if we were to move, we would need to translate a lot of quality
>> > docs to a new format - but I would be up for contributing to that if that
>> > was a deciding factor.
>> 
>> There are some Markdown exporters AFAIK, or it could be written.
>> 
>> 
>> Esteban A. Maringolo

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Eliot Miranda]

> On Aug 15, 2017, at 7:25 AM, Ben Coman  wrote:
> 
> 
> 
>> On Tue, Aug 15, 2017 at 12:54 AM, Esteban A. Maringolo 
>>  wrote:
>> You hit several birds with one single mail.
>> 
>> 2017-08-14 13:34 GMT-03:00 Tim Mackinnon :
>> > Jimmie et al. nicely reasoned arguments - and Doru's point about 
>> > controlling
>> > the syntax is an interesting one that I hadn’t thought about.
>> >
>> > Personally, I find having too many similar syntax’s confusing - 
>> > contributing
>> > to things is hard enough - having to remember that its !! Instead of ## and
>> > “” instead of ** is just frustrating for me.
>> 
>> +1
>> 
>> Not only for docs, most platforms like Slack/Discord share the syntax,
>> so now I'm getting "muscle memory" when typing literals using the
>> backtick (`) character, quoting with > or pasting snippets using ```
> 
> +1.  So I've posted this before...
>   
> https://www.joelonsoftware.com/2000/06/03/strategy-letter-iii-let-me-go-back/
> describing that "The only strategy in getting people to switch to your 
> product is to eliminate barriers"
> 
> But more... the best reason for Pillar to support a Markdown-ish syntax, is 
> that when we scratch-our-own-itch (nominally for Pillar) to build the best 
> damn markup-editor ever (because we can!) - if this happened to support 
> Markdown it can draw in Markdown-non-Pharo users (because its the best editor 
> ever!). Those users later want to make modifications, and now have a *reason* 
> to learn Pharo... ahHaA! now you see the cunning plan...
> 
> So don't just promote to people "hey come and play with this cool toy of ours 
> (Pharo)."
> Instead give them a toy they *already-want* (Markdown editor) and then when 
> they want to change the batteries, they *need* to use our special screwdriver 
> (Pharo). 

+1!

> 
> cheers -ben
>  
>> 
>> > Sure, maybe we were first with Pillar, but for me, lots of programming is 
>> > in
>> > other languages, and I use Smalltalk where I can, and a hybrid of multiple
>> > languages and projects is often the reality - so a lowest common 
>> > denominator
>> > of Markdown is just easier. The fact that we are quite close to what our
>> > colleagues in other languages use (regardless of what Python has chosen), 
>> > is
>> > quite interesting.
>> 
>> This helps building "bridges" with other communities. 
>>  
> 
> 
> 
>  
>> 
>> The language as a means of exchange is always the lowest common denominator.
>> As long as it's "efficient enough" then I vote to use what other
>> communities use.
>> 
>> > That said, if the community wants to stick to its gun’s thats fine - I will
>> > probably still investigate how to use Commonmark for myself, and will still
>> > contribute to Pillar docs where I can (and curse history) - but I think we
>> > are long better off trying to join emerging standards where we can
>> > particularly if they aren’t our core language thing. And it just makes it
>> > less frictionless for ourselves and newcomers.
>> 
>> The "Not Invented Here" syndrome is strong among Smalltalkers, it's
>> important to be aware of this bias and think more than once whether
>> eating our own dogfood adds value to the core of what Pharo brings.
>> 
>> I think we missed some good years fighting with our own SCM and in the
>> end git (or any other file based SCM) prevailed, even when it has
>> limitations.
>> 
>> Pareto (80-20) for everything non-core business should be a guide.
>> 
>> > Of course, if we were to move, we would need to translate a lot of quality
>> > docs to a new format - but I would be up for contributing to that if that
>> > was a deciding factor.
>> 
>> There are some Markdown exporters AFAIK, or it could be written.
>> 
>> 
>> Esteban A. Maringolo
>> 
> 

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Ben Coman]

On Tue, Aug 15, 2017 at 12:54 AM, Esteban A. Maringolo  wrote:

> You hit several birds with one single mail.
>
> 2017-08-14 13:34 GMT-03:00 Tim Mackinnon :
> > Jimmie et al. nicely reasoned arguments - and Doru's point about
> controlling
> > the syntax is an interesting one that I hadn’t thought about.
> >
> > Personally, I find having too many similar syntax’s confusing -
> contributing
> > to things is hard enough - having to remember that its !! Instead of ##
> and
> > “” instead of ** is just frustrating for me.
>
> +1


> Not only for docs, most platforms like Slack/Discord share the syntax,
> so now I'm getting "muscle memory" when typing literals using the
> backtick (`) character, quoting with > or pasting snippets using ```
>

+1.  So I've posted this before...

https://www.joelonsoftware.com/2000/06/03/strategy-letter-iii-let-me-go-back/
describing that "The only strategy in getting people to switch to your
product is to eliminate barriers"

But more... the best reason for Pillar to support a Markdown-ish syntax, is
that when we scratch-our-own-itch (nominally for Pillar) to build the best
damn markup-editor ever (because we can!) - if this happened to support
Markdown it can draw in Markdown-non-Pharo users (because its the best
editor ever!). Those users later want to make modifications, and now have a
*reason* to learn Pharo... ahHaA! now you see the cunning plan...

So don't just promote to people "hey come and play with this cool toy of
ours (Pharo)."
Instead give them a toy they *already-want* (Markdown editor) and then when
they want to change the batteries, they *need* to use our special
screwdriver (Pharo).

cheers -ben


>
> > Sure, maybe we were first with Pillar, but for me, lots of programming
> is in
> > other languages, and I use Smalltalk where I can, and a hybrid of
> multiple
> > languages and projects is often the reality - so a lowest common
> denominator
> > of Markdown is just easier. The fact that we are quite close to what our
> > colleagues in other languages use (regardless of what Python has
> chosen), is
> > quite interesting.
>
> This helps building "bridges" with other communities.








>
> The language as a means of exchange is always the lowest common
> denominator.
> As long as it's "efficient enough" then I vote to use what other
> communities use.
>
> > That said, if the community wants to stick to its gun’s thats fine - I
> will
> > probably still investigate how to use Commonmark for myself, and will
> still
> > contribute to Pillar docs where I can (and curse history) - but I think
> we
> > are long better off trying to join emerging standards where we can
> > particularly if they aren’t our core language thing. And it just makes it
> > less frictionless for ourselves and newcomers.
>
> The "Not Invented Here" syndrome is strong among Smalltalkers, it's
> important to be aware of this bias and think more than once whether
> eating our own dogfood adds value to the core of what Pharo brings.
>
> I think we missed some good years fighting with our own SCM and in the
> end git (or any other file based SCM) prevailed, even when it has
> limitations.
>
> Pareto (80-20) for everything non-core business should be a guide.
>
> > Of course, if we were to move, we would need to translate a lot of
> quality
> > docs to a new format - but I would be up for contributing to that if that
> > was a deciding factor.
>
> There are some Markdown exporters AFAIK, or it could be written.
>
>
> Esteban A. Maringolo
>
>

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Tudor Girba]

Hi,


> On Aug 14, 2017, at 3:51 PM, Esteban Lorenzano  wrote:
> 
> again, I think this is a discussion for pharo-dev. 
> Please keep it there (is good discussion, btw ;) ).
> 
> What about my proposal of including a tiny PetitParser? (it would be 
> “InfimeParser” :P)

I am for it, but there will be some work to repackage PetitParser2.

Also, I notice that the French lessons start to pay off :)

Cheers,
Doru


> Esteban
> 
> 
>> On 14 Aug 2017, at 11:10, Tudor Girba  wrote:
>> 
>> Hi Tim,
>> 
>> The main benefit of relying on Pillar is that we control its syntax and can 
>> easily extend it for our purposes. Also, there was quite a bit of 
>> engineering invested in it, and even though we still need to improve it, 
>> there exists a pipeline that allows people to quickly publish books.
>> 
>> The figure embedding problem is one example of the need to customize the 
>> syntax and behavior, but this extensibility will become even more important 
>> for supporting the idea of moving the documentation inside the image. For 
>> example, the ability to refer to a class, method or other artifacts will be 
>> quite relevant soon especially that the editor will be able to embed 
>> advanced elements inside the text.
>> 
>> Cheers,
>> Doru
>> 
>> 
>>> On Aug 14, 2017, at 10:46 AM, Tim Mackinnon  wrote:
>>> 
>>> Hi Stef - I think your’s is a fair requirement (in fact I hit something 
>>> similar when doing a static website using a JS markdown framework - and 
>>> this is why I mentioned Kramdown which adds a few extras to regular 
>>> markdown - but it feels like it goes a bit too far).
>>> 
>>> My next item on my learning todo list was to try and replace that JS 
>>> generator with something from Smalltalk - so I think we can possibly come 
>>> up with something that ticks all the right boxes (I’d like to try anyway).
>>> 
>>> I’ll keep working away on it and compare notes with you. I think with 
>>> Pillar, it was more that things like headers, bold and italics are similar 
>>> concepts but just use different characters - so I keep typing the wrong 
>>> thing and getting frustrated particularly when we embrace Git and readme.md 
>>> is in markdown.
>>> 
>>> 
>>> Tim
>>> 
 On 13 Aug 2017, at 20:08, Stephane Ducasse  wrote:
 
 Hi tim
 
 I personally do not care much about the syntax but I care about what I
 can do with it
 (ref, cite, ... )
 I cannot write books in markdown because reference to figures!!
 were missing.
 
 And of course a parser because markdown is not really nice to parse
 and I will not write a parser because I have something else to do. I
 want to make pillar smaller, simpler, nicer.
 
 Now if someone come up with a parser that parse for REAL a markdown
 that can be extended with decent behavior (figure reference, section
 reference, cite) and can be extended because there are many things
 that can be nice to have (for example I want to be able to write the
 example below) and emit a PillarModel (AST) we can talk to have
 another syntax for Pillar but not before.
 
 [[[test
 2+3
>>> 5
 ]]]
 
 and being able to verify that the doc is in sync.
 
 
 Stef
 
 
 
 On Sat, Aug 12, 2017 at 12:37 AM, Tim Mackinnon  wrote:
> 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  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
>> 
> 
> 
 
>>> 
>>> 
>> 
>> --
>> www.tudorgirba.com
>> www.feenk.com 
>> 
>> “Live like you mean it."
>> 
>> 
> 
> 

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

"To lead is not to demand things, it is to make them happen."

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Jimmie Houchin]

Thank Tim,

My primary reason to submit the message was not to necessarily persuade 
you per se. But to provide something historical for the mailing list as 
this can be a recurring subject. Why use Pillar markup instead of 
???(insert personal favorite).


If Pharo were to decide on a different markup language. The question 
would still be which one, why and then how do we proceed. Then our 
extensions may not be accepted by the greater body of users of said 
markup. We would still be contributing to the fragmentation of markup. 
As far as familiarity, I don't know. And familiarity with what. I do not 
find that reStructuredText to be similar to Markdown.


It would stop people from asking why we aren't using Markdown. But it 
wouldn't prevent others. Why aren't we using GFM Markdown, or Kramdown 
or Commonmark or ...? Why aren't we using YAML or reST or AsciiDoc or 
insert latest greatest creation markup or current flavor of the moment. 
Which is why I wanted to point out that there is no consensus among 
users of markup languages. At least I do not see one. Nor do I believe 
that we have seen the end of creation of new markup languages.


I understand the difficulty, though I do not suffer from it as I have 
not mastered any of those other languages. I have been using 
Squeak/Pharo for a long time. I struggle when I look at those other 
languages. To me they are the foreign ones.


And I do not see these emerging standards you refer to. When we see 
Python, Ruby, Perl, C++, various projects, etc. communities having 
consensus on a common markup for documentation. Then I see an emerging 
standard. Until then it seems to possibly be an emerging standard for a 
particular markup language which is among the set of markup languages.


If we were the only language and development environment doing our own 
thing. Then we might have a very good reason to talk. But we are not. 
Python with its enormous community does its own thing. I don't know that 
other languages have a consensus for markup for documentation except for 
Python and Pharo.


While writing this email I went and discovered that even GitHub is not 
dogmatic about the subject. Obviously they have an opinion. But they 
permit multiple markup languages. Quite possibly someone could write a 
Pillar tool for GitHub to use and then we could just submit 
Readme.pillar for our projects. :)


https://github.com/github/markup

Shows that GitHub allows for .markdown, .mdown, .mkdn, .md; .textile; 
.rdoc; .org; .creole; .mediawiki, .wiki; .rst; .asciidoc, .adoc, .asc; 
.pod.  So it seems that there are many communities on GitHub who prefer 
their own markup and tools.


We could possibly write the Pillar tool for GitHub or an exporter to the 
preferred markup language of the above.


This author provides arguments for using reStructuredText over Markdown 
for GitHub documents. Citing deficiencies in Markdown and expressiveness 
in reST.


https://gist.github.com/dupuy/1855764

So again. I am just not seeing a consensus around any emerging standard 
for "the markup language".


At the same time if you are desirous of writing in Commonmark in your 
text editor. Can you not write conversion software that goes from 
Commonmark to Pillar? Thus, meeting want you want and what we require? 
If you were to do so, you would definitely have a good understanding of 
the differences in philosophy and capabilities of each. Just a thought.


Any way, thanks for engaging in the conversation. I wasn't targeting you 
personally, but rather the topic. You are not alone in your thinking. 
The Pharo community is not alone in its thinking either.


Thanks.

Jimmie




On 08/14/2017 11:34 AM, Tim Mackinnon wrote:
Jimmie et al. nicely reasoned arguments - and Doru's point about 
controlling the syntax is an interesting one that I hadn’t thought about.


Personally, I find having too many similar syntax’s confusing - 
contributing to things is hard enough - having to remember that its !! 
Instead of ## and “” instead of ** is just frustrating for me.


My vote would be what Peter suggested - use 
http://spec.commonmark.org/0.28/ and put our Pillar extensions back on 
top for things that Stef was mentioning. (I think that’s what I’ve 
understood gfm markdown is).


Sure, maybe we were first with Pillar, but for me, lots of programming 
is in other languages, and I use Smalltalk where I can, and a hybrid 
of multiple languages and projects is often the reality - so a lowest 
common denominator of Markdown is just easier. The fact that we are 
quite close to what our colleagues in other languages use (regardless 
of what Python has chosen), is quite interesting.


That said, if the community wants to stick to its gun’s thats fine - I 
will probably still investigate how to use Commonmark for myself, and 
will still contribute to Pillar docs where I can (and curse history) - 
but I think we are long better off trying to join emerging standards 
where we can particularly if they aren’t 

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Stephane Ducasse]

We can change the syntax or propose an alternate one as soon as it
uses the same internal structure.

Stef

On Mon, Aug 14, 2017 at 6:34 PM, Tim Mackinnon  wrote:
> Jimmie et al. nicely reasoned arguments - and Doru's point about controlling
> the syntax is an interesting one that I hadn’t thought about.
>
> Personally, I find having too many similar syntax’s confusing - contributing
> to things is hard enough - having to remember that its !! Instead of ## and
> “” instead of ** is just frustrating for me.
>
> My vote would be what Peter suggested - use http://spec.commonmark.org/0.28/
> and put our Pillar extensions back on top for things that Stef was
> mentioning. (I think that’s what I’ve understood gfm markdown is).
>
> Sure, maybe we were first with Pillar, but for me, lots of programming is in
> other languages, and I use Smalltalk where I can, and a hybrid of multiple
> languages and projects is often the reality - so a lowest common denominator
> of Markdown is just easier. The fact that we are quite close to what our
> colleagues in other languages use (regardless of what Python has chosen), is
> quite interesting.
>
> That said, if the community wants to stick to its gun’s thats fine - I will
> probably still investigate how to use Commonmark for myself, and will still
> contribute to Pillar docs where I can (and curse history) - but I think we
> are long better off trying to join emerging standards where we can
> particularly if they aren’t our core language thing. And it just makes it
> less frictionless for ourselves and newcomers.
>
> Of course, if we were to move, we would need to translate a lot of quality
> docs to a new format - but I would be up for contributing to that if that
> was a deciding factor.
>
> Tim
>
>
> On 14 Aug 2017, at 16:41, Jimmie Houchin  wrote:
>
> TL;DR
>
> Main points:
> Their is no universally accepted markup language.
> Other communities use their own markup and  tools and their markup and tools
> choice is not determine by other communities decisions.
> We need a language and tool chain that we can control and maintain which
> accomplishes our goals.
> Our language and tools already exist and have existed for longer than most
> of the other markup languages. Of course they existed in various different
> forms over the years and have evolved into what they currently are.
> It might be nice to have a GFM Markdown exporter from Pillar for GitHub
> projects.
>
>
> I just want to comment on the fact that there is no universal markup
> language that every development community has settled upon. Making Markdown
> or some variant the markup language for Pharo only aligns us with a certain
> part of the development community. Even Markdown is not unified as is
> evident by the discussion.
>
> It is true that GitHub uses their variant of Markdown. And as long as we use
> GitHub we will need to use their variant for documents that reside on their
> system.
>
> However as a significant counter example to lets all use gfm Markdown, is
> the Python community and their documentation.
>
> https://docs.python.org/devguide/documenting.html
> """
> 7. Documenting Python
> The Python language has a substantial body of documentation, much of it
> contributed by various authors. The markup used for the Python documentation
> is reStructuredText, developed by the docutils project, amended by custom
> directives and using a toolset named Sphinx to post-process the HTML output.
>
> This document describes the style guide for our documentation as well as the
> custom reStructuredText markup introduced by Sphinx to support Python
> documentation and how it should be used.
>
> The documentation in HTML, PDF or EPUB format is generated from text files
> written using the reStructuredText format and contained in the CPython Git
> repository.
> """
>
> So the Python community uses their own markup language and their own tool
> chain. So therefore, it is not wrong for a community to go their own way,
> for their own reasons. Even within the conventional file based languages
> such as Python.
>
> The fact that you have tools such as Pandoc, suggest that there is not true
> uniformity or unanimity among developers as to the best markup language or
> tool chain.
>
> I believe that a language that we can control and maintain is better than
> adopting some other foreign markup language that is neither better, nor
> unanimously used by all. That would ultimately potentially require
> extensions to accomplish our goals. Then we would be maintaining someone
> else's language with our extensions that may or may not be accepted by the
> larger community. This does not prevent but rather encourages fragmentation
> of the existing Markdown.
>
> Regardless, Pillar markup already exists. The tools in Pharo already
> understand it. Should someone desire to use Pharo which is far more
> different from Python/Ruby/etc. than Pillar syntax is from Markdown. Then it
> should be worth their effort to learn our too

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban A. Maringolo]

You hit several birds with one single mail.

2017-08-14 13:34 GMT-03:00 Tim Mackinnon :
> Jimmie et al. nicely reasoned arguments - and Doru's point about controlling
> the syntax is an interesting one that I hadn’t thought about.
>
> Personally, I find having too many similar syntax’s confusing - contributing
> to things is hard enough - having to remember that its !! Instead of ## and
> “” instead of ** is just frustrating for me.

+1

Not only for docs, most platforms like Slack/Discord share the syntax,
so now I'm getting "muscle memory" when typing literals using the
backtick (`) character, quoting with > or pasting snippets using ```

> Sure, maybe we were first with Pillar, but for me, lots of programming is in
> other languages, and I use Smalltalk where I can, and a hybrid of multiple
> languages and projects is often the reality - so a lowest common denominator
> of Markdown is just easier. The fact that we are quite close to what our
> colleagues in other languages use (regardless of what Python has chosen), is
> quite interesting.

This helps building "bridges" with other communities.

The language as a means of exchange is always the lowest common denominator.
As long as it's "efficient enough" then I vote to use what other
communities use.

> That said, if the community wants to stick to its gun’s thats fine - I will
> probably still investigate how to use Commonmark for myself, and will still
> contribute to Pillar docs where I can (and curse history) - but I think we
> are long better off trying to join emerging standards where we can
> particularly if they aren’t our core language thing. And it just makes it
> less frictionless for ourselves and newcomers.

The "Not Invented Here" syndrome is strong among Smalltalkers, it's
important to be aware of this bias and think more than once whether
eating our own dogfood adds value to the core of what Pharo brings.

I think we missed some good years fighting with our own SCM and in the
end git (or any other file based SCM) prevailed, even when it has
limitations.

Pareto (80-20) for everything non-core business should be a guide.

> Of course, if we were to move, we would need to translate a lot of quality
> docs to a new format - but I would be up for contributing to that if that
> was a deciding factor.

There are some Markdown exporters AFAIK, or it could be written.


Esteban A. Maringolo

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Tim Mackinnon]

Jimmie et al. nicely reasoned arguments - and Doru's point about controlling 
the syntax is an interesting one that I hadn’t thought about.

Personally, I find having too many similar syntax’s confusing - contributing to 
things is hard enough - having to remember that its !! Instead of ## and “” 
instead of ** is just frustrating for me.

My vote would be what Peter suggested - use http://spec.commonmark.org/0.28/ 
 and put our Pillar extensions back on top 
for things that Stef was mentioning. (I think that’s what I’ve understood gfm 
markdown is).

Sure, maybe we were first with Pillar, but for me, lots of programming is in 
other languages, and I use Smalltalk where I can, and a hybrid of multiple 
languages and projects is often the reality - so a lowest common denominator of 
Markdown is just easier. The fact that we are quite close to what our 
colleagues in other languages use (regardless of what Python has chosen), is 
quite interesting. 

That said, if the community wants to stick to its gun’s thats fine - I will 
probably still investigate how to use Commonmark for myself, and will still 
contribute to Pillar docs where I can (and curse history) - but I think we are 
long better off trying to join emerging standards where we can particularly if 
they aren’t our core language thing. And it just makes it less frictionless for 
ourselves and newcomers.

Of course, if we were to move, we would need to translate a lot of quality docs 
to a new format - but I would be up for contributing to that if that was a 
deciding factor.

Tim


> On 14 Aug 2017, at 16:41, Jimmie Houchin  wrote:
> 
> TL;DR
> 
> Main points:
> Their is no universally accepted markup language.
> Other communities use their own markup and  tools and their markup and tools 
> choice is not determine by other communities decisions.
> We need a language and tool chain that we can control and maintain which 
> accomplishes our goals.
> Our language and tools already exist and have existed for longer than most of 
> the other markup languages. Of course they existed in various different forms 
> over the years and have evolved into what they currently are.
> It might be nice to have a GFM Markdown exporter from Pillar for GitHub 
> projects.
> 
> 
> I just want to comment on the fact that there is no universal markup language 
> that every development community has settled upon. Making Markdown or some 
> variant the markup language for Pharo only aligns us with a certain part of 
> the development community. Even Markdown is not unified as is evident by the 
> discussion.
> 
> It is true that GitHub uses their variant of Markdown. And as long as we use 
> GitHub we will need to use their variant for documents that reside on their 
> system.
> 
> However as a significant counter example to lets all use gfm Markdown, is the 
> Python community and their documentation.
> 
> https://docs.python.org/devguide/documenting.html
> """
> 7. Documenting Python
> The Python language has a substantial body of documentation, much of it 
> contributed by various authors. The markup used for the Python documentation 
> is reStructuredText, developed by the docutils project, amended by custom 
> directives and using a toolset named Sphinx to post-process the HTML output.
> 
> This document describes the style guide for our documentation as well as the 
> custom reStructuredText markup introduced by Sphinx to support Python 
> documentation and how it should be used.
> 
> The documentation in HTML, PDF or EPUB format is generated from text files 
> written using the reStructuredText format and contained in the CPython Git 
> repository.
> """
> 
> So the Python community uses their own markup language and their own tool 
> chain. So therefore, it is not wrong for a community to go their own way, for 
> their own reasons. Even within the conventional file based languages such as 
> Python.
> 
> The fact that you have tools such as Pandoc, suggest that there is not true 
> uniformity or unanimity among developers as to the best markup language or 
> tool chain.
> 
> I believe that a language that we can control and maintain is better than 
> adopting some other foreign markup language that is neither better, nor 
> unanimously used by all. That would ultimately potentially require extensions 
> to accomplish our goals. Then we would be maintaining someone else's language 
> with our extensions that may or may not be accepted by the larger community. 
> This does not prevent but rather encourages fragmentation of the existing 
> Markdown.
> 
> Regardless, Pillar markup already exists. The tools in Pharo already 
> understand it. Should someone desire to use Pharo which is far more different 
> from Python/Ruby/etc. than Pillar syntax is from Markdown. Then it should be 
> worth their effort to learn our tools.
> 
> Pillar markup is older than Markdown, etc. It's history begins in SmallWiki. 
> It isn't as if we jumped up an

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Jimmie Houchin]

TL;DR

Main points:
Their is no universally accepted markup language.
Other communities use their own markup and  tools and their markup and 
tools choice is not determine by other communities decisions.
We need a language and tool chain that we can control and maintain which 
accomplishes our goals.
Our language and tools already exist and have existed for longer than 
most of the other markup languages. Of course they existed in various 
different forms over the years and have evolved into what they currently 
are.
It might be nice to have a GFM Markdown exporter from Pillar for GitHub 
projects.



I just want to comment on the fact that there is no universal markup 
language that every development community has settled upon. Making 
Markdown or some variant the markup language for Pharo only aligns us 
with a certain part of the development community. Even Markdown is not 
unified as is evident by the discussion.


It is true that GitHub uses their variant of Markdown. And as long as we 
use GitHub we will need to use their variant for documents that reside 
on their system.


However as a significant counter example to lets all use gfm Markdown, 
is the Python community and their documentation.


https://docs.python.org/devguide/documenting.html
"""
7. Documenting Python
The Python language has a substantial body of documentation, much of it 
contributed by various authors. The markup used for the Python 
documentation is reStructuredText, developed by the docutils project, 
amended by custom directives and using a toolset named Sphinx to 
post-process the HTML output.


This document describes the style guide for our documentation as well as 
the custom reStructuredText markup introduced by Sphinx to support 
Python documentation and how it should be used.


The documentation in HTML, PDF or EPUB format is generated from text 
files written using the reStructuredText format and contained in the 
CPython Git repository.

"""

So the Python community uses their own markup language and their own 
tool chain. So therefore, it is not wrong for a community to go their 
own way, for their own reasons. Even within the conventional file based 
languages such as Python.


The fact that you have tools such as Pandoc, suggest that there is not 
true uniformity or unanimity among developers as to the best markup 
language or tool chain.


I believe that a language that we can control and maintain is better 
than adopting some other foreign markup language that is neither better, 
nor unanimously used by all. That would ultimately potentially require 
extensions to accomplish our goals. Then we would be maintaining someone 
else's language with our extensions that may or may not be accepted by 
the larger community. This does not prevent but rather encourages 
fragmentation of the existing Markdown.


Regardless, Pillar markup already exists. The tools in Pharo already 
understand it. Should someone desire to use Pharo which is far more 
different from Python/Ruby/etc. than Pillar syntax is from Markdown. 
Then it should be worth their effort to learn our tools.


Pillar markup is older than Markdown, etc. It's history begins in 
SmallWiki. It isn't as if we jumped up and decided to create something 
new in order to be different. Our markup and tools are older. They (and 
others) are the ones that decided to do their own markup and tools. And 
it is okay that they did so. Nothing wrong with doing so. Every 
community has the right to what they believe is best for their 
community. Even if other communities disagree.


The ability to control and maintain is highly valuable. We can 
understand what our requirements are for today. But we can not know what 
the requirements are in the future. Nor can we know that Markdown or 
whomever will have such requirements when they appear. It is easy to see 
in the beginning with the Squeak Wiki syntax to the now Pillar syntax, 
changes that have been made to accommodate new requirements as they 
became known. We need to maintain that ability. Sure we would reserve 
the right to do so in any language we adopt. But the then current 
standard bearer of said language would determine whether what we do is 
acceptable and incorporate or whether we are then in fact adding to 
their fragmentation. Pillar is ours. There is not fragmentation when we 
evolve.


However, since we have made a decision to use GitHub and GitHub has made 
a decision to use their own GFM Markdown. It might be nice to have a GFM 
Markdown exporter from Pillar for GitHub projects. This way we can use 
our own tools and markup language to accomplish whatever we want to 
accomplish. Including generating a Readme.md for our GitHub projects.


Just wanted to toss out this simple opinion and facts about the situation.

Jimmie


On 08/14/2017 04:10 AM, Tudor Girba wrote:

Hi Tim,

The main benefit of relying on Pillar is that we control its syntax and can 
easily extend it for our purposes. Also, there was quite a bi

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

again, I think this is a discussion for pharo-dev. 
Please keep it there (is good discussion, btw ;) ).

What about my proposal of including a tiny PetitParser? (it would be 
“InfimeParser” :P)

Esteban


> On 14 Aug 2017, at 11:10, Tudor Girba  wrote:
> 
> Hi Tim,
> 
> The main benefit of relying on Pillar is that we control its syntax and can 
> easily extend it for our purposes. Also, there was quite a bit of engineering 
> invested in it, and even though we still need to improve it, there exists a 
> pipeline that allows people to quickly publish books.
> 
> The figure embedding problem is one example of the need to customize the 
> syntax and behavior, but this extensibility will become even more important 
> for supporting the idea of moving the documentation inside the image. For 
> example, the ability to refer to a class, method or other artifacts will be 
> quite relevant soon especially that the editor will be able to embed advanced 
> elements inside the text.
> 
> Cheers,
> Doru
> 
> 
>> On Aug 14, 2017, at 10:46 AM, Tim Mackinnon  wrote:
>> 
>> Hi Stef - I think your’s is a fair requirement (in fact I hit something 
>> similar when doing a static website using a JS markdown framework - and this 
>> is why I mentioned Kramdown which adds a few extras to regular markdown - 
>> but it feels like it goes a bit too far).
>> 
>> My next item on my learning todo list was to try and replace that JS 
>> generator with something from Smalltalk - so I think we can possibly come up 
>> with something that ticks all the right boxes (I’d like to try anyway).
>> 
>> I’ll keep working away on it and compare notes with you. I think with 
>> Pillar, it was more that things like headers, bold and italics are similar 
>> concepts but just use different characters - so I keep typing the wrong 
>> thing and getting frustrated particularly when we embrace Git and readme.md 
>> is in markdown.
>> 
>> 
>> Tim
>> 
>>> On 13 Aug 2017, at 20:08, Stephane Ducasse  wrote:
>>> 
>>> Hi tim
>>> 
>>> I personally do not care much about the syntax but I care about what I
>>> can do with it
>>> (ref, cite, ... )
>>> I cannot write books in markdown because reference to figures!!
>>> were missing.
>>> 
>>> And of course a parser because markdown is not really nice to parse
>>> and I will not write a parser because I have something else to do. I
>>> want to make pillar smaller, simpler, nicer.
>>> 
>>> Now if someone come up with a parser that parse for REAL a markdown
>>> that can be extended with decent behavior (figure reference, section
>>> reference, cite) and can be extended because there are many things
>>> that can be nice to have (for example I want to be able to write the
>>> example below) and emit a PillarModel (AST) we can talk to have
>>> another syntax for Pillar but not before.
>>> 
>>> [[[test
>>> 2+3
>> 5
>>> ]]]
>>> 
>>> and being able to verify that the doc is in sync.
>>> 
>>> 
>>> Stef
>>> 
>>> 
>>> 
>>> On Sat, Aug 12, 2017 at 12:37 AM, Tim Mackinnon  wrote:
 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  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
> 
 
 
>>> 
>> 
>> 
> 
> --
> www.tudorgirba.com
> www.feenk.com 
> 
> “Live like you mean it."
> 
> 

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

> On 12 Aug 2017, at 18:22, Guillermo Polito  wrote:
> 
> Esteban, I think that when Stef says "a mini version of pillar" he does not 
> mean a mini version of the parser or the AST, but a version that does not 
> have the exporting to html/latex/…

I know that. 
But Cyril talked about “getting a parser without PP”. That's where my comment 
belongs :)

Esteban

> 
> On Sat, Aug 12, 2017 at 4:37 PM, Esteban Lorenzano  > wrote:
> and btw, this kind of threads belongs to pharo-dev, not to pharo-users :)
> 
> Esteban
> 
> > On 12 Aug 2017, at 16:35, Esteban Lorenzano  > > wrote:
> >
> >
> >> On 12 Aug 2017, at 12:46, Tudor Girba  >> > 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  >>> > wrote:
> >>>
> >>> hi,
> >>>
>  On 11 Aug 2017, at 18:57, Cyril Ferlicot D.   > 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."
> >>
> >>
> >>
> >>
> >>
> >
> 
> 
> 
> 
> 
> -- 
>
> Guille Polito
> 
> Research Engineer
> French National Center for Scientific Research - http://www.cnrs.fr 
> 
> 
> 
> Web: http://guillep.github.io 
> Phone: +33 06 52 70 66 13

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Guillermo Polito]

Esteban, I think that when Stef says "a mini version of pillar" he does not
mean a mini version of the parser or the AST, but a version that does not
have the exporting to html/latex/...

On Sat, Aug 12, 2017 at 4:37 PM, Esteban Lorenzano 
wrote:

> and btw, this kind of threads belongs to pharo-dev, not to pharo-users :)
>
> Esteban
>
> > On 12 Aug 2017, at 16:35, Esteban Lorenzano  wrote:
> >
> >
> >> On 12 Aug 2017, at 12:46, Tudor Girba  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 
> wrote:
> >>>
> >>> hi,
> >>>
>  On 11 Aug 2017, at 18:57, Cyril Ferlicot D. 
> 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."
> >>
> >>
> >>
> >>
> >>
> >
>
>
>


-- 



Guille Polito


Research Engineer

French National Center for Scientific Research - *http://www.cnrs.fr*




*Web:* *http://guillep.github.io* 

*Phone: *+33 06 52 70 66 13

Re: [Pharo-dev] [Pharo-users] including Pillar in Pharo image by default

[Esteban Lorenzano]

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

Esteban

> On 12 Aug 2017, at 16:35, Esteban Lorenzano  wrote:
> 
> 
>> On 12 Aug 2017, at 12:46, Tudor Girba  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  wrote:
>>> 
>>> hi, 
>>> 
 On 11 Aug 2017, at 18:57, Cyril Ferlicot D.  
 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."
>> 
>> 
>> 
>> 
>> 
>