On Wed, 18 Jul 2001 17:33:43 GMT, Erik Naggum <e...@naggum.net> wrote: > Since documentation strings are routinely discarded by most CL systems, > the best way to do this would be to use an interface that could take a > package name, a symbol name, and the documentation type. This would be a > lot easier to implement on top of the generic function documentation than > interfacing with magic values of the documentation string.
I would prefer this "scheme" to any that ties down symbol property names, or specifies a particular location (in the source file, in a "parallell" documentation file or in a db) , or in some particular file or text format. In particular, I would not want to have HTML as the common agreed-upon format.
There are obvious advantages in that there is no requirement for the symbol's documentation to be loaded into the running (development) environment. The function provider is free to choose whatever tool that suits him in the development phase, as well as the way his external audience should see the finished documentation.
On Thu, 19 Jul 2001 19:21:49 GMT, Erik Naggum <e...@naggum.net> wrote: > That would also work, but in essence, the mapping from package plus > symbol name and documentation type is nearly an ideal match for the way > URLs may contain queries. This way, we can outboard the mapping and use > it from other places, too, instead of making all that enormous amount of > data hang around in the Lisp image. After all, part of the reason
I had missed the idea of a _mapping_ in your original posting. Now I understand it, and I realize about the resource usage implications of my suggestion of storing the information in a symbol property.
> On Thu, 19 Jul 2001 19:21:49 GMT, Erik Naggum <e...@naggum.net> wrote:
> > That would also work, but in essence, the mapping from package plus > > symbol name and documentation type is nearly an ideal match for the way > > URLs may contain queries. This way, we can outboard the mapping and use > > it from other places, too, instead of making all that enormous amount of > > data hang around in the Lisp image. After all, part of the reason
> I had missed the idea of a _mapping_ in your original posting. Now I > understand it, and I realize about the resource usage implications of my > suggestion of storing the information in a symbol property.
Doing it with a tuple mapping has the advantage, too, that you can make different documentation for the selfsame (i.e., eq) symbol based on which package it's exported from, since even though its actual implementation and function might not vary, its "intentional" use might in some cases.
> Doing it with a tuple mapping has the advantage, too, that you can make > different documentation for the selfsame (i.e., eq) symbol based on which > package it's exported from, since even though its actual implementation > and function might not vary, its "intentional" use might in some cases.
But how would you know which package that would be? Packages being a reader concept, it is quite hard to figure out which package you mean after the fact, other than the symbol's home package. So although I appreciate the idea, I am not sure how you think it could be implemented. I thought one would take the package from (symbol-package symbol) and the symbol name from (symbol-name symbol), since the generic function documentation does not receive the package separately from the symbol.
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
> * Kent M Pitman <pit...@world.std.com> > > Doing it with a tuple mapping has the advantage, too, that you can make > > different documentation for the selfsame (i.e., eq) symbol based on which > > package it's exported from, since even though its actual implementation > > and function might not vary, its "intentional" use might in some cases.
> But how would you know which package that would be? Packages being a > reader concept, it is quite hard to figure out which package you mean > after the fact, other than the symbol's home package. So although I > appreciate the idea, I am not sure how you think it could be implemented. > I thought one would take the package from (symbol-package symbol) and > the symbol name from (symbol-name symbol), since the generic function > documentation does not receive the package separately from the symbol.
Sorry, I was assuming a parser that was either grabbing a string name and could see the prefix the user typed, or that had hyperlinks intra-document from one intentional name to another. I do agree if you have a symbol, you have this problem.
But you also have this problem already anyway in reverse if someone asks for doc on foo::car from outside of package FOO and really has no right to know that CAR has any meaning internal to FOO at all, yet MIGHT find the documentation for COMMON-LISP:CAR as a result...
=> 404 Symbol FOO::CAR is not exported and no documentation of a function FOO::CAR was found.
This won't happen, obviously, if you just use the symbol's home package, but that doesn't mean it's not a useful error message to get when you do have the intentional package name.
: (It is likewise sad to see vendors completely ignoring the specification : and reinventing the wheel badly when the "need" suddenly arises and : half-assed stuff like the "web" suddenly appears.)
Nevertheless the ... "web" made it, the lispmachine or Xanadu not. Worse WAS better, esp. in this pragmatic context.
For extracting docstrings with simple text scanning I also have a simple perl script (exefied to win32) at my pages somewhere (lspdoc) which generates winhelp and html. But mine uses the autolisp commenting conventions, which has no docstrings.
BTW: Corman Lisp puts the CLHS page entry in a symbol property in the interactive environment. (I extended it to CLtL2 also). Only the page name, not the whole url. This needs less memory than emacs and is much faster, but emacs of course has all the other features we love. -- Reini Urban http://xarch.tu-graz.ac.at/acadwiki/AutoLispFaq
I used javadoc was a tool for reading my class documentation exported in an HTML format. Lisp entities can carry a documentation string that you can access programmatically and write out as HTML, but someone (i.e., you) have to include the documentation string.
Some ways to educate yourself...
Books besides the "Gentle approach":
"Object-Oriented Common Lisp", Stephen Slade (sp) "Common Lisp, the Language", Guy Steele (a must if you are going to do any extensive amount of work) "On Lisp", Paul Graham (macros -- a more difficult subject but very useful)
Submit questions to this newsgroup. Sure, folks sometimes pontificate on this subject or that, and sometimes they can be a bit short with newbies (especially grad students looking for help with their homework!) but I've learned an enormous amount from these lads (and lasses).
Larry Loen wrote: > Thanks to people posting here, I've read the "Gentle Introduction" and even coded up a few interesting programs in LISP.
> What I think I need now is what I needed at a comparable point in my Java journey -- a simple, on-line, indexed, HTML version of all the functions > described.
> Something very much like Javadoc does.
> I don't really want another book (I have a couple more, but nowadays, books are awkward and I flit around several computers and between home and > work). As much as I admire Knuth, I don't want stuff in tex format (which I don't yet have any way of handling, especially a whole directory's > worth).
> If it isn't HTML, it does have to be in a format that isn't Unix-specific and one which will work on a variety of platforms readily without me > learning another damn tool.
> In short, I need a place to go to "find out" what I don't know about COMMON Lisp, function-by-function as I need it.
Erik Naggum wrote: > * Paolo Amoroso <amor...@mclink.it> > > What about a symbol property?
> If the WWW had actually _been_ hypertext <insert > long and pained sigh>, it would have been possible for a user to add > links between disjoint documents, but we need to figure out a way to do > that outside of that immensely retarded _tragedy_ called HTML.
> #:Erik > -- > There is nothing in this message that under normal circumstances should > cause Barry Margolin to announce his moral superiority over others, but > one never knows how he needs to behave to maintain his belief in it.
> Any ideas for implementing this functionality in the XML world, a > direction that much of the sofware world seems to be heading?
What on _earth_ can XML possibly have to offer people who are not already completely out of their mind? The interesting thing is to use Common Lisp to deal with that abomination so that some people can see how dumb SGML and HTML and XML really are and how it should have been done. There is _zero_ point in moving from Common Lisp to XML. Making a connection from CL to XML that is not pure kindness to the losers is _dangerous_. Even as a data notation, CL is already at least a decade ahead of XML. SGML and XML are good ideas if you were comatose when you designed your software to begin with, but _only_ then. We should approach XML people with a "good, good, you figured out that a uniform syntax has benefits -- how many _more_ years of pain and suffering and agonizing over lost data before you figure out that types, read-write consistencey, _intelligent_ in-memory representation, programmable syntax, and macros have benefits, too?" Sigh! These folks are coming from a third-world country as far as software goes, and absolutely anything that carries symptoms of IQ above freezing (Fahrenheit, just like the room temperature), is better than their astonishingly retarded data formats. That _includes_ most of the dreadfully "look, ma, I can also reinvent the wheel, with no hands!" Unix "configuration file" syntaxes, log file formats, etc, etc. My God, it is so amazingly mindless! Speaking of which, if anyone needs evidence that there is _no_ god, that whatever god was here has _left_ the planet, etc, take a look at the fantastic mess that people arrange for themselves in data formats and what they actually consider improvements! Clearly, this could not have taken place if anyone, I mean _anyone_, had had a grand plan. Even a god who were responsible for the platypus would have done better than XML.
Now, what did you have in mind?
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
Steve Long <stevel...@isomedia.com> writes: > Any ideas for implementing this functionality in the XML world, a > direction that much of the sofware world seems to be heading?
HyTime (ISO/IEC 10744:1992) is the SGML architecture for linking and addressing, scheduling and rendition. But, the XML community being what it is, they will no doubt (in the name of simplicity) produce a completely new, incompatible, piece-meal standard, which will in the end be even more complex, make the same mistakes as SGML did, add some more of its own, throw out the useful features of SGML/HyTime, and add a couple of useless ones instead.
And since no XML implementor will be bright enough to understand the produced standard, no really conforming implementations will come forth anyway, and any remaining interoperability between implementations will be purely by chance.
Regs, Pierre.
-- Pierre R. Mai <p...@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
Steve Long <stevel...@isomedia.com> writes: > Any ideas for implementing this functionality in the XML world, a > direction that much of the sofware world seems to be heading?
Erik Naggum wrote: > * Steve Long <stevel...@isomedia.com> > > Any ideas for implementing this functionality in the XML world, a > > direction that much of the sofware world seems to be heading?
<snipped>
> The interesting thing is to use Common > Lisp to deal with that abomination so that some people can see how dumb > SGML and HTML and XML really are and how it should have been done. There > is _zero_ point in moving from Common Lisp to XML. Making a connection > from CL to XML that is not pure kindness to the losers is _dangerous_.
> Now, what did you have in mind?
I have no personal opinion nor direction in mind, but thanks for the colorful analysis. I don't need much arm twisting to avoid the alphabet soup of other languages and "standards" out there that I have no objective basis with which to evaluate.
>>>>> "Erik" == Erik Naggum <e...@naggum.net> writes:
Erik> * Raymond Toy >> I'm not familiar with javadoc, but perhaps Mark K's user_man >> package is what you are looking for. (See the CMU AI >> archives). It extracts, I think, the docstrings of functions >> and produces TeX output for the function and docstring.
Erik> I think this is a bad way to use documentation strings. Erik> This is also why I think literate programming is bunk. The Erik> best case of documentation strings put to real use that I Erik> know of is GNU Emacs. Even with Emacs, there is a separate Erik> manual, written to be _read_, that describes a lot more Erik> stuff in a pedagogical order and with an eye to physical Erik> proximity of related details and information.
True, but the purpose of literate programming (LP) [1] is *not* to generate _User Documentation_ from (annotated) source code, but to describe the implementation in more detail than usually done with comments.
For example, Knuth's TeXbook, i.e. the user manual of TeX is not a literate program (although it does contain some TeX macros with explanations), but "TeX, the Program" is. Few people bother to read the latter, because it is not necessary if you just want to use TeX.
[snip]
Erik> Writing good documentation is hard, because intelligent Erik> people bore easily and just put down documentation that Erik> explains the obvious, yet do not use documentation that Erik> fails to be readable. What should be in the documentation Erik> is stuff that people cannot figure out for themselves faster Erik> than reading it. That is why I love specifications to be Erik> online and why I think hypertext in specifications is such a Erik> wonderful use of the technology. This is why I wrote Erik> hyperspec.el. But now I want the same level of Erik> documentation for vendor-supplied pacakges that come with Erik> tons of high quality documentation, although more of a Erik> tutorial kind than specifications, since it is written after Erik> the fact, rather than before.
Erik> The reason I think literate programming is so stupid is Erik> the same reason I found SGML's promise of "one source, Erik> multiple publications" to be so hollow and ignorant.
What actually works (with LP) is to have one source from which the code and _documentation of the implementation_ can be extracted. Depending on the LP tools used, the documentation can include cross-references, indices etc. Probably not such a big deal for Lisp users, who have introspective tools available, but useful for languages like C.
Erik> A piece of text has an audience, a context, and a set of Erik> expectations associated with it. Until we can program Erik> computers to deal with this, _people_ need to write text for Erik> different audiences, different contexts, and different Erik> expectations. When I look at code, I expect the Erik> documentation there to help me understand it. When I read Erik> the documentation, I hope to understand the system design.
This would be something like the architecture documentation, right? Unfortunately, I have seen few good examples of this kind of document. With Emacs, you can get some ideas about its architecture from the Emacs Manual, some more from the Emacs Lisp Manual, the Emacs paper, but I know of no document which describes the "design" in a way detailed enough to make one feel comfortable with changing things.
Erik> If the system design expectation is attempted filled by Erik> giving me a mere dump of the code documentation sans code, I Erik> have reason to accuse people of fraud. When I read Erik> specifications, I expect it to become the background noise Erik> of my own expectations when I deal with a conforming system. Erik> (This is why lack of conformance is so much more annoying Erik> than bugs in stuff that does nto purport to conform to a Erik> specification; I have to become _conscious_ of my Erik> expectation that the specification is actually implemented, Erik> and that means having to test for it and not being able to Erik> believe it. This is like asking people if they understand Erik> every word you use, instead of assuming that you agree to Erik> speaking the same language.)
I have a similar problem with documentation, or more generally with "broken rules"--once I see that there are (grave) mistakes, I am getting sceptical and start wondering how much I can trust it. LP does help here by reducing the distance between code and documentation, so it is easier to keep them in sync. One still has to update the other documents (user manual, architecture document) by hand/
Erik> Also, please note that a lot more than functions have Erik> documentation. That often tends to be forgotten in systems Erik> that primarly have functions as exportable interface Erik> concepts. Classes, slots, types, packages, variables, and a Erik> lot more stuff have documentation in Common Lisp. It is Erik> sometimes hard to understand how people who invented these Erik> things could be so futuristic that they would foresee such Erik> needs. (It is likewise sad to see vendors completely Erik> ignoring the specification and reinventing the wheel badly Erik> when the "need" suddenly arises and half-assed stuff like Erik> the "web" suddenly appears.)
Could you elaborate?
[1] From what I gathered as a long time reader of comp.prog.literate and occasional user of LP. -- best regards Roland Kaufmann
Reini Urban <rur...@x-ray.at> writes: > BTW: Corman Lisp puts the CLHS page entry in a symbol property in the > interactive environment. (I extended it to CLtL2 also). > Only the page name, not the whole url. > This needs less memory than emacs and is much faster, but > emacs of course has all the other features we love.
Actually, Emacs keeps its docstrings on disk. So you only pay the price of keeping them in memory if you use them.
Thomas F. Burdick wrote: >Reini Urban <rur...@x-ray.at> writes:
>> BTW: Corman Lisp puts the CLHS page entry in a symbol property in the >> interactive environment. (I extended it to CLtL2 also). >> Only the page name, not the whole url. >> This needs less memory than emacs and is much faster, but >> emacs of course has all the other features we love.
>Actually, Emacs keeps its docstrings on disk. So you only pay the >price of keeping them in memory if you use them.
Oops, I knew that. But why don't they store just the offset into the DOC file as symbol property? Just like corman lisp does it.
RANT: maybe because their int is too short :) Disk IO vs Memory probably. -- Reini Urban http://tv.mur.at/film/
Erik Naggum wrote: > * Steve Long <stevel...@isomedia.com> > > Any ideas for implementing this functionality in the XML world, a > > direction that much of the sofware world seems to be heading?
> ....catatonic drivel deleted... > so amazingly mindless! Speaking of which, if anyone needs evidence that > there is _no_ god, that whatever god was here has _left_ the planet, etc, > take a look at the fantastic mess that people arrange for themselves in > data formats and what they actually consider improvements! Clearly, this > could not have taken place if anyone, I mean _anyone_, had had a grand > plan. Even a god who were responsible for the platypus would have done > better than XML.
I take it that you do, to answer the other amazingly relevant comment you made.
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
> * Steve Long <stevel...@isomedia.com> > > Any ideas for implementing this functionality in the XML world, a > > direction that much of the sofware world seems to be heading?
> What on _earth_ can XML possibly have to offer people who are not already > completely out of their mind? The interesting thing is to use Common > Lisp to deal with that abomination so that some people can see how dumb > SGML and HTML and XML really are and how it should have been done. There > is _zero_ point in moving from Common Lisp to XML [snip] > Now, what did you have in mind?
Well, the only thing that I can see in XML is that it is simple: (It seems to me) It is just the idea of describing data as lists of other data using the <entity> list </entity> <symbol/> syntax. Not exciting, not too pernicious.
> What actually works (with LP) is to have one source from which the > code and _documentation of the implementation_ can be extracted. > Depending on the LP tools used, the documentation can include > cross-references, indices etc. Probably not such a big deal for Lisp > users, who have introspective tools available, but useful for > languages like C.
I've been following this discussion, and a question, at the risk of sounding ignorant, but... What introspective tools/features exist in/for Cl?
Erik Naggum wrote: > * Robert Gonzalez <no-s...@austin.rr.com> > > > ....catatonic drivel deleted... > > data formats and what they actually consider improvements! Clearly, this > > could not have taken place if anyone, I mean _anyone_, had had a grand > > plan. Even a god who were responsible for the platypus would have done > > better than XML. > I take it that you do, to answer the other amazingly relevant comment you made.
I think the relevancy issue is in your court. What does God have to do with the design of XML? Are'nt your rants getting a little ignominious?
> I think the relevancy issue is in your court. What does God have to do > with the design of XML? Are'nt your rants getting a little ignominious?
It seems that you have been offended. This was not intended on my part. I consider the various versions of religions to be interesting fairy tales and consider the fact that they collectively agree on absolutely nothing to be evidence of their status as fairy tales created by people. If you feel that your religion is under threat from someone who considers it silly, you need to talk to someone to get over your hypersensitivity. There are, for any given religion, literally _billions_ of people who consider it not just silly, but wrong, evil, heresy, a danger to mankind, etc. I think you should be more worried about your real enemies than the people who have fun with something that is both tragic _and_ funny in the development of human societies and belief systems. If you do wish to discuss your religious hypersensitivity, do it somwehere appropriate. If you want to get respect for your religious views, have respect for mine first. So far, you appear to attack me for no reason whatsoever. For that reason alone, I think your religion is bad, for your information. Your need to continue to talk about this is not a very good sign, either.
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
Erik Naggum wrote: > * Robert Gonzalez <no-s...@austin.rr.com> > > I think the relevancy issue is in your court. What does God have to do > > with the design of XML? Are'nt your rants getting a little ignominious?
> It seems that you have been offended. This was not intended on my part.
Actually, no offense taken Erik, I simply questioned the tangled thread you were weaving, I'm not sure anyone else understood either. You need to re-read the original to see how irrelevant that whole paragraph was. It appeared more to be a statement of your religious beliefs more that it was a statement about the subject matter. People simply want a means of documenting code, and its very valuable to a newbie starting out in a development project, that should be the intended target audience for such a tool, not necessarily the end user.
> I consider the various versions of religions to be interesting fairy > tales and consider the fact that they collectively agree on absolutely > nothing to be evidence of their status as fairy tales created by people.
That's fine also. I do not have any religion whatsoever. Your powers of observation are not as keen as you think. Religion is man's invention. I agree with you 100% on that. It has nothing to do with God, except that they make reference to God. And they can totally contradict or disagree with each other, but this does not prove or disprove the existence of an omnipotent, and/or omniscient being. Neither does the opposite. If all religions agreed with each other, that still would not prove anything. Especially not with a God who does not show himself freely.
> If you feel that your religion is under threat from someone who considers > it silly, you need to talk to someone to get over your hypersensitivity.
Again, there is no threat to something that does exist on my end. I have just been following this line of discussion, and the obtuse turns it took. You seem to think you are very smart, and apparently enjoy putting people down who you judge infererior to yourself, but this type of behaviour only exposes ones own moral and intellectual inferiority. You may want to seek counseling on that, it could cause problems for you in society. Are you having trouble on a professional or personal front? I don't mean to be intrusive, but I have read many of your posts, and was amazed by the vituperativeness of many of them. Why are you so acrimonious towards so many of the posters? Some of them simply need someone to help them.
> There are, for any given religion, literally _billions_ of people who > consider it not just silly, but wrong, evil, heresy, a danger to mankind, > etc. I think you should be more worried about your real enemies than the
That is absolutely true, religion does set itself up that way, how tragic. But are you a person of principle or a pragmatist? If you are a person of principle, then you should either just shoot yourself, for the future is meaningless, either everything ends up in a collapsing inferno of which there is no escape, or (as the current theory goes) the universe goes cold and there is nothing we can do about it, or the flip side of a person of principle is you believe in God and stick with that principle to the end, which now has some meaning attached to it. If you are a pragmatist, then the practical thing would be to believe in God, for the sheer probablistic imbalance of 80 years vs infinity, i.e. if you are a betting man, you should bet on infinity and get over any objections you have, otherwise that makes you a man of principle. I'm with you, religion does not have anything to offer, but there are alternatives, did you know that?
> people who have fun with something that is both tragic _and_ funny in the > development of human societies and belief systems. If you do wish to > discuss your religious hypersensitivity, do it somwehere appropriate. If > you want to get respect for your religious views, have respect for mine > first. So far, you appear to attack me for no reason whatsoever. For
You never answered my question, you simply made an assumption about my question. So no one knows your religious views, therefore I made no assumption about them. It seems that you may be the one who is hypersensitive about this issue. It appears that maybe you have an internal conflict that makes you defensive in this area. If you want respect for your views, you need to state them. What are they Erik?
> that reason alone, I think your religion is bad, for your information. > Your need to continue to talk about this is not a very good sign, either.
But you also continue to want to talk about it. You also appear to need to want to talk about this further. The proof is in your answers. I don't mind either way. I love stimulating intellectual conversation about just about anything. And don't worry about getting me upset, I find that getting upset about anything is a waste of time, I'm way past that juvenile stage of my life.
> #:Erik > -- > There is nothing in this message that under normal circumstances should > cause Barry Margolin to announce his moral superiority over others, but > one never knows how he needs to behave to maintain his belief in it.
> You need to re-read the original to see how irrelevant that whole > paragraph was.
I would need to be you to see how irrelevant that whole paragraph was. I am not you. I do not have your hypersensitivity to this issue. In my eyes, it was a joke. To you, it is getting closer and closer to a master thesis on the relevance of indinvidual paragraphs in USENET articles.
I have not read the rest of your article. It did not appear relevant to either XML or Common Lisp, but rather extremely relevant only to yourself. However, if relevance was such an issue, you would not have talked about this here. Ergo, relevance is _not_ your issue. In other words, you need to examine your whole article to see how irrelevant it is here.
Drop it and move on.
#:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.
