Note that simple bare words are never interpreted as references.
Why not? Of course this may go wrong, if you use very common words like 'a', 'is', 'so' ... as identifiers. But I don't believe, that this will happen too much.
umm ... I believe the reverse. * A string-processing function with an argument which decides whether to capitalise the string is almost certain to use the verb capitalise (in its Natural Language sense) in the course of its account of the argument which it will, naturally, call `capitalise'. * Many I/O routines use buffers whose size the caller can control via a parameter, usually called buffer; an account of whose meaning will routinely involve refering (in the NL sense) to the buffer whose size is controlled by the argument. * ... It is *in general* Good Practice to name parameters (especially those which the caller is expected to give in name=value form) using plain words which fit close to the NL words relating to the purpose of the parameter. Any account of the purpose of the parameter is, consequently, liable to use the NL sense of the word as well as using the word to refer to the parameter. IMO, this forces us to have some equivalent of the *emphasis* markup. As to *what* should serve in this role: well, it's going to enclose things which are to be read as lumps of python code in the doc string, within which any identifiers are to be hyperlinked to the definition of the object referenced by that identifier; so we can't go using any character which can appear in an inline-in-the-doc code fragment (e.g. regarding 'quoted text' as code fragment is unacceptable, because my code fragment may wish to include a 'quoted string'). I don't think $, @ and ! are good candidates, but they could work; however, how do folk feel about # as a marker ? Since we're in a doc-string, it doesn't have any special meaning; nor do I think it sensible to include an end-of-line-comment in an inline-in-the-doc code fragment (as opposed to a code fragment displayed using a Code: block or
). Thus #any.valid(python + ' code') is guaranteed(to, work)#.
[Ka Ping's] rules sound a little bit complicated.
Then we get: Arguments: file ! string -- the name of the file to be opened. mode ! string -- the file access mode string ... If #mode#'s first letter is #'r'#, #file# must exist. buffer ! int or None [None] -- size of the I/O buffer to use. A size #< 0# indicates that no buffering should be done (raw I/O). If #buffer# is given as #None#, a `sensible' buffer size will be chosen. and only treat words in the description (after --) as special if explicitly marked as such. Of course, since this is the Arguments: block, treating the key (before !) as special comes naturally without needing to mark it using #. Exceptions: IOError -- raised if #file# does not exist, #mode# is unrecognised or if #buffer#'s value is inappropriate for the given #file# and #mode#. This fits the `easy to type' requirement; how do folk feel about `easy to read' ? Note that I, at least, find it has one bonus under `easy to read'; I know when a word is used in its NL sense and when it is used to refer to something in the python code; that makes it easier to understand what I read. As to creating cross-references: identifiers appearing inside #...# or in the body of a Code: block can be sought using the namespace lookup machinery python would use from within the body of the thing whose doc-string we're parsing; where the lookup finds something with a doc-string, it is natural to generate an href to that doc-string (or, rather, what it will become when parsed). This should only need to happen for things marked as code. Does this fit the requirement for clear and simple rules ? Summary: * Within text (not within Code: &c. blocks), # is used as delimiter for (start and end of) in-text code fragments. * Code:, Example: and >>> blocks and in-text code fragments are parsed; identifiers within them are looked up as if by the interpreter when executing the suite which the doc-string begins; if these lookups yield something to which the generated docs can make an HREF, they do so. Note that, * in #open('peter', 'r')#, peter does not appear as an identifier (it appears as a string) so no attempt is made to look peter up in any namespaces. * use of #code(fragments)# is viable within comments, either in real python code (outside the doc-string) or in Code: &c. blocks. Given the latter, it would make sense for the parse-and-href idiom to ignore end-of-line comments in Code: &c. blocks, but to recognise code fragments in such comments and subject these to parse-and-href. they are amenable to some simplification, though. Eddy. -- Actually, starting /* and ending */ would do fine ... the funny thing is, in C, that */ would be the obvious way to *start* comments, since it cannot appear in valid code. As ever, K&R didn't do the obvious.