hi, I learned some lisp a while ago,
and appreciate it's conciseness very much.
as I java programmer, I heavily depends on javadoc (html of libaray APIs)
for quick reference.
is there're something similiar to this in lisp (lisp's library)?
or how do you look up library/functions ?
thanks,
raymond
* ··········@hotmail.com (Raymond Tam)
| hi, I learned some lisp a while ago,
| and appreciate it's conciseness very much.
|
| as I java programmer, I heavily depends on javadoc (html of libaray APIs)
| for quick reference.
|
| is there're something similiar to this in lisp (lisp's library)?
| or how do you look up library/functions ?
I'm glad you asked, because the way Lisp programmers access such
documentation is a good example of a benefit from Lisp systems'
dynamic nature.
Lisp development environments interface your editor to a running Lisp
process. You load the libraries you use into this process; also, each
time you modify a definition of a function, class or something else in
your program, you press a key to load the new version of it into the
Lisp.
The development environment can then poke around in the running Lisp
process, using both standard and implementation-specific means of
introspection. For instance, you can look up names; ask which
arguments a function takes; retrieve the documentation strings for
functions, classes and other objects; and browse classes and class
hierarchies.
The beauty of it all is that the running Lisp process contains all the
stuff you're actually using---you don't have to consult different web
sites for documentation for different libraries that you use. And as
you modify your program, you don't have to worry about the information
about it being outdated, because it is not generated from the source
at some point in the past, but elicited from the current system on
demand.
I should also mention the Hyperspec, which is a world-wide web version
of the ANSI Common Lisp standard. It is _the_ reference for the
Common Lisp languages, and I tend to use it a lot. Erik Naggum wrote
the Emacs extension hyperspec.el, which has an index to the Hyperspec
in it, and automatically opens you web browser to the right page of
the Hyperspec when you place the cursor next to a Common Lisp symbol
and press a magic key.
--
Vebjorn Ljosa
··········@hotmail.com (Raymond Tam) writes:
> is there're something similiar to this in lisp (lisp's library)?
> or how do you look up library/functions ?
The apropos and describe functions are most useful for this:
(apropos "pathname")
(describe 'make-load-form)
for example.
--
-> -/- - Rahul Jain - -\- <-
-> -\- http://linux.rice.edu/~rahul -=- ·················@usa.net -/- <-
-> -/- "I never could get the hang of Thursdays." - HHGTTG by DNA -\- <-
|--|--------|--------------|----|-------------|------|---------|-----|-|
Version 11.423.999.220020101.23.50110101.042
(c)1996-2000, All rights reserved. Disclaimer available upon request.
··········@hotmail.com (Raymond Tam) writes:
> hi, I learned some lisp a while ago,
> and appreciate it's conciseness very much.
>
> as I java programmer, I heavily depends on javadoc (html of libaray APIs)
> for quick reference.
>
> is there're something similiar to this in lisp (lisp's library)?
> or how do you look up library/functions ?
http://www.xanalys.com/software_tools/reference/HyperSpec/FrontMatter/
You can download your own local copy from
http://www.xanalys.com/software_tools/reference/HyperSpec/
··········@hotmail.com (Raymond Tam) writes:
> hi, I learned some lisp a while ago,
> and appreciate it's conciseness very much.
>
> as I java programmer, I heavily depends on javadoc (html of libaray APIs)
> for quick reference.
>
> is there're something similiar to this in lisp (lisp's library)?
> or how do you look up library/functions ?
Others have already pointed out different ways of looking at the
documentation situation. Here is my take:
- If I want to find out about the implementation details of some
function or variable, then I use the commands of my environment,
that will tell me about the functions or variables (or other
entities) matching a prefix or substring, their argument names,
argument-types, result-type, their short doc-string documentation,
etc.
As others have pointed out, this is preferable (in my book) to HTML
and browser-based documentation, because it is dynamically kept
up-to-date by the lisp environment, and because it is better
integrated into the environment, e.g. if I press C-c a in ILISP[1],
it will show me the lambda-list of the function at point, and if I
prefix that with C-u, it will insert the lambda-list:
(sort [now press C-u C-c a]
=>
(sort ["cursor" here]sequence predicate &key key)
Few IDEs integrate the browser/HTML stuff enough to be that fast.
Furthermore there is nothing special I have to do to use that
facility, I can just use the mechanisms that are part of the
language, and get what I want. No silly specially formatted
comments, no new conventions to learn, this works on my own stuff,
Lisp implementation stuff, and foreign stuff all alike. Just load
it into your lisp image, and there it is...
- And then there is documentation that _specifies_ a certain API. For
Common Lisp, this is the ANSI standard, enjoyed at its best in its
electronic derivative, the Common Lisp HyperSpec. Again this is
best used if it is tightly integrated with the IDE, and that's why
the various Emacs/IDE <-> HyperSpec Interfaces are so popular.
Personally I use a slightly hacked version of Erik Naggum's
hyperspec.el in conjunction with W3 (an Emacs internal WWW browser),
so that I don't have to switch my cognitive attention to another
user interface to browse the HyperSpec.
The important thing about the HyperSpec, and any similar
specification document, is that it is _not_ automatically generated
from an implementation. That obviously isn't appropriate for a
standard, but IMHO it isn't appropriate for any API documentation.
The API documentation should lay out the specification of said API,
which should be independent from the random things that the
implementation of that API does today. Bonding both into one entity
in the source file is IMHO the first step on a very slippery slope,
and in the end the implementation will drive the API spec, and not
vice-versa.
Now people will argue that keeping both in one place will ease the
burden of keeping them in sync. There are two points I'd like to
make about that:
* If you find that you are changing your API spec more often than
very infrequently, then your API isn't one. Microsoft and friends
notwithstanding, interfaces (remember the I in API) are not
supposed to vary more frequently than clothing trends.
So there should very, very rarely be the need to adapt the API
spec in the first place, and those few occasions are so special,
that they warrant special attention anyway.
* So the syncing mostly happens in one direction, namely API spec ->
implementation. If your programmers find it difficult to take a
look at their own API spec before making changes to the
implementation, unless you forcefully shove it in front of their
faces all the time, what do you think your users, who by necessity
will have to look into a seperate document, will be doing?
So if we find that noone reads specifications anyway, we might as
well forget about keeping up the pretense, and do what modern
programmers do: Without ever taking a look at any form of
documentation what-so-ever, write something that works by chance
for the one trivial test-case you could think up in 10 seconds,
and dump that onto your unsuspecting users. Change your job every
year, repeat.
So IMNSHO, specification should be written and maintained in a
completely separate file, with your Customer-Representative hat on,
and introducing changes to the specification should require more
thought and work than fixing some random think-o in some random
file. Otherwise you might IMHO just as well forget about separate
documentation, and do what Open Source does, namely providing source
code to your users, so that they can find out for themselves what
the code _does_, regardless of what it is supposed to be doing.
To me, an API specification is part of a (often legally binding)
contract between customer and supplier. It means that there is an
objective arbitrator when a difference is found between user
expectations and implementation behaviour: If the implementation
contradicts the specification, it is the suppliers fault, if it
doesn't, it is the users fault. Subjecting the API specification to
arbitrary changes as the implementation changes is like allowing one
party to make arbitrary changes to the contract after it is signed.
So the specification shouldn't be bound to the implementation, and
this goes doubly so for non-specification API documentation, like
tutorials, user's guides, etc., because those documents should
follow a logical structure of their own, that is targetted at the
expectations of the reader, rather than slavishly following the
structure of the implementation.
That said, API specifications can (and should) still be tightly
integrated into the IDE, similar to the way the HyperSpec is
integrated into Lisp IDEs today. For example I've got some Emacs
Lisp code that can look for documentation relevant to a symbol based
on the symbol's home package and name, again via W3.
And you might want to hack up some small tools that can be used to
semi-automatically check things like lambda-lists, etc. against
those contained in the specification, so that conflicts can be
identified and cured.
Sorry for the rants in there, and hope this helps to give some
inspiration to you and other readers on suitable documentation
techniques.
Regs, Pierre.
Footnotes:
[1] Or if I press the space bar after the function symbol in a form...
--
Pierre R. Mai <····@acm.org> http://www.pmsf.de/pmai/
The most likely way for the world to be destroyed, most experts agree,
is by accident. That's where we come in; we're computer professionals.
We cause accidents. -- Nathaniel Borenstein