[Cuis] [4.1] Porting need: HelpSystem

[Chris Hogan]

Hi,

I am a bit of a lurker.  The comment earlier about most people going to
google or stack overflow reminded me of the old hypertextclasscomments.

Does anyone still use those?

http://wiki.squeak.org/squeak/162.diff?id=8

http://lists.squeakfoundation.org/pipermail/squeak-dev/2003-February/052863.html


On Fri, Jan 25, 2013 at 1:42 AM, Casey Ransberger
<casey.obrien.r at gmail.com>wrote:

> Hi Angel, and sorry about the late reply. Inline, and I've cut it short to
> the points I've responded to.
>
> On Sat, Jan 5, 2013 at 4:44 AM, Angel Java Lopez <ajlopez2000 at gmail.com>wrote:
>
>> Hi people!
>>
>> I'm the "non-smalltalk dev" in this list ;-)  And I want to say something.
>>
>
> Heh;) My resume mostly says "Ruby" these days. It said "Perl" before that.
> I'm hoping to make it say "Smalltalk" or something more directly related
> than "Ruby."
>
>
>> Yes, I know there is the "Smalltalk way" of doing many things...
>>
>
> Makes me think of:
> http://www.drdobbs.com/architecture-and-design/interview-with-alan-kay/240003442#
>
> "The most disastrous thing about programming — to pick one of the 10 most
> disastrous things about programming — there's a very popular movement based
> on pattern languages. WhenChristopher Alexander<http://www.amazon.com/Pattern-Language-Buildings-Construction-Environmental/dp/0195019199/?tag=drdos-20> first
> did that in architecture, he was looking at 2,000 years of ways that humans
> have made themselves comfortable. So there was actually something to it,
> because he was dealing with a genome that hasn't changed that much. I think
> he got a few hundred valuable patterns out of it. But the bug in trying to
> do that in computing is the assumption that we know anything at all about
> programming. So extracting patterns from today's programming practices
> ennobles them in a way they don't deserve. It actually gives them more
> cachet."
>
> What he said.
>
>
>> but... in other technologies, no help system is practically used (since
>> last decade? more?). The flow is:
>>
>> - Google search
>> - Giving post resulst, or stack overflow question, answers
>>
>
> You left a piece out. Most of what you're searching for on Google after
> your first tutorial or two in most of these systems is API documentation.
> This is usually automatically extracted from the code (method/function
> signatures) and the comments in the code (so-called "documentation
> comments.") Most of the time this stuff can be rendered directly in several
> formats, e.g., text, html, markdown, etc, and more often than not, the
> documentation is generated and updated constantly by a continuous
> integration server.
>
> Regardless, an advantage of doing it this way is that the code and the
> docs are related not by release version, but by *checkin,* which is nice --
> even if most of the time no one documents anything, you want to make it
> painless when they do, so you just change the doc comment when you change
> what the code does and check it in.
>
> I wish I could find the email in question, but after talking about
> HelpSystem with Andreas for a bit and suggesting that we use it to capture
> our docs in the MC update stream, he sent me what amounted to a five-ish
> line patch which allowed you to change the content of the help and then
> accept (cmd/alt/ctrl-s, depending on OS) and it would dirty the Monticello
> package by storing the text of the help content in a method, thus causing
> the change to be easy to commit just like anything else. Unfortunately, I
> don't think it got integrated in the trunk, and I don't know why. Might
> just have found the cutting room floor.
>
> http://en.wikipedia.org/wiki/Cutting_room_floor
>
> For samples, if the project is hosted in GitHub, usually there is a
>> samples folder in the project. (well, I'm very proud of my samples in
>> CobolScript
>> https://github.com/ajlopez/CobolScript/tree/master/samples
>> ;-)
>>
>
> One of the things I wanted to do with HelpSystem was give it export
> formats, most importantly text and html. Text is trivial and html isn't
> hard to do. I've had other priorities though, so I haven't gotten it done.
> I'd much rather see docs.cuis.org than just a text file on GitHub.
>
> Oh! And I forgot to mention: HelpSystem automatically extracts method
> signatures, and treats the first comment in every method as a doc comment
> (which actually works out pretty well, as it's a common stylistic
> affectation to document a method at the top.) So in most respects, other
> than the missing export feature, it's really a lot *more* like the way
> other systems do it. Also, it's only a couple of years old; if there's a
> "Smalltalk Way" it's got to be at least some ten to twenty years older than
> HelpSystem!
>
> :D
>
> <snip />
>
> --
> Casey Ransberger
> _______________________________________________
> Cuis mailing list
> Cuis at jvuletich.org
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://jvuletich.org/pipermail/cuis_jvuletich.org/attachments/20130125/e7389549/attachment-0002.html>