Re: [Help-smalltalk] Documentation syntax

[Paolo Bonzini]

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