[Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
Hi guys - not sure how many people noticed this, but at the end of the tutorial for gtDocumentor, there is a section on Examples as Documentation. What is neat (and easily missed) is how when an example references another - there is a little triangle you can toggle to expose that example inline. (See photo). This isn’t a completely new ideas (didn’t Newspeak hopscotch do this?) but its very well done in gtDocumentor and this implication could be that if our code editors had this too - then its very handy to unfold code to understand it in one place without having to open new windows. (I still think there are times when you may want to do that - particularly for long chains of methods?) but its certainly an idea that I would be very receptive to having in our code browsers (heck - give me all of gtDocumentor in our source editors). I’m wondering what others thing of this? Perhpas not for Pharo 7 - but Pharo 8 (pretty please?) Tim p.s. Note to @feenk, as its the last example its incredibly tricky to expand it to actually see it well as you can’t scroll further down to then drag the window bigger. I had to add a lot of Cr’s to make some space to do this.
Re: [Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
Hi, > On Jun 26, 2018, at 1:16 PM, Tim Mackinnon wrote: > > Hi guys - not sure how many people noticed this, but at the end of the > tutorial for gtDocumentor, there is a section on Examples as Documentation. Thanks for going through the tutorial. Quick questions: - how did it feel to go through it? - did applying changes work fine for you? - was there any confusion about what happened and where you were in the tutorial? - anything missing that might have helped? > What is neat (and easily missed) is how when an example references another - > there is a little triangle you can toggle to expose that example inline. (See > photo). > > This isn’t a completely new ideas (didn’t Newspeak hopscotch do this?) but > its very well done in gtDocumentor and this implication could be that if our > code editors had this too - then its very handy to unfold code to understand > it in one place without having to open new windows. (I still think there are > times when you may want to do that - particularly for long chains of > methods?) but its certainly an idea that I would be very receptive to having > in our code browsers (heck - give me all of gtDocumentor in our source > editors). This actually a new take on the nature of an editor. Hopscotch did not allow expanding things inside the text editor. The editor was always a leaf, and it is so in all editors I have seen so far. In our case, the triangle is added live by the syntax highlighter. Right now, we only use it for navigating examples both because we needed to explore how we can make deeply nested examples simple to reason about, and because we wanted to validate the Bloc architecture. Of course, this ability is usable in many different ways. For example, the embedding in Pillar of various artifacts is done using the same mechanisms. And I think you will start seeing all sorts of applications in the UI area that you will simply not see in other places. > I’m wondering what others thing of this? Perhpas not for Pharo 7 - but Pharo > 8 (pretty please?) > > Tim > > p.s. Note to @feenk, as its the last example its incredibly tricky to expand > it to actually see it well as you can’t scroll further down to then drag the > window bigger. I had to add a lot of Cr’s to make some space to do this. Thanks. Indeed, the resizer solution you see now is just a first attempt without much polishing. Cheers, Doru > > > > -- www.tudorgirba.com www.feenk.com "Problem solving efficiency grows with the abstractness level of problem understanding."
Re: [Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
Tim Mackinnon wrote > its very handy to unfold code to understand it in one place There is also a Code Bubble-like demo from Feenk. - Cheers, Sean -- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
Re: [Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
Hi Doru - I’ll comment inline below:
> On 26 Jun 2018, at 13:05, Tudor Girba wrote:
>
> Hi,
>
>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon wrote:
>>
>> Hi guys - not sure how many people noticed this, but at the end of the
>> tutorial for gtDocumentor, there is a section on Examples as Documentation.
>
> Thanks for going through the tutorial. Quick questions:
> - how did it feel to go through it?
> - did applying changes work fine for you?
> - was there any confusion about what happened and where you were in the
> tutorial?
> - anything missing that might have helped?
Going through the tutorial felt reasonably intuitive (I have sort of seen
people use Jupyter from afar, so I guess I had an idea of what it was trying to
do)
I did notice that when I click on the Apply buttons, the change to “Applied”
was a bit subtle - particular if you scroll back to see if you missed a step.
So not sure if colouring the applied buttons or having some kind of Tick might
make it a bit more obvious (but it wasn’t that bad)
Applying the changes seemed to work fine - sometimes examples took a bit of
time, (but there is the progress indicator top left - although I was looking at
the button that I clicked, so maybe some subtle feedback there might help as
well)
I didn’t really get confused - however I will confess I only superficially
followed along and didn’t question any of what it was telling me (e.g. what
methods actually got created etc.). But conceptually it felt compelling and I
believed it.
I did find it a little bit sluggish to scroll (on a MacBook Pro 13” 2015 16gb
ram) - so sometimes I over scrolled - I also kind of missed having a proper
scrollbar in the window to help me understand how far down I was. I already
mentioned the diff pane scrolling issue. Also, only being able to resize output
boxes down was sometimes a bit frustrating (but workable)
I wasn’t clear on whether I was supposed to be able to edit the markup myself
while reading - e.g. putting * around some text didn’t make it bold (I kind of
thought it might - but maybe that’s not supported?)
When I click on the + or - magnifying glasses, I also can’t scroll anymore (so
its not like a zoom level - but again maybe this is just how its supposed to
work? - clicking circle/square icon put it back to 100% and it worked fine).
Before I loaded the full gToolkit, I did get some messages about things being
undefined - but the example still worked and I understood I needed to load
something else (and hence asked you here).
Something that did cross my mind (and this was something I questioned about
Jupyter) - if you want to reuse intermediate results - as in assign a script
result to a variable and then reference later down in your text (like when
doing a math’s problem) - it wasn’t clear if that is possible and obvious.
Something like
X := ${example:GtExamplesTutorial>>#createFileInMemory}$
And then you talk about X and then demonstrate something like (making use of X):
${example:GtExamplesTutorial>>#selectUppcaseLinesFrom: X}$
I’m guessing you can hide it all in the image with global variables - but I was
thinking about how we auto define variables in the playground, and then
incorporating those in the narrative.
Anyway I was very impressed (as was the group at UK Smalltalk) - there is lots
of legs in this.
Tim
P.s. It was cool that the inspectors work and jump into the gtInspector stuff.
I wasn’t clear on what all the different tabs are - maybe of which are similar
(_Pillar vs _GT) - but I assume this is just the WIP nature of it. I did also
get a few talkbacks clicking on items in the inspector -but again WIP or just
missing dependencies?
>
>> What is neat (and easily missed) is how when an example references another -
>> there is a little triangle you can toggle to expose that example inline.
>> (See photo).
>>
>> This isn’t a completely new ideas (didn’t Newspeak hopscotch do this?) but
>> its very well done in gtDocumentor and this implication could be that if our
>> code editors had this too - then its very handy to unfold code to understand
>> it in one place without having to open new windows. (I still think there are
>> times when you may want to do that - particularly for long chains of
>> methods?) but its certainly an idea that I would be very receptive to having
>> in our code browsers (heck - give me all of gtDocumentor in our source
>> editors).
>
> This actually a new take on the nature of an editor. Hopscotch did not allow
> expanding things inside the text editor. The editor was always a leaf, and it
> is so in all editors I have seen so far. In our case, the triangle is added
> live by the syntax highlighter. Right now, we only use it for navigating
> examples both because we needed to explore how we can make deeply nested
> examples simple to reason about, and because we wanted to validate the Bloc
> architecture.
>
> Of course, this ability is usable in many differe
Re: [Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
Hi Tim,
Thanks a lot for the detailed comments! More inline.
> On Jun 26, 2018, at 2:57 PM, Tim Mackinnon wrote:
>
> Hi Doru - I’ll comment inline below:
>
>> On 26 Jun 2018, at 13:05, Tudor Girba wrote:
>>
>> Hi,
>>
>>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon wrote:
>>>
>>> Hi guys - not sure how many people noticed this, but at the end of the
>>> tutorial for gtDocumentor, there is a section on Examples as Documentation.
>>
>> Thanks for going through the tutorial. Quick questions:
>> - how did it feel to go through it?
>> - did applying changes work fine for you?
>> - was there any confusion about what happened and where you were in the
>> tutorial?
>> - anything missing that might have helped?
>
> Going through the tutorial felt reasonably intuitive (I have sort of seen
> people use Jupyter from afar, so I guess I had an idea of what it was trying
> to do)
>
> I did notice that when I click on the Apply buttons, the change to “Applied”
> was a bit subtle - particular if you scroll back to see if you missed a step.
> So not sure if colouring the applied buttons or having some kind of Tick
> might make it a bit more obvious (but it wasn’t that bad)
Ok.
> Applying the changes seemed to work fine - sometimes examples took a bit of
> time, (but there is the progress indicator top left - although I was looking
> at the button that I clicked, so maybe some subtle feedback there might help
> as well)
Ok.
> I didn’t really get confused - however I will confess I only superficially
> followed along and didn’t question any of what it was telling me (e.g. what
> methods actually got created etc.). But conceptually it felt compelling and I
> believed it.
This is great!
> I did find it a little bit sluggish to scroll (on a MacBook Pro 13” 2015 16gb
> ram) - so sometimes I over scrolled - I also kind of missed having a proper
> scrollbar in the window to help me understand how far down I was. I already
> mentioned the diff pane scrolling issue. Also, only being able to resize
> output boxes down was sometimes a bit frustrating (but workable)
What do you mean by only being able to resize down? You should be able to
resize them up as well. Or did I misunderstand?
> I wasn’t clear on whether I was supposed to be able to edit the markup myself
> while reading - e.g. putting * around some text didn’t make it bold (I kind
> of thought it might - but maybe that’s not supported?)
Bold is not added in the highlighter. Indeed, what you see is a live editor so
editing is intended. However, we still have a few issues with it. While they
are small, the experience can appear brittle at the moment.
> When I click on the + or - magnifying glasses, I also can’t scroll anymore
> (so its not like a zoom level - but again maybe this is just how its supposed
> to work? - clicking circle/square icon put it back to 100% and it worked
> fine).
Thanks. We have to update those.
> Before I loaded the full gToolkit, I did get some messages about things being
> undefined - but the example still worked and I understood I needed to load
> something else (and hence asked you here).
Ok.
> Something that did cross my mind (and this was something I questioned about
> Jupyter) - if you want to reuse intermediate results - as in assign a script
> result to a variable and then reference later down in your text (like when
> doing a math’s problem) - it wasn’t clear if that is possible and obvious.
> Something like
>
> X := ${example:GtExamplesTutorial>>#createFileInMemory}$
> And then you talk about X and then demonstrate something like (making use of
> X):
>
> ${example:GtExamplesTutorial>>#selectUppcaseLinesFrom: X}$
> I’m guessing you can hide it all in the image with global variables - but I
> was thinking about how we auto define variables in the playground, and then
> incorporating those in the narrative.
The document already provides an out variable with the output of the previous
snippet, and and outs variable with all results. However, we do want to extend
this a bit more. For example, if you define a variable in a script, that
variable will be usable in other snippets throughout the document.
Indeed, we can bring the narrative significantly further than it is now.
> Anyway I was very impressed (as was the group at UK Smalltalk) - there is
> lots of legs in this.
Thanks!
> Tim
>
> P.s. It was cool that the inspectors work and jump into the gtInspector
> stuff. I wasn’t clear on what all the different tabs are - maybe of which are
> similar (_Pillar vs _GT) - but I assume this is just the WIP nature of it. I
> did also get a few talkbacks clicking on items in the inspector -but again
> WIP or just missing dependencies?
We are now in a transition period: because we do not have windows and enough
widgets in Bloc, we are reusing the existing Morphic-based infrastructure. All
presentations that start with _ are rendered in Bloc. _GT is the new bloc-based
inspector
Re: [Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation
This is all so cool - I see a lot of stuff really coming together (and I still
think gtInspector and moldability continue to have legs which nicely underpin
documentor).
I’m sad I can’t make it to esug this year as I’d love to be inspired more.
Tim
Sent from my iPhone
> On 26 Jun 2018, at 18:14, Tudor Girba wrote:
>
> Hi Tim,
>
> Thanks a lot for the detailed comments! More inline.
>
>
>> On Jun 26, 2018, at 2:57 PM, Tim Mackinnon wrote:
>>
>> Hi Doru - I’ll comment inline below:
>>
>>> On 26 Jun 2018, at 13:05, Tudor Girba wrote:
>>>
>>> Hi,
>>>
On Jun 26, 2018, at 1:16 PM, Tim Mackinnon wrote:
Hi guys - not sure how many people noticed this, but at the end of the
tutorial for gtDocumentor, there is a section on Examples as Documentation.
>>>
>>> Thanks for going through the tutorial. Quick questions:
>>> - how did it feel to go through it?
>>> - did applying changes work fine for you?
>>> - was there any confusion about what happened and where you were in the
>>> tutorial?
>>> - anything missing that might have helped?
>>
>> Going through the tutorial felt reasonably intuitive (I have sort of seen
>> people use Jupyter from afar, so I guess I had an idea of what it was trying
>> to do)
>>
>> I did notice that when I click on the Apply buttons, the change to “Applied”
>> was a bit subtle - particular if you scroll back to see if you missed a
>> step. So not sure if colouring the applied buttons or having some kind of
>> Tick might make it a bit more obvious (but it wasn’t that bad)
>
> Ok.
>
>> Applying the changes seemed to work fine - sometimes examples took a bit of
>> time, (but there is the progress indicator top left - although I was looking
>> at the button that I clicked, so maybe some subtle feedback there might help
>> as well)
>
> Ok.
>
>> I didn’t really get confused - however I will confess I only superficially
>> followed along and didn’t question any of what it was telling me (e.g. what
>> methods actually got created etc.). But conceptually it felt compelling and
>> I believed it.
>
> This is great!
>
>> I did find it a little bit sluggish to scroll (on a MacBook Pro 13” 2015
>> 16gb ram) - so sometimes I over scrolled - I also kind of missed having a
>> proper scrollbar in the window to help me understand how far down I was. I
>> already mentioned the diff pane scrolling issue. Also, only being able to
>> resize output boxes down was sometimes a bit frustrating (but workable)
>
> What do you mean by only being able to resize down? You should be able to
> resize them up as well. Or did I misunderstand?
>
>> I wasn’t clear on whether I was supposed to be able to edit the markup
>> myself while reading - e.g. putting * around some text didn’t make it bold
>> (I kind of thought it might - but maybe that’s not supported?)
>
> Bold is not added in the highlighter. Indeed, what you see is a live editor
> so editing is intended. However, we still have a few issues with it. While
> they are small, the experience can appear brittle at the moment.
>
>> When I click on the + or - magnifying glasses, I also can’t scroll anymore
>> (so its not like a zoom level - but again maybe this is just how its
>> supposed to work? - clicking circle/square icon put it back to 100% and it
>> worked fine).
>
> Thanks. We have to update those.
>
>> Before I loaded the full gToolkit, I did get some messages about things
>> being undefined - but the example still worked and I understood I needed to
>> load something else (and hence asked you here).
>
> Ok.
>
>> Something that did cross my mind (and this was something I questioned about
>> Jupyter) - if you want to reuse intermediate results - as in assign a script
>> result to a variable and then reference later down in your text (like when
>> doing a math’s problem) - it wasn’t clear if that is possible and obvious.
>> Something like
>>
>> X := ${example:GtExamplesTutorial>>#createFileInMemory}$
>> And then you talk about X and then demonstrate something like (making use of
>> X):
>>
>> ${example:GtExamplesTutorial>>#selectUppcaseLinesFrom: X}$
>> I’m guessing you can hide it all in the image with global variables - but I
>> was thinking about how we auto define variables in the playground, and then
>> incorporating those in the narrative.
>
> The document already provides an out variable with the output of the previous
> snippet, and and outs variable with all results. However, we do want to
> extend this a bit more. For example, if you define a variable in a script,
> that variable will be usable in other snippets throughout the document.
>
> Indeed, we can bring the narrative significantly further than it is now.
>
>> Anyway I was very impressed (as was the group at UK Smalltalk) - there is
>> lots of legs in this.
>
> Thanks!
>
>> Tim
>>
>> P.s. It was cool that the inspectors work and jump into the gtInspector
>> stuff. I wasn’t clear on what all the differen
