[Cuis] [4.1] Porting need: HelpSystem

[Casey Ransberger]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://jvuletich.org/pipermail/cuis_jvuletich.org/attachments/20130124/22e9196a/attachment-0002.html>