Documentation systems for other languages
I've started a list of documentation systems used for other languages: http://www.python.org/sigs/doc-sig/otherlangs.html The list isn't complete, and that's not really my intention. If there are other systems that are interesting, I'll be glad to add them to the list. So far, all of these are for source-embedded docs, but I'd love to find examples that aren't. If someone can send me a meaningful link to POD information, and an example, I'll add it. (It's on the list, just not hyperlinked.) This is *not* intended to be a list of general-purpose systems, so things like DocBook and LinuxDoc are not listed. -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives
Fred L. Drake, Jr. writes:
If someone can send me a meaningful link to POD information, and an example, I'll add it. (It's on the list, just not hyperlinked.)
For POD, what about http://www.perl.com/pub/doc/manual/html/pod/perlpod.html ? I suppose literate programming systems like CWEB are too far afield, since they usually need a general-purpose system like TeX. -- A.M. Kuchling http://starship.python.net/crew/amk/ "If you had stayed with us, we could have given you life until death." "Don't I get that anyway?" -- Stheno and Lyta Hall, in SANDMAN #61: "The Kindly Ones:5"
Andrew M. Kuchling writes:
For POD, what about http://www.perl.com/pub/doc/manual/html/pod/perlpod.html ?
Works for me! I'd been using the installed man page, as I don't know how to find things in the Perl world. I've updated the page.
I suppose literate programming systems like CWEB are too far afield, since they usually need a general-purpose system like TeX.
Processing requirements are irrelevant for our (immediate) purposes, I think. This does indicate an entire category of tools that I didn't include a category for; I've added an acknowledgement of their existance, but I'd rather not create a new list. If anyone has a link to a fairly well maintained list of LitProg tools, I'll be glad to include the link on the page. Thanks! -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives
If there are other systems that are interesting,
Occam, specifically the *folding* idiom, as applied to docs in this case. [Imagine, in a paper page on which your code is written, making sideways folds in the paper below each line of text; then you can hide a chunk of the page from view by concertina-ing up that bit of the page.] For a pythonic system, folding would mean taking any fairly large chunk of code or doc (sharing a common base indent) and providing for it to be *displayed* (by the IDE) either (open fold) as the whole chunk or (closed fold) as a single line carrying (typically encoded as a comment) some text that says what's in the fold. In between, of course, we have the fold open but some portions of its contents folded out of sight. Most modern directory-browsers display directory tree hierarchies in a way instantly recognisable to anyone who ever used a folded editor. Shape Data, here in Cambridge, have a (roughly) C source-system using folded files, implemented in-house (by Alan Smith), in which one obvious kind of fold is the doc-fold (but I doubt they've ever thought about publishing it, and it may have passed out of use in the decade or so since I left them). I've heard rumours of a folded-HTML browser. Folding would be a natural idiom for XML (except that it wouldn't be so line-oriented). In many ways it's a particularly natural idiom for indentation-alert languages. A python IDE could implement a folding idiom without necessarily changing the source file: this would integrate naturally with the indentation-based structure. i.e. even if the language and doc tools don't believe in folding, the IDE could offer it.
I'll be glad to add them to the list. But I don't know of anywhere with web pages about folded editors.
So far, all of these are for source-embedded docs, Folded fits that bill, with the twist that a long doc-string (such as verbose folk might write) doesn't carry the penalty of (e.g.) the function name-and-arguments line being on a different page (or screen-full) from the implementation.
Eddy.
Edward Welbourne wrote:
Occam, specifically the *folding* idiom, as applied to docs in this case. [Imagine, in a paper page on which your code is written, making sideways folds in the paper below each line of text; then you can hide a chunk of the page from view by concertina-ing up that bit of the page.]
I saw something similar at a presentation given by Peter Pierrou from Excosoft at the recent Markup Technologies '99 conference. The prenentation was titled Literate Programming in XML: Combining source code and documentation. Apparently Excosoft uses this tool for all their internal development work (including Python and 7-8 other languages). It's based on their Documentor SGML/XML editor, which unfortunately is a commercial tool. The paper is available at ftp://www.excosoft.se/pub/seminars/litprog.pdf in case anyone's interested. This is a little off the topic of Fred's original question but maybe some future free IDE for Python might incorporate the folding concept. --David Niergarth
David Niergarth writes:
This is a little off the topic of Fred's original question but maybe some future free IDE for Python might incorporate the folding concept.
Interesting snippets are always interesting! A number of people have proposed adding folding support to IDLE, but I don't know if anyone is actually working on it. Heck, for all I know, it might be in there already! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives
From: "Fred L. Drake, Jr." <fdrake@acm.org>
David Niergarth writes:
This is a little off the topic of Fred's original question but maybe some future free IDE for Python might incorporate the folding concept.
Interesting snippets are always interesting! A number of people have proposed adding folding support to IDLE, but I don't know if anyone is actually working on it. Heck, for all I know, it might be in there already!
No, it's not been done yet. It might be tricky, given that the Tk text widget we're using doesn't support such a concept -- we'd have to delete the folded text from the buffer and trap keystrokes. I agree though that it's a useful feature. (Among many others.) --Guido van Rossum (home page: http://www.python.org/~guido/)
Guido van Rossum writes:
No, it's not been done yet. It might be tricky, given that the Tk text widget we're using doesn't support such a concept -- we'd have to delete the folded text from the buffer and trap keystrokes.
Which of course complicates the colorizing code; I seem to recall that it works directly with the text widget's buffer rather than an internal representation. Ahh, the breakage! ;) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives
Edward Welbourne writes:
Occam, specifically the *folding* idiom, as applied to docs in this case. [Imagine, in a paper page on which your code is written, making
Is there a pointer to something that describes this in the context of Occam? I've heard about folding as a general approach to editing sources and structured documentation, but had not heard of it as specific to a language. Or do I misunderstand? -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives
Is there a pointer to something that describes this in the context of Occam? None I know of.
I've heard about folding as a general approach ... ... but had not heard of it as specific to a language.
AFAIK, Occam introduced the idiom. It is otherwise irrelevant to the discussion: the folding idiom is what I was thinking of, not Occam. I only mentioned Occam because it'd ring some bells where `folded files' might not have done. Eddy. -- And a happy new year to doc-sig, too ;^>
Edward Welbourne writes:
AFAIK, Occam introduced the idiom. It is otherwise irrelevant to the discussion: the folding idiom is what I was thinking of, not Occam. I only mentioned Occam because it'd ring some bells where `folded files' might not have done.
I did not know that; interesting!
And a happy new year to doc-sig, too ;^>
Bah, humbug! ;) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives
For a pythonic system, folding would mean taking any fairly large chunk of code or doc (sharing a common base indent) and providing for it to be *displayed* (by the IDE) either (open fold) as the whole chunk or (closed fold) as a single line carrying (typically encoded as a comment) some text that says what's in the fold. In between, of course, we have the fold open but some portions of its contents folded out of sight. Most modern directory-browsers display directory tree hierarchies in a way instantly recognisable to anyone who ever used a folded editor.
Sounds like outline mode in emacs. The GNU Emacs support for SGML provides this, perhaps more closely resembling what you describe. Bill
participants (6)
-
Andrew M. Kuchling -
Bill Janssen -
David Niergarth -
Edward Welbourne -
Fred L. Drake, Jr. -
Guido van Rossum