[Pharo-project] 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
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
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."
sounds good to me too. #Luc 2010/12/11 Tudor Girba <tudor.girba@gmail.com>
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."
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 -- View this message in context: http://forum.world.st/About-using-pragma-for-help-like-in-setting-tp3078978p... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
On 11 December 2010 20:25, Sean P. DeNigris <sean@clipperadams.com> 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-tp3078978p... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
-- Best regards, Igor Stasenko AKA sig.
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
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? ;-) -- View this message in context: http://forum.world.st/About-using-pragma-for-help-like-in-setting-tp3078978p... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
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
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 -- View this message in context: http://forum.world.st/About-using-pragma-for-help-like-in-setting-tp3078978p... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
- 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
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
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
On Mon, Dec 13, 2010 at 9:56 AM, Stéphane Ducasse <stephane.ducasse@inria.fr
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
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 <stephane.ducasse@inria.fr> 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
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
+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
participants (7)
-
Igor Stasenko -
laurent laffont -
Luc Fabresse -
Lukas Renggli -
Sean P. DeNigris -
Stéphane Ducasse -
Tudor Girba