Hi Michael,
On 1 Aug., 18:53, Michael Orlitzky <mich...@orlitzky.com> wrote:
> >http://sagemath.org/doc/developer/conventions.html#documentation-strings
>
> I don't see the "::" documented anywhere (did I read past it?). What do
> they do?
You are somehow right: Even though the :: is frequently used, it does
not seem to be explicitly explained. I think that the information
should be added!
The double colon indicates that the following indented block is not
just indented, but is in fact a block of sage code.
Hence, it is a mistake if you use the double colon and do not have it
followed by an indentation. Also, it MUST be followed by a blank line.
"""
EXAMPLE::
That double colon would result in an error when the documentation is
built, since there is no indentation.
Moreover::
sage: print "the blank line is missing..."
"""
If the double colon is not preceded by text in the same line, then it
does not show up in the html text -- it only indicates that a code
block follows, such as here:
"""
EXAMPLE:
The single colon in the previous line is fine. Next, we start a block
of code.
::
sage: print "hello world"
"""
The `::` will not result in a printed character, but it implies that
`sage: print "hello world"` is typeset as a code block.
Typically, if you have an explanation inserted between lines of your
example, then the text ends with a colon. Therefore, a little short-
cut has been introduced:
"""
The code starts now::
sage: print "hello world"
"""
does the same as
"""
The code starts now:
::
sage: print "hello world"
"""
At least that's what I (hope to) know about the ::...
Best regards,
Simon
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
