[Doc-SIG] Some random thoughts

[Peter Funk]

Edward Welbourne wrote:
> Meanwhile, what do folk make of #inline-code# ?

Personally I find this ugly.  But I've looked through the Python 
standard library and my own code and found out, that such 
inline code is absolutely rare.  code examples occur almost always
in separated paragraphs.

What is more often used, are references to identifiers.  We had some 
discussion about this before.  I suggested the use of a single '^' in
front of the identifer as markup.  In the meantime I have used this in my 
docstrings and find it rather appealing.  Here are two examples:

    def __init__(self, typedValue):
        """This class behaves similar to the class ^Tkinter.Variable
        If the ^typedValue is something simple like a number or a string, 
        most functionality is delegated to a private member ^self._tk_var.

        But ^typedValue may also be a list or a dictionary containing
        other structures or simple values.
        """

    def setval(self, value, from_listener = None):
        """assigns a new data ^value to ^self.

        After assigning the ^value all listeners will be called.  To avoid
        loops, the calling object should submit itself as second parameter 
        ^from_listener to this method here.
        """

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)