[Doc-SIG] anchors and local references

[Edward D. Loper]

> OK, lots of stuff here and I'm a bit lost so I'm going to think out loud
> at you, so you have a good chance of spotting where my confusion
> diverges from what you thought you were saying.  If I'm confused, how
> confused are the lurkers ?

I think part of that confusion comes from me talking without 
actually knowing what I'm talking about. :)

So, I'll go ahead and try to give a brief description of where
anchors and local references currently stand (I think), so
everyone will be clear on it:

/======================================================================\

FUNCTION

Anchors and local references are used to add bibliographic references
and endnotes to StructuredText.  Local references are used to refer
to the references/endnotes, and anchors are used to write the
references/endnote.  (n.b.: we may want to change these terms, because
the words themselves suggest something more general).

SYNTAX

Local references look like [this].  They are normally used either 
for bibliographic reference, like this: [eddy00]; or for endnotes,
like this: [1].  Local references can appear anywhere in the text
of a paragraph or list item (and possibly other places, like in
a heading).

Anchors look like this::

    ..[this] This is the anchor for the reference '[this]'

The form "..[name]" patterns syntactically almost exactly like
the form "name:".  In other words, you can do the following::

    ..[anchor1] Anchors may span multiple
                lines.

    ..[anchor2]

        Anchors may contain multiple paragraphs.

        Or even lists.

etc.

The name of a local reference/anchor should be a single word,
but can contain a few punctuation marks (&, _, -, maybe others).
The exact contents of a name is yet to be determined, but we
can tentitively say it's something like: '[\w&_-]+|[\d]+'

Anchors must be the last top-level elements of a StructuredText
string.

SEMANTICS

When a StructuredText string is displayed, a local reference 
should appear as it does in plaintext.  However, it may also 
be linked in some way to its anchor (e.g., with an href in 
HTML).  For example, in HTML, '[this]' would be rendered as::

    <a href="#this">[this]</a>

When anchors are displayed, their name should be displayed as some
type of heading or list bullet, and their contents should be listed
under that section or in that list item.  For example, it might
be sensible to render anchors using DL's in HTML.  Also, if
local references are linked to anchors, then the anchor should 
include the target for the link.  So::

    ..[this] anchor

Might be rendered in HTML as::

    <a name="this"></a>
    <dl><dt>this</dt><dd>anchor</dd></dl>

..[eddy00] email from Edward Welbourne, recieved Fri, 23 Mar 2001
           20:44:49 +0000 (GMT).
..[1] It may make sense to say that we should use numbers for 
      endnotes and words for bibliographic entries, but we won't
      say that for now.

\======================================================================/

Note that this is *not* used for out-of-line URI references, which
is what I thought it was for at one point.

Hmm.. hopefully that helped clarify things a little.  I'll have
a better explanation once I'm done with my PEP. :)

> aside: [blah] is surely what *bibliographic citations* look like, 
> not *footnotes* in any typesetting idiom I've ever met.

But *endnotes* do look like that in some typesetting idioms..

> Hmm.  Well, ideally we'd support standard citation forms, which would
> include '[this, that, other]', to be treated like '[this], [that],
> [other]'

Fine with me, if others also want it.  Of course, I also wouldn't
feel bad about making people type [this], [that], [other].

> One might plausibly want to allow '&' in ref names

I agree.

> (By the way - Edward, some of your sentences end .. others end in a
> single . - why ? i.e. is there a reason other than bouncy fingers ?)

No, it's not bouncy fingers..  I'm not sure, exactly.. it's an idiom
I only use in emails.  I think I use it where I would pause slightly
longer if I were speaking.  But I'd have to go read my own emails
over to figure it out for sure.  Sometime's I'll even end my sentences
with three periods... :)

-Edward..