Intermediate-Level Tutorials for Pharo

>>> I've been thinking lately that it would be nice to expand the number of
>>> Pharo tutorials we have available.  But rather than (or along with)
>>> creating
>>> more "beginner" level tutorials, I'd like to see some good "intermediate"
>>> level Pharo tutorials.
>> Me too :)
> Let's do it, then.  I'll volunteer to do most of the work.  :^)
>
> My hope is that participating in this will make me capable of creating
> advanced tutorials all by myself.
>
>>>  I think that programmers who already know the Pharo
>>> syntax and messaging semantics could benefit from more advanced tutorials
>>> that demonstrate how to develop "real world" Pharo code for "real world"
>>> processing needs.
>> Yes yes I would love that.
> That was part of my motivation for creating a Pharo app to solve the Zebra
> Puzzle.  First, of course, I wanted to solve it.  ;^)
>
>>> What I'm talking about is something that assumes you know the language,
>>> the
>>> basics of the IDE (but not necessarily how to leverage its capabilities
>>> to
>>> aid development), and the basics of the foundation classes (but not its
>>> details).  I'd like a tutorial for intermediate Pharo programmers who
>>> want
>>> to become experts with Pharo.  Something that can show you how to apply
>>> the
>>> tools of the IDE and the features of the language and base classes to
>>> create
>>> solutions that solve complex problems.
>> do you have ideas?
> I do!
>
> As I started building the Logic Puzzle app, it occurred to me that I could
> probably find several different, common structures in OOP (specifically,
> Pharo) to add to the solution.  And then each would be its own example of
> "what real Pharo code looks like".  I.e., be good examples.
>
> But first, I needed to explore "how to do it in Pharo" for myself, which
> naturally would have me working the IDE strongly.
>
> Then I thought, the entire application can/should be an example, so it
> should be a tutorial.
>
> That means that I need more than just a completed application (that's "just
> an example").  To be a *tutorial*, it means starting from scratch, showing
> how to approach the solution, how to start a Pharo app, how to use the IDE,
> how to write tests, how to refactor code, etc.
>
> Then I thought, this needs a GUI.  Either a Spec2 UI or a web app UI (with
> Seaside or Teapot).  But I would need help with that!  So I'll start by
> creating a message-based solution, and maybe get help to add a UI later.
>
> I did some prototyping, then got what I think might be a good code structure
> (by version 4; it took a while to "think pure OOP"; old habits are hard to
> fight against).  It runs, it works.
>
> But.. Is it "good Pharo code"?  I'm not experienced enough to answer that
> question.  I need a code review, criticism, guidance.  Point me in the right
> direction and I'll keep working on it, and start thinking about how to
> express the "meta" elements (how to use the IDE to make/test the code,
> etc.).
>
>>> What does the community think of this idea?
>> I love it. I did Pharo by example so that I can get of rid of the beginner
> parts.
>> After I did learning OOP and Pharo with style so that I do not have to talk
> about it
>> again.
>>
>> So definitively.
> Okay, great.  I'll do most of the work.  But I need help...
>
> I don't want to go any further without someone much more experienced than I
> am to review what I have and let me know what I'm doing right & what I'm
> doing "no quite so right".  Yes, it runs, it works -- but that's *not* good
> enough.  The goal here isn't to "hack out a solution and move on", the goal
> is to "create an example and tutorial that's high enough quality to use to
> teach Pharo to other people".  I don't want to be teaching *my* bad habits!
>
> Also, I know next to nothing about Spec2 or Seaside/Teapot.  I just know
> that I need to learn it, and I need to use it to give my tutorial a UI (or
> two).  Newcomers will show up wanting to learn Pharo, and they need to be
> reassured that they can create nice (enough) UIs without a huge effort.
> (Not everyone is a command line hacker, and end-users certainly don't want
> to be.)
>
> The more I learn (from you), the more I can be independent, and the more
> tutorials I could produce -- without a lot of help.  I'm willing to do the
> work, because that will help make me a Pharo "master programmer".  (I don't
> want to be a hack, and I can't really be a trainer if I'm just a hack
> myself.)  
>
> I'll pay back the community by helping to attract and advance more
> developers' skills.  I just have to have the more advanced knowledge &
> skills myself.  So, train the (future) trainer, anyone??
>  
> -Ted
>
>
>
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
>

> > Okay, I'll do that. But this brings up a more general question...
> >
> > If I wanted to add a diagram, or maybe a document with equations
> (rendered
> > in LaTex), then a class comment wouldn't work.
> >
> > ...Unless that's intended to be part of the newer format??
>
>
> Microdown supports latex via external services (I should check that the
> implementation uses the same cache than the one for pictures).
> For diagram you can use png but we will have to spot glitches.

>
> S.
>
> >
> > -t
> >
> >
> >> I would put it in class comment.
> >>
> >> We are about to release a nicer rendering of comments.
> >>
> >> S.
> >>
> >>> On 4 Aug 2020, at 06:46, tbrunz wrote:
> >>>
> >>> I wrote a "theory of operation" document for my app,
> >>> https://github.com/tbrunz/logic-puzzle 
> >>>
> >>> But then I realized, "Where do I put it??"
> >>>
> >>> I thought of a few possibilities:
> >>>
> >>> * Commit it to the git repo, but then it wouldn't be easy to access
> from
> >>> Pharo,
> >>> * Add it to a top-level Pharo class comment,
> >>> * Make it into a string in Pharo, put it in a method in a class.
> >>>
> >>> What's the standard practice for "attaching" non-code documents to
> Pharo
> >>> applications?
> >>>
> >>> -t
> >>>

>>> Okay, I'll do that. But this brings up a more general question...
>>>
>>> If I wanted to add a diagram, or maybe a document with equations
>> (rendered
>>> in LaTex), then a class comment wouldn't work.
>>>
>>> ...Unless that's intended to be part of the newer format??
>>
>> Microdown supports latex via external services (I should check that the
>> implementation uses the same cache than the one for pictures).
>> For diagram you can use png but we will have to spot glitches.
> One more thought on this...  I assume you've seen Jupyter Notebooks?
> They're starting to see some use where I work (we now have our own
> 'enterprise server').  I recently took an intro class to see how it works,
> and how to use them.
>
> How much of a "Jupyter-style" notebook capability would the community be
> interested in?  By that I mean having the ability to mix 'rich'
> documentation with code and data to produce interactive 'notebooks' with
> similarities to what Jupyter does -- but simpler!  Jupyter is much too
> complicated...

> What you describe for enhanced comments sounds like a step in that
> direction...  Obviously Pharo is already oriented toward mixing code and
> data in one document, and enhancing the comments moves it closer to a
> notebook with richer documentation possibilities.  
>
> So it seems to me that generalizing this "enhanced document capability" and
> making it more prominent (such as giving it its own type of window, rather
> than it being a browser pane tied to the code?) would take it closer yet to
> realizing a general, flexible "Pharo Notebooks" concept.
>
> My understanding is that Offray's Grafoscopio is essentially what I'm
> describing, but maybe more oriented to data analysis & presentation..??  (He
> can say better than I, as I'm not sure how accurate that is.)  I am thinking
> of something that would include that, but maybe be more general-purpose.

>
> Part of this idea is to feature a "semi-automated" subset of Spec2 that
> makes it easier to get nice graphical UIs in a notebook fashion -- but does
> not require as much depth of understanding Spec2.  (All of Spec2 allows
> anyone to build anything.. but not everyone needs to build so much..?  This
> is the value of frameworks and selectable motifs, yes?)  
>
> Could what I'm describing be a way for everyone to step easily into Spec2
> when its full flexibility for making GUIs isn't needed (yet)?  By this I'm
> implying code generators that create common/typical Spec2 framework classes
> & methods that would make up the front-end of the 'documentation' element of
> "Pharo Notebooks".  Pharo being Pharo, one could then customize further...

> Hi,
>
> On 5/08/20 9:43 a. m., tbrunz wrote:
>>>> Okay, I'll do that. But this brings up a more general question...
>>>>
>>>> If I wanted to add a diagram, or maybe a document with equations
>>> (rendered
>>>> in LaTex), then a class comment wouldn't work.
>>>>
>>>> ...Unless that's intended to be part of the newer format??
>>> Microdown supports latex via external services (I should check that the
>>> implementation uses the same cache than the one for pictures).
>>> For diagram you can use png but we will have to spot glitches.
>> One more thought on this...  I assume you've seen Jupyter Notebooks?
>> They're starting to see some use where I work (we now have our own
>> 'enterprise server').  I recently took an intro class to see how it works,
>> and how to use them.
>>
>> How much of a "Jupyter-style" notebook capability would the community be
>> interested in?  By that I mean having the ability to mix 'rich'
>> documentation with code and data to produce interactive 'notebooks' with
>> similarities to what Jupyter does -- but simpler!  Jupyter is much too
>> complicated...
> I can't speak for the wider community, but I think that there is some
> interest as we have 3 Smalltalk interactive notebooks alternatives. Two
> of them where mentioned as a long talks [1][2] in the last ESUG and
> Grafoscopio was presented there also as a speed talk (someday I need to
> make a proper ESUG long talk, but being self funded means that my
> participation has been always confirmed in last moments). I share your
> concern about Jupyter being overcomplicated and in fact I started
> Grafoscopio in part out of my frustration with the incidental complexity
> in the Python notebook ecosystem (see [3]). We can be more lean and agile.
>
> [1]
> https://www.slideshare.net/esug/polyglot-notebooks-with-squeaksmalltalk-on-the-graalvm
> [2] https://www.slideshare.net/esug/building-a-scientific-workbench-in-pharo
> [3]
> http://mutabit.com/offray/static/blog/output/posts/grafoscopio-idea-and-initial-progress.html
>
> One of the differences of Grafoscopio with other Smalltalk notebooks is
> that is has an older diverse community (since 2015), beyond academia and
> software developers, including activists, journalists, librarians,
> philosophers, designers, among others. A key concern is to balance
> practical choices in such communities with the PhD research that created
> Grafoscopio (which was on Design and Creation with immersive community
> research). For example a simple extensible format to exchange
> Grafoscopio notebooks was an early concern and for that I used the
> excellent STON  format to mix documentation markup (Markdown) and Pharo
> code. Also I bridged external tools (Pandoc, Lua) to make format
> conversions (Markdown to LaTeX, HTML and PDF). The only other Smalltalk
> notebook I know that has a notebook format is Documenter's[4] Xdoc,
> which is a compressed folder mixing Pillar, JSON, txt and external files
> referred in the Pillar document. Our approach for that composed
> documents is to use Fossil [5], so such composed document or any
> collection of documents in fact is just a self contained Fossil
> repository, adding history, web interface and collaboration, while
> keeping documents self contained and storage simple and portable. It's
> aligned with ideas of SQLite as and application format[5a] and the
> Panama Papers 2016 prototypes [6][6a] even predate the idea of Fossil as
> a repository document[5b].
>
> [4] https://gtoolkit.com/components/documenter/
> [5] https://fossil-scm.org/
> [5a]
> https://www.pgcon.org/2014/schedule/attachments/319_PGCon2014OpeningKeynote.pdf
> [6] https://mutabit.com/offray/blog/en/entry/panama-papers-1
> [6a] https://mutabit.com/repos.fossil/panama-papers/dir
> [5b] https://fossil-scm.org/forum/forumpost/2ac0171524
>
> What I want to point is that different approaches to rich interactive
> documentation related with Pharo exist and they're exploring interesting
> alternative spaces beyond what Jupyter has done, despite of lacking the
> maturity, momentum and/or visibility behind Jupyter's. Scientific
> Workbench, Documenter, or polyglot notebooks for sure are providing
> valuable explorations and would be nice to be more aware of each others
> work and approaches.
>
>> What you describe for enhanced comments sounds like a step in that
>> direction...  Obviously Pharo is already oriented toward mixing code and
>> data in one document, and enhancing the comments moves it closer to a
>> notebook with richer documentation possibilities.  
>>
>> So it seems to me that generalizing this "enhanced document capability" and
>> making it more prominent (such as giving it its own type of window, rather
>> than it being a browser pane tied to the code?) would take it closer yet to
>> realizing a general, flexible "Pharo Notebooks" concept.
>>
>> My understanding is that Offray's Grafoscopio is essentially what I'm
>> describing, but maybe more oriented to data analysis & presentation..??  (He
>> can say better than I, as I'm not sure how accurate that is.)  I am thinking
>> of something that would include that, but maybe be more general-purpose.
> In Grafoscopio, interactive notebooks play an essential role with their
> own window and usage metaphor (document as an interactive tree). When I
> started, microdown was not in the radar and I would like explore further
> integration with it, instead of relaying on (excellent) Pandoc for
> format conversion. I have scripted Pandoc with Lua and is a pretty
> powerful combination and an interesting language, but nothing beats the
> Pharo's live coding experience and I would like to have that also for
> document exporters and (pre)processors. I think that Grafoscopio is
> already general concept-purpose enough. I wrote the Grafoscopio
> manual[7] in Pharo. We have done other non-coding and visualization
> documents on it, like porting the Data Journalism Handbook[8][8a] and
> Data Feminism Book[9][9a] to our pocket infrastructures.
>
> [7]
> https://mutabit.com/repos.fossil/grafoscopio/uv/Docs/En/Books/Manual/manual.pdf
> [8] https://mutabit.com/repos.fossil/mapeda/doc/tip/intro.md
> [8a] https://mutabit.com/repos.fossil/mapeda/uv/mapeda.pdf
> [9] https://mutabit.com/repos.fossil/datafem/
> [9a] https://mutabit.com/repos.fossil/datafem/uv
>
> That being said, Grafoscopio was the "first real app" I ever did. The
> one that allowed me to go from scripting and formal modelling to
> programming and development. Its development has been directed by
> necessity and I have conceptual gaps and rookie code here and there.
> Development has been improved as I learn more, and I have being
> fortunate enough to have the attention and support from several
> community members, from testing and installing, to answering newbie
> questions, to my PhD internship, to bug reporting and even one offered
> to pair program with me (but I was too newbie, non-native speaker and
> shy to accept at that moment). Our last collaborator is Santiago
> Bragragnolo and he has been working on some refactoring.
>
> August will be kind of busy for me until 21th, but I would gladly be
> more involved with Grafoscopio after and meanwhile, retaking slowly some
> workshops and solving bugs.
>
>> Part of this idea is to feature a "semi-automated" subset of Spec2 that
>> makes it easier to get nice graphical UIs in a notebook fashion -- but does
>> not require as much depth of understanding Spec2.  (All of Spec2 allows
>> anyone to build anything.. but not everyone needs to build so much..?  This
>> is the value of frameworks and selectable motifs, yes?)  
>>
>> Could what I'm describing be a way for everyone to step easily into Spec2
>> when its full flexibility for making GUIs isn't needed (yet)?  By this I'm
>> implying code generators that create common/typical Spec2 framework classes
>> & methods that would make up the front-end of the 'documentation' element of
>> "Pharo Notebooks".  Pharo being Pharo, one could then customize further...
> My idea was to use a "self referential system" to explore the question
> about "How can we change the digital artifacts that change us?", from
> the perspective of a PhD in design and creation (not in computer
> science). But the idea was to create/introduce a tool inside a community
> (Grafoscopio) see how the community learn such tool and was able to
> change it. Interactive notebooks was my bridge to approach Pharo to
> non-coders. We are still far away of changing the tool itself, as Pharo
> and Grafoscopio has been kind of behind scenes in the projects we do and
> the more visible part has been documentation and a little bit of
> scripting. But I hope that the Indie Web workshops talked in other
> thread, make more visible the coding and scripting part so people can
> use it to customize their web sites, then notebooks and, at some point
> Grafoscopio or Pharo. The idea is to use interactive notebooks to
> automatize and customize Pharo to user needs and make such learning a
> bridge to customize Pharo.
>
>> Because "it's always easier to edit something than to create from a blank
>> page", yes?
>>
>> I can see Pharo taking away "market share" from Jupyter Notebooks, by being
>> simpler and easier to work with.  Data + Code + Document: All three elements
>> being "live" and interactive.  Pharo has the first two.. What about the
>> third?
> You could check the "Data continuum environment: data <-> queries <->
> code <-> visuals <-> docs" of the Panama Papers blog post [10], that
> points in the same direction.
>
> [10] https://mutabit.com/offray/blog/en/entry/panama-papers-1
>
> Cheers,
>
> Offray
>
>
>
>

> >>> I've been thinking lately that it would be nice to expand the number of
> >>> Pharo tutorials we have available. But rather than (or along with)
> >>> creating
> >>> more "beginner" level tutorials, I'd like to see some good
> "intermediate"
> >>> level Pharo tutorials.
> >>
> >> Me too :)
> >
> > Let's do it, then. I'll volunteer to do most of the work. :^)
>
> I will review anything you write :)
> >
> > My hope is that participating in this will make me capable of creating
> > advanced tutorials all by myself.
>
> I usually like to write to learn and dump what I learned.
> >
> >>> I think that programmers who already know the Pharo
> >>> syntax and messaging semantics could benefit from more advanced
> tutorials
> >>> that demonstrate how to develop "real world" Pharo code for "real
> world"
> >>> processing needs.
> >>
> >> Yes yes I would love that.
> >
> > That was part of my motivation for creating a Pharo app to solve the
> Zebra
> > Puzzle. First, of course, I wanted to solve it. ;^)
>
> I will send you some feeedback and PR.

> One more thought on this...  I assume you've seen Jupyter Notebooks?
> They're starting to see some use where I work (we now have our own
> 'enterprise server').  I recently took an intro class to see how it works,
> and how to use them.
>
> How much of a "Jupyter-style" notebook capability would the community be
> interested in?  By that I mean having the ability to mix 'rich'
> documentation with code and data to produce interactive 'notebooks' with
> similarities to what Jupyter does -- but simpler!  Jupyter is much too
> complicated…

> My understanding is that Offray's Grafoscopio is essentially what I'm
> describing, but maybe more oriented to data analysis & presentation..??  (He
> can say better than I, as I'm not sure how accurate that is.)  I am thinking
> of something that would include that, but maybe be more general-purpose.
>
> Part of this idea is to feature a "semi-automated" subset of Spec2 that
> makes it easier to get nice graphical UIs in a notebook fashion -- but does
> not require as much depth of understanding Spec2.  (All of Spec2 allows
> anyone to build anything.. but not everyone needs to build so much..?  This
> is the value of frameworks and selectable motifs, yes?)  
>
> Could what I'm describing be a way for everyone to step easily into Spec2
> when its full flexibility for making GUIs isn't needed (yet)?  By this I'm
> implying code generators that create common/typical Spec2 framework classes
> & methods that would make up the front-end of the 'documentation' element of
> "Pharo Notebooks".  Pharo being Pharo, one could then customize further…

> Hi Offray,
>
> Just wanted to let you know that I enjoyed your several responses, and that
> I'm working on following-up to them.
>
> But first I wanted to look at all your links and make as thoughtful a reply
> as you have, and that takes a while...
>
> I think what you've been working on could be a good entry point for some
> groups where I work, so I do want to learn more.
>
> Cheers!
> -Ted
>
>
>
>
>
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
>