Well there is a move towards Pillar for class and method commands so who knows maybe we will have that soon enough ;) There is a solution, not a great solution but it can do this. You can kinda do this via metacello and filetree, because when you export to git , it coverts class and method comments to markdown that can be viewed like online documentation . They are saved as README.md which is the standard for github. That means you can use markdown inside the class and method comments , and then convert that to HTML . Tons of markdown to html coverters out there so it would not be a problem. Of course Pharo users may not be happy to read comments in markdown but then markdown has minimal syntax so it should not be such a major issue. The real problem is the class comments itself, if you lack comments talking about automated API reference documentation sounds the least of the problems. Cannot blame developers, documentation is as much work as writting the code and I can understand that some may find it much less pleasant than I do :) I tried my best to help on the documentation department but we need more people because its an effort not only to document but also to keep the documentation updated. One of the perk working in an enviroment improving very fast, but you wont get any complain from me about this ;) On Wed, Oct 11, 2017 at 6:02 PM Offray Vladimir Luna Cárdenas < offray.luna@mutabit.com> wrote:
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
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.alios@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.luna@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 <vitormcruz@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...
My 2 cents.
On Tue, Oct 10, 2017 at 11:59 PM, john pfersich <jpfersich@gmail.com> wrote:
On Oct 10, 2017, at 09:58, horrido <horrido.hobbies@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