Re: [Chicken-users] RFC: documentation lookup utility

[Brandon J. Van Every]

Toby Butzon wrote:
> Did you have plans for where the data for each function would come from
> for your application? And are you planning to provide just the argument
> list or also a description of the function? I would be happy to combine
> efforts on this indexing/retrieval problem if our needs really do overlap.
>   

I don't really have a plan for such things.  My bag is OpenGL, AI, game 
development, and CMake.  As it is, I don't have any development time.  
Just found out today that I'm completely broke, so I've got fires to put 
out.

I don't document functions in any consistent way.  I'm a lone wolf 
developer, I don't need to ensure that every single one of my functions 
has a description.  I do believe in clarity of design, and I do comment 
things that are unclear.  But some stuff, people just have to study the 
code and scratch their head to figure out how it works.  I don't like 
doing that; I'm not sure anyone does; in any event it is time 
consuming.  I just don't think abundant comments are going to save 
anyone the burden of understanding someone else's code.  So I comment 
briefly where I feel it's needed.

If I were maintaining a public API I'd be more into comments and 
documentation.  Maintaining public APIs is a huge chore.  The CMake 
people aren't interested in doing it, for instance, even when offered 
the labor.  An app is much easier to maintain than a public API.

Another consideration is that some people prefer locally installed 
documentation to internet documentation.  For one thing, some crazies 
like myself are still on dialup.  Although someone else is footing my 
cell phone bill, it does tie up my cell phone and the battery only lasts 
so long.  Laptop users have similar problems.  Also, sometimes people's 
online access goes down and they don't want to be shafted waiting for 
the network to come back up.  Internet documentation has the advantage 
of being up-to-date, but I think a packaging system that pulled docs 
from remote repositories as they are updated, would be preferable to 
being required to be online.

There's an ecology of various Scheme development tools.  I know that 
Quack http://www.neilvandyke.org/quack/ has some Chicken support in it, 
but it hasn't kept up with Chicken's website and documentation changes.  
I'll hazard a guess that the author isn't particularly into Chicken.  
Quack looks like a one man project, and as such, I doubt it's going to 
have any traction or use in Chicken circles.  Quack seems heavily PLT 
oriented, and also GNU Emacs rather than XEmacs.

It seems pretty important to have an author or group that actually uses 
Chicken, in order for Chicken to get first class support.  Really this 
open source stuff doesn't work when it's just 1 guy doing his own thing 
with his own toolchain, and not really caring about other people's 
toolchains.  I mean, it just took me 9 months to get the CMake build 
together, and eggs are still broken on MSVC and MinGW, quite apart from 
CMake.  And Chicken has multiple contributors and some semblance of 
critical mass.

I don't know what the answer is, because good editor support is not a 
fun problem for most people.  I tried to use the Schemeway plugin on 
Eclipse and eventually gave up, because it was a one man project and my 
problems on Windows weren't getting fixed.  It's been a long time and 
maybe it works now, but the strategic realities haven't changed.  
Eclipse means getting one's hands dirty with Java, and it's Kawa Scheme 
rather than Chicken Scheme, so that's another pull away from people's 
attention.  Also I'm now into CMake and Eclipse is an Ant build 
culture.  I seem to be stuck with a mishmash of tools and XEmacs is what 
passes for an editor lately.  My knowledge of XEmacs from a programming 
standpoint is still decidedly primitive.  I've used it as a glorified 
text editor, which is all that CMake requires.  I"ve got a CMake mode, 
it colorizes stuff, but it doesn't add any value to my work.

I think I'll take a poke at the XEmacs website and see if there are any 
capabilities or 3rd party elisps I haven't noticed.


Cheers,
Brandon Van Every