[Doc-SIG] Documentation systems for other languages

[Edward Welbourne]

> 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.