About implementing a "Mini Pillar" in-image renderer for Pharo ...

I have been just trying to install GT Documenter and is really frustrating (I have been unable to install it even for the first time!).

This was the list of errors I got and steps I followed, in almost sequential order, just to get a (bittersweet!) taste of GT Documenter:

• 1st: LGit_GIT_ERROR: No ssh-agent suitable credentials found. So I go to GitHub, follow the five pages of documentation to get my SSH credentials that start at [1], then, because I still get the same error, go to the Iceberg FAQ [2], try to surpass the erro,r via command line and doesn't work, so I go to the Iceberg settings and try the manual configuration, going to the next item
  
  [1] https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#generating-a-new-ssh-key
  [2] https://github.com/pharo-vcs/iceberg/blob/master/README.md
  
  
• Now I get "Instance of LGitCredentialsSSH class did not understand #ifTrue:ifFalse:". I try to make sense of it in the debugger, but is something I cannot. Anyway, I rerun it and now I get: LGit_GIT_EEXISTS: '/home/offray/Programas/Pharo/6.1a/Dev24/pharo-local/iceberg/feenkcom/gtoolkit' exists and is not an empty directory. I delete that directory and try an installation... again
  
• Now I get: "Instance of FileReference did not understand #notEmpty". I try to make sense of it in the debugger. My user is git, my public and private ssh keys are not empty. Despite of not making sense of all I understand that is trying to clone something at [hidden email]. I go to my image dir and then to `iceberg/feenkcom/gtoolkit/`. There is a git repository there, but is empty.
  
• Now I wonder, maybe if I can just clone the directory there, but how I say Iceberg to load it? So I run now only the Metacello part. Same error and solution that the last time but now for gtoolkit-visualizer, Brick, gtoolkit-examples, Bloc and Sparta.
• After getting my ssh keys, overcome config problems in shell and the Pharo settings, chasing these errors and solving them by cloning the repositories manually, I'm, a couple of hours later, ready to test GT Documenter, but with the last Iceberg's duplicated repository message about Sparta I give up. Is not nice to start your day accumulating frustration... that sets a bad mood for the rest of it, and you need to actively fight against.
  

I have thought that Git is overcomplicated for most of the developers' tasks and communities. I don't know if the root of previous issues is in the "Iceberg enableMetacelloIntegration: true" line, but having to get your pair of keys working to just install software is overkill for the common user (and when LibGit errors are present, the documented solutions don't work seamlessly). Maybe a more sensitive solution would be just to use libgit, without any ssh auth to clone repositories and its prerequisites or even better, some download that goes to the files in the tip (or other) version without all this overhead.

Anyway, as I said, I have been unable to test GT Documenter properly and getting feedback over GT Tools from the team usually requires a lot of effort in my case (insisting on getting answers or getting none). And that is just to test a promising tech that still doesn't offer saving features (just and awesome preview). I think that a more sensible approach for a good documentation toolkit for now is on Spec and creating custom syntax highlighters with SmaCC[3], that is well documented and works today.

[3] https://medium.com/@juliendelplanque/hacking-a-simple-syntactic-highlighter-around-specs-textmodel-44ba2e2b1ab9

Hi,

As shown at ESUG, GT Documenter offers an advanced viewer (and editor) for Pillar working on top of Bloc.

You can get it by loading:

Iceberg enableMetacelloIntegration: true.
Metacello new
   baseline: 'GToolkit';
   repository: 'github://feenkcom/gtoolkit/src';
   load.

For example, you can then inspect:
'PATH_TO_ICEBERG/feenkcom/gtoolkit/doc/transcript/index.pillar’ asFileReference

Cheers,
Doru

On Nov 10, 2017, at 12:58 PM, H. Hirzel [hidden email] wrote:

A note:

Tudor Girba wrote:
[hidden email]	Fri, Aug 25, 2017 at 1:31 PM
Reply-To: Any question about pharo is welcome [hidden email]
To: Any question about pharo is welcome [hidden email]

Hi,

As mentioned in an announcement about 10 days ago, we are building a
Pillar editor with inline viewing abilities in Bloc. Here is how it
looked like. Please note the embedded picture. We continued working on
it since then and we will probably announce the next version this
weekend:


Maybe there is now enough progress to do simple presentations in Bloc?


On 11/10/17, H. Hirzel [hidden email] wrote:

Hello

In the thread 'including Pillar in Pharo image by default' it was
suggested by Stephane Ducasse to include a subset of Pillar in the
Pharo image[1] .

I'd like to extend that proposal a little bit it in order  to do very
simple presentations. This should allow to describe at least part of
the slides used in the MOOC course [3].

This will be  _a possible_ solution to the question  brought up in the
thread 'Writing "powerpoint" like presentations in Pharo?'.

Another use is to write instructions with executable content within
the image ("Assistants").

So below is the a proposal for a Pillar syntax _subset_ for class
comments and _simple_ presentations.
The numbering scheme follows the 'Pillar syntax cheat sheet' [2]




MINI PILLAR SYNTAX (a subset of Pillar)

1. Headers

   !Header 1
   !!Header 2
   !!!Header 3


2. Lists

   - Unordered List
   # Ordered list



5. Emphasis

   ""bold""


6. Code blocks

    [[[
    Transcript show: 'Hello World'.
    \]]]


9. Annotation

${slide:title=About Pharo}$




Next week I plan to implement the rendering of this 'Mini Pillar' in
Morphic using the Morphic API subset that works in Pharo and Squeak.

A renderer using Bloc would also be nice. [4]

Comments, suggestions, code snippets and other help is welcome.

Regards
Hannes




--------------------------------------------------------------------------------------------------
[1] Pillar subset for class comments

Stephane Ducasse
[hidden email]	Fri, Aug 11, 2017 at 7:09 PM
To: Any question about pharo is welcome [hidden email]

Tx cyril

For class comment I image that we want

!

-
-
*url*
and bold
[[[

]]]

Did I miss something.

Stef





--------------------------------------------------------------------------------------------------
[2]
http://pillarhub.pharocloud.com/hub/pillarhub/pillarcheatsheet
--------------------------------------------------------------------------------------------------


1. Headers

   !Header 1
   !!Header 2
   !!!Header 3
   !!!!Header 4
   !!!!!Header 5
   !!!!!!Header 6

2. Lists

   - Unordered List
   # Ordered list

3. Table

   |! Left |! Right |! Centered
   |{Left |}Right| Centered


4. Description
Note
on a new line

   ;head
   :item


5. Emphasis

   ""bold""
   ''italic''
   --strikethrough--
   __underscore__
   ==inline code==
   @@subscript@@
   ^^sub-script^^

6. Code blocks

    [[[lab­el=­hel­loS­cri­pt|­cap­tio­n=How to print Hello
World|­lan­gua­ge=­Sma­lltalk
    Transcript show: 'Hello World'.
    \]]]


7. Raw


   {{{latex:
   this is how you inject raw \LaTeX in your output file
   }}}

   {{{mar­kdown:
   this is how you inject raw `markdown` in your output file
   }}}

   {{{html:
   this is how you inject raw <b>­htm­l</­b> in your output file
   }}}


8. Links

   Anchor @anchor (new line)
   Internal link *anchor*
   External link *Google>http://google.com*
   Image +Caption><a class="moz-txt-link-freetext" href="file://image.png|width=50|label=label+">file://image.png|width=50|label=label+


9. Annotation
Note
on a new line

   Annotation @@note this is a note
   Todo item @@todo this is to do


10. Comments

   % each line starting with % is commented


11. References

This document is copied from
http://www.cheatography.com/benjaminvanryseghem/cheat-sheets/pillar/
















----------------------------------------------------------------------
[3] Example pillar code for slides
----------------------------------------------------------------------

https://github.com/SquareBracketAssociates/PharoMooc/blob/master/Slides/1-Templates/SlideExample.pillar

{
	"title":"To the Roots of Objects",
	"subtitle":"Learning from beauty",
	"author":"Stephane Ducasse",
	"complement":<a class="moz-txt-link-rfc2396E" href="http://stephane.ducasse.free.fr/\\\\stephane.ducasse@inria.fr">"http://stephane.ducasse.free.fr/ \\\\
stephane.ducasse@..."
}


${toc:depthLevel=2|level=0|highlight=0}$

%Les sections ne sont pas des titres de slide mais définnissent la
structure du doucment. Il est possible de rajouter
"renderStructureAsSlide":false dans pillar.conf pour ne pas créer de
slide à partir d'un titre.


${slide:title=License}$

+><a class="moz-txt-link-freetext" href="file://figures/CreativeCommons.png|width=50|label=figCreativeCommons+">file://figures/CreativeCommons.png|width=50|label=figCreativeCommons+


! Introduction

%
${toc:depthLevel=1|level=0|highlight=1}$


${slide:title=Really?!|label=really}$

${columns}$

${column:width=50}$

%the width parameter take an Int between 1 and 100
%For now we have to pass a line before and after an annotation, I'll
correct that soon in Pillar.
- No primitive types
- No hardcoded constructs for conditional
- Only messages
- Only objects

${column:width=50}$

- and this works?
- I mean really?
- Not even slow?
- Can't be real!

${endColumns}$

${slide:title=Motto}$

- Let's open our eyes, look, understand, and deeply understand the
underlying design aspects of object-oriented programming.


*@really*

*TEST !>@really*

${slide:title=Booleans}$

[[[language=smalltalk
3 > 0
	ifTrue: ['positive']
	ifFalse: ['negative']
-> 'positive'
]]]

${slide:title=Yes ifTrue\:ifFalse\: is a message!}$

[[[language=smalltalk
Weather isRaining
	ifTrue: [self takeMyUmbrella]
	ifFalse: [self takeMySunglasses]
]]]

- Conceptually ==ifTrue:ifFalse:== is a message sent to an object: a
boolean!
- ==ifTrue:ifFalse:== is in fact radically optimized by the compiler
but you can implement another one such ==siAlors:sinon:== and check.

${slide:title=Booleans}$

In Pharo booleans have nothing special
- & | not
- or: and: (lazy)
- xor:
- ifTrue:ifFalse:
- ifFalse:ifTrue:
- ...

${slide:title=Lazy Logical Operators}$

	*LINK>@frm:really*

[[[language=smalltalk
	false and: [1 error: 'crazy']
-> false and not an error
]]]

! Exercices
${toc:depthLevel=1|level=0|highlight=1}$

!! Exercise 1: Implement not

${slide:title=Exercise 1\: Implement not}$

- Propose an implementation of not in a world where you do not have
Booleans.
- You only have objects and messages.
[[[language=smalltalk
false not
	-> true

true not
	-> false
]]]

!!Exercise 2: Implement | (Or) ifTrue: ifFalse:

${toc:depthLevel=2|level=0|highlight=1}$

${slide:title=Exercise 2\: Implement \| (Or)}$

- Propose an implementation of or in a world where you do not have
Booleans.
- You only have objects and messages.

[[[language=smalltalk
	true | true -> true
	true | false -> true
	true | anything -> true

	false | true -> true
	false | false -> false
	false | anything -> anything
]]]

${slide:title=Exercise2\: Variation - Implement ifTrue\:ifFalse\:}$

- Propose an implementation of not in a world where you do not have
Booleans.
- You only have objects, messages and closures.

[[[language=smalltalk
false ifTrue: [ 3 ] ifFalse: [ 5 ]
-> 5
true ifTrue: [ 3 ] ifFalse: [ 5 ]
-> 3
]]]

! Boolean Implementation

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Booleans Implementation Hint One}$

- The solution does not use conditionals
- else we would obtain a recursive definition of ==ifTrue:ifFalse:==

${slide:title=Boolean Implementation Hint Two}$

- The solution uses three classes: ==Boolean==, ==True== and ==False==
- ==false== and ==true== are unique instances described by their own
classes
- ==false== is an instance of the class ==False==
- ==true== is an instance of the class ==True==

+Boolean Hierarchy><a class="moz-txt-link-freetext" href="file://figures/BooleanHiearchyAndInstances.png|width=50+">file://figures/BooleanHiearchyAndInstances.png|width=50+

${slide:title=How do we express choice in OOP?}$

- We send messages to objects

[[[language=smalltalk
	aButton color
	-> Color red
	
	aPane color
	-> Color blue
	
	aWindow color
	-> Color grey
]]]

- Let's the receiver decide

- Do not ask, tell

${slide:title=Boolean not implementation}$

- Class ==Boolean== is an abstract class that implements behavior
common to true and false. Its subclasses are ==True== and ==False==.
Subclasses must implement methods for logical operations ==&==,
==not==, and controls ==and:==, ==or:==, ==ifTrue:==, ==ifFalse:==,
==ifTrue:ifFalse:==, ==ifFalse:ifTrue:==

[[[language=smalltalk
Boolean>>not
	"Negation. Answer true if the receiver is false, answer false if the
receiver is true."
	self subclassResponsibility
]]]

${slide:title=Not implementation in two methods}$

[[[language=smalltalk
False>>not
	"Negation -- answer true since the receiver is false."
	^ true
]]]

[[[language=smalltalk
True>>not
	"Negation--answer false since the receiver is true."
	^ false
]]]

${slide:title=Not implementation in two methods}$

+Not
implementation.><a class="moz-txt-link-freetext" href="file://figures/BooleanHiearchyAndInstancesWithNotMethods.png|width=80+">file://figures/BooleanHiearchyAndInstancesWithNotMethods.png|width=80+

${slide:title=\| (Or)}$
[[[language=smalltalk
	
	true | true -> true
	true | false -> true
	true | anything -> true

	false | true -> true
	false | false -> false
	false | anything -> anything

]]]

${slide:title=Boolean>> \| aBoolean}$

[[[language=smalltalk
	Boolean>> | aBoolean
		"Evaluating disjunction (OR). Evaluate the argument. Answer true if
either the receiver or the argument is
true."
	self subclassResponsibility
]]]

${slide:title=False>> \| aBoolean}$

[[[language=smalltalk
false | true -> true
false | false -> false
false | anything -> anything
]]]

[[[language=smalltalk
False >> | aBoolean
	"Evaluating disjunction (OR) -- answer with the argument, aBoolean."
	^ aBoolean
]]]

${slide:title=True>> \| aBoolean}$

[[[language=smalltalk
true | true -> true
true | false -> true
true | anything -> true
]]]

[[[language=smalltalk
True>> | aBoolean
	"Evaluating disjunction (OR) -- answer true since the receiver is true."
	^ self
]]]	

${slide:title=Or implementation in two methods}$

+><a class="moz-txt-link-freetext" href="file://figures/BooleanHiearchyAndInstancesWithOrMethods.png|width=80+">file://figures/BooleanHiearchyAndInstancesWithOrMethods.png|width=80+

${slide:title=Implementing ifTrue\:ifFalse\:}$

- Do you see the pattern?
- Remember that a closure freezes execution and that value launches
the execution of a frozen code.

[[[language=smalltalk
True>>ifTrue: aTrueBlock ifFalse: aFalseBlock
	^ aTrueBlock value
]]]

[[[language=smalltalk
False>>ifTrue: aTrueBlock ifFalse: aFalseBlock
	^ aFalseBlock value
]]]

${slide:title=Implementation Note}$

- Note that the Virtual Machine shortcuts calls to boolean such as
condition for speed reason.
- But you can implement your own conditional method and debug to see
that sending a message is dispatching to the right object.

! So what ?

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Ok so what?}$

- You will probably not implement another Boolean classes
- So is it really that totally useless?


${slide:title=Message sends act as case statements}$

- The execution engine will select the right method in the class of the
receiver
- The case statements is dynamic in the sense that it depends on the
classes loaded and the objects to which the message is sent.
- Each time you send a message, the system will select the method
corresponding to the receiver.


${slide:title=A Class Hierarchy is a Skeleton for Dynamic Dispatch}$

- If we would have said that the ==Boolean== would be composed of only
one class, we could not have use dynamic binding.
- A class hierarchy is the exoskeleton for dynamic binding

- Compare the solution with one class vs. a hierarchy.

+One single class vs. a nice
hierarchy.><a class="moz-txt-link-freetext" href="file://figures/Design-FatVsDispatch.png|width=70+">file://figures/Design-FatVsDispatch.png|width=70+

- The hierarchy provides a way to specialize behavior.
- It is also more declarative in the sense that you only focus on one
class.
- It is more modular in the sense that you can package different
classes in different packages.

${slide:title=Avoid Conditionals}$

- Use objects and messages, when you can
- The execution engine acts as a conditional switch: Use it!
- Check the AntiIfCampaign.

${slide:title=Follow-up: Implement ternary logic}$

- Boolean: ==true==, ==false==, ==unknown==
+Ternaru Logic decision table

<a class="moz-txt-link-freetext" href="file://figures/ArrayBoolean.png|width=30|label=fig:ternLogic+">file://figures/ArrayBoolean.png|width=30|label=fig:ternLogic+

- Implementing in your own classes.

! Summary

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Summary}$
- Tell, do not ask
- Let the receiver decide
- Message sends as potential dynamic conditional
- Class hiearchy builds a skeleton for dynamic dispatch
- Avoid conditional




-----------------------------------------
[4] Bloc
Load Bloc with executing in a playground (Pharo 6.1)

   Metacello new
   baseline: 'Bloc';
   repository: 'github://pharo-graphics/Bloc:pharo6.1/src';
   load: #core


A tutorial to use bloc is available on
http://files.pharo.org/books/
Bloc Memory Game (alpha) is a first tutorial on Bloc the new graphics
core for Pharo. Booklet written by A. Chis, S. Ducasse, A. Syrel.

http://files.pharo.org/books-pdfs/booklet-Bloc/2017-11-09-memorygame.pdf

To load the memory game

   Metacello new
   baseline: 'BlocTutorials';
   repository: 'github://pharo-graphics/Tutorials/src';
   load


A similar booklet could be done for the title
'Doing a presentation / slide show / assitant with Bloc' (or similar,
adapt  .....)

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

"Obvious things are difficult to teach."

Alex,

I understand that frustration on installation could be motivated by other issues instead of GT Documenter, but if the team ask to use "Iceberg enableMetacelloIntegration: true." in the project readme, where it also says that is supported for Pharo 6.1 and 7.0, is natural to think that something is wrong with documentation and/or in the project's expectations about its intended users and their will to invest the effort, time and motivation for "living in the edge". I understand that if we want stuff to be improved it should be tested, but also that not all the people that is willing to test stuff for Pharo 6.1 needs to live in such edge. Or the project is sending a message that is not giving the bests firsts impressions, or is going to users which are not intended . I would go for a smooth install first and then for collaboration with git. I'll make a pull request with the proposal for a better documentation, but my understanding about how you can go from the first (user of GT Documenter) to the second (developer using Git integration) is not clear.

GT Tools has been pretty empowering. I have told that several times and I don't think that I have wrote a single line of code in their repos. But is getting more difficult just to test and use them and I think that is related with the idea that my user *needs* to be also my co-developer, starting with their ssh git key pair. If we don't make easier to contribute by just making easier to install, there will be no evolution either.

Cheers,

Offray

Hi Offray,

I understand your frustration, but with all respect, the fact that you have problems with Iceberg does not mean that GT Documenter or any other GT tool is responsible for described problems.

Most complains about bloc, brick, whatever is because of unrelated stuff. It is a little bit disappointing. Especially for me, as one of the maintainers. But it is ok, I got used to it :)

I don’t remember when last time I used stable Pharo (not because it does not exist), simply live on the edge since Pharo4. If no one will use Git and report problems Iceberg will never progress. If no one will use Bloc it will never get “there”. Unfortunately, living on the edge is dangerous, requires effort, motivation and time.

The script that Doru provided works flawlessly on OSX, we load it almost everyday. !! Bloc is tested on CI and builds are green on Windows, Linux and OSX !!. If computer (CI) manages to install it, I am pretty sure human can do it too. Looks like there is something missing in your configuration, something tiny :) Error handling in Iceberg can be definitely improved, but it is a different story.

P.S. Documenter can be installed without enabled Iceberg integration. This is how CI does it. You will just not be able to contribute.

Cheers,

Alex

On Tue, 14 Nov 2017 at 16:37, Offray Vladimir Luna Cárdenas <[hidden email]> wrote:

I have been just trying to install GT Documenter and is really frustrating (I have been unable to install it even for the first time!).

This was the list of errors I got and steps I followed, in almost sequential order, just to get a (bittersweet!) taste of GT Documenter:

• 1st: LGit_GIT_ERROR: No ssh-agent suitable credentials found. So I go to GitHub, follow the five pages of documentation to get my SSH credentials that start at [1], then, because I still get the same error, go to the Iceberg FAQ [2], try to surpass the erro,r via command line and doesn't work, so I go to the Iceberg settings and try the manual configuration, going to the next item
  
  [1] https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#generating-a-new-ssh-key
  [2] https://github.com/pharo-vcs/iceberg/blob/master/README.md
  
  
• Now I get "Instance of LGitCredentialsSSH class did not understand #ifTrue:ifFalse:". I try to make sense of it in the debugger, but is something I cannot. Anyway, I rerun it and now I get: LGit_GIT_EEXISTS: '/home/offray/Programas/Pharo/6.1a/Dev24/pharo-local/iceberg/feenkcom/gtoolkit' exists and is not an empty directory. I delete that directory and try an installation... again
  
• Now I get: "Instance of FileReference did not understand #notEmpty". I try to make sense of it in the debugger. My user is git, my public and private ssh keys are not empty. Despite of not making sense of all I understand that is trying to clone something at [hidden email]. I go to my image dir and then to `iceberg/feenkcom/gtoolkit/`. There is a git repository there, but is empty.
  
• Now I wonder, maybe if I can just clone the directory there, but how I say Iceberg to load it? So I run now only the Metacello part. Same error and solution that the last time but now for gtoolkit-visualizer, Brick, gtoolkit-examples, Bloc and Sparta.
• After getting my ssh keys, overcome config problems in shell and the Pharo settings, chasing these errors and solving them by cloning the repositories manually, I'm, a couple of hours later, ready to test GT Documenter, but with the last Iceberg's duplicated repository message about Sparta I give up. Is not nice to start your day accumulating frustration... that sets a bad mood for the rest of it, and you need to actively fight against.
  

I have thought that Git is overcomplicated for most of the developers' tasks and communities. I don't know if the root of previous issues is in the "Iceberg enableMetacelloIntegration: true" line, but having to get your pair of keys working to just install software is overkill for the common user (and when LibGit errors are present, the documented solutions don't work seamlessly). Maybe a more sensitive solution would be just to use libgit, without any ssh auth to clone repositories and its prerequisites or even better, some download that goes to the files in the tip (or other) version without all this overhead.

Anyway, as I said, I have been unable to test GT Documenter properly and getting feedback over GT Tools from the team usually requires a lot of effort in my case (insisting on getting answers or getting none). And that is just to test a promising tech that still doesn't offer saving features (just and awesome preview). I think that a more sensible approach for a good documentation toolkit for now is on Spec and creating custom syntax highlighters with SmaCC[3], that is well documented and works today.

[3] https://medium.com/@juliendelplanque/hacking-a-simple-syntactic-highlighter-around-specs-textmodel-44ba2e2b1ab9

I understand that community is trying its best, but expressing how current offerings are not mature and constructive criticism can help on that. At the moment my feeling is that if you want to try the new shinny alpha stuff from GT Documenter, you will need to be prepared for a lot of frustration and silence.

Cheers,

Offray

On 10/11/17 12:41, Tudor Girba wrote:

Hi,

As shown at ESUG, GT Documenter offers an advanced viewer (and editor) for Pillar working on top of Bloc.

You can get it by loading:

Iceberg enableMetacelloIntegration: true.
Metacello new
   baseline: 'GToolkit';
   repository: 'github://feenkcom/gtoolkit/src';
   load.

For example, you can then inspect:
'PATH_TO_ICEBERG/feenkcom/gtoolkit/doc/transcript/index.pillar’ asFileReference

Cheers,
Doru

On Nov 10, 2017, at 12:58 PM, H. Hirzel [hidden email] wrote:

A note:

Tudor Girba wrote:
[hidden email]	Fri, Aug 25, 2017 at 1:31 PM
Reply-To: Any question about pharo is welcome [hidden email]
To: Any question about pharo is welcome [hidden email]

Hi,

As mentioned in an announcement about 10 days ago, we are building a
Pillar editor with inline viewing abilities in Bloc. Here is how it
looked like. Please note the embedded picture. We continued working on
it since then and we will probably announce the next version this
weekend:


Maybe there is now enough progress to do simple presentations in Bloc?


On 11/10/17, H. Hirzel [hidden email] wrote:

Hello

In the thread 'including Pillar in Pharo image by default' it was
suggested by Stephane Ducasse to include a subset of Pillar in the
Pharo image[1] .

I'd like to extend that proposal a little bit it in order  to do very
simple presentations. This should allow to describe at least part of
the slides used in the MOOC course [3].

This will be  _a possible_ solution to the question  brought up in the
thread 'Writing "powerpoint" like presentations in Pharo?'.

Another use is to write instructions with executable content within
the image ("Assistants").

So below is the a proposal for a Pillar syntax _subset_ for class
comments and _simple_ presentations.
The numbering scheme follows the 'Pillar syntax cheat sheet' [2]




MINI PILLAR SYNTAX (a subset of Pillar)

1. Headers

   !Header 1
   !!Header 2
   !!!Header 3


2. Lists

   - Unordered List
   # Ordered list



5. Emphasis

   ""bold""


6. Code blocks

    [[[
    Transcript show: 'Hello World'.
    \]]]


9. Annotation

${slide:title=About Pharo}$




Next week I plan to implement the rendering of this 'Mini Pillar' in
Morphic using the Morphic API subset that works in Pharo and Squeak.

A renderer using Bloc would also be nice. [4]

Comments, suggestions, code snippets and other help is welcome.

Regards
Hannes




--------------------------------------------------------------------------------------------------
[1] Pillar subset for class comments

Stephane Ducasse
[hidden email]	Fri, Aug 11, 2017 at 7:09 PM
To: Any question about pharo is welcome [hidden email]

Tx cyril

For class comment I image that we want

!

-
-
*url*
and bold
[[[

]]]

Did I miss something.

Stef





--------------------------------------------------------------------------------------------------
[2]
http://pillarhub.pharocloud.com/hub/pillarhub/pillarcheatsheet
--------------------------------------------------------------------------------------------------


1. Headers

   !Header 1
   !!Header 2
   !!!Header 3
   !!!!Header 4
   !!!!!Header 5
   !!!!!!Header 6

2. Lists

   - Unordered List
   # Ordered list

3. Table

   |! Left |! Right |! Centered
   |{Left |}Right| Centered


4. Description
Note
on a new line

   ;head
   :item


5. Emphasis

   ""bold""
   ''italic''
   --strikethrough--
   __underscore__
   ==inline code==
   @@subscript@@
   ^^sub-script^^

6. Code blocks

    [[[lab­el=­hel­loS­cri­pt|­cap­tio­n=How to print Hello
World|­lan­gua­ge=­Sma­lltalk
    Transcript show: 'Hello World'.
    \]]]


7. Raw


   {{{latex:
   this is how you inject raw \LaTeX in your output file
   }}}

   {{{mar­kdown:
   this is how you inject raw `markdown` in your output file
   }}}

   {{{html:
   this is how you inject raw <b>­htm­l</­b> in your output file
   }}}


8. Links

   Anchor @anchor (new line)
   Internal link *anchor*
   External link *Google>http://google.com*
   Image +Caption>file://image.png|width=50|label=label+


9. Annotation
Note
on a new line

   Annotation @@note this is a note
   Todo item @@todo this is to do


10. Comments

   % each line starting with % is commented


11. References

This document is copied from
http://www.cheatography.com/benjaminvanryseghem/cheat-sheets/pillar/
















----------------------------------------------------------------------
[3] Example pillar code for slides
----------------------------------------------------------------------

https://github.com/SquareBracketAssociates/PharoMooc/blob/master/Slides/1-Templates/SlideExample.pillar

{
	"title":"To the Roots of Objects",
	"subtitle":"Learning from beauty",
	"author":"Stephane Ducasse",
	"complement":"http://stephane.ducasse.free.fr/ \\\\
stephane.ducasse@..."
}


${toc:depthLevel=2|level=0|highlight=0}$

%Les sections ne sont pas des titres de slide mais définnissent la
structure du doucment. Il est possible de rajouter
"renderStructureAsSlide":false dans pillar.conf pour ne pas créer de
slide à partir d'un titre.


${slide:title=License}$

+>file://figures/CreativeCommons.png|width=50|label=figCreativeCommons+


! Introduction

%
${toc:depthLevel=1|level=0|highlight=1}$


${slide:title=Really?!|label=really}$

${columns}$

${column:width=50}$

%the width parameter take an Int between 1 and 100
%For now we have to pass a line before and after an annotation, I'll
correct that soon in Pillar.
- No primitive types
- No hardcoded constructs for conditional
- Only messages
- Only objects

${column:width=50}$

- and this works?
- I mean really?
- Not even slow?
- Can't be real!

${endColumns}$

${slide:title=Motto}$

- Let's open our eyes, look, understand, and deeply understand the
underlying design aspects of object-oriented programming.


*@really*

*TEST !>@really*

${slide:title=Booleans}$

[[[language=smalltalk
3 > 0
	ifTrue: ['positive']
	ifFalse: ['negative']
-> 'positive'
]]]

${slide:title=Yes ifTrue\:ifFalse\: is a message!}$

[[[language=smalltalk
Weather isRaining
	ifTrue: [self takeMyUmbrella]
	ifFalse: [self takeMySunglasses]
]]]

- Conceptually ==ifTrue:ifFalse:== is a message sent to an object: a
boolean!
- ==ifTrue:ifFalse:== is in fact radically optimized by the compiler
but you can implement another one such ==siAlors:sinon:== and check.

${slide:title=Booleans}$

In Pharo booleans have nothing special
- & | not
- or: and: (lazy)
- xor:
- ifTrue:ifFalse:
- ifFalse:ifTrue:
- ...

${slide:title=Lazy Logical Operators}$

	*LINK>@frm:really*

[[[language=smalltalk
	false and: [1 error: 'crazy']
-> false and not an error
]]]

! Exercices
${toc:depthLevel=1|level=0|highlight=1}$

!! Exercise 1: Implement not

${slide:title=Exercise 1\: Implement not}$

- Propose an implementation of not in a world where you do not have
Booleans.
- You only have objects and messages.
[[[language=smalltalk
false not
	-> true

true not
	-> false
]]]

!!Exercise 2: Implement | (Or) ifTrue: ifFalse:

${toc:depthLevel=2|level=0|highlight=1}$

${slide:title=Exercise 2\: Implement \| (Or)}$

- Propose an implementation of or in a world where you do not have
Booleans.
- You only have objects and messages.

[[[language=smalltalk
	true | true -> true
	true | false -> true
	true | anything -> true

	false | true -> true
	false | false -> false
	false | anything -> anything
]]]

${slide:title=Exercise2\: Variation - Implement ifTrue\:ifFalse\:}$

- Propose an implementation of not in a world where you do not have
Booleans.
- You only have objects, messages and closures.

[[[language=smalltalk
false ifTrue: [ 3 ] ifFalse: [ 5 ]
-> 5
true ifTrue: [ 3 ] ifFalse: [ 5 ]
-> 3
]]]

! Boolean Implementation

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Booleans Implementation Hint One}$

- The solution does not use conditionals
- else we would obtain a recursive definition of ==ifTrue:ifFalse:==

${slide:title=Boolean Implementation Hint Two}$

- The solution uses three classes: ==Boolean==, ==True== and ==False==
- ==false== and ==true== are unique instances described by their own
classes
- ==false== is an instance of the class ==False==
- ==true== is an instance of the class ==True==

+Boolean Hierarchy>file://figures/BooleanHiearchyAndInstances.png|width=50+

${slide:title=How do we express choice in OOP?}$

- We send messages to objects

[[[language=smalltalk
	aButton color
	-> Color red
	
	aPane color
	-> Color blue
	
	aWindow color
	-> Color grey
]]]

- Let's the receiver decide

- Do not ask, tell

${slide:title=Boolean not implementation}$

- Class ==Boolean== is an abstract class that implements behavior
common to true and false. Its subclasses are ==True== and ==False==.
Subclasses must implement methods for logical operations ==&==,
==not==, and controls ==and:==, ==or:==, ==ifTrue:==, ==ifFalse:==,
==ifTrue:ifFalse:==, ==ifFalse:ifTrue:==

[[[language=smalltalk
Boolean>>not
	"Negation. Answer true if the receiver is false, answer false if the
receiver is true."
	self subclassResponsibility
]]]

${slide:title=Not implementation in two methods}$

[[[language=smalltalk
False>>not
	"Negation -- answer true since the receiver is false."
	^ true
]]]

[[[language=smalltalk
True>>not
	"Negation--answer false since the receiver is true."
	^ false
]]]

${slide:title=Not implementation in two methods}$

+Not
implementation.>file://figures/BooleanHiearchyAndInstancesWithNotMethods.png|width=80+

${slide:title=\| (Or)}$
[[[language=smalltalk
	
	true | true -> true
	true | false -> true
	true | anything -> true

	false | true -> true
	false | false -> false
	false | anything -> anything

]]]

${slide:title=Boolean>> \| aBoolean}$

[[[language=smalltalk
	Boolean>> | aBoolean
		"Evaluating disjunction (OR). Evaluate the argument. Answer true if
either the receiver or the argument is
true."
	self subclassResponsibility
]]]

${slide:title=False>> \| aBoolean}$

[[[language=smalltalk
false | true -> true
false | false -> false
false | anything -> anything
]]]

[[[language=smalltalk
False >> | aBoolean
	"Evaluating disjunction (OR) -- answer with the argument, aBoolean."
	^ aBoolean
]]]

${slide:title=True>> \| aBoolean}$

[[[language=smalltalk
true | true -> true
true | false -> true
true | anything -> true
]]]

[[[language=smalltalk
True>> | aBoolean
	"Evaluating disjunction (OR) -- answer true since the receiver is true."
	^ self
]]]	

${slide:title=Or implementation in two methods}$

+>file://figures/BooleanHiearchyAndInstancesWithOrMethods.png|width=80+

${slide:title=Implementing ifTrue\:ifFalse\:}$

- Do you see the pattern?
- Remember that a closure freezes execution and that value launches
the execution of a frozen code.

[[[language=smalltalk
True>>ifTrue: aTrueBlock ifFalse: aFalseBlock
	^ aTrueBlock value
]]]

[[[language=smalltalk
False>>ifTrue: aTrueBlock ifFalse: aFalseBlock
	^ aFalseBlock value
]]]

${slide:title=Implementation Note}$

- Note that the Virtual Machine shortcuts calls to boolean such as
condition for speed reason.
- But you can implement your own conditional method and debug to see
that sending a message is dispatching to the right object.

! So what ?

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Ok so what?}$

- You will probably not implement another Boolean classes
- So is it really that totally useless?


${slide:title=Message sends act as case statements}$

- The execution engine will select the right method in the class of the
receiver
- The case statements is dynamic in the sense that it depends on the
classes loaded and the objects to which the message is sent.
- Each time you send a message, the system will select the method
corresponding to the receiver.


${slide:title=A Class Hierarchy is a Skeleton for Dynamic Dispatch}$

- If we would have said that the ==Boolean== would be composed of only
one class, we could not have use dynamic binding.
- A class hierarchy is the exoskeleton for dynamic binding

- Compare the solution with one class vs. a hierarchy.

+One single class vs. a nice
hierarchy.>file://figures/Design-FatVsDispatch.png|width=70+

- The hierarchy provides a way to specialize behavior.
- It is also more declarative in the sense that you only focus on one
class.
- It is more modular in the sense that you can package different
classes in different packages.

${slide:title=Avoid Conditionals}$

- Use objects and messages, when you can
- The execution engine acts as a conditional switch: Use it!
- Check the AntiIfCampaign.

${slide:title=Follow-up: Implement ternary logic}$

- Boolean: ==true==, ==false==, ==unknown==
+Ternaru Logic decision table

file://figures/ArrayBoolean.png|width=30|label=fig:ternLogic+

- Implementing in your own classes.

! Summary

${toc:depthLevel=1|level=0|highlight=1}$

${slide:title=Summary}$
- Tell, do not ask
- Let the receiver decide
- Message sends as potential dynamic conditional
- Class hiearchy builds a skeleton for dynamic dispatch
- Avoid conditional




-----------------------------------------
[4] Bloc
Load Bloc with executing in a playground (Pharo 6.1)

   Metacello new
   baseline: 'Bloc';
   repository: 'github://pharo-graphics/Bloc:pharo6.1/src';
   load: #core


A tutorial to use bloc is available on
http://files.pharo.org/books/
Bloc Memory Game (alpha) is a first tutorial on Bloc the new graphics
core for Pharo. Booklet written by A. Chis, S. Ducasse, A. Syrel.

http://files.pharo.org/books-pdfs/booklet-Bloc/2017-11-09-memorygame.pdf

To load the memory game

   Metacello new
   baseline: 'BlocTutorials';
   repository: 'github://pharo-graphics/Tutorials/src';
   load


A similar booklet could be done for the title
'Doing a presentation / slide show / assitant with Bloc' (or similar,
adapt  .....)

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

"Obvious things are difficult to teach."

--

Cheers,

Alex