Ken,
Yeah; it supports keeping documentation in methods. Andreas added a patch that makes it easy to edit a help topic in a workspace, and it recompiles the source method automatically when you accept. So we should be able to use our revision control on our docs (which has proven very useful for me in the past.)
The reason I recommend using Trunk is so that folks don't need to switch contexts to add documentation. I also think that having a help system in a standard image is a good idea. I would expect to modify Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a system belongs in a core image at all.
These are just my feelings, though. I do appreciate your caution about adding bloat to Trunk; I cringe a little suggesting it, but I still think it's a good idea. Would you be willing to wait a bit, and gauge the broader community's opinion before making a decision about this? I'm really hoping to have a few more people weigh in on pros and cons. That said, I really do respect your opinion on the matter, and a separate repo on source.squeak.orgwould be fine (maybe source.squeak.org/help).
One thing I would like to do is get a quick gauge of the complexity of HelpSystem so people can get a sense of how much I'm really talking about adding. I'll try and find some time to do that in the next day or two. Good time for me to read el bloggo de Raabo:)
On Fri, Apr 30, 2010 at 3:35 PM, Ken Causey ken@kencausey.com wrote:
-------- Original Message -------- Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control, and process From: Ian Trudel ian.trudel@gmail.com Date: Fri, April 30, 2010 5:20 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Quick question, Ken (and Casey).
How will the core related documentation will be transfered to the core image assuming what you wrote will define our process? HelpSystem includes classes and methods comments.
Ian.
Well, this is exactly why I have that leading sentence. ;) I have no idea how content distribution (which is what I assume you are asking about) is meant to work in HelpSystem. I have to assume from Casey's question that it can be distributed in a mcz. As such it can be retrieved via any method desired and from any location. What triggers loading any particular content? I don't know, is there meant to be a catalog something like SqueakMap or Package Universes? Or is help for a particular package an optional dependency? Clearly, as I stated, I have no end of questions.
Ken
2010/4/30 Ken Causey ken@kencausey.com:
I haven't been following the HelpSystem discussion very closely so
there
is no limit to what I don't know on this subject. That said I would be perfectly happy setting up a HelpSystem repository on
source.squeak.org.
In general I feel we need to start limiting the contents of the trunk repository to those packages that compose 'core' Squeak and start considering add-ons used to build 'basic' Squeak as separate packages installed into 'core'. I'm assuming that HelpSystem is something we would want to include in a 'basic' image, but not a 'core' image. (Of course a 'core' ZIP might include ready to load optional packages including HelpSystem.)
Ken
-------- Original Message -------- Subject: [squeak-dev] [documentation] HelpSystem, revision control,
and
process From: Casey Ransberger casey.obrien.r@gmail.com Date: Fri, April 30, 2010 3:22 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Folks,
I'd like to get a process going around HelpSystem. It doesn't have to
be a
perfect process. We can tweak it as we go.
How do people feel about having help in the Trunk? It'll allow us to document things right along side of our software development.
One thing worth noting: we can have our HelpSystem "book" in Trunk
without
necessarily having HelpSystem itself in the Trunk; however, if we do
it that
way, we run the risk of changes in HelpSystem on SqueakSource making
our
help content impossible to load. I think having both in the Trunk is a really good idea.
If folks aren't comfortable with having some documentation and
HelpSystem in
Trunk, I'd like to propose opening up a 'docs' SS repository on source.squeak.org. We'd lose the ability to track the evolution of
our docs
in the context of the evolution of Squeak, but we'd still have the
keys to
the kingdom (license, code, content.)
I'd rather not go with squeaksource.com, as I'd like to think that
our docs
should live with the other things on squeak.org.
As always, feedback is appreciated.
-- Casey Ransberger<hr>