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 €/mtl.! Jetzt auch mit
gratis Notebook-Flat! http://portal.gmx.net/de/go/dsl
