Smalltalk › Pharo › Pharo Smalltalk Developers

About using pragma for help like in setting

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

17 messages Options

Stéphane Ducasse

About using pragma for help like in setting

Hi guys

yesterday on the irc we got a discussion on the dependency introduced when using HelpSystem.
Some proposed to used pragmas like in settings since they work well for setting and we can also browse help
with implementors.

Torsten do you have a word to say before we start to implement this solution?

Stef

Stéphane Ducasse

Re: About using pragma for help like in setting

since nobody replied I send again this mail.
We should plan that for 1.3

Stef

> Hi guys
>
> yesterday on the irc we got a discussion on the dependency introduced when using HelpSystem.
> Some proposed to used pragmas like in settings since they work well for setting and we can also browse help
> with implementors.
>
> Torsten do you have a word to say before we start to implement this solution?
>
> Stef

Tudor Girba

Re: About using pragma for help like in setting

Great :)

Doru

On 11 Dec 2010, at 10:53, Stéphane Ducasse wrote:

> since nobody replied I send again this mail.
> We should plan that for 1.3
>
> Stef
>
>
>> Hi guys
>>
>> yesterday on the irc we got a discussion on the dependency introduced when using HelpSystem.
>> Some proposed to used pragmas like in settings since they work well for setting and we can also browse help
>> with implementors.
>>
>> Torsten do you have a word to say before we start to implement this solution?
>>
>> Stef
>
>

--
www.tudorgirba.com

"No matter how many recipes we know, we still value a chef."

Luc Fabresse

Re: About using pragma for help like in setting

sounds good to me too.

#Luc

2010/12/11 Tudor Girba <[hidden email]>

Great :)

Doru

On 11 Dec 2010, at 10:53, Stéphane Ducasse wrote:

> since nobody replied I send again this mail.
> We should plan that for 1.3
>
> Stef
>
>
>> Hi guys
>>
>> yesterday on the irc we got a discussion on the dependency introduced when using HelpSystem.
>> Some proposed to used pragmas like in settings since they work well for setting and we can also browse help
>> with implementors.
>>
>> Torsten do you have a word to say before we start to implement this solution?
>>
>> Stef
>
>

--
www.tudorgirba.com

"No matter how many recipes we know, we still value a chef."

Sean P. DeNigris

Re: About using pragma for help like in setting

Administrator

In reply to this post by Stéphane Ducasse

I'm trying to wrap my mind around the issue...

Stéphane Ducasse wrote

yesterday on the irc we got a discussion on the dependency introduced when using HelpSystem.

On the chat, it seemed that the main objection was depending on an external class. Since HelpSystem is now part of core, what is the problem there? Isn't it just like Tests depending on TestCase?

Stéphane Ducasse wrote

Some proposed to used pragmas... and we can also browse help with implementors.

Again, if HelpSystem is in core, how does it help to browse with implementors?

Sean

Cheers,
Sean

Igor Stasenko

Re: About using pragma for help like in setting

On 11 December 2010 20:25, Sean P. DeNigris <[hidden email]> wrote:

>
> I'm trying to wrap my mind around the issue...
>
>
> Stéphane Ducasse wrote:
>>
>> yesterday on the irc we got a discussion on the dependency introduced when
>> using HelpSystem.
>>
>
> On the chat, it seemed that the main objection was depending on an external
> class. Since HelpSystem is now part of core, what is the problem there?
> Isn't it just like Tests depending on TestCase?
>
>

So, what the problem here?
Put a 'HelpSystem' class var somewhere.
And if its nil, do nothing,
and then HelpSystem , when loading set this var to some object,
responsible for handling requests.

Then use
self helpSystem
instead of
HelpSystem
everywhere, and you don't have external dependencies.

> Stéphane Ducasse wrote:
>>
>> Some proposed to used pragmas... and we can also browse help with
>> implementors.
>>
>
> Again, if HelpSystem is in core, how does it help to browse with
> implementors?
>
> Sean
> --
> View this message in context: http://forum.world.st/About-using-pragma-for-help-like-in-setting-tp3078978p3083618.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>
>

--
Best regards,
Igor Stasenko AKA sig.

Lukas Renggli

Re: About using pragma for help like in setting

In reply to this post by Sean P. DeNigris

> On the chat, it seemed that the main objection was depending on an external
> class. Since HelpSystem is now part of core, what is the problem there?
> Isn't it just like Tests depending on TestCase?

After running the tests, first thing I do in a Pharo 1.2 core image on
my build server:

======================================

"Unload all tests"
(MCWorkingCopy allManagers
inject: Gofer new
into: [ :gofer :each |
((each packageName endsWith: 'Test') or: [ each packageName
endsWith: 'Tests' ])
ifTrue: [ gofer package: each packageName ].
gofer ])
unload.

"Unload other packages"
Gofer new
package: 'FixUnderscores';
package: 'Glamour-Morphic-Theme';
package: 'HelpSystem-Core';
package: 'Announcements-Help';
package: 'Regex-Help';
unload.

======================================

That means that I cannot load any package that includes pages for the
help system. Furthermore, this means that none of my packages will
ever include help system text, even if I would love to include my blog
articles (for example for PetitParser) somehow more accessible than in
a class comment.

In fact, I haven't seen a single non-core package providing help
pages. On contrary, there are many packages providing settings. This
does not introduce any dependencies. Maybe this is a hint?

Lukas

--
Lukas Renggli
www.lukas-renggli.ch

Sean P. DeNigris

Re: About using pragma for help like in setting

Administrator

Lukas Renggli wrote

I cannot load any package that includes pages for the
help system.

I guess that's what I don't understand. Why remove HelpSystem at all?

Lukas Renggli wrote

In fact, I haven't seen a single non-core package providing help
pages. On contrary, there are many packages providing settings. This
does not introduce any dependencies. Maybe this is a hint?

A hint that non-documentation habits are hard to break? ;-)

Cheers,
Sean

Lukas Renggli

Re: About using pragma for help like in setting

>> I cannot load any package that includes pages for the
>> help system.
>>
> I guess that's what I don't understand. Why remove HelpSystem at all?

- For deployment I don't want to have unnecessary code loaded.
- For portability I don't want to depend on "proprietary" code.
- For usability I want to have documentation accessible.

Lukas

--
Lukas Renggli
www.lukas-renggli.ch

Sean P. DeNigris

Re: About using pragma for help like in setting

Administrator

Lukas Renggli wrote

- For usability I want to have documentation accessible.

My intention is to learn something here. Are you saying that it would be beneficial to have your project's help pages included, even if the HelpSystem is not present, and have them degrade (e.g. to being browsed via implementorsOf like Steph mentioned).

Because otherwise, it seems...

Lukas Renggli wrote

- For deployment I don't want to have unnecessary code loaded.

Couldn't you just add another loop to your script to "unload all help" just like unload all tests

Lukas Renggli wrote

- For portability I don't want to depend on "proprietary" code.

If you were installing on a non-HelpSystem platform, wouldn't you not even load the help packages?

Sean

Cheers,
Sean

Lukas Renggli

Re: About using pragma for help like in setting

>> - For deployment I don't want to have unnecessary code loaded.
>>
> Couldn't you just add another loop to your script to "unload all help" just
> like unload all tests

Sure, but that means I have to package help text separately. This is
the contrary to what Java, Ruby, Python, Javascript, ... are doing;
keeping code and documention as close together as possible.

>> - For portability I don't want to depend on "proprietary" code.
>>
> If you were installing on a non-HelpSystem platform, wouldn't you not even
> load the help packages?

Documenation is not going to be written (and read) if this is
painful. I wouldn't bother to create a separate help package for each
of the 30 Seaside model packages. I wouldn't even bother to load 30
packages to find some help, or find the right class to maintain them.

Code should be as close with the documentation as possible, e.g. in
method and class comments; but sometimes you want to present an overal
picture or nicely aggreate method and class comments. This is not
currently possible without pain.

I think, the fact that there is no single external package with help
system documentation proves this, no?

Lukas

--
Lukas Renggli
www.lukas-renggli.ch

Stéphane Ducasse

Re: About using pragma for help like in setting

In reply to this post by Lukas Renggli

+1

On Dec 11, 2010, at 8:45 PM, Lukas Renggli wrote:

>> On the chat, it seemed that the main objection was depending on an external
>> class. Since HelpSystem is now part of core, what is the problem there?
>> Isn't it just like Tests depending on TestCase?
>
> After running the tests, first thing I do in a Pharo 1.2 core image on
> my build server:
>
> ======================================
>
> "Unload all tests"
> (MCWorkingCopy allManagers
> inject: Gofer new
> into: [ :gofer :each |
> ((each packageName endsWith: 'Test') or: [ each packageName
> endsWith: 'Tests' ])
> ifTrue: [ gofer package: each packageName ].
> gofer ])
> unload.
>
> "Unload other packages"
> Gofer new
> package: 'FixUnderscores';
> package: 'Glamour-Morphic-Theme';
> package: 'HelpSystem-Core';
> package: 'Announcements-Help';
> package: 'Regex-Help';
> unload.
>
> ======================================
>
> That means that I cannot load any package that includes pages for the
> help system. Furthermore, this means that none of my packages will
> ever include help system text, even if I would love to include my blog
> articles (for example for PetitParser) somehow more accessible than in
> a class comment.
>
> In fact, I haven't seen a single non-core package providing help
> pages. On contrary, there are many packages providing settings. This
> does not introduce any dependencies. Maybe this is a hint?
>
> Lukas
>
> --
> Lukas Renggli
> www.lukas-renggli.ch
>

Stéphane Ducasse

Re: About using pragma for help like in setting

In reply to this post by Sean P. DeNigris

Sean

I understand 100% lukas's approach, somebody contacted me to know if we the core with a web server can be under a certain size and
if this is needed then we must remove the doc on production.

The setting tag is working well so we can just use the same pattern and we get an help system that does not depend
on any external class of the package, that can be searched. It scales.

Now I was thinking that torsten would reply to this mail but in 1.3 will take a decision because I want a really better help
and documentation inside the right class and package.

Stef

laurent laffont

Re: About using pragma for help like in setting

In reply to this post by Lukas Renggli

I think, the fact that there is no single external package with help
system documentation proves this, no?

Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside mailing-list nobody have answered :(

So yes there's some help, it's slow.

I agree 100% on what you said about dependencies, documentation close to code, tagging/pragma approach, .... but it seems to me that whatever system we adopt, growing documentation will be slow .

So we need to push to write doc. even if the current or futures systems are not perfect.

Laurent.

Lukas

--
Lukas Renggli
www.lukas-renggli.ch

Stéphane Ducasse

Re: About using pragma for help like in setting

I read all the Help on Help and could not find what I wanted to know.
I read also the code same here.

Stef

On Dec 12, 2010, at 10:33 AM, laurent laffont wrote:

>
> I think, the fact that there is no single external package with help
> system documentation proves this, no?
>
>
> Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside mailing-list nobody have answered :(
>
> So yes there's some help, it's slow.
>
> I agree 100% on what you said about dependencies, documentation close to code, tagging/pragma approach, .... but it seems to me that whatever system we adopt, growing documentation will be slow .
>
> So we need to push to write doc. even if the current or futures systems are not perfect.
>
> Laurent.
>
>
>
> Lukas
>
> --
> Lukas Renggli
> www.lukas-renggli.ch
>
>

laurent laffont

Re: About using pragma for help like in setting

On Mon, Dec 13, 2010 at 9:56 AM, Stéphane Ducasse <[hidden email]> wrote:

I read all the Help on Help and could not find what I wanted to know.

What do you want to know / looking for ?

Laurent

I read also the code same here.

Stef

On Dec 12, 2010, at 10:33 AM, laurent laffont wrote:

>
> I think, the fact that there is no single external package with help
> system documentation proves this, no?
>
>
> Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside mailing-list nobody have answered :(
>
> So yes there's some help, it's slow.
>
> I agree 100% on what you said about dependencies, documentation close to code, tagging/pragma approach, .... but it seems to me that whatever system we adopt, growing documentation will be slow .
>
> So we need to push to write doc. even if the current or futures systems are not perfect.
>
> Laurent.
>
>
>
> Lukas
>
> --
> Lukas Renggli
> www.lukas-renggli.ch
>
>

Stéphane Ducasse

Re: About using pragma for help like in setting

see my previous mail :)

Stef

On Dec 13, 2010, at 10:39 AM, laurent laffont wrote:

> On Mon, Dec 13, 2010 at 9:56 AM, Stéphane Ducasse <[hidden email]> wrote:
> I read all the Help on Help and could not find what I wanted to know.
>
> What do you want to know / looking for ?
>
> Laurent
>
>
> I read also the code same here.
>
> Stef
>
>
> On Dec 12, 2010, at 10:33 AM, laurent laffont wrote:
>
> >
> > I think, the fact that there is no single external package with help
> > system documentation proves this, no?
> >
> >
> > Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside mailing-list nobody have answered :(
> >
> > So yes there's some help, it's slow.
> >
> > I agree 100% on what you said about dependencies, documentation close to code, tagging/pragma approach, .... but it seems to me that whatever system we adopt, growing documentation will be slow .
> >
> > So we need to push to write doc. even if the current or futures systems are not perfect.
> >
> > Laurent.
> >
> >
> >
> > Lukas
> >
> > --
> > Lukas Renggli
> > www.lukas-renggli.ch
> >
> >
>
>
>