Hi,
sorry for changing the topic - but again I saw discussion on "in-image" documentation. Are you all aware of the "HelpSystem" project that I wrote for Pharo and Squeak and that was already discussed on pharo-dev list. It is ready for integration and we can already fill it with content packages (docus, lessons as books). It is still ASCII based but maybe we can later enhance it using old Scamper code to be based on simple markup, ... If you want to have a look at the "core": Installer squeaksource project: 'HelpSystem'; install: 'HelpSystem-Core'. This "core" has the basic support and the browser. But you can write your documentation content even without it and later convert it using a special method. More on this below. You can open the help browser via "open" -> "HelpBrowser" or by evaluating "HelpBrowser open". By default it only provides the help for the help system itself. If you load it with example books like Installer squeaksource project: 'HelpSystem'; install: 'HelpSystem-Core'; install: 'HelpSystem-Tests'; install: 'Metacello-Help'; install: 'Pharo-Project-Help'; install: 'Squeak-Project-Help'. HelpBrowser open from the same repository you will get examples how books can look like. It also integrates an API Help like system, try one of these: HelpBrowser openOn: Integer. HelpBrowser openOn: (SystemReference hierarchyFor: Integer). HelpBrowser openOn: SystemReference. "Complete reference" Gives contents without much work ;) The basic model is simple now (see [1] and class HelpTopic and HelpBrowser). Read [2] and [3] and the "Help on Help" book in the help browser itself to learn about it. If you want to write own books that show up in the standard SystemHelp look at subclasses of CustomHelp. But you can open the help browser on anything that implements #asHelpTopic. Check for implementors to learn from the code. So either you create a book in the CustomHelp class hierarchy or define your content elsewhere. You can easily convert any source into a help topic, which I demoed with the IRC channel logs. Evaluate my code example in [4] to get a help browser on last weeks activity on squeak IRC channel. See also the attached screenshots. Bye Torsten -- GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT! Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01 |
Torsten,
Thanks for putting me onto this, it's way cool, and you have saved me from trying to implement it myself. I wanted to point out, ascii (or maybe unicode) is fine. If we want markup, I think the way to do that would be to implement something like #asWAComponent on HelpTopic and let Seaside do the heavy lifting.
Anyhow, way cool!
On Tue, Apr 20, 2010 at 11:31 AM, Torsten Bergmann <[hidden email]> wrote: Hi, |
Regarding markup
I think we should look into the ideas presented by 'markdown'. http://en.wikipedia.org/wiki/Markdown There are a lot of converters in many languages and into many formats. The idea is to have a markup language which "degrades" nicely when it is viewed as pure text. For example you write a documentation snippet in an email, you paste it into the documentation and it it nicely rendered. The question is: which 'markup' elements do we need? - bold - italic - code - headings - links - images And then which is the 'original code'. Maybe we should go for the wiki syntax used in Pier2. The help file could be turned into a viewer for a pier document tree. Hannes On 4/21/10, Casey Ransberger <[hidden email]> wrote: > Torsten, > > Thanks for putting me onto this, it's way cool, and you have saved me from > trying to implement it myself. > > I wanted to point out, ascii (or maybe unicode) is fine. If we want markup, > I think the way to do that would be to implement something like > #asWAComponent on HelpTopic and let Seaside do the heavy lifting. > > Anyhow, way cool! > > On Tue, Apr 20, 2010 at 11:31 AM, Torsten Bergmann <[hidden email]> wrote: > >> Hi, >> >> sorry for changing the topic - but again I saw discussion on >> "in-image" documentation. >> >> Are you all aware of the "HelpSystem" project that I wrote for Pharo and >> Squeak and that was already discussed on pharo-dev list. >> >> It is ready for integration and we can already fill it with >> content packages (docus, lessons as books). It is still ASCII based >> but maybe we can later enhance it using old Scamper code to be based >> on simple markup, ... >> >> If you want to have a look at the "core": >> >> Installer squeaksource >> project: 'HelpSystem'; >> install: 'HelpSystem-Core'. >> >> This "core" has the basic support and the browser. But you can >> write your documentation content even without it and later >> convert it using a special method. More on this below. >> >> You can open the help browser via "open" -> "HelpBrowser" or by evaluating >> "HelpBrowser open". By default it only provides the help for the help >> system itself. >> >> If you load it with example books like >> >> Installer squeaksource >> project: 'HelpSystem'; >> install: 'HelpSystem-Core'; >> install: 'HelpSystem-Tests'; >> install: 'Metacello-Help'; >> install: 'Pharo-Project-Help'; >> install: 'Squeak-Project-Help'. >> HelpBrowser open >> >> >> from the same repository you will get examples how books can >> look like. >> >> It also integrates an API Help like system, try one of these: >> >> HelpBrowser openOn: Integer. >> HelpBrowser openOn: (SystemReference hierarchyFor: Integer). >> HelpBrowser openOn: SystemReference. "Complete reference" >> >> Gives contents without much work ;) >> >> The basic model is simple now (see [1] and class HelpTopic and >> HelpBrowser). Read [2] and [3] and the "Help on Help" book in >> the help browser itself to learn about it. >> >> If you want to write own books that show up in the standard >> SystemHelp look at subclasses of CustomHelp. >> >> But you can open the help browser on anything that implements >> #asHelpTopic. Check for implementors to learn from the code. >> >> So either you create a book in the CustomHelp class hierarchy >> or define your content elsewhere. >> >> You can easily convert any source into a help topic, which I >> demoed with the IRC channel logs. >> Evaluate my code example in [4] to get a help browser on last >> weeks activity on squeak IRC channel. >> >> See also the attached screenshots. >> >> Bye >> Torsten >> -- >> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT! >> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01 >> >> > |
Am 2010-04-21 um 09:53 schrieb Hannes Hirzel: > Regarding markup > > I think we should look into the ideas presented by 'markdown'. > > http://en.wikipedia.org/wiki/Markdown > There are a lot of converters in many languages and into many formats. > There are Different such languages. • Markdown, incarnation in Perl http://daringfireball.net/projects/markdown/ – a bunch of extenstions thereof like http://fletcherpenney.net/multimarkdown/ • Textile incarnation in PHP http://textile.thresholdstate.com/ Both tend to be heavily used in Rails/Ruby on Rails • reStructured Text incarnation in Python docutils http://docutils.sourceforge.net/rst.html used for python docstrings and PEPs From its history and its application (and because i like the syntax) I'd vote for the last one so Long, -Tobias |
Thank you Tobias for this background information.
I would like to remind us that we have our "own markup language": Text. It is not possible to write it manually as a plain text but the string representation is OK. So we need convenience methods like Text fromTextile: aString Text fromReStructuredText: aString Text fromPier2WikiText: aString and the inverse Text>>asTextile Text>>asRestructuredText Text>>asPier2WikiText As these languages are not feature complete there could be some loss of formatting by doing a round-trip. However I would say let's focus on what works. - headings - bold / italics - links - images - code - ... maybe more Helpful in addition http://en.wikipedia.org/wiki/Lightweight_markup_language It contains a syntax comparison table, HTH Hannes >From WP <citation> A lightweight markup language is a markup language with a simple syntax, designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form. Lightweight markup languages are used in applications where people might be expected to read the document source as well as the rendered output. For instance, a person downloading a software library might prefer to read the documentation in a text editor rather than a browser. Another application is for entry in web-based publishing, such as weblogs and wikis, where the input interface is a simple text box. The server software converts the input to a common document markup language like HTML or XHTML. </citation> On 4/21/10, Tobias Pape <[hidden email]> wrote: > > Am 2010-04-21 um 09:53 schrieb Hannes Hirzel: > >> Regarding markup >> >> I think we should look into the ideas presented by 'markdown'. >> >> http://en.wikipedia.org/wiki/Markdown >> There are a lot of converters in many languages and into many formats. >> > > There are Different such languages. > • Markdown, incarnation in Perl > http://daringfireball.net/projects/markdown/ > – a bunch of extenstions thereof > like http://fletcherpenney.net/multimarkdown/ > • Textile incarnation in PHP > http://textile.thresholdstate.com/ > Both tend to be heavily used in Rails/Ruby on Rails > > • reStructured Text incarnation in Python docutils > http://docutils.sourceforge.net/rst.html > used for python docstrings and PEPs > > From its history and its application > (and because i like the syntax) > I'd vote for the last one > > so Long, > -Tobias > |
Free forum by Nabble | Edit this page |