About using pragma for help like in setting

>
> Stef wrote on Mon Dec 13 10:02:56 (see [1]):
>> Now what I want is that people can type
>> ...
>> <help>
>>
>
> I already gave exactly such an example to Lukas already back in
> May. Again - PLEASE have a look at it (just load the code in [2]
> and run
>
>   HelpBrowser openOn: PragmaHelp
>
> The code is small and simple:
>
> - beside the existing help builders it just introduces a
>   "PragmaHelpBuilder" that uses the pragma <help> to
>   collect the help data
>
> - a Foo and Bar class is included to demonstrate
>   how you define help with this new builder (similar to
>   the way Stef/Lukas wanted)
>
> As I said adding "pragma help" is just a new "help builder"
> to define and one can easily add it.
>
> Think of another scenario: maybe one doesnt care about
> the "class to book mapping" or a "pragma approach".
>
> He wants to define his help contents completely different
> in external text files. Same pattern: he introduces a new
> HelpBuilderFromExternalTextFile that converts his custom
> (external) format into help topics. Nothing more.
>
> So the real work is in thinking about/defining how and in what
> format you want to write the help contents itself.
>
> The problem: there are MANY ways to define the contents -
> and as Stef showed us with the TWO "pragma" descriptions
> examples in his mail [2] that we are currently NOT SURE
> about the "pragma description" format to use.
> But if we want pragma help in the help system we have to
> find ONE and it should be simple and fit best.
>
> To say it in simple words: if we want to use pragmas
> we have to find a way to use pragmas to define nestable
> and extensible books (with pages and page order).
>
> I once requested this from Lukas but regarding extensible
> books his simple answer was:
>
>  "I would not make the books extensible themselves,
>   that complicates things and is rarely needed in practice."
>
> This answer is not satisfying to me since extensible books
> ARE EASILY POSSIBLE with the "class to book mapping" that
> the help system already have. And I use them.
>
> We can use "pragmas" but we should have the same possibilities
> and not use pragmas because they are "modern" or they are
> used by the Settings framework.
>
> And I agree with him that it may be hard to do with pragmas ...
> especially since I already experimented on this with pragmas
> But maybe we all can find a solution here together.
>
> In the end I switched to the "use classes and the class hierarchy"
> approach since it is more natural (at least to me) and easy to
> use/understand.
>
> Stef further wrote:
>> and that if the help is loaded we can see it in help.
>
> A registration mechanism to mark which custom help builders
> are included in the standard browser is on my todo list.
> Currently it is only one and hard coded (see HelpBrowser>>defaultRoot)
>
> If the above pragma help builder is in good shape we
> can add it too as one of the defaults - but a registration
> mechanism is better in the long run.
>
> But again:
> The problem I have with this simple pragma approach
>
>  foo: myBuidler
>    <help>
>    myBuilder ...
>
> is that with this you can easily describe a page with a
> title and text - but it is hard to describe a complete
> book with structure and even extensible books.
>
> So we have to clearly think about the builder part of
> this approach to keep the help contents definitions
> simple. And this is what I requested you all to do if
> we want to move on here...
>
> Just use my simple code example [2] to experiment and
> find the "pragma" description format we want to introduce.
>
> Stef may answer: use the one that I showed you. But if
> one uses pragmas we may want to describe the whole book.
> Not just a simple <help> tag to describe a single page
> with a title!
>
> Thx
> T.
>
> [1] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037545.html
>
> [2] http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20100505/cc589ac2/attachment-0001.obj
>
> --
> GMX DSL Doppel-Flat ab 19,99 &euro;/mtl.! Jetzt auch mit
> gratis Notebook-Flat! http://portal.gmx.net/de/go/dsl
>