Fred L. Drake, Jr. wrote: > > While the goal of reST is to avoid explicit markup, IMO it's fine to use > > explicit markup where considered necessary and it doesn't make reST less > > useful. > > Yep. I just don't see a way to avoid lots of markup. There are probably > some > ways to make the default interpreted text role context-sensitive to avoid > having to be really heavy with markup in places where we can determine what's > the most reasonable role. (`var` in a function description with an argument > named "var" should be able to determine that `var` refers to the parameter.)
I've always been fuzzy on what `name` really meant in ReST, when it doesn't have any other markup. But it seems vague enough to potentially be useful. Imagine that you specifically name objects that are documented, like: .. class:: ZipFile(file, mode='r', compression=ZIP_STORED) .. function:: is_zipfile(filename) Then when you refer to `is_zipfile`, it would know that this referred to a function, because of the directive declared elsewhere. Potentially you could have lookup rules that would first search the "local namespace" (the module's document), then look for another module (e.g., `zlib.compress`). I'm not sure if it would be reasonable to change the documentation to make everything unambiguous, for instance changing this zipfile.ZipInfo doc: Class used to represent information about a member of an archive. Instances of this class are returned by the getinfo() and infolist() methods of ZipFile objects. To: Class used to represent information about a member of an archive. Instances of this class are returned by the `ZipFile.getinfo()` and `ZipFile.infolist()` instance methods. Ugh. And I don't know if there's a good way of making indirect links, like: ... returned by the `getinfo() <object:ZipFile.getinfo>`_ ... But, hm... maybe that's not so bad. You wouldn't know what kind of thing you were referencing until you built all the docs (first pass) and resolved the links, but I don't know if that's actually a problem. It's just dynamically typed documentation ;) It *does* seem like "semantic markup" of references is just another way of saying "static typing" -- you are giving types to names, when only objects should have types. -- Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
