What about a seaside-based system browser oriented towards code documentation? That would fit both paradigms: html-like reference + live browsing.
You could even make it buzzword compliant: have a REST interface to documentation and code. Note how the panes in a system browser could make for a nice URI: just look for pharo://Kernel/Number/mathematical%20functions/raisedTo: And we could even include version numbers, etc.... pharo://6.1/Kernel/Number/mathematical%20functions/raisedTo: Not very different from the github url for the pharo project relevant file... https://github.com/pharo-project/pharo/blob/development/src/Kernel.package/Number.class/instance/raisedTo..st Thierry 2017-10-11 17:01 GMT+02:00 Offray Vladimir Luna Cárdenas < offray.l...@mutabit.com>: > Yes. I know them. I mean API docs as static files. I don't really sold on > them compared with a live system and I don't think static API docs are > critical for Pharo success. > > Cheers, > > Offray > > On 11/10/17 09:52, Dimitris Chloupis wrote: > > Ah and my static website was built with Pillar and Bootstrap, using > bootstrap templates was easy because Pillar supports mustache that makes > html manipulation much easier > > http://www.kilon-alios.com > > Pillar of course is not made for generating websites but it’s an awesome > Pharo library that allows for great degree of freedom so I thought , why > not ? > On Wed, 11 Oct 2017 at 17:48, Dimitris Chloupis <kilon.al...@gmail.com> > wrote: > >> Docs are available in static online html format , at least the book I was >> working on >> >> Pharo By Example >> >> You can find those links here >> >> https://github.com/SquareBracketAssociates/UpdatedPharoByExample >> >> Our documentation system , Pillar , outputs pdf , html and markdown >> files. >> >> If the book in question is built like PBE with CI of Inria where most >> Pharo related official projects are built then it should have at least pdf >> and html with online access so you can easily link to. >> >> Don’t quote me on this but I think the html output of pillar generate >> links even for paragraphs you can do an even more process linking to the >> documentation. >> On Wed, 11 Oct 2017 at 17:40, Offray Vladimir Luna Cárdenas < >> offray.l...@mutabit.com> wrote: >> >>> The more I use Pharo, the less I use web documentation. For me seems >>> pretty suboptimal compared to live environment with code browser and >>> GT-Spotter. Regarding the comment on Medium, it also took me little to find >>> #raisedTo:, so the millage can vary. What I was missing was proper books >>> for particular domains, but Pharo books are covering that. I don't know if >>> a Q&A site could improve search-ability for newbies (certainly you can find >>> little stuff in Stack Overflow). >>> >>> My bet is about trying to create more "end user" tools (Grafoscopio is >>> kind of this), besides tools for developers. There is a broad community of >>> people who can be active contributors and members of the community, welcome >>> Pharo and live coding a lot and don't complain that much about stuff that >>> is not already pretty similar to what they already know (being that only >>> English MOOC or online static html docs). >>> >>> Cheers, >>> >>> Offray >>> >>> On 11/10/17 07:34, Dimitris Chloupis wrote: >>> >>> for me it is a yes and no situation, yes its very coold to have your >>> entire system in your fingertips but Pharo has serious issues with code >>> organisation and I find the lack of namespaces quite inconvenient. You have >>> to be careful how to name your classes which does not sound to me very OOP >>> friendly. >>> >>> Also the IDE does not handle spaggetification very well, sure you can >>> find implementors , senders etc but if the execution chain is complex , >>> welcome to spaggeti hell. But that is a problem with most other IDEs if not >>> all as well. Problem is in this case that we have the very good rule of >>> using sort methods which multiplies this problem and makes navigation even >>> harder. Code becomes much easier to read per method and messages but much >>> harder to understand in a bird eye view. >>> >>> Some of that pain has been aleviated with the introduction of GTSpotter >>> which I have praised quite a lot and I will continue to do so. But yeah >>> there are more needed to be done in the department to make Pharo code >>> navigation a more comfortable task. >>> >>> On Wed, Oct 11, 2017 at 2:57 PM Vitor Medina Cruz <vitormc...@gmail.com> >>> wrote: >>> >>>> I dunno, maybe I’m weird, but I find the System Browser a fantastic way >>>> to explore the class library. If you find a class or method that isn’t well >>>> documented, write a comment and send a change request. Stef told me this >>>> ages ago. I might add, if you find a bug you should write a test that >>>> exercises the bug and submit it on fogbugz (the bug tracking system). >>>> >>>> >>>> I will reference of response of mine to a similar opinion made by >>>> Richard: https://medium.com/@vitormcruz/i-disagree-it-is- >>>> much-harder-to-find-anything-in-the-environment-c6bdd44f6eea >>>> >>>> My 2 cents. >>>> >>>> >>>> >>>> >>>> On Tue, Oct 10, 2017 at 11:59 PM, john pfersich <jpfers...@gmail.com> >>>> wrote: >>>> >>>>> >>>>> > On Oct 10, 2017, at 09:58, horrido <horrido.hobb...@gmail.com> >>>>> wrote: >>>>> > >>>>> > Interestingly, I'm getting a fair amount of pushback on this. >>>>> Personally, I >>>>> > think it would be very helpful to have a live (updatable, so as to >>>>> keep it >>>>> > current) reference page for the class library, something that >>>>> developers can >>>>> > easily look up what they need. After all, most of the power of Pharo >>>>> comes >>>>> > from the class library and we need to make it as accessible as >>>>> possible to >>>>> > less experienced Pharoers (i.e., beginners). >>>>> > >>>>> > Exploring the class library through the System Browser is very >>>>> inefficient. >>>>> > This is further exacerbated by the fact that many classes and >>>>> methods are >>>>> > simply not well-documented (containing a cursory remark which is >>>>> just barely >>>>> > useful). >>>>> > >>>>> I dunno, maybe I’m weird, but I find the System Browser a fantastic >>>>> way to explore the class library. If you find a class or method that isn’t >>>>> well documented, write a comment and send a change request. Stef told me >>>>> this ages ago. I might add, if you find a bug you should write a test that >>>>> exercises the bug and submit it on fogbugz (the bug tracking system). >>>>> >>>>> > I realize that creating a live reference page is not easy to do. In >>>>> fact, >>>>> > it's a lot of work. But the absence of such a page is a real >>>>> obstacle to >>>>> > Pharo acceptance. >>>>> > >>>>> > >>>>> > >>>>> > horrido wrote >>>>> >> Thanks. I gave your answer verbatim. I also added the following >>>>> paragraph: >>>>> >> >>>>> >> The problem I find with today’s developers is that they are rather >>>>> >> closed-minded. They are rigid and inflexible, and not willing to >>>>> adapt to >>>>> >> new and different ways of doing things. In my generation (circa >>>>> >> 1980–1990), >>>>> >> people didn’t have a problem with trying different technologies. >>>>> That’s >>>>> >> why >>>>> >> I had no issue with learning Smalltalk 10 years ago, after I had >>>>> retired >>>>> >> from a 20-year-long career in C systems programming and FORTRAN >>>>> scientific >>>>> >> programming. >>>>> >> >>>>> >> >>>>> >> >>>>> >> Sven Van Caekenberghe-2 wrote >>>>> >>>> On 6 Oct 2017, at 14:54, horrido < >>>>> >> >>>>> >>> horrido.hobbies@ >>>>> >> >>>>> >>> > wrote: >>>>> >>>> >>>>> >>>> I received this comment from someone who complained: >>>>> >>>> >>>>> >>>> *What about the lack of documentation? From time to time I’ve >>>>> checked >>>>> >>>> some >>>>> >>>> SmallTalk implementations like Squeak, GNU-Smalltalk and now >>>>> Pharo. Of >>>>> >>>> these, only GNU-SmallTalk appears to have a free, official >>>>> programming >>>>> >>>> guide >>>>> >>>> and core library reference that any serious programmer expects >>>>> from a >>>>> >>>> language. >>>>> >>>> >>>>> >>>> https://www.gnu.org/software/smalltalk/manual-base/html_node/* >>>>> >>>> >>>>> >>>> I pointed to Pharo's documentation but then he came back with: >>>>> >>>> >>>>> >>>> *Then show me a link of the free, maintained reference >>>>> documentation for >>>>> >>>> the >>>>> >>>> classes that form “the core library”, like this one for Python >>>>> >>>> (https://docs.python.org/3/library/index.html)* >>>>> >>>> >>>>> >>>> It's true, most Smalltalks do not have a core library reference, >>>>> not >>>>> >>>> even >>>>> >>>> VisualWorks! So what is the proper response to this complaint? >>>>> >>> >>>>> >>> The first answer is that Pharo/Smalltalk is unique in that a >>>>> running >>>>> >>> system/IDE contains _all_ source code, _all_ documentation (class, >>>>> >>> method, >>>>> >>> help, tutorial), _all_ unit tests and _all_ runnable examples in a >>>>> very >>>>> >>> easy, accessible way. It takes some getting used to, but this is >>>>> actually >>>>> >>> better and much more powerful than any alternative. >>>>> >>> >>>>> >>> The second answer is that there are lots of books and articles >>>>> that take >>>>> >>> the classic/structured book/paper approach. There is >>>>> >>> http://books.pharo.org, http://themoosebook.org, >>>>> >>> http://book.seaside.st/book, http://medium.com/concerning-pharo >>>>> and many >>>>> >>> more. >>>>> >>> >>>>> >>>> Thanks. >>>>> >>>> >>>>> >>>> >>>>> >>>> >>>>> >>>> -- >>>>> >>>> Sent from: http://forum.world.st/Pharo- >>>>> Smalltalk-Users-f1310670.html >>>>> >>>> >>>>> >> >>>>> >> >>>>> >> >>>>> >> >>>>> >> >>>>> >> -- >>>>> >> Sent from: http://forum.world.st/Pharo- >>>>> Smalltalk-Users-f1310670.html >>>>> > >>>>> > >>>>> > >>>>> > >>>>> > >>>>> > -- >>>>> > Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html >>>>> > >>>>> >>>>> >>>> >>> >
