-----Original Message----- From: Robin Friedrich <friedrich@pythonpros.com> To: Doc-SIG <doc-sig@python.org> Date: Tuesday, 24 February 1998 7:59 Subject: Re: [DOC-SIG] Xrefs
... .. [O'Reilly] http://www.oreilly.com/catalog/html2/index.html for an ordinary URL, or: .. [Wizbang] win32api:spamDialog.toolBar.wizBangPrime for an external reference object called win32api, or: .. [Geo-model] self.GeoPotentials.Model to point to an object within our current package with an absolute path. Since we mandate full pathing to python objects we don't need to specify what the stating point of the reference is. Note also that the bracket highlighted text does not have to correspond to the object it's pointing to.
This does seem pretty good, and the last word so far on the matter. This fits well with the existing code, and I imagine that if someone _really_ wanted the completely inline style, they could implement it with "<" tags. Im probably way over generalising, but it does seem a good idea to reserve some tokens for additional growth - I dont know - say an inline image reference (ok - bad example - umm - anyway). Maybe we could reserve "<" and ">" as special indicators to allow future growth. At this stage, all it means is that you must escape literal "<" and ">"... Either way, the scheme above seems to meet my requirements, so we can steam ahead :-) How exactly do we get started (he says, suffering work overload as it is :-) Are there still design issues to resolve? eg, I saw the note saying "you must explicitly reference all objects". I dont like that idea - IMO, you should require the same level of reference that the code would. Eg: def foo(): pass def bar()" """ See also [foo function] ..[foo function] foo # Should not need to know the full location Or did I mis-understand? Thanks, Mark. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
Mark Hammond wrote:
Im probably way over generalising, but it does seem a good idea to reserve some tokens for additional growth - I dont know - say an inline image reference (ok - bad example - umm - anyway). Maybe we could reserve "<" and ">" as special indicators to allow future growth. At this stage, all it means is that you must escape literal "<" and ">"...
I might add here that such tokens need not be escaped because we have adopted the structured text approach of infering markup based on context. For example if we want to assign special meaning to <x> then the rule would be written that they are only special when set off by whitespace on only the outside. That means <x> would be special and 1< x < 5 would not. (or something to that effect) I don't want to see 1 \< x \< 5 in my doc strings! But still I will always defend the policy of minimizing inline markup on legibility grounds.
Either way, the scheme above seems to meet my requirements, so we can steam ahead :-) How exactly do we get started (he says, suffering work overload as it is :-) Are there still design issues to resolve?
Not really. Now some more detailed architecture (APIs etc) are in order. Daniel outlined the classes a while back and we need to follow up on that, resulting in a detailed module/package division of functions and a firm API for the objects.
eg, I saw the note saying "you must explicitly reference all objects". I dont like that idea - IMO, you should require the same level of reference that the code would. Eg:
def foo(): pass def bar()" """ See also [foo function] ..[foo function] foo # Should not need to know the full location
Or did I mis-understand?
didn't misunderstand. That's because it was thought that it would make it easier for the reader (of the source) to know which object without having to calculate the python scoping rules and deduce the correct path. Maybe this is unnecessary. It would make things somewhat more complicated for gendoc though. If you guys think it's easy enough fine, (i hearby volunteer NOT to code this bit). -- Robin K. Friedrich Houston, Texas Python Professional Services, Inc. friedrich@pythonpros.com http://www.pythonpros.com _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
On Mon, 2 Mar 1998, Robin Friedrich wrote:
eg, I saw the note saying "you must explicitly reference all objects". I dont like that idea - IMO, you should require the same level of reference that the code would. Eg:
def foo(): pass def bar()" """ See also [foo function] ..[foo function] foo # Should not need to know the full location
Or did I mis-understand?
didn't misunderstand. That's because it was thought that it would make it easier for the reader (of the source) to know which object without having to calculate the python scoping rules and deduce the correct path. Maybe this is unnecessary. It would make things somewhat more complicated for gendoc though. If you guys think it's easy enough fine, (i hearby volunteer NOT to code this bit).
Do we really want to limit ourselves to Python scoping rules (e.g. the two-scope rule) in a purely textual description? It strikes me that Python's rules, which make some sense in the context of evaluated code, make very little sense in the context of documentation. E.g. I think it'd be nice to be able to have: class Klass def f3(): print 'Ni!' def f1(): foo = 'SPAM!' def f2(): """ and here I refer to f1, Klass, f2, Klass.f3, and f1.foo """ something... After all, .py files are pretty static... --da _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
participants (3)
-
David Ascher -
Mark Hammond -
Robin Friedrich