From mal@lemburg.com  Fri Nov  1 12:09:59 2002
From: mal@lemburg.com (M.-A. Lemburg)
Date: Fri, 01 Nov 2002 13:09:59 +0100
Subject: [Doc-SIG] epydoc 1.1 release
References: <3DC09D12.9060804@gradient.cis.upenn.edu>	<200210310302.g9V32fK22735@pcp02138704pcs.reston01.va.comcast.net>	<3DC0AFC8.4030901@gradient.cis.upenn.edu> <3DC0F0DE.808@lemburg.com> <3DC0F850.7010300@gradient.cis.upenn.edu>
Message-ID: <3DC26F17.9050507@lemburg.com>

Edward Loper wrote:
> M.-A. Lemburg wrote:
> 
>> Edward Loper wrote:
>>
>>> - Some advantages of pydoc are:
> 
>  >>     [...]
> 
>>
>> I like the output of epydoc a lot (except maybe for the dim
>> colors ;-). Wouldn't it be possible to add most of the above
>> in form of options to epydoc ?
> 
> 
> For some of these, they would be added (as defaults, not options) if I 
> had time to code them.  And there's plenty more on the epydoc todo list 
> (see the comment at the bottom of epydoc.py/__init__.py).
> 
> Others don't really go with epydoc's design philosophy.  In particular, 
> I doubt epydoc will ever automatically (implicitly) create intra-doc 
> links.  This can sometimes make mistakes, and puts links all over the 
> place.  I would rather have the user explicitly create links.  I'm also 
> unlikely to add support for processing python comments.  And I doubt 
> I'll add manpage-style and interpreter (pydoc.help) usage, because pydoc 
> already does such a good job at it, and is already part of the standard 
> library.

Hmm, that doesn't leave much ;-)

>> What I don't understand about epydoc is why it uses a syntax
>> that's almost JavaDoc-style, but not all the way ?
> 
> Actually, the only real similarity between epytext and javadoc comments 
> is that the @field's look roughly similar.

That's what I was looking at. Your @field defs look very similar,
but aren't compatible, e.g. was there a reason to add colons ? (this
is really what I'm interested in; not the HTML formatting used
in JavaScript)

>  E.g., note that you have to 
> use explicit <p>'s in javadoc to mark paragraph boundaries; and you have 
> to explicitly use <ul><li></ul> for lists, etc.
> 
> I find javadoc's markup conceptually ugly.  The idea of allowing 
> unrestricted html code in your docstring really bothers me.  And it 
> makes the docstrings very difficult to read when you're looking at the 
> source code.  That said, it might be good to add support for 
> javadoc-style docstrings, just because it would reduce the learning 
> curve for java programmers.  It wouldn't be that technically difficult 
> to do; javadoc docstrings are basically just raw html plus @field's. And 
> epydoc's docstring processing is pretty compartmentalized.  But I only 
> have limited time to spend on epydoc, and that's not a feature that I 
> feel very motivated to add.
> 
> If someone else wants to add it, I'd certainly accept a patch.  What 
> would probably be involved is:
> 
>   - Write epydoc/javadoc.html to parse javadoc-style comments.  It
>     would probably produce an xml document with a <javadoc> node
>     that contains a <rawhtml> node followed by a <fieldlist> node
>     similar to epytext's.  Of course, if you wanted to handle
>     javadoc's syntax for intradocumentation links, etc, you would
>     need to do a little more work.
>   - Patch ObjDoc.__parse_docstring in epydoc/objdoc.py to recognize
>     'javadoc' as a value for __docformat__.
>   - Patch HTML_Formatter._dom_to_html_helper in epydoc/html.py to
>     handle <rawhtml> elements.
>   - (Optionally) add all of the field's that javadoc implements that
>     epydoc does not (e.g., @since and @depreciated).
> 
> Then you could just use "--docformat javadoc" to set the default 
> docstring format to javadoc, or add "__docformat__='javadoc'" to each 
> module that uses javadoc-style docstrings.

Thanks for the instructions. I think I'll have a go once we're
sure that we need this.

-- 
Marc-Andre Lemburg
CEO eGenix.com Software GmbH
_______________________________________________________________________
eGenix.com -- Makers of the Python mx Extensions: mxDateTime,mxODBC,...
Python Consulting:                               http://www.egenix.com/
Python Software:                    http://www.egenix.com/files/python/



From edloper@gradient.cis.upenn.edu  Fri Nov  1 17:30:55 2002
From: edloper@gradient.cis.upenn.edu (Edward Loper)
Date: Fri, 1 Nov 2002 12:30:55 -0500 (EST)
Subject: [Doc-SIG] epydoc 1.1 release
In-Reply-To: <3DC26F17.9050507@lemburg.com>
Message-ID: <Pine.LNX.4.44.0211011212530.26866-100000@34.mupb.bstn.bstnmaco.dsl.att.net>

On Fri, 1 Nov 2002, M.-A. Lemburg wrote:
> > Actually, the only real similarity between epytext and javadoc comments 
> > is that the @field's look roughly similar.
> 
> That's what I was looking at. Your @field defs look very similar,
> but aren't compatible, e.g. was there a reason to add colons ? (this
> is really what I'm interested in; not the HTML formatting used
> in JavaScript)

For those who are not familiar with javadoc, their field syntax is:
    @param x description...
    @author description...
Whereas my field syntax is
    @param x: description...
    @author: description...

The problem I have with javadoc's syntax is that the markup language 
itself has to specify which fields take arguments and which don't.  That 
goes against epytext's philosophy, where everything should be as simple 
and consistant as possible.  By adding a colon, epytext doesn't need to 
know anything about what the set of fields are; and the later systems that 
actually use the fields can complain if they're invalid in some way.

Another reason for using the colon is that strings of the form "@...:" are 
much less likely to occur "naturally" than strings of the form "@...".

(Another difference is that using a colon would let you provide optional 
arguments, but none of the fields I have defined use optional arguments, 
and I doubt that any will.)

> Thanks for the instructions. I think I'll have a go once we're
> sure that we need this.

Ok, thanks.

-Edward



From guido@python.org  Tue Nov  5 22:40:31 2002
From: guido@python.org (Guido van Rossum)
Date: Tue, 05 Nov 2002 17:40:31 -0500
Subject: [Doc-SIG] epydoc 1.1 release
In-Reply-To: Your message of "Wed, 30 Oct 2002 23:21:28 EST."
 <3DC0AFC8.4030901@gradient.cis.upenn.edu>
References: <3DC09D12.9060804@gradient.cis.upenn.edu> <200210310302.g9V32fK22735@pcp02138704pcs.reston01.va.comcast.net>
 <3DC0AFC8.4030901@gradient.cis.upenn.edu>
Message-ID: <200211052240.gA5MeVi25839@odiug.zope.com>

Thanks for clarifying the differences between pydoc and epydoc.  I
think I'd like to see some of epydoc's features in pydoc, but I'm not
sure how to do this given that the code bases are different, so I'll
accept that these are separate tools.  I do find epydoc's default
color scheme hard to read (not enough contrast), but I'm sure that's
customizable too. :-)

--Guido van Rossum (home page: http://www.python.org/~guido/)


From goodger@python.org  Fri Nov  8 01:48:33 2002
From: goodger@python.org (David Goodger)
Date: Thu, 07 Nov 2002 20:48:33 -0500
Subject: [Doc-SIG] Docutils Update: statemachine.ViewList
In-Reply-To: <B9F08142.2B61D%goodger@python.org>
Message-ID: <B9F08220.2B622%goodger@python.org>

I've just checked in code for ViewList and StringList classes to
docutils/statemachine.py.  StringList objects are now used inside the
state machine (the guts of the parser) instead of standard Python
lists.  The change should be internal-only, with no outside effects,
but outside code should be tested.  Please let me know if there are
any problems.

Here's the ViewList class docstring:

    List with extended functionality: slices of ViewList objects are
    child lists, linked to their parents. Changes made to a child list
    also affect the parent list.  A child list is effectively a "view"
    (in the SQL sense) of the parent list.  Changes to parent lists,
    however, do *not* affect active child lists.  If a parent list is
    changed, any active child lists should be recreated.

    The start and end of the slice can be trimmed using the
    `trim_start()` and `trim_end()` methods, without affecting the
    parent list.  The link between child and parent lists can be
    broken by calling `disconnect()` on the child list.

    Also, ViewList objects keep track of the source & offset of each
    item. This information is accessible via the `source()`,
    `offset()`, and `info()` methods.

BTW, this solves the "include" directive problems brought up by Brett
Porter last week.  (A long way to go to fix a small problem!  But it
should pay off in the long term.)

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



-------------------------------------------------------
This sf.net email is sponsored by: See the NEW Palm
Tungsten T handheld. Power & Color in a compact size!
http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0001en
_______________________________________________
Docutils-develop mailing list
Docutils-develop@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop



From drifty@bigfoot.com  Fri Nov  8 03:11:02 2002
From: drifty@bigfoot.com (Brett Cannon)
Date: Thu, 7 Nov 2002 19:11:02 -0800 (PST)
Subject: [Doc-SIG] in-line hyperlinks
Message-ID: <Pine.SOL.4.44.0211071854530.9481-100000@death.OCF.Berkeley.EDU>

Since this is my first post to the list I should probably introduce
myself.  My name is Brett Cannon and I write the python-dev Summary.  That
is also where my use of Docutils and reST stems from.  This is also why I
would love to see a way to do inline hyperlinks.

David gave me the current front-runner for the syntax (`phrase
reference <http://www.example.org/phrase_reference/>`__).  I basically
agree with the points made at
http://docutils.sourceforge.net/spec/rst/alternatives.html#inline-external-targets
about it.  I can only think of two possible alternatives that do not
necessarily deal with all the points, but my at least aesthetically work.

One is something along the lines of `phrase
reference`->http://www.example.org/phrase_reference/ .  I personally think
it is a little less noisy then the front-runner, although I just realized
that ambiguity with the ending of the hyperlink and possible punctuation
might be an issue.  I also realize that single word references probably
will still require the back-ticks.

The second possibility I thought of was `phrase
reference`@http://www.example.org/phrase_reference/ .  I think this also
reads well since if you read it as a statement; "phrase statement at
http..." .  One possible problem is that it looks a little cluttered.  So
alternatives are `phrase reference`__
@http://www.example.org/phrase_reference/ or `phrase
reference`_@_http://www.example.org/phrase_reference/ .  There are also
other ways to play with it such as changing the spacer to `_@ http... or `
@_http... to make sure that there is no chance of ambiguity.  And all the
variations that have a space deal with the issue of the hyperlink being
tied to the last part of the phrase and thus creating a wrapping issue.

Anyway, these are just some suggestions I came up with.  I am willing to
do my part to get in-line hyperlinks into reST if a reasonable syntax can
be agreed upon.

-Brett C.



From goodger@python.org  Fri Nov  8 21:55:31 2002
From: goodger@python.org (David Goodger)
Date: Fri, 08 Nov 2002 16:55:31 -0500
Subject: [Doc-SIG] in-line hyperlinks
In-Reply-To: <Pine.SOL.4.44.0211071854530.9481-100000@death.OCF.Berkeley.EDU>
Message-ID: <B9F19D02.2B673%goodger@python.org>

Brett Cannon wrote:
> Since this is my first post to the list I should probably introduce
> myself.  My name is Brett Cannon and I write the python-dev Summary.
> That is also where my use of Docutils and reST stems from.  This is
> also why I would love to see a way to do inline hyperlinks.

Welcome, Brett!  Your Python-Dev Summaries are a perfect example of
the kind of document where inline targets would be beneficial.  This
feature has languished unattended for two reasons:

First, nobody's been asking for it.  Simon Budig, the original
proposer, has been quiet.  There are old sayings that are applicable
here: "the squeaky wheel gets the grease" and "out of sight, out of
mind".

(There's also the old Japanese saying, "the nail that sticks up gets
hammered down".  It's a cultural thing, group harmony versus
individual creativity and innovation.  Draw your own conclusions.)

Second, I'm still not comfortable with any of the syntax variations.
Each of them has the problem of "poor plaintext readability", but
that's a direct consequence of putting the URL in the text (inline).
Can't be helped.  It's the nature of the beast.

Listed below are the "front-runner" (#1) and Brett's proposed syntax
variations:

1. `phrase reference <http://www.example.org/phrase_reference/>`__

2. `phrase reference`->http://www.example.org/phrase_reference/

3. `phrase reference`@http://www.example.org/phrase_reference/

4. `phrase reference`__ @http://www.example.org/phrase_reference/

5. `phrase reference`_@_http://www.example.org/phrase_reference/

Of the new proposals (2-5), #2 is the least objectionable to me.  All
the others look much too cluttered, and "@" already has the
connotation of email addresses.  But #2 lacks consistency with the
existing reference syntaxes, which all use trailing underscores.
Attempting to fix that leads us to:

6. `phrase reference`__ ->http://www.example.org/phrase_reference/

But the whole point is that

    The underscore can be thought of as a right-pointing arrow.  The
    trailing underscores point away from hyperlink references, and the
    leading underscores point toward `hyperlink targets`_.

    (http://docutils.sf.net/spec/rst/reStructuredText.html
    #hyperlink-references)

Factoring that back in, we're led back to syntax alternative #2 in
http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets:

7. `phrase reference`__ __<http://www.example.org/phrase_reference/>

I still think syntax #1 above is the best alternative.  The brackets
serve a useful function, since they're associated with URLs already.
Don't forget that not all URLs are absolute (beginning with
"http://"); many are relative, and don't look URLs without the
brackets.  Let's look at all the variations with relative URLs:

1. `phrase reference <relative_url>`__

2. `phrase reference`->relative_url

3. `phrase reference`@relative_url

4. `phrase reference`__ @relative_url

5. `phrase reference`_@_relative_url

6. `phrase reference`__ ->relative_url

7. `phrase reference`__ __<relative_url>

To me, syntax #1 is even more strongly in front with relative URLs.

> I just realized that ambiguity with the ending of the hyperlink and
> possible punctuation might be an issue.

In email or news messages, yes, but that's true of any URL.  The URL
recognition depends on the client software.  The PiperMail software
that provides web access to Python mailing lists always includes a
trailing period if a URL appears at the end of a sentence (like this:
"... see http://www.example.org.").  The reStructuredText parser
always leaves off that pesky trailing punctuation though.  I realize
that your application, the Python-Dev Summaries, is primarily a
mail/news message, so that's important.  All you can do is keep on
delimiting the URLs somehow, with <brackets> or a space before the
period .

> Anyway, these are just some suggestions I came up with.

And thanks for them!

> I am willing to do my part to get in-line hyperlinks into reST if a
> reasonable syntax can be agreed upon.

I wouldn't be surprised if we can't get any better syntax than what's
already been proposed.  There are only so many characters in 7-bit
ASCII.

CALL FOR OPINIONS: Please take a look at the implementation notes
(http://docutils.sf.net/spec/notes.html#inline-external-targets) and
tell us what you think.  The alternatives are: implement this as a
general feature; require a global/pragma directive to enable it;
require a local directive; or don't implement it at all.

Just thought of a better name for this beast: "embedded targets".

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From drifty@bigfoot.com  Fri Nov  8 22:16:30 2002
From: drifty@bigfoot.com (Brett Cannon)
Date: Fri, 8 Nov 2002 14:16:30 -0800 (PST)
Subject: [Doc-SIG] in-line hyperlinks
In-Reply-To: <B9F19D02.2B673%goodger@python.org>
Message-ID: <Pine.SOL.4.44.0211081402470.19800-100000@death.OCF.Berkeley.EDU>

[David Goodger]

> First, nobody's been asking for it.  Simon Budig, the original
> proposer, has been quiet.  There are old sayings that are applicable
> here: "the squeaky wheel gets the grease" and "out of sight, out of
> mind".
>

Well that issue has now been solved.  =)

> Second, I'm still not comfortable with any of the syntax variations.
> Each of them has the problem of "poor plaintext readability", but
> that's a direct consequence of putting the URL in the text (inline).
> Can't be helped.  It's the nature of the beast.
>

Yes, unfortunately.  I am afraid this one might come down to the least
offensive solution.

> Listed below are the "front-runner" (#1) and Brett's proposed syntax
> variations:
>
> 1. `phrase reference <http://www.example.org/phrase_reference/>`__
>
> 2. `phrase reference`->http://www.example.org/phrase_reference/

<snip>

>
> Of the new proposals (2-5), #2 is the least objectionable to me.  All
> the others look much too cluttered, and "@" already has the
> connotation of email addresses.  But #2 lacks consistency with the
> existing reference syntaxes, which all use trailing underscores.
> Attempting to fix that leads us to:
>
> 6. `phrase reference`__ ->http://www.example.org/phrase_reference/
>
> But the whole point is that
>
>     The underscore can be thought of as a right-pointing arrow.  The
>     trailing underscores point away from hyperlink references, and the
>     leading underscores point toward `hyperlink targets`_.
>

I don't view the underscores like that (might be my training in philosophy
and symbolic logic).  I see them more just as visual delineators for the
reST parser and not as a metaphorical pointer.  This is especially true
since the hyperlink that the underscores supposedly point to are never on
the same line and can quite easily have other text between the text and
the link.

I do understand the point that it does not exactly fit in with the rest of
reST.  But then again I personally find the angle brackets obtrusive and
ugly.  If I wanted angle brackets I would be using XML.  =)

> I still think syntax #1 above is the best alternative.  The brackets
> serve a useful function, since they're associated with URLs already.

True, but then having a syntax that somehow connects to the beginning of
the URL serves the same purpose of association.

> Don't forget that not all URLs are absolute (beginning with
> "http://"); many are relative, and don't look URLs without the
> brackets.  Let's look at all the variations with relative URLs:
>
> 1. `phrase reference <relative_url>`__
>
> 2. `phrase reference`->relative_url
>
> 3. `phrase reference`@relative_url
>
> 4. `phrase reference`__ @relative_url
>
> 5. `phrase reference`_@_relative_url
>
> 6. `phrase reference`__ ->relative_url
>
> 7. `phrase reference`__ __<relative_url>
>
> To me, syntax #1 is even more strongly in front with relative URLs.
>

Here is a case where #1 looks better to me then before, but not enough to
discount #2 for me.  But then again I am biased toward how it looks for
absolute hyperlinks since that is what all of my links are.

> I wouldn't be surprised if we can't get any better syntax than what's
> already been proposed.  There are only so many characters in 7-bit
> ASCII.
>

Could always move to Unicode.  =)

> CALL FOR OPINIONS: Please take a look at the implementation notes
> (http://docutils.sf.net/spec/notes.html#inline-external-targets) and
> tell us what you think.  The alternatives are: implement this as a
> general feature; require a global/pragma directive to enable it;
> require a local directive; or don't implement it at all.
>

I vote for general feature or a directive.  Either was I want the feature.
=)

> Just thought of a better name for this beast: "embedded targets".
>

Using "embedded" works for me, but not targets.  When I hear "target" I
think of internal document target liks <a name="Target1" />.  "Embedded
hyperlinks" sounds better to me.

-Brett



From lists@morpheus.demon.co.uk  Sat Nov  9 16:28:12 2002
From: lists@morpheus.demon.co.uk (Paul Moore)
Date: Sat, 09 Nov 2002 16:28:12 +0000
Subject: [Doc-SIG] in-line hyperlinks
References: <Pine.SOL.4.44.0211071854530.9481-100000@death.OCF.Berkeley.EDU> <B9F19D02.2B673%goodger@python.org>
Message-ID: <n2m-g.vg36so6b.fsf@morpheus.demon.co.uk>

David Goodger <goodger@python.org> writes:

> 1. `phrase reference <relative_url>`__
>
> 2. `phrase reference`->relative_url
>
> 3. `phrase reference`@relative_url
>
> 4. `phrase reference`__ @relative_url
>
> 5. `phrase reference`_@_relative_url
>
> 6. `phrase reference`__ ->relative_url
>
> 7. `phrase reference`__ __<relative_url>
>
> To me, syntax #1 is even more strongly in front with relative URLs.

I agree. And I think that looking only at absolute URLs gives a false
feeling of what is easily parsed (by human and/or computer). So I
appreciate your reminder that relative URLs need to be covered, too.

> CALL FOR OPINIONS: Please take a look at the implementation notes
> (http://docutils.sf.net/spec/notes.html#inline-external-targets) and
> tell us what you think.  The alternatives are: implement this as a
> general feature; require a global/pragma directive to enable it;
> require a local directive; or don't implement it at all.

My preference is for syntax #1 above. The only other one I find
readable is #2, but doesn't that count as "infix syntax", and hence
score badly, as mentioned in the implementation notes?

I've not got a very strong opinion on implementation - I have a vague
gut feeling that it should be either a general feature or not there at
all - it doesn't "feel like" a directive to me.

One other point. I think I lost track of the issue here. I *think*
that the need for inline targets is self-evident (David just used one,
above) [#]_. But the way David did it leaves both text and URL in the
processed text. Am I right in thinking that the proposal is purely for
a way of writing the *source* so that text and URL appear together,
whereas the *output* contains only the text, as a link to the target?
If so, my views above still stand, but I think it's a pretty minor
issue. (Then again, I don't think I'd ever use the construct in
practice - I spend most of my time when writing plain text, trying to
find a way of moving URLs *out of line*, so reST already has what I
want).

.. [#] Where he said::
       the implementation notes
       (http://docutils.sf.net/spec/notes.html#inline-external-targets)


> Just thought of a better name for this beast: "embedded targets".

How about simply "embedded links"?

Paul.

-- 
This signature intentionally left blank


From b.fallenstein@gmx.de  Thu Nov 14 03:45:46 2002
From: b.fallenstein@gmx.de (Benja Fallenstein)
Date: Thu, 14 Nov 2002 04:45:46 +0100
Subject: [Doc-SIG] In-line hyperlink alternatives
Message-ID: <3DD31C6A.7010809@gmx.de>

Hi,

I'm new to this list but read the recent discussion about embedded 
hyperlinks in the archives. I find this issue quite important for 
plain-text readability: While for long URIs, putting them after a 
paragraph is good, for short URIs, it seems quite unnatural. (Short URIs 
include references to the root of a web site as well as most relative 
URIs-- both common cases for hyperlinks.) To give an example [see 
example.html], I often refer to web sites like this 
[http://example.com/]. Giving the example__ like this__ seems much less 
natural, and actually sometimes makes me not put in hyperlinks where I 
would normally put them (or if they're absolute, put them in like above, 
which reST renders by showing the URI).

__ example.html
__ http://example.com/

Of course, things like this_@_http://example.com would not help me with 
my problem in the least ;-)

The 'most obvious' syntax extension to reST would, for me, be having the 
URI-in-square-brackets trap the last word, or last `backquoted phrase`, 
like the underscore put right after the word/phrase does. Obviously this 
doesn't work, since reST already interprets these differently. I have 
come up with an only slightly different possible syntax that doesn't 
seem to have been discussed before.

The first goes like this:

    This is an example [-> http://www.example.com] of
    `embedded links` [-> http://www.example.com/links/].

I find it especially comfortable with relative URIs:

    To learn more about Foo [-> foo.html], go to the `class documentation`
    [-> class-foo.html]. Or go back to the index [-> ../index.html].

I really like the plain-text readability of this syntax. It does not use 
the underscores that usually indicate links within reST and is therefore 
inconsistent; I don't see this as a major problem, because I find the 
syntax quite indicative of its meaning, but if this is seen as a 
problem, another possibility is:

    This is an example [__ http://www.example.com].

However, I find that less readable.

Both syntaxes share the problem that the markup that makes a word/a 
backquoted phrase into a hyperlink is not directly connected to the 
word/phrase itself. However, they are still unambiguous, and especially 
the first jumps clearly out to my eye. My personal feeling is that some 
conceptional purity should be sacrificed for plain-text readability here.

Thanks for listening!
- Benja



From drifty@bigfoot.com  Thu Nov 14 21:57:35 2002
From: drifty@bigfoot.com (Brett Cannon)
Date: Thu, 14 Nov 2002 13:57:35 -0800 (PST)
Subject: [Doc-SIG] In-line hyperlink alternatives
In-Reply-To: <3DD31C6A.7010809@gmx.de>
Message-ID: <Pine.SOL.4.44.0211141356150.9191-100000@death.OCF.Berkeley.EDU>

[Benja Fallenstein]

>     `embedded links` [-> http://www.example.com/links/].
>

I find this very readable, although his point that it breaks the __
hyperlink connection is true.

>     This is an example [__ http://www.example.com].
> However, I find that less readable.
>

This works for me, too.

-Brett



From goodmansond@yahoo.com  Thu Nov 14 22:51:21 2002
From: goodmansond@yahoo.com (Dean Goodmanson)
Date: Thu, 14 Nov 2002 14:51:21 -0800 (PST)
Subject: [Doc-SIG] In-line hyperlink alternatives
In-Reply-To: <Pine.SOL.4.44.0211141356150.9191-100000@death.OCF.Berkeley.EDU>
Message-ID: <20021114225121.95769.qmail@web21109.mail.yahoo.com>

Thanks for giving this so much attention.

Notating hyper-links is a feature that will get a lot
of use in venue's outside pure documentation: Message
boards, Wiki's, etc.  Replacing the simplicity of
"text":http://link isn't an easy job, especially
trying to overcome it's faults. 

- Dean


--- Brett Cannon <bac@OCF.Berkeley.EDU> wrote:
> [Benja Fallenstein]
> 
> >     `embedded links` [->
> http://www.example.com/links/].
> >
> 
> I find this very readable, although his point that
> it breaks the __
> hyperlink connection is true.
> 
> >     This is an example [__
> http://www.example.com].
> > However, I find that less readable.
> >
> 
> This works for me, too.
> 
> -Brett
> 
> 
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG@python.org
> http://mail.python.org/mailman/listinfo/doc-sig


__________________________________________________
Do you Yahoo!?
Yahoo! Web Hosting - Let the expert host your site
http://webhosting.yahoo.com


From b.fallenstein@gmx.de  Thu Nov 14 23:17:35 2002
From: b.fallenstein@gmx.de (Benja Fallenstein)
Date: Fri, 15 Nov 2002 00:17:35 +0100
Subject: [Doc-SIG] In-line hyperlink alternatives
References: <Pine.SOL.4.44.0211141356150.9191-100000@death.OCF.Berkeley.EDU>
Message-ID: <3DD42F0F.9080007@gmx.de>

Brett Cannon wrote:

>[Benja Fallenstein]
>  
>
>>    `embedded links` [-> http://www.example.com/links/].
>>    
>>
>
>I find this very readable, although his point that it breaks the __
>hyperlink connection is true.
>

I've come up with a third variation that doesn't break the _ convention 
as much as the other two:

An `example hyperlink` <http://example.com>_.

Here, everything from the first backquote to the closing angle bracket 
can be seen as being made a hyperlink by the underscore. As long as 
there's only a single underscore, I find this still quite readable in 
plaintext; I read the backquotes as 'link markers' and the angle 
brackets as the specification where the link goes, and I ignore the 
final underscore. :-) (It *is* necessary to distinguish from XML/SGML 
tags.) I find this variation even a little less obstrusive than the 
square bracket one. Depends on the context.


Relative links are nice this way:


The `specification` <spec.html>_ is explicit about this:
no `identifier` <terms/identifier.html>_ may appear outside
the `correct context` <#context>_.

- Benja



From goodger@python.org  Fri Nov 15 05:54:21 2002
From: goodger@python.org (David Goodger)
Date: Fri, 15 Nov 2002 00:54:21 -0500
Subject: [Doc-SIG] in-line hyperlinks
In-Reply-To: <Pine.SOL.4.44.0211081402470.19800-100000@death.OCF.Berkeley.EDU>
Message-ID: <B9F9F63B.2BBD6%goodger@python.org>

Sorry about the delay replying.

[David]
>> But the whole point is that
>> 
>>     The underscore can be thought of as a right-pointing arrow.
>>     The trailing underscores point away from hyperlink references,
>>     and the leading underscores point toward `hyperlink targets`_.

[Brett]
> I don't view the underscores like that (might be my training in
> philosophy and symbolic logic).  I see them more just as visual
> delineators for the reST parser and not as a metaphorical pointer.

Of course they're "visual delineators"; so is *all* syntax.  In the
end, everything is just pixels on a screen or ink on paper.  The point
is that in reStructuredText's terms, the underscores *act* as if
they're right-pointing arrows, pointing away from references and
toward targets.  Example below.  The existing forms of hyperlinks use
underscores in this way, and I don't see any value in adding new
syntax ("->") to do the same conceptual job.  Also, the underscore
syntax (which originated with Setext) was chosen because underscores
are unobtrusive; "->" stands out more.

>> Just thought of a better name for this beast: "embedded targets".
>
> Using "embedded" works for me, but not targets.

This is in terms of the reStructuredText vocabulary, in which a
"hyperlink" is made up of two parts, a "reference" and a "target".
The vocabulary is established, and it's not going to change without a
good strong reason.

Putting them together, we have a reference::

    name_

and a target::

    .. _name: URL

The reference name is what ties the two together.

In any case, I'm going to call it "embedded URI", which is very
specific.

> I vote for general feature or a directive.  Either was I want the
> feature.

I'm going to make it a general feature.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@python.org  Fri Nov 15 05:54:39 2002
From: goodger@python.org (David Goodger)
Date: Fri, 15 Nov 2002 00:54:39 -0500
Subject: [Doc-SIG] In-line hyperlink alternatives
In-Reply-To: <3DD31C6A.7010809@gmx.de>
Message-ID: <B9F9F64E.2BBD7%goodger@python.org>

Benja Fallenstein wrote:
> I'm new to this list but read the recent discussion about embedded
> hyperlinks in the archives. I find this issue quite important for
> plain-text readability: While for long URIs, putting them after a
> paragraph is good, for short URIs, it seems quite unnatural. (Short
> URIs include references to the root of a web site as well as most
> relative URIs-- both common cases for hyperlinks.) To give an
> example [see example.html], I often refer to web sites like this
> [http://example.com/]. Giving the example__ like this__ seems much
> less natural, and actually sometimes makes me not put in hyperlinks
> where I would normally put them (or if they're absolute, put them in
> like above, which reST renders by showing the URI).
> 
> __ example.html
> __ http://example.com/

Well put.
 
> The 'most obvious' syntax extension to reST would, for me, be having
> the URI-in-square-brackets trap the last word, or last `backquoted
> phrase`, like the underscore put right after the word/phrase
> does. Obviously this doesn't work, since reST already interprets
> these differently. I have come up with an only slightly different
> possible syntax that doesn't seem to have been discussed before.
> 
> The first goes like this:
> 
>     This is an example [-> http://www.example.com] of
>     `embedded links` [-> http://www.example.com/links/].

There are several problems with this syntax.  First, there's no
indication that the word "example" is a reference until we see the
target (as you mention further on).  The "reference" role magically
jumps back from the target to the word.  Second, there's already a
meaning associated with plain-backquoted words & phrases (no
underscores): interpreted text.  (I know it doesn't actually do
anything yet; consider it reserved syntax.)  The proposed syntax would
require back-tracking in the parser, which I have no desire to
implement.

Adding trailing underscores solves both problems, resulting in::

    This is an example__ [-> http://www.example.com] of
    `embedded links`__ [-> http://www.example.com/links/].

> I really like the plain-text readability of this syntax.

I agree, it *is* quite obvious at first glance what's going on.  But
the syntax is quite noisy and doesn't fit well with the rest of
reStructuredText.  A debatable point.  Read on for a showstopper.

> It does not use the underscores that usually indicate links within
> reST and is therefore inconsistent; I don't see this as a major
> problem, because I find the syntax quite indicative of its meaning,
> but if this is seen as a problem, another possibility is:
> 
>     This is an example [__ http://www.example.com].

Same problem with back-tracking.  The underscores are not in a useful
place.

Unfortunately, there's a final, showstopper problem with this syntax:
RFC 2732 ("Format for IPv6 Literal Addresses in URL's") adds the "["
and "]" characters to the set of possible URI characters.  This means
we can't surround URIs with "[]" with the current parser, which is
intentionally limited in its inline markup parsing ability (uses
regexps).  Here's an example::

    http://[3ffe:2a00:100:7031::1]/

In fact, because IPv6 literal addresses end with "]", the parser
specifically allows a "]" at the end of a URI.  So if you put
[http://example.com] in your text, the final bracket would mistakenly
be included in the URI.  I think that it's fair to say that a
bracketed URI is much more likely than a standalone IPv6 URI, so I
fixed the regexp to favor the former.

> Both syntaxes share the problem that the markup that makes a word/a
> backquoted phrase into a hyperlink is not directly connected to the
> word/phrase itself. However, they are still unambiguous, and
> especially the first jumps clearly out to my eye.

Unfortunately not unambiguous.  The human eye/brain combination is
much more flexible and forgiving of exceptions than program code and
IETF specs ;)

[in a follow-up:]
> I've come up with a third variation that doesn't break the _
> convention as much as the other two:
>
> An `example hyperlink` <http://example.com>_.

>From there it's a *very* short step back to::

    An `example hyperlink <http://example.com>`_.

One underscore means "named", two means "anonymous", same as in the
rest of the cases.

> Thanks for listening!

Thanks for writing.  While the proposed syntax variations didn't win
me over, your initial rationale has provided the final nudge to
convince me that such a construct is a worthwhile addition to
reStructuredText.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From Paul.Moore@atosorigin.com  Fri Nov 15 09:45:12 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Fri, 15 Nov 2002 09:45:12 -0000
Subject: [Doc-SIG] In-line hyperlink alternatives
Message-ID: <16E1010E4581B049ABC51D4975CEDB885E2DD1@UKDCX001.uk.int.atosorigin.com>

From: Benja Fallenstein [mailto:b.fallenstein@gmx.de]
> I've come up with a third variation that doesn't break the _
> convention as much as the other two:
>
> An `example hyperlink` <http://example.com>_.
[...]
> Relative links are nice this way:
>
>
> The `specification` <spec.html>_ is explicit about this:
> no `identifier` <terms/identifier.html>_ may appear outside
> the `correct context` <#context>_.

I like this one! I'll leave implementation and consistency
issues to David, but otherwise I'd say go for this.

Paul.


From b.fallenstein@gmx.de  Fri Nov 15 17:15:57 2002
From: b.fallenstein@gmx.de (Benja Fallenstein)
Date: Fri, 15 Nov 2002 18:15:57 +0100
Subject: [Doc-SIG] In-line hyperlink alternatives
References: <B9F9F64E.2BBD7%goodger@python.org>
Message-ID: <3DD52BCD.1050402@gmx.de>

Hi David!

David Goodger wrote:

>Unfortunately, there's a final, showstopper problem with this syntax:
>RFC 2732 ("Format for IPv6 Literal Addresses in URL's") adds the "["
>and "]" characters to the set of possible URI characters.  This means
>we can't surround URIs with "[]" with the current parser, which is
>intentionally limited in its inline markup parsing ability (uses
>regexps).  Here's an example::
>
>    http://[3ffe:2a00:100:7031::1]/
>

Wow. Oops. Ok, point well taken; I've always missed that update to RFC 
2396, so far, and have assumed that [] are still reserved URI chars.

>[in a follow-up:]
>  
>
>>I've come up with a third variation that doesn't break the _
>>convention as much as the other two:
>>
>>An `example hyperlink` <http://example.com>_.
>>    
>>
>
>From there it's a *very* short step back to::
>
>    An `example hyperlink <http://example.com>`_.
>
>One underscore means "named", two means "anonymous", same as in the
>rest of the cases.
>

Well, yes, it can be argued that it is just one backquote moving a 
little forwards. Ultimately, this is a question of taste, but I still 
find that the first version is quite a bit more readable; there, I'm 
able to parse the backquotes as a marker for the extent of the link (as 
in `example hyperlink`_), and the angle bracketed text as an annotation 
to the link-- my interpretation of the syntax is, `example hyperlink`_ 
with an intersparsed annotation that gives the URI inline. With `example 
hyperlink <http://example.com>`_, on the other hand, I find it harder to 
ignore the URI when reading: my eyes search for the corresponding 
closing marker to the first backquote, which in the context of reST I 
interpret as an opening marker (like an opening bracket). What happens 
is that the URI jumps into the foreground (because it's immediately 
before the closing backquotes my eyes are searching for) and doesn't any 
more look like the annotation I'm used to from plain text.

Now, I can understand that you don't want to implement backtracking in 
the parser for this, but I don't actually see why that's necessary (then 
again, I'm still trying to grasp how the parser works, so if I'm 
misinterpreting here, I'd be glad for being corrected). As far as I can 
see, in ``parsers/rst/states.py``, you already distinguish between 
inline literals and single-backquoted text; then at a latter point I 
think you further distinguish between single-backquoted phrase refs 
(underscore at end) and single-backquoted domain-specific text (no 
underscore at end).

How about simply introducing another case, inline hyperlinks? The 
opening marker would be a single backquote (i.e., a backquote not 
preceded or followed by another backquote, as currently). The closing 
marker would be identified by the following regular expression::

r'`\s*<' + uri + r'>_'

(Can be improved by allowing for a second underscore at the end and 
checking that whitespace or punctuation follows.) Possibly we'd have to 
do a little more parsing to get the URI out of the angle brackets, but 
that won't be hard. -- Ok, maybe this isn't extremely beautiful, but 
from what I understand now it could work without implementing backtracking.

Again, it's a matter of taste to decide whether this is worth the 
effort; because of the reasons above, in my humble opinion, it is ;-)

- Benja





From pobrien@orbtech.com  Sat Nov 16 01:35:29 2002
From: pobrien@orbtech.com (Patrick K. O'Brien)
Date: Fri, 15 Nov 2002 19:35:29 -0600
Subject: [Doc-SIG] Re: [Python-Dev] [maintenance doc updates]
In-Reply-To: <20021116005959.2E61D18EC39@grendel.zope.com>
References: <20021116005959.2E61D18EC39@grendel.zope.com>
Message-ID: <200211151935.29103.pobrien@orbtech.com>

On Friday 15 November 2002 06:59 pm, Fred L. Drake wrote:
> The maintenance version of the documentation has been updated:
>
>     http://www.python.org/dev/doc/maint22/
>
> Small updates.
> Add embarrassing note about sneaky feeping creaturism:
> The "chars" argument to str.strip(), .lstrip(), and .rstrip(), as
> well as the str.zfill() method, were all added in Python 2.2.2!
> Woe to over-eager backporters!

The string module docstrings for lstrip and rstrip need updating as well 
then. It looks like only strip has been updated so far. And it would be 
good if this argument was called the same thing in the string type as 
in the string module. The one calls it `sep` and the other `chars`. In 
fact, the docstring for string.strip mixes the two:

def strip(s, chars=None):
    """strip(s [,chars]) -> string

    Return a copy of the string s with leading and trailing
    whitespace removed.
    If chars is given and not None, remove characters in sep instead.
    If chars is unicode, S will be converted to unicode before 
stripping.

    """
    return s.strip(chars)

The docstring for the type still calls it `sep`, as does lstrip and 
rstrip:

PyDoc_STRVAR(strip__doc__,
"S.strip([sep]) -> string or unicode\n\
\n\
Return a copy of the string S with leading and trailing\n\
whitespace removed.\n\
If sep is given and not None, remove characters in sep instead.\n\
If sep is unicode, S will be converted to unicode before stripping");

It looks like the documentation is consistent in calling it `chars`, but 
the implementation is lagging behind.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------



From goodger@python.org  Sat Nov 16 02:44:35 2002
From: goodger@python.org (David Goodger)
Date: Fri, 15 Nov 2002 21:44:35 -0500
Subject: [Doc-SIG] In-line hyperlink alternatives
In-Reply-To: <3DD52BCD.1050402@gmx.de>
Message-ID: <B9FB1B42.2BDA2%goodger@python.org>

[Benja]
>>> I've come up with a third variation that doesn't break the _
>>> convention as much as the other two:
>>>
>>> An `example hyperlink` <http://example.com>_.

[David]
>> From there it's a *very* short step back to::
>>
>>    An `example hyperlink <http://example.com>`_.

[Benja]
> Well, yes, it can be argued that it is just one backquote moving a
> little forwards. Ultimately, this is a question of taste,

No, it's not just taste.  The `text in single backquotes` syntax is
already used for the interpreted text construct.  That's not going to
be compromised.

> but I still find that the first version is quite a bit more readable

I can understand that, and sympathize.  But the realities of the
markup means that "`this <url>`_" is feasible, whereas "`this` <url>_"
isn't.  The latter would complicate the code and the markup model more
than the feature is worth.

> With `example hyperlink <http://example.com>`_, on the other hand, I
> find it harder to ignore the URI when reading

Putting it bluntly: so what?  It's irrelevant.  From the recently
revised spec:

    .. Caution::
    
       This construct offers easy authoring and maintenance of
       hyperlinks at the expense of general readability.  Inline URIs,
       especially long ones, inevitably interrupt the natural flow of
       text.  For documents meant to be read in source form, the use
       of independent block-level `hyperlink targets`_ is **strongly**
       recommended.  The embedded URI construct is most suited to
       documents intended *only* to be read in processed form.

> How about simply introducing another case, inline hyperlinks? The
> opening marker would be a single backquote (i.e., a backquote not
> preceded or followed by another backquote, as currently). The closing
> marker would be identified by the following regular expression::
> 
> r'`\s*<' + uri + r'>_'

That's just an end-run around the fact that "`this` <url>_" is two
separate things, and the first has an independent meaning.  Such an
overloading would be a huge wart.  How could I possibly explain it?

> Ok, maybe this isn't extremely beautiful, but from what I understand
> now it could work without implementing backtracking.

The backtracking issue is minor compared to the interpreted text
issue, which is a show-stopper.

The construct has been implemented, and "`this <url>`_" is the syntax.
Be glad that it's been implemented at all!  It's an ugly convenience
though.  The ugliness was enough to delay implementation for 5 months,
and almost enough to prevent implementation altogether.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From goodger@python.org  Sat Nov 16 02:56:06 2002
From: goodger@python.org (David Goodger)
Date: Fri, 15 Nov 2002 21:56:06 -0500
Subject: [Doc-SIG] Update to Docutils
Message-ID: <B9FB1DF5.2BDA6%goodger@python.org>

As always, the latest CVS snapshot can be had from

    http://docutils.sf.net/docutils-snapshot.tgz

Embedded URIs in Hyperlink References
=====================================

Back in June, Simon Budig proposed a new syntax for reStructuredText
hyperlinks, to allow target URIs/URLs to be specified inline with the
reference in the text.  I was initially ambivalent/against the
proposal (a similar mechanism was one of the flaws I found in my
analysis of StructuredText!).  One of the core values of
reStructuredText is its readability, and although the proposed syntax
offers convenience, I wasn't sure if the convenience was worth the
cost.

After a great deal of thought and much input from users, I've decided
that there are reasonable use cases for such a construct, and we've
settled on a reasonable syntax.  The following syntax will be used::

    See the `Python home page <http://www.python.org>`_ for info.

This is exactly equivalent to::

    See the `Python home page`_ for info.

    .. _Python home page: http://www.python.org

As with the non-embedded reference forms, a single trailing underscore
means "named", and you can use the same name to reference the same
target URI again.  Two trailing underscores means "anonymous"; the
target URI cannot be referenced again.

Full details can be found in the spec:

  http://docutils.sf.net/spec/rst/reStructuredText.html#embedded-uris

Details of the issues considered and alternatives weighed can be found
here:

  http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets


Recognition of Schemeless Email Addresses in Targets
====================================================

The parser has always recognized bare standalone email addresses in
text, like "Send email to jdoe@example.com", automatically prefixing a
"mailto:" URI scheme.  I noticed some cases of schemeless email
addresses in explicit targets, like this::

    .. _mail me: me@example.org

Such targets were *not* getting a "mailto:" scheme prefix, resulting
in bad hyperlinks.  That's been fixed now, in explicit targets and in
the new embedded URIs.


French & Slovak Language Support
================================

New language modules have been contributed to Docutils: Slovak from
Miroslav Vasko, and French from Stefane Fermigier.  Already supported
are German, Swedish, and English.

New language modules are always welcome.  They're easy to make;
they're just translations of a couple dozen terms.  See the newly
expanded "Docutils Internationalization" for instructions:

    http://docutils.sf.net/spec/howto/i18n.html

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From b.fallenstein@gmx.de  Sat Nov 16 03:33:10 2002
From: b.fallenstein@gmx.de (Benja Fallenstein)
Date: Sat, 16 Nov 2002 04:33:10 +0100
Subject: [Doc-SIG] In-line hyperlink alternatives
References: <B9FB1B42.2BDA2%goodger@python.org>
Message-ID: <3DD5BC76.9060502@gmx.de>

David Goodger wrote:

>The construct has been implemented, and "`this <url>`_" is the syntax.
>Be glad that it's been implemented at all!  It's an ugly convenience
>though.  The ugliness was enough to delay implementation for 5 months,
>and almost enough to prevent implementation altogether.
>  
>

It is implemented? Ok, I am glad. :-)

I accept your decision, of course, but I'll reply to your other points 
below, anyway, because I do not agree with your reasoning: I believe 
that my proposed construct does not conflict with interpreted text (I 
would not have proposed it otherwise). It can still be seen as ugly, and 
if you choose to reject it, I don't argue-- the point of this post (as 
well as the last) is just to get the facts straight.

>[Benja]
>  
>
>>Well, yes, it can be argued that it is just one backquote moving a
>>little forwards. Ultimately, this is a question of taste,
>>    
>>
>
>No, it's not just taste.  The `text in single backquotes` syntax is
>already used for the interpreted text construct.  That's not going to
>be compromised.
>

In my mind, `example` <example.html>_ is a single construct, just as 
`example`_ is; it is as well distinguished from `example` as `example`_ 
is. This is true to the human eye (which recognizes the angle brackets 
and URI), to the parser (which distinguishes the two constructs by the 
regexps), and to the syntax (which defines backquoted text to be a link 
if followed by a underscore, *with an optional 
whitespace-angle-url-angle construct in between*, and as interpreted 
text otherwise). In other words, on all three levels, the difference 
between the three constructs is clear; but while the inner logic in the 
syntax is that the underscore is the signifier, and the angle-bracketed 
URI is inserted between the phrase and the underscore, the eye uses the 
URI as the signifier that the quoted text is a link. (It's quite hard to 
come up with an example where the author didn't put an underscore 
because they intend the interpreted text + angle-bracketed text 
interpretation, while a reader could reasonably assume that a link is 
meant; thus, I don't see this as a problem.)

The ugly thing is that this allows whitespace inside a construct, of 
course. This is what I see as the main tradeoff here: More readability 
vs. no whitespace in constructs.

>>but I still find that the first version is quite a bit more readable
>>    
>>
>
>I can understand that, and sympathize.  But the realities of the
>markup means that "`this <url>`_" is feasible, whereas "`this` <url>_"
>isn't.  The latter would complicate the code and the markup model more
>than the feature is worth.
>

Hm, looking at the parser, I think it should be possible to reduce the 
code complication to some additional regexp trickery. I can give it a 
try if states.py's complexity is what you're worried about.

OTOH, about the complication in the markup model (whitespace in 
constructs) there is no arguing.

>>With `example hyperlink <http://example.com>`_, on the other hand, I
>>find it harder to ignore the URI when reading
>>    
>>
>
>Putting it bluntly: so what?  It's irrelevant.  From the recently
>revised spec:
>
>    .. Caution::
>    
>       This construct offers easy authoring and maintenance of
>       hyperlinks at the expense of general readability.  Inline URIs,
>       especially long ones, inevitably interrupt the natural flow of
>       text.  For documents meant to be read in source form, the use
>       of independent block-level `hyperlink targets`_ is **strongly**
>       recommended.  The embedded URI construct is most suited to
>       documents intended *only* to be read in processed form.
>

Now this I don't agree with at all. As I said in my first post, I'm not 
interested in long inline URIs (the current mechanism handles longer 
URIs better), but I find short inline URIs very common in plain text. I 
use them all the time, absolute URIs for references to web sites in 
e-mails (though I don't include the http:// there) and relative URIs for 
references to other files in documentation. In plain text, I put the 
URI/file name right next to the reference, so that readers can see what 
I'm talking about, to go to that site/file or maybe copy&paste it into a 
browser. In HTML, I want a clickable link made out of that.

I don't mind if you use block-level constructs even for really short 
URIs, but I don't agree at all that short URIs interrupt the natural 
flow-- au contraire. (Wouldn't be discussing this otherwise :-) )

>>How about simply introducing another case, inline hyperlinks? The
>>opening marker would be a single backquote (i.e., a backquote not
>>preceded or followed by another backquote, as currently). The closing
>>marker would be identified by the following regular expression::
>>
>>r'`\s*<' + uri + r'>_'
>>    
>>
>
>That's just an end-run around the fact that "`this` <url>_" is two
>separate things, and the first has an independent meaning.  Such an
>overloading would be a huge wart.  How could I possibly explain it?
>

Hm, I guess I've explained my take on that above (ask if it's still 
unclear). That's what you get when you quote e-mail out of order :-)

Just to reiterate: I accept your decision, I just want to be sure that 
you understand my proposal the way I meant it and base the decision on that.

- Benja



From goodger@python.org  Sat Nov 16 05:42:02 2002
From: goodger@python.org (David Goodger)
Date: Sat, 16 Nov 2002 00:42:02 -0500
Subject: [Doc-SIG] In-line hyperlink alternatives
In-Reply-To: <3DD5BC76.9060502@gmx.de>
Message-ID: <B9FB44D8.2BDB6%goodger@python.org>

Benja Fallenstein wrote:
> In my mind, `example` <example.html>_ is a single construct, just as
> `example`_ is; it is as well distinguished from `example` as `example`_
> is. This is true to the human eye

Not to my eye, not to my mind.  The underscore has to be *immediately*
adjacent to the backquote to provide an alternate meaning.  After the URL is
just too far away: action from a distance.

To me, the `reftext <url>`_ construct says "a reference with text 'reftext'
(and oh, by the way, it's a reference directly to this URL)".  The angle
brackets serve to parenthesize the URL within the reference, and "`...`_"
encloses the whole.

> (It's quite hard to
> come up with an example where the author didn't put an underscore
> because they intend the interpreted text + angle-bracketed text
> interpretation, while a reader could reasonably assume that a link is
> meant; thus, I don't see this as a problem.)

Not so hard.  For this example, assume the default role of interpreted text
is to indicate index entries:

    The `HTML element` <a> is used for hyperlinks.

> The ugly thing is that this allows whitespace inside a construct, of
> course. This is what I see as the main tradeoff here: More readability
> vs. no whitespace in constructs.

It's not just whitespace; it's one thing vs. two, and the first thing isn't
what it normally is because of the end of the second thing.

> Hm, looking at the parser, I think it should be possible to reduce the
> code complication to some additional regexp trickery. I can give it a
> try if states.py's complexity is what you're worried about.

I'm not worried about the code.  Much more important is the conceptual
complication to the markup model.

> I don't mind if you use block-level constructs even for really short
> URIs, but I don't agree at all that short URIs interrupt the natural
> flow-- au contraire. (Wouldn't be discussing this otherwise :-) )

We agree to disagree :)

> Just to reiterate: I accept your decision, I just want to be sure that
> you understand my proposal the way I meant it and base the decision on that.

I understand it, and I thank you for your input, but it's just one data
point in a series.  I've been sitting on this proposal for 5 months, giving
it *lots* of thought.  Many people have chimed in, and I'm tired of the
debate.  My job is to make the best decision for the project as a whole, and
I believe that has been done.  Let's move on.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



From bac@OCF.Berkeley.EDU  Sat Nov 16 08:30:47 2002
From: bac@OCF.Berkeley.EDU (Brett Cannon)
Date: Sat, 16 Nov 2002 00:30:47 -0800 (PST)
Subject: [Doc-SIG] Update to Docutils
In-Reply-To: <B9FB1DF5.2BDA6%goodger@python.org>
Message-ID: <Pine.SOL.4.44.0211160028100.3996-100000@death.OCF.Berkeley.EDU>

[David Goodger]

> After a great deal of thought and much input from users, I've decided
> that there are reasonable use cases for such a construct, and we've
> settled on a reasonable syntax.  The following syntax will be used::
>
>     See the `Python home page <http://www.python.org>`_ for info.
>

And it is already being used in the python-dev Summary!  I just sent the
rough draft to python-dev@python.org .  If anyone is curious to see the
notation in action the rough draft should be in the Maiilman archives
shortly.  Otherwise you can wait until I get the summary up and online
since I am planning on putting the original text versions up on python.org
along with the HTML version in hopes of getting more people into using
reST.

-Brett



From b.fallenstein@gmx.de  Sat Nov 16 13:17:03 2002
From: b.fallenstein@gmx.de (Benja Fallenstein)
Date: Sat, 16 Nov 2002 14:17:03 +0100
Subject: [Doc-SIG] In-line hyperlink alternatives
References: <B9FB44D8.2BDB6%goodger@python.org>
Message-ID: <3DD6454F.1040104@gmx.de>

David--

David Goodger wrote:

>Benja Fallenstein wrote:
>  
>
>>Just to reiterate: I accept your decision, I just want to be sure that
>>you understand my proposal the way I meant it and base the decision on that.
>>    
>>
>
>I understand it, and I thank you for your input, but it's just one data
>point in a series.  
>

Of course.

>I've been sitting on this proposal for 5 months, giving
>it *lots* of thought.  Many people have chimed in, and I'm tired of the
>debate.  My job is to make the best decision for the project as a whole, and
>I believe that has been done.  Let's move on.
>  
>

Ok. Thanks for listening, and thanks for developing ReST!

- Benja