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 <casey.obrien.r at gmail.com> 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 <astares at gmx.de> 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
>>
>>
>