yes I think that is a nice idea. we would need to see how it fitted in with http://pharo-project.org/documentation as it is currently, and if we load cms-box with all content or something else for dynamically generated stuff like your seaside example (or -> static html).
cheers, Mike 2010/4/21 laurent laffont <[email protected]>: > Yes, Python documentation is really impressive, the best I know. > May be we can go the other way, from HelpSystem to web. I've tried something > like some months > ago.ex: http://magaloma.seasidehosting.st/Collections-Streams. > So we can have a documentation page like http://docs.python.org/py3k/ with: > - collaborator book > - web edition of Pharo By Example > - HelpSystem books > - API reference generated from comments in classes / methods (with the > possibility to add comments like jQuery or PHP online docs.) > All on one page, starting point to look for documentation, at > http://docs.pharo-project.org > Cheers, > Laurent Laffont > > > On Wed, Apr 21, 2010 at 10:46 PM, Michael Roberts <[email protected]> wrote: >> >> Laurent, i think this is a tension that a number of us feel. should we >> put documentation in the colab book, or in the system? For me the two >> are distinct. The book, ultimately, should read as a book. That is >> there is a logical flow from start to finish and the content is >> consistent, from start to finish, for a given version of the system. >> Writing a book appears hard - i have never done it - but i have >> attempted to copy-edit material that turned out to be as big as a >> reasonably sized book; i found that near impossible. So whilst the >> colab book effort is currently in its infancy, i would expect over >> time it to tend towards being published as a consistent whole. I'm >> sure anyone involved in SBE/PBE could comment on the real work >> required to write such a book. >> >> As for help in the system, as torsten nicely articulated either "Help" >> or "Reference", this should really be dynamic. It should change at the >> unit of which it is changing. so if a new version of a package is >> loaded, perhaps the Reference docs change. using hyperlink references >> you should be able to jump around it in an arbitrary order. I don't >> see a book performing this function. really it must flow consistently >> from start to finish and the layout of the book is carefully picked by >> the editors. the only realy hyperlink function is from the TOC, and to >> any particular index or reference. it is quite distinct from arbitrary >> jumping at a system doc level. >> >> at the moment these two forces I consider are at tension, because >> there is not enough reference material in the system as we shipped >> 1.0, and i think the barrier to viewing & editing such reference >> documentation, as a coherent whole, to my satisfaction is harder than >> using Pier. therefore i find it easier to edit pier even if i have >> only contributed a few paragraphs. however longer term this will not >> be the case. We must strive for something akin to Python >> documentation. as an engineering artifact, it is simply stunning; you >> can find documentation on anything to do with a given released >> version. i'm sure this applies to other languages too, i just use >> python as an example because I particularly like its style towards doc >> annotation and its completeness. >> >> so personally i don't think we should export the pier content into the >> help system. i see them as quite different, and for both to succeed I >> think they require a different point of view to writing the content. >> >> Torsten - i did not reply to the other thread which stef and I both >> commented on, have not had the time. For me i am a total pragmatist >> when it comes toward reference documentation and i am only really >> interested in reference docs. i fully understand your design and i'm >> fine with that. I just hope that as a community we can author the >> reference side, since that is what i feel is most missing. >> >> cheers, >> Mike >> >> 2010/4/21 laurent laffont <[email protected]>: >> > Hi, >> > It's cool to have so many interests in documentation. I deeply think >> > it's a >> > key point to success. >> > As an hobbyist contributor to Pharo documentation :) I wonder whether I >> > should write doc in HelpSystem (which indeed is very cool !) or in the >> > collaborator active book (which is very attractive for me). >> > So a way to get the best of both world may be to generate an HelpSystem >> > book >> > from the collaborator book. Every day, if there has been changes in the >> > collaborative book, it can be "packaged" automatically as an HelpSystem >> > book >> > / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem >> > project >> > lastVersion pointing to the last package. >> > Sounds good ? >> > Cheers, >> > Laurent Laffont >> > >> > >> > On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[email protected]> >> > wrote: >> >> >> >> To clearify a few things from my side on the discussion >> >> on squeak-dev: >> >> >> >> 1. HelpSystem is working, if ASCII is OK for now we can use >> >> it Pharo/Squeak - otherwise I would see it as an early preview. >> >> I have clear goals how it should look like in the >> >> next iterations. For this more patience is necessary. >> >> >> >> 2. HelpSystem is independent from where and how the actual >> >> information is stored (I think I demonstrated this with >> >> the IRC example, the books and the API help). >> >> >> >> 3. I hope to keep HelpSystem in sync for major Squeak distributions >> >> (Squeak, Pharo, Cuis, ...) >> >> >> >> The last additions from Hannes already broke the code >> >> in Pharo. Seems to be a Pharo issue this time >> >> http://code.google.com/p/pharo/issues/detail?id=2342 >> >> >> >> But please dont commit when it is only working in >> >> Squeak since my development environment is Pharo. >> >> >> >> 4. Yes, the content is currently ASCII but the design is prepared >> >> to add other types in future releases. >> >> >> >> A HelpTopic defines an ivar "contents" - currently referring >> >> to a string. I may add another ivar "contentType" >> >> in the future to handle/distinguish additionaly types >> >> (HTML, SqueaksRichText, Morphs/BookMorph, ...) >> >> >> >> 5. HelpSystem should not be limited to Squeak. It should also >> >> serve the case that when you write and deploy a commercial >> >> app in Squeak you may use it to provide help to your >> >> end user/customer >> >> >> >> 6. There are two types of help I see: >> >> >> >> A. SystemHelp: Help books/Tutorials/Manuals >> >> B. SystemReference: API Help, class comments >> >> >> >> HelpSystem is supporting both. >> >> I already wrote about the differences and details in >> >> >> >> >> >> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html >> >> >> >> 7. I would really like to see support for HTML viewing >> >> in the image (HTMLViewMorph or so) - maybe based on Scamper >> >> to get a better viewer (headings, tables, ...) than the >> >> current plain text. >> >> If people want to contribute they should start right with this >> >> task. >> >> >> >> I know that Laurent already made Scamper loadable in Pharo, >> >> dont know about the state in Squeak. >> >> >> >> There is also another HTML browser with markup and CSS now >> >> available >> >> open source as MIT (WithStyle), I already mentioned this. >> >> >> >> >> >> >> >> http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145 >> >> >> >> 8. I know that we now have discussions on which syntax (Wiki,...) >> >> to use for describing the contents. >> >> My answer is: it is important but I dont care (yet) since >> >> this discussion is useless until we have an HTML viewer (see 7.) >> >> and even when there are different syntax styles you can provides >> >> builders to transform them into HTML or other contentTypes >> >> afterwards. >> >> >> >> See the class HelpBuilder and subclasses. >> >> >> >> 9. If you want to write a book for SystemHelp (see 6.A) then >> >> the help system provides a class "CustomHelp" similar >> >> to TestCase in SUnit. This class is used to directly >> >> map book structures to the class hierarchy. >> >> >> >> The intention was to be able to create, store and manage >> >> these books directly with the usual Smalltalk tools. >> >> You can even restructure your book with the RefactoringBrowser. >> >> >> >> 10. If you want to write API help you (see 6.B) can contribute >> >> right now by commenting all the undocumented classes in the >> >> standard image. >> >> >> >> HelpSystem just queries these informations from the usual >> >> sources (class comments, ...). I would not change this >> >> or make it too complicated since this is what people are >> >> used too. >> >> >> >> I dont see more documented classes by introducing a >> >> special syntax (wiki or whatever) people have to learn/know about >> >> - so lets clean up documenting the classes first. >> >> >> >> 11. HelpSystem is able to get contents from external sources >> >> (see the IRC example) - but I would prefer that authoring/viewing >> >> could be done right from within the image. >> >> Even when the result is stored external afterwards. >> >> >> >> Look at my example books: I can view and change them >> >> right from the image and make them available to other images >> >> using Metacello/Squeaksource. >> >> Accessibility of docu (viewing and authoring) is the key to keep >> >> the system and docu in sync and up to date. >> >> >> >> External authoring mostly results in unmaintained docu (see >> >> the Squeak Swiki). >> >> >> >> 12. I thought again if it is ready to integrate into Pharo and >> >> Squeak. From all the discussions I would say it is too early. >> >> >> >> 13. If one wants the docu on the web the answer is easy: we >> >> can generate static files or serve them with Seaside. >> >> But I have no need for that right now, especially since >> >> this is already available in various forms. >> >> >> >> We can do many things (similar to Python, JavaDoc, you name it) >> >> >> >> But - let's do it step by step. As I said: >> >> >> >> - Someone working on a good HTML Viewer that I can integrate >> >> would really help moving this forward >> >> (based on Scamper or by porting WithStyle) >> >> - Updating class comments would also help a lot >> >> >> >> Bye >> >> Torsten >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> -- >> >> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT! >> >> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01 >> >> >> >> _______________________________________________ >> >> Pharo-project mailing list >> >> [email protected] >> >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > >> > >> > _______________________________________________ >> > Pharo-project mailing list >> > [email protected] >> > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > >> >> _______________________________________________ >> Pharo-project mailing list >> [email protected] >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > _______________________________________________ > Pharo-project mailing list > [email protected] > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
