Okay.
The current manual looks like it was generated with makeinfo. Where can I find the source for that?
Is it necessarily desirable to continue using that documentation model? I just put togther documentation for a large set of codes at work using doxygen which, of course, has no Lisp support, but did open my eyes to the possibilities.
--Jeff
On Sat Nov 04, 2006 at 03:17:12PM +0100, Marco Baringer wrote:
Jeffrey Cunningham jeffrey@cunningham.net writes:
Okay. What's the best way to get a comprehensive list of features?
walk through slime.el and swank.lisp......
-- -Marco Ring the bells that still can ring. Forget your perfect offering. There is a crack in everything. That's how the light gets in. -Leonard Cohen
Jeffrey Cunningham jeffrey@cunningham.net writes:
Okay.
The current manual looks like it was generated with makeinfo. Where can I find the source for that?
doc/slime.texi
Is it necessarily desirable to continue using that documentation model? I just put togther documentation for a large set of codes at work using doxygen which, of course, has no Lisp support, but did open my eyes to the possibilities.
personally i believe the things like doxygen, while usefull, should only complement a hand written user manual. using something like sbcl's docstrings.lisp would be cool for the swank configuration variables, but i'd strongly suggest keeping the current model.
On Sat Nov 04, 2006 at 03:49:33PM +0100, Marco Baringer wrote:
personally i believe the things like doxygen, while usefull, should only complement a hand written user manual. using something like sbcl's docstrings.lisp would be cool for the swank configuration variables, but i'd strongly suggest keeping the current model.
I agree, the manual should be largely hand-written. But one of the reasons documentation always falls way behind rapidly moving development projects is that its out of date as fast as you write it.
What I'm envisioning is a way to automatically generate the outline - with all the stubs - which keeps all the hand-written content as it is added. Everytime this document 'generator' is run, it adds any new stubs and maybe flags ones that no longer exist.
An additional very power feature could be automated linkage of functions/parameters,key-bindings, etc to their definitions. Using the current model would require this all be done by hand, which means it will almost never be done, or done completely.
I was thinking of writing something in Lisp to generate and update the documentation. Does this sound like a bad idea?
-Jeff
On Sat, 2006-11-04 at 15:49 +0100, Marco Baringer wrote:
Jeffrey Cunningham jeffrey@cunningham.net writes:
Okay.
The current manual looks like it was generated with makeinfo. Where can I find the source for that?
doc/slime.texi
Is it necessarily desirable to continue using that documentation model? I just put togther documentation for a large set of codes at work using doxygen which, of course, has no Lisp support, but did open my eyes to the possibilities.
personally i believe the things like doxygen, while usefull, should only complement a hand written user manual. using something like sbcl's docstrings.lisp would be cool for the swank configuration variables, but i'd strongly suggest keeping the current model.
I agree. Anything automatically generated from the code is not going to have the right structure to serve as a good online manual.
That said, I do think that the documentation should be kept in the same version control regime as the code. Developers with commit privileges must get used to the idea that whenever making a change with user-visible consequences, this document should be updated. My 2 cents.
Dan Weinreb dlw@itasoftware.com writes:
That said, I do think that the documentation should be kept in the same version control regime as the code. Developers with commit privileges must get used to the idea that whenever making a change with user-visible consequences, this document should be updated. My 2 cents.
Currently we only have 1 cent for your two: the texinfo source for the manual is in the same CVS as the code, but we have been pretty lax on updating it.
Cheers,
-- Nikodemus Schemer: "Buddha is small, clean, and serious." Lispnik: "Buddha is big, has hairy armpits, and laughs."
-
Dan Weinreb -
Jeffrey Cunningham -
Marco Baringer -
Nikodemus Siivola