[DOC-SIG] Xrefs

[Robin Friedrich]

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
_______________