|
From: | Paolo Bonzini |
Subject: | Re: [Help-smalltalk] Documentation syntax |
Date: | Wed, 16 Aug 2006 17:33:05 +0200 |
User-agent: | Thunderbird 1.5.0.5 (Macintosh/20060719) |
I agree that, in general, Smalltalk methods tend to be small enough that nobody felt the need for markup. However, I think it would not be bad to support some kind of markup, especially a very simple one.I don't really know what you mean by "an online documentation system", so I might still be persuaded, but I don't really see the need for the markup. Take this method: PositionableStream >> copyFrom: start to: end "Answer the collection on which the receiver is streaming, from the start-th item to the end-th" ^collection copyFrom: start to: end Arguably, this comment doesn't tell us anything that isn't self-evident, but anyway, how would you mark it up so that it gives us more information?
For example, some Texinfo commands could be recognized and subject to special treatment. For Texinfo, the @ would not be escaped @var{start}; for HTML, a suitable markup could be produced. For example, the above could be written as
"Answer the collection on which the receiver is streaming, from the @var{start}-th item to the @var{end}-th"I believe that this could help the readability of the manual--OTOH it would hinder the readability of the source code. Maybe we need a simpler coding, like
"Answer the collection on which the receiver is streaming, from the @{start}-th item to the @{end}-th. address@hidden and @{end} are not checked to be less than or equal to the stream's position!_"i.e. @{XXX} becomes @var{XXX} or <i><tt>XXX</tt></i>, and _abc_ becomes @emph{XXX} or <strong>XXX</strong> (respectively for Texinfo and HTML).
Paolo
[Prev in Thread] | Current Thread | [Next in Thread] |