> > 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... 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? -t > > 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 > >>> -- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
