About using pragma for help like in setting

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

About using pragma for help like in setting

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

Re: About using pragma for help like in setting

Stéphane Ducasse
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


Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Tudor Girba
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."







Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Luc Fabresse
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."








Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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

Re: About using pragma for help like in setting

Igor Stasenko
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.

Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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

Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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

Re: About using pragma for help like in setting

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

Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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

Re: About using pragma for help like in setting

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

Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Stéphane Ducasse
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
>


Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Stéphane Ducasse
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


Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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


Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Stéphane Ducasse
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
>
>


Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

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



Reply | Threaded
Open this post in threaded view
|

Re: About using pragma for help like in setting

Stéphane Ducasse
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
> >
> >
>
>
>