HelpSystem (was Documentation Team)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

HelpSystem (was Documentation Team)

Torsten Bergmann
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

Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Casey Ransberger-2
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




Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

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.

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
>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Tobias Pape

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
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Hannes Hirzel
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
>