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?
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.
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. [EMAIL PROTECTED] 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
_______________________________________________
help-smalltalk mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/help-smalltalk
