Igor wrote: >it would be cool being able to write help using markdown syntax, without >too much dependencies, so we can (hopefully) integrate it in base image.
I can only point again and again to "Pharo Online Help" which is solving all this already: one can write your docu without any dependency on the help system itself. So no need to subclass CustomHelp, no need to subclass HelpTopic. It already uses Markdown and is based on a single "marker" pragma. I also refer again to these two posts: http://lists.gforge.inria.fr/pipermail/pharo-project/2013-April/077036.html http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2013-September/083743.html So I already did my homework, and I can only gently ask people to do theirs too. Please try it in Pharo 2.0, its available in the config browser. Since there is no dependency anymore one can even add the markup docu to the ConfigurationOf... class in a basic image and load "Pharo Online Help" afterwards to view or serve it to others as a webpage. Markdown is used more and more (not only in the Pharo world) to easily write documentation. Even SmalltalkHub has Markdown support and many projects display their docu there. There are good editors with Preview available: http://benweet.github.io/stackedit and there is no excuse not to document ;) "Pharo Online Help" has (currently) to be viewed with an external browser. This way you can use more medias - many project provide tutorial videos on Youtube, Vimeo, ... and you can easily embed or link to them if you run in the browser. With better Text widget and better media support I'm sure we can also improve the in-image way of displaying documentation done in markup. My suggestions to improve the current situation: 1. The community agreed on Spec to build UI's - so we should also agree on a common way for docu too. Otherwise more and more different solutions will come up (and the situation will get worse). We should agree on a common way where to package documentation: maybe on the ConfigurationOfXXX class (Stef extends them with catalog informations, so why not also with docu) 2. SmalltalkHub already allows markup documentation of a project in the web ui. If we choose "ConfigurationOfXXX" as the place for storing docu then SmalltalkHub could be extended to display the markup right after uploading the config. This way I can write my docu together with the code in the browser, package my docu with my code, version it with Metacello and it automagically is gets up to date on STHub when I upload the config. Same goes if we agree on another convention (maybe a specific "MyProject-Docu" package name). 3. Yes - (even with less media support in Pharo) we should also allow viewing the documentation directly within the image. As Igor already proved this can be done even with the old help system also based on Markup. Fixing the broken markdown parser would help as a first step - but it has IMHO too many dependencies for general inclusion in the standard image. Maybe a lean MarkupParser could be written? 4. Write a spec based in-image help browser if step 3 is finished as I already explained in http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2013-September/084025.html 5. Write a markdown to Gutenberg converter so we can also use the documentation also in future Pharo books. So using Markdown, automatic display in SmalltalkHub and "Online Help" as well as improving in-image display is my proposal here. Feel free to help or provide better alternatives. Thx T.
