docstring-checkins

[David G. <go...@us...>]

Update of /cvsroot/docstring/dps/spec
In directory usw-pr-cvs1:/tmp/cvs-serv1597/dps/spec

Modified Files:
	dps-notes.txt 
Log Message:
updated

Index: dps-notes.txt
===================================================================
RCS file: /cvsroot/docstring/dps/spec/dps-notes.txt,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** dps-notes.txt	2002/01/28 02:18:17	1.20
--- dps-notes.txt	2002/01/29 02:18:32	1.21
***************
*** 17,21 ****
          [Tibs:] Eventually we need to have direct documentation in
          there on how it all hangs together - the DTD is not enough
!         (indeed, is it still meant to be correct?).
  
  - Rework PEP 257, separating style from spec from tools, wrt DPS. See
--- 17,21 ----
          [Tibs:] Eventually we need to have direct documentation in
          there on how it all hangs together - the DTD is not enough
!         (indeed, is it still meant to be correct? [Yes, it is.]).
  
  - Rework PEP 257, separating style from spec from tools, wrt DPS. See
***************
*** 49,58 ****
  - Write modules for common transforms. See Transforms_ below.
  
-   - Resolving auto-numbered footnotes & references.
-   - Resolving internal, external, and indirect hyperlinks.
-   - Propagating URIs to chained hyperlink targets.
- 
-   These transformations may be turned on or off by individual modes.
- 
  - Ask Python-dev for opinions (GvR for a pronouncement) on special
    variables (__author__, __version__, etc.): convenience vs. namespace
--- 49,52 ----
***************
*** 101,254 ****
  ==========
  
- Footnote Numbering
- ------------------
- 
- [Tony]
- This runs over a subtree (clearly for Python code, we don't want to
- run it over anything bigger than a docstring, lest we confuse
- footnotes!) and sorts out the numbering (in my development version of
- pyspd (not on the web yet) this is actually done as part of the HTML
- output phase, which is clearly the Wrong Place for it.
- 
- David - a question or two on this. Each autonumbered footnote/footnote
- reference has the attribute 'auto' set to "1". I want to *insert*
- actual footnote numbers into the tree. I can just add a new attribute
- 'auto-number' into elements as required, *or* I could ask that you set
- 'auto' to be "-1" for the "no number yet" case, and use 'auto' to
- store the *actual* number calculated. Which to do is a style issue, so
- I'd prefer to leave it up to you (but using the same attribute would
- make things a bit neater in the code - I'm not sure if it would
- generate as elegant XML, though - I'd need to look up the detailed
- attribute present/absent rules).
- 
- [David]
- Auto-numbered footnotes have attribute ``auto=1`` and no label.
- Auto-numbered footnote_references have no reference text (they're
- empty elements). If you resolve the numbering, just add a label
- element to the beginning of the footnote, and reference text to the
- footnote_reference. Take this input::
- 
-     References to the first ([A]_), third ([#spam]_), and second
-     ([#]_) footnotes.
- 
-     .. [A] This footnote is labeled with "A".
-     .. [#] This footnote is auto-numbered.
-     .. [#spam] This footnote has autonumber name "spam".
- 
- Parsed (watch for empty footnote_reference elements: indentation)::
- 
-     <document>
-         <paragraph>
-             References to the first (
-             <footnote_reference refname="a">
-                 A
-             ), third (
-             <footnote_reference auto="1" refname="spam">
-             ), and second
-             (
-             <footnote_reference auto="1">
-             ) footnotes.
-         <footnote name="a">
-             <label>
-                 A
-             <paragraph>
-                 This footnote is labeled with "A".
-         <footnote auto="1">
-             <paragraph>
-                 This footnote is auto-numbered.
-         <footnote auto="1" name="spam">
-             <paragraph>
-                 This footnote has autonumber name "spam".
- 
- Only the first footnote_reference contains reference text. After
- auto-numbering resolution, the tree should become::
- 
-     <document>
-         <paragraph>
-             References to the first (
-             <footnote_reference refname="a">
-                 A
-             ), third (
-             <footnote_reference auto="1" refname="spam">
-                 2
-             ), and second
-             (
-             <footnote_reference auto="1" refname="_footnote 1">
-                 1
-             ) footnotes.
-         <footnote name="a">
-             <label>
-                 A
-             <paragraph>
-                 This footnote is labeled with "A".
-         <footnote auto="1" name="_footnote 1">
-             <label>
-                 1
-             <paragraph>
-                 This footnote is auto-numbered.
-         <footnote auto="1" name="spam">
-             <label>
-                 2
-             <paragraph>
-                 This footnote has autonumber name "spam".
- 
- The labels and reference text are added to the two auto-numbered
- footnotes & footnote_references. The unnamed auto-numbered footnote
- & reference need name & refname attributes. Let's use "_footnote " +
- footnote number for those attributes (a name-mangling unlikely to
- occur in the real world; note that this hasn't been documented yet).
- Of course (!), the implicitlinks and refnames instance attributes of
- the dps.nodes.document instance must be updated. (It will soon be my
- pleasure to document the dps/nodes.py data structure, since I'm
- gradually forgetting its details.)
- 
- After adding labels and reference text, the "auto" attributes can be
- ignored.
- 
- 
- [David]
- > Let's use "_footnote " + footnote number for those attributes
- > (a name-mangling unlikely to occur in the real world; note that
- > this hasn't been documented yet).
- 
- [Tony]
- > Hmm - I wasn't assuming that unnamed autonumbered footnotes would have any
- > name other than the number (since you're following the XML tradition and
- > storing such things as strings anyway).
- 
- [David]
- I suppose we could go either way. I'm re-examining (for validity) what I
- wrote in the spec:
- 
-     Automatic footnote numbering may not be mixed with manual footnote
-     numbering; it would cause numbering and referencing conflicts.
- 
- Would such mixing inevitably cause conflicts? We could probably work around
- potential conflicts with a decent algorithm. Should we? Requires thought.
- Opinions?
- 
- [Tony]
- Well, I read that paragraph in the documentation, and decided that it
- was in the category of "don't, in practice, care" so far as I was
- concerned. This is the same category I put the forbidding of nested
- inline markup - quite clearly one *can* do it, but equally clearly it's
- a pain to implement, and not a terribly great gain, all things
- considered.
- 
- It's a category with the subtext "examine for correctness after we've
- had some experience of people *using* reST in the wild".
- 
- Thus, given there are lots of other things to do, I would tend to leave
- it as-is (especially if you are able to *warn* people about it if they
- do it by mistake).
- 
- To my mind, being able to do ``[#thing]_`` probably give people enough
- precision over footnotes whils still allowing autonumbering - the *only*
- potential problem is when referring to a footnote in a different
- document (and that, again, is something I would leave fallow for the
- moment, although we know I tend to want to use roles as annotation for
- that sort of thing).
- 
- 
  Footnote Gathering
  ------------------
--- 95,98 ----
***************
*** 261,280 ****
  
  It probably comes in two phases, because in a Python context we need
! to *resolve* them on a per-docstring basis, but if the user is trying
! to do the callout form of presentation, they would then want to group
! them all at the end of the document.
  
  
! Substitutions
! -------------
  
! @@@
  
  
  Table of Contents
  -----------------
  
- @@@
- 
  This runs over the entire tree, and locates <section> elements. It
  produces a <contents> subtree, which can be inserted at the
--- 105,131 ----
  
  It probably comes in two phases, because in a Python context we need
! to *resolve* them on a per-docstring basis [do we? --DG], but if the
! user is trying to do the callout form of presentation, they would then
! want to group them all at the end of the document.
  
  
! Reference Merging
! -----------------
  
! When merging two or more subdocuments (such as docstrings),
! conflicting references may need to be resolved.  There may be:
  
+ - duplicate reference and/or substitution names that need to be made
+   unique; and
+ - duplicate footnote numbers that need to be renumbered.
  
+ Should this be done before or after reference-resolving transforms
+ are applied? What about references from within one subdocument to
+ inside another?
+ 
+ 
  Table of Contents
  -----------------
  
  This runs over the entire tree, and locates <section> elements. It
  produces a <contents> subtree, which can be inserted at the
***************
*** 446,449 ****
--- 297,335 ----
          self.doctree.walkabout(self)
  
+ 
+ Mixing Automatic and Manual Footnote Numbering
+ ==============================================
+ 
+ [David]
+ I'm re-examining (for validity) what I wrote in the spec:
+ 
+     Automatic footnote numbering may not be mixed with manual footnote
+     numbering; it would cause numbering and referencing conflicts.
+ 
+ Would such mixing inevitably cause conflicts? We could probably work around
+ potential conflicts with a decent algorithm. Should we? Requires thought.
+ Opinions?
+ 
+ [Tony]
+ Well, I read that paragraph in the documentation, and decided that it
+ was in the category of "don't, in practice, care" so far as I was
+ concerned. This is the same category I put the forbidding of nested
+ inline markup - quite clearly one *can* do it, but equally clearly it's
+ a pain to implement, and not a terribly great gain, all things
+ considered.
+ 
+ It's a category with the subtext "examine for correctness after we've
+ had some experience of people *using* reST in the wild".
+ 
+ Thus, given there are lots of other things to do, I would tend to leave
+ it as-is (especially if you are able to *warn* people about it if they
+ do it by mistake).
+ 
+ To my mind, being able to do ``[#thing]_`` probably give people enough
+ precision over footnotes whils still allowing autonumbering - the *only*
+ potential problem is when referring to a footnote in a different
+ document (and that, again, is something I would leave fallow for the
+ moment, although we know I tend to want to use roles as annotation for
+ that sort of thing).