Docutils: Documentation Utilities

[Mike Orr]
> Hello everyone; this is my new address.  I'm trying to make a
> bibliographic page with externally-accesible targets each entry; i.e.,
>  <a name=3D"foo"></a>, which is accessible as document.html#foo .  I'm
> trying the Hyperlink Targets in the spec with no success.  I'm using
> the docutils snapshot downloaded today.

What you want is this:

"""
=2E. _foo:

Stuff about foo.
"""

> .. _foo: foo2
>=20
> Does not appear in the output at all.

Here "foo" is referring to the URL "foo2".

> .. _foo: Stuff about foo.
>=20
> Same thing.

Another URL (whitespace is removed).

> .. _foo:
>=20
>     Stuff about foo.
>=20
> Appears as:
>=20
> <blockquote id=3D"foo">
> Stuff about foo.</blockquote>

As it should.  ".. _foo:" is a target marker, which attaches to the next
element in the document.

> .. __foo: foo2
>=20
> Does not appear, although in an earlier version of docutils it caused
> a target without reference error.

Hmmm, it should still.  Potential regression.

> =3D=3D=3D
> __ foo
>=20
> Appears as a literal   <p>foo</p>.

The literal block should have been inside a system message, something
like "Anonymous hyperlink mismatch: 0 references but 1 targets".
I see the system message, but not the literal block.  Another potential
regression.

******

Mike, do you normally learn by trial-and-error?  There *is* extensive
documentation, at all levels from quickref to spec.  ;-)

--=20
David Goodger <http://python.net/~goodger>

On 1/21/06, David Goodger <goodger@...> wrote:
> Mike, do you normally learn by trial-and-error?  There *is* extensive
> documentation, at all levels from quickref to spec.  ;-)

Yes, but I find the docutils docs perennially confusing.  I keep
finding situations the docs don't seem to cover.  The spec and
directives generally answer my questions best so I usually refer to
those.  The main problem is, the docs explain the directives but not
how they interact.  I wrote before about literal blocks (::)
interspersed with text inside list items, which sometimes I can get to
work but sometimes the literal overextends and I have to insert a
comment or move text around to get a better interaction.  I'd have to
look at my past documents to see if the problem mainly happened when
the literal was first or last in the list item, or when there was a
lone text line after it.

Putting a blockquote after directives is also difficult.  My current
project has an index document with:

=3D=3D=3D
title
%%%
:date: bla bla
:Author: bla bla

.. container:: menu
    `chapter1 <chapter1.html>`__ |
    `chapter2 <chapter2.html>`__

..
    unused menu links...

Disclaimer paragraph as ordinary text.

    "Cool proverb in a blockquote."  *--Citation*

Main text.
=3D=3D=3D

I'm sure I could do more with the TOC feature and multi-file document
features, but this is the level I'm at.  It formats fine as is.  But
when I decided to move the menu/comment/disclaimer to the bottom of
the document, I got 'index.txt:4: (WARNING/2) Cannot extract compound
bibliographic field "Author".'  It thinks the blockquote is part of
the author value, even with blank lines in between.    If I put a
comment in between, it thinks the blockquote is part of the comment.=20
The disclaimer is temporary, so when it goes away the problem will be
more acute.

Besides the interaction issues, I guess what I mainly miss is an
HTML-to-ReST howto.  Hmm, maybe I'll have to write one of those.  I
know how to do what I want in HTML, but sometimes I have to spend
quite a while perusing the docs and doing trial-and-error to figure
out the equivalent ReST syntax.

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

[Mike Orr]
> On 1/21/06, David Goodger <goodger@...> wrote:
>> Mike, do you normally learn by trial-and-error?  There *is*
>> extensive documentation, at all levels from quickref to spec.  ;-)
>
> Yes, but I find the docutils docs perennially confusing.  I keep
> finding situations the docs don't seem to cover.  The spec and
> directives generally answer my questions best so I usually refer to
> those.  The main problem is, the docs explain the directives but not
> how they interact.

They don't.  What you're talking about is indentation interaction.
And it's fully covered in the docs:

    Simple directives may not require any content.  If a directive
    that does not employ a content block is followed by indented text
    anyway, it is an error.  If a block quote should immediately
    follow a directive, use an empty comment in-between (see Comments_
    below).

    -- http://docutils.sf.net/docs/ref/rst/restructuredtext.html#directiv=
es

Also see
http://docutils.sf.net/docs/ref/rst/restructuredtext.html#comments
The info is there at least twice.  I don't know where else to put it!

> I wrote before about literal blocks (::) interspersed with text
> inside list items, which sometimes I can get to work but sometimes
> the literal overextends and I have to insert a comment or move text
> around to get a better interaction.

I don't recall, but I'd guess that it has to do with indentation.
After "::", all indented content is consumed into the literal block.

> I'd have to look at my past documents to see if the problem mainly
> happened when the literal was first or last in the list item, or
> when there was a lone text line after it.

I'd have to see an example.

> Putting a blockquote after directives is also difficult.  My current
> project has an index document with:
>
> =3D=3D=3D
> title
> %%%
> :date: bla bla
> :Author: bla bla
>
> .. container:: menu
>     `chapter1 <chapter1.html>`__ |
>     `chapter2 <chapter2.html>`__
>
> ..
>     unused menu links...
>
> Disclaimer paragraph as ordinary text.
>
>     "Cool proverb in a blockquote."  *--Citation*
>
> Main text.
> =3D=3D=3D
>
> I'm sure I could do more with the TOC feature and multi-file document
> features, but this is the level I'm at.  It formats fine as is.  But
> when I decided to move the menu/comment/disclaimer to the bottom of
> the document, I got 'index.txt:4: (WARNING/2) Cannot extract compound
> bibliographic field "Author".'  It thinks the blockquote is part of
> the author value, even with blank lines in between.

Yes, that's part of the spec.  List items consume all subsequent
indented content.  Basically, anything that expects indented content
will consume *all* subsequent indented content.  If that's not what
you want, use an empty comment::

    Some text::

        # This is a literal block, indented

    ..

        This is a block quote.

    The empty comment (".." by itself on a line, with a blank line
    following) is used to separate indented contexts.

> Besides the interaction issues, I guess what I mainly miss is an
> HTML-to-ReST howto.  Hmm, maybe I'll have to write one of those.

Please do!

> I know how to do what I want in HTML, but sometimes I have to spend
> quite a while perusing the docs and doing trial-and-error to figure
> out the equivalent ReST syntax.

Maybe stop thinking about HTML and start thinking about the document
structure instead?

BTW, did you intend to reply to me privately?  OK to post your reply
to the list?

--=20
David Goodger <http://python.net/~goodger>

[David Goodger]
> BTW, did you intend to reply to me privately?  OK to post your reply
> to the list?

Please disregard; you *did* reply to the list, it just wasn't filed
properly at my end.

--=20
David Goodger <http://python.net/~goodger>

David Goodger wrote:

> Mike Orr wrote:
>
>> .. __foo: foo2
>> 
>> Does not appear, although in an earlier version of docutils it caused
>> a target without reference error.
>
> Hmmm, it should still.

(I just got a little scared because I thought the anomymous target
syntax has broken and wondered how it got through the tests.  :-))

But no, ".. __foo: foo2" is just invalid reST syntax.  An correct
anonymous target would be ".. __: foo2" or "__ foo2".  The parser
recognizes ".. __foo: foo2" as a target with the name "_foo", but it
should probably throw an error.  I added this to BUGS.txt.

>> ===
>> __ foo
>> 
>> Appears as a literal   <p>foo</p>.
>
> The literal block should have been inside a system message, something
> like "Anonymous hyperlink mismatch: 0 references but 1 targets".

No, it shouldn't.  There can be many unused targets ("5 references but
10 targets"), so you can't insert just one of them as a literal block.
And there could also be more references than targets.

The system message just indicates that the *global* target and reference
counts don't match, it doesn't happen at a specific target that could be
inserted as a literal block.

> I see the system message, but not the literal block.

Me too, and that's correct.

> Mike, do you normally learn by trial-and-error?  There *is* extensive
> documentation, at all levels from quickref to spec.  ;-)

The fact that Mike learns by trial-and-error suggests that the
documentation needs improvement.  And I think it does indeed.  The reST
spec could use an overhaul for example.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

On 1/21/06, David Goodger <goodger@...> wrote:
> Basically, anything that expects indented content
> will consume *all* subsequent indented content.  If that's not what
> you want, use an empty comment::
>
>     Some text::
>
>         # This is a literal block, indented
>
>     ..
>
>         This is a block quote.
>
>     The empty comment (".." by itself on a line, with a blank line
>     following) is used to separate indented contexts.

I guess that's what confused me, that the other directives consume
multiple paragraphs but a comment stops at a blank line.

> > Besides the interaction issues, I guess what I mainly miss is an
> > HTML-to-ReST howto.  Hmm, maybe I'll have to write one of those.
>
> Please do!

I'll look into it.  Most of the people I know who use ReST come from
an HTML background.

By the way, the Cheetah docs are switching from a LaTeX/PythonDoc
system to templates with embedded ReST snippets.  So I'll be writing a
lot of ReST documents in the next two months.    There's a new #call
directive to facilitate this.  Assuming you had an rst2html function
called rest():

#call rest
This is a ReST document that will be converted to HTML and inserted
into the template output.  This is also the argument to the rest()
function, and can contain Cheetah $placeholders and new
${True and "expression placeholders" or 999}.
#end call

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

> On 1/21/06, David Goodger <goodger@...> wrote:
>> Basically, anything that expects indented content
>> will consume *all* subsequent indented content.  If that's not what
>> you want, use an empty comment::
>>
>>     Some text::
>>
>>         # This is a literal block, indented
>>
>>     ..
>>
>>         This is a block quote.
>>
>>     The empty comment (".." by itself on a line, with a blank line
>>     following) is used to separate indented contexts.

[Mike Orr]
> I guess that's what confused me, that the other directives consume
> multiple paragraphs but a comment stops at a blank line.

Comments do *not* stop at a blank line; they consume subsequent
indented content the same as anything else:

    .. This is the fist line of a comment.

       And this is part of the comment too.

    But this isn't, because its indentation level is lower.

Empty comments are a special case, expressly allowed to end
indentation contexts.  IOW, if and only if a comment contains no
content on its first line, *and* the following line is blank, it
ends right there and never *starts* consuming any further indented
content.  Viz:

    A normal paragraph.

        A block quote.

    ..

        Another block quote.

The empty comment above serves only to separate two block quotes.

--=20
David Goodger <http://python.net/~goodger>

>> Mike Orr wrote:
>>> .. __foo: foo2
>>>
>>> Does not appear, although in an earlier version of docutils it
>>> caused a target without reference error.

> David Goodger wrote:
>> Hmmm, it should still.

[Felix Wiemann]
> (I just got a little scared because I thought the anomymous target
> syntax has broken and wondered how it got through the tests.  :-))
>
> But no, ".. __foo: foo2" is just invalid reST syntax.  An correct
> anonymous target would be ".. __: foo2" or "__ foo2".  The parser
> recognizes ".. __foo: foo2" as a target with the name "_foo", but it
> should probably throw an error.  I added this to BUGS.txt.

Yes, this should be caught as invalid.  An intentional leading
underscore should be backquoted:

   .. _`_foo`:

However, the point Mike made, and that I concurred with, was that
unused targets used to throw system messages (probably INFO-level).

>>> __ foo
>>>
>>> Appears as a literal   <p>foo</p>.
>>
>> The literal block should have been inside a system message,
>> something like "Anonymous hyperlink mismatch: 0 references but 1
>> targets".
>
> No, it shouldn't.  There can be many unused targets ("5 references
> but 10 targets"), so you can't insert just one of them as a literal
> block.  And there could also be more references than targets.

Right, my mistake.  I wonder why Mike saw a literal block.

>> Mike, do you normally learn by trial-and-error?  There *is*
>> extensive documentation, at all levels from quickref to spec.  ;-)
>
> The fact that Mike learns by trial-and-error suggests that the
> documentation needs improvement.  And I think it does indeed.

Documentation *always* needs improvement.

> The reST spec could use an overhaul for example.

I have to disagree here though.  The spec is just that: a
specification.  It should not be used as a tutorial or intro.  In
fact, it begins with the following:

   This document is a detailed technical specification; it is not a
   tutorial or a primer.  If this is your first exposure to
   reStructuredText, please read `A ReStructuredText Primer`_ and the
   `Quick reStructuredText`_ user reference first.

If we need to expand on one of those, or add another doc, I'm all for
it (but I have no *time* to do it :-( ).  The spec works just fine as
it is, AFAICT.  If you have some specific ideas for improvement,
please spell them out, but don't just criticize without backing up
your statement.

--=20
David Goodger <http://python.net/~goodger>

On 1/21/06, David Goodger <goodger@...> wrote:
> > Besides the interaction issues, I guess what I mainly miss is an
> > HTML-to-ReST howto.  Hmm, maybe I'll have to write one of those.
>
> Please do!


Here's a start.

http://sluggo.kicks-ass.org/python/rest/rest_for_html_users.html

It's public domain like the rest of the docs are.

I saw David's message about empty comments being a special case, and
adjusted the text accordingly.

Actually, the Quick ReStructuredText talks about the blockquote
problem too, in the comments section.  Maybe move it up to the
blockquote section.  Or one could add a ".. blockquote::" directive
for this situation, which is what I would have expected.

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

Hmm, what about hyperlinks in italics?  In this case a book title.

*`SWAT Fitness <links.html#swat>`__*
`*SWAT Fitness* <links.html#swat>`__

Only the outer ones are recognized.  Another interaction?

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

David Goodger wrote:

> However, the point Mike made, and that I concurred with, was that
> unused targets used to throw system messages (probably INFO-level).

They still do:

~ $ rst2pseudoxml.py --report=1
.. __foo: bar
<stdin>:1: (INFO/1) Hyperlink target "_foo" is not referenced.
<document source="<stdin>">
    <target ids="foo" names="_foo" refuri="bar">
    <section classes="system-messages">
        <title>
            Docutils System Messages
        <system_message level="1" line="1" source="<stdin>" type="INFO">
            <paragraph>
                Hyperlink target "_foo" is not referenced.

>>> Mike, do you normally learn by trial-and-error?  There *is*
>>> extensive documentation, at all levels from quickref to spec.  ;-)
>>
>> The fact that Mike learns by trial-and-error suggests that the
>> documentation needs improvement.  And I think it does indeed.
>
> Documentation *always* needs improvement.

Just as code always needs improvement, sure.  :-)

The point is, in this case the improvement should have priority, it
seems to me.

>> The reST spec could use an overhaul for example.
>
> I have to disagree here though.  The spec is just that: a
> specification.  It should not be used as a tutorial or intro.

Yes, but it should be usable as a *reference*, and I think it's overly
wordy for that because it often explains the motivation too detailedly
or gives examples for possible uses of syntax constructs that are not
currently implemented.  Most users aren't interested in such possible
uses because they use the spec as a reference.

> In fact, it begins with the following:
>
>    This document is a detailed technical specification; it is not a
>    tutorial or a primer.  If this is your first exposure to
>    reStructuredText, please read `A ReStructuredText Primer`_ and the
>    `Quick reStructuredText`_ user reference first.

First thought: "I already know reST, so I don't need/want a tutorial or
primer.  I just want to look up a particular piece of syntax."

> If you have some specific ideas for improvement, please spell them
> out, but don't just criticize without backing up your statement.

I do, but I'm not sure if I should implement them offline and
communicate the changes via patches.  It might be more effective if we
improved the documentation using pair-programming at PyCon (I'd compile
a list of specific things I want to see improved/removed before).

-- 
Felix Wiemann -- http://www.ososo.de/

Mike Orr wrote:
[snip..]
>>> Besides the interaction issues, I guess what I mainly miss is an
>>> HTML-to-ReST howto.  Hmm, maybe I'll have to write one of those.
>>>       
>> Please do!
>>     
>
> I'll look into it.  Most of the people I know who use ReST come from
> an HTML background.
>
>   
This by the way is why I think that embedding the stylesheet is the
wrong default option. I think most new users will be more surprised by
this behaviour than the reverse. :-)

Anyway - I'll stop banging on about it now.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

Mike Orr scripsit:
> Hello everyone; this is my new address.  I'm trying to make a
> bibliographic page with externally-accesible targets each entry; i.e.,
> <a name="foo"></a>, which is accessible as document.html#foo .  I'm
> trying the Hyperlink Targets in the spec with no success.  I'm using
> the docutils snapshot downloaded today.

<a name> is so twentieth century ;)
>
>
><blockquote id="foo">
> Stuff about foo.</blockquote>

``id`` is legal #target in HTML. Just make sure each foo is unique.

m.
-- 
LaTeX + Vim = http://vim-latex.sourceforge.net/
Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078
vim.pl - http://skawina.eu.org/mikolaj
CLEWN - http://clewn.sf.net

Mike Orr wrote:

> Hmm, what about hyperlinks in italics?

That's nested inline markup, which is currently not supported,
unfortunately.  You can use substitution, however:

> *`SWAT Fitness <links.html#swat>`__*
> `*SWAT Fitness* <links.html#swat>`__

.. |swat fitness| replace:: *SWAT Fitness*

|swat fitness|__

__ links.html#swat

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

Mikolaj Machowski wrote:

> Mike Orr scripsit:
>
>> <blockquote id="foo">Stuff about foo.</blockquote>
>
> ``id`` is legal #target in HTML. Just make sure each foo is unique.

You don't have to make sure it's unique.  Docutils does it for you.  :-)

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

Felix Wiemann wrote:

> The parser recognizes ".. __foo: foo2" as a target with the name
> "_foo", but it should probably throw an error.

Fixed.  :-)

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

Felix Wiemann scripsit:
> Mikolaj Machowski wrote:
>
>> Mike Orr scripsit:
>>
>>> <blockquote id="foo">Stuff about foo.</blockquote>
>>
>> ``id`` is legal #target in HTML. Just make sure each foo is unique.
>
> You don't have to make sure it's unique.  Docutils does it for you.  :-)
>

Good :)

Just wanted to show this may be good solution for him. Semantical horror
but should work as intended.

m.
-- 
LaTeX + Vim = http://vim-latex.sourceforge.net/
Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078
vim.pl - http://skawina.eu.org/mikolaj
CLEWN - http://clewn.sf.net

On Sun, Jan 22, 2006, Mike Orr wrote:
>
> Hmm, what about hyperlinks in italics?  In this case a book title.
> 
> *`SWAT Fitness <links.html#swat>`__*
> `*SWAT Fitness* <links.html#swat>`__
> 
> Only the outer ones are recognized.  Another interaction?

That's a separate issue:
http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#nested-inline-markup
-- 
Aahz (aahz@...)           <*>         http://www.pythoncraft.com/

"19. A language that doesn't affect the way you think about programming,
is not worth knowing."  --Alan Perlis

On 1/22/06, Felix Wiemann <Felix.Wiemann@...> wrote:
> David Goodger wrote:
> > I have to disagree here though.  The spec is just that: a
> > specification.  It should not be used as a tutorial or intro.
>
> Yes, but it should be usable as a *reference*, and I think it's overly
> wordy for that because it often explains the motivation too detailedly
> or gives examples for possible uses of syntax constructs that are not
> currently implemented.  Most users aren't interested in such possible
> uses because they use the spec as a reference.

I agree with David that the spec is pretty good as is.  It may need
minor revisions but that's not something I can judge.

I go to the spec because the other docs don't have the details I need.
 So it serves as a users' guide as well as a reference.  That may be
outside its target role, but it's currently needed for that.

Most of my problems probably stem from misunderstanding a few key=20
concepts that come up again and again, like the indentation and
directive endings.  I can point those issues out for the docs but
first I have to figure out what they are. :)  Maybe just a few pages
explaing these issues in a different way will make them clearer.

Text parsing is just a complex topic in general.  I would have been
more involved in docutils development over the years but I can't
contribute much to parser code, and I've had kind of a long learning
curve with ReST.  But I like it because it's a standard format (as
opposed to those wikis that all use their own dialect), pretty
intuitive, is more convenient to type than HTML, and has an extraction
API for custom uses.

I'd hesitate to just "add a tutorial" because ReST already has several
manuals that largely overlap, so you have to read all of them to see
which one has what you need.  Specialized tutorials like the HTML one
I'm writing are different, I think, because they target a specific
type of background, and I'm linking every topic to the corresponding
place in the spec so people can read them side by side if they want
more.

The HTML tutorial will probably be done in April.  I have a couple
months of projects to finish before I can get to it.

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

On 1/22/06, Mikolaj Machowski <mikmach@...> wrote:
> Mike Orr scripsit:
> > Hello everyone; this is my new address.  I'm trying to make a
> > bibliographic page with externally-accesible targets each entry; i.e.,
> > <a name=3D"foo"></a>, which is accessible as document.html#foo .  I'm
> > trying the Hyperlink Targets in the spec with no success.  I'm using
> > the docutils snapshot downloaded today.
>
> <a name> is so twentieth century ;)
> >
> >
> ><blockquote id=3D"foo">
> > Stuff about foo.</blockquote>
>
> ``id`` is legal #target in HTML. Just make sure each foo is unique.

Can I set a meaningful ID for an element, or do I have to take
whatever ReST chooses and hope it doesn't change later?  But...

.. _the_name:

is working well now for fragment targets, so I think I'll just stick
with that.  It expands to
<span id=3D"the_name"></span>
which is a bit surprising, but it works.

What tripped me up in the spec was:

.. _hyperlink-name: link-block
.. __: anonymous-hyperlink-target-link-block
_ anonymous-hyperlink-target-link-block

and trying to figure out what "hyperlink-name" and "link-block" meant.
 At least I didn't find them defined near that section, nor did I see
a glossary or grammar anywhere.  After a few tries I found that
hyperlink-name is the #fragment name, but link-block still didn't make
sense.
Looking at it now I can see it's the URL that's inserted wherever
the's a hyperlink-name_ construct, but that's more of a "put a
hyperlink somewhere else" operation rather than "make an anchor
pointing here", so I didn't think about it at the time.

--
Mike Orr <sluggoster@...>
(mso@... address is semi-reliable)

[Mike Orr]
> Here's a start.
>=20
> http://sluggo.kicks-ass.org/python/rest/rest_for_html_users.html

It's a good start.  How about putting it under the Docutils SVN
so others can work on it in the meantime?
Just get a berlios.de account and let me know the name, and I'll
give you write access.

> Actually, the Quick ReStructuredText talks about the blockquote
> problem too, in the comments section.  Maybe move it up to the
> blockquote section.

I have added a cross-reference.

> Or one could add a ".. blockquote::" directive
> for this situation, which is what I would have expected.

Unnecessary, methinks.

--=20
David Goodger <http://python.net/~goodger>

> David Goodger wrote:
>> However, the point Mike made, and that I concurred with, was that
>> unused targets used to throw system messages (probably INFO-level).

[Felix Wiemann]
> They still do:
>
> ~ $ rst2pseudoxml.py --report=3D1
> .. __foo: bar
> <stdin>:1: (INFO/1) Hyperlink target "_foo" is not referenced.
> <document source=3D"<stdin>">
>    <target ids=3D"foo" names=3D"_foo" refuri=3D"bar">
>    <section classes=3D"system-messages">
>        <title>
>            Docutils System Messages
>        <system_message level=3D"1" line=3D"1" source=3D"<stdin>" type=3D=
"INFO">
>            <paragraph>
>                Hyperlink target "_foo" is not referenced.

Right, I forgot about the filtering of system messages.  Thanks.

>>> The reST spec could use an overhaul for example.
>>
>> I have to disagree here though.  The spec is just that: a
>> specification.  It should not be used as a tutorial or intro.
>
> Yes, but it should be usable as a *reference*, and I think it's
> overly wordy for that because it often explains the motivation too
> detailedly or gives examples for possible uses of syntax constructs
> that are not currently implemented.  Most users aren't interested in
> such possible uses because they use the spec as a reference.

I don't want to lose that material; it is useful.  Even if the spec is
used as a reference, that's not its primary purpose -- it's a
*specification*.  There may be need for a separate reference, or
perhaps the spec could use some reorganization (like putting the extra
material in sidebars).  I'd rather judge from specifics though, not
generalities.

>> If you have some specific ideas for improvement, please spell them
>> out, but don't just criticize without backing up your statement.
>
> I do, but I'm not sure if I should implement them offline and
> communicate the changes via patches.  It might be more effective if
> we improved the documentation using pair-programming at PyCon (I'd
> compile a list of specific things I want to see improved/removed
> before).

So keep a list in docs/dev/todo.txt.  Keep development open, and try
not to surprise us with sudden, drastic changes from out of the blue.

--=20
David Goodger <http://python.net/~goodger>

[Mike Orr]
> Can I set a meaningful ID for an element, or do I have to take
> whatever ReST chooses and hope it doesn't change later?  But...
>
> .. _the_name:
>
> is working well now for fragment targets, so I think I'll just stick
> with that.

That's exactly how to do it.

> It expands to
> <span id=3D"the_name"></span>
> which is a bit surprising, but it works.

That's some Netscape-4 compatibility cruft, IIRC, which will probably
be removed before long.

> What tripped me up in the spec was:
>
> .. _hyperlink-name: link-block
> .. __: anonymous-hyperlink-target-link-block
> _ anonymous-hyperlink-target-link-block
>
> and trying to figure out what "hyperlink-name" and "link-block"
> meant.  At least I didn't find them defined near that section, nor
> did I see a glossary or grammar anywhere.

Those terms are explained immediately adjacent to their use (in the
numbered list following).

> After a few tries I found that hyperlink-name is the #fragment name,

In HTML terms, yes, but that's not appropriate for the spec, which
must be independent of output format.

> but link-block still didn't make sense.

That's just a place-holder.  In the syntax:

    .. _hyperlink-name: link-block

"hyperlink-name" is whatever appears in that position (it's just the
name of the hyperlink), and "link-block" is whatever appears in that
position (nothing, for internal hyperlink targets; a URL for external
hyperlink targets; or a hyperlink reference like "reference_" for
indirect hyperlink targets).

> Looking at it now I can see it's the URL that's inserted wherever
> the's a hyperlink-name_ construct, but that's more of a "put a
> hyperlink somewhere else" operation rather than "make an anchor
> pointing here", so I didn't think about it at the time.

I think you're reading the spec with too much HTML baggage, expecting
terms to correspond exactly, which they don't and never will.  Try not
to read meaning into the spec that isn't there.  Perhaps you should be
using the "Quick reStructuredText" document, which teaches by example:
http://docutils.sf.net/docs/user/rst/quickref.html

--=20
David Goodger <http://python.net/~goodger>

David Goodger scripsit:
>> It expands to
>> <span id=3D"the_name"></span>
>> which is a bit surprising, but it works.
>
> That's some Netscape-4 compatibility cruft, IIRC, which will probably
> be removed before long.

What will replace that?

m.
-- 
LaTeX + Vim = http://vim-latex.sourceforge.net/
Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078
vim.pl - http://skawina.eu.org/mikolaj
CLEWN - http://clewn.sf.net

Mikolaj Machowski wrote:
> David Goodger scripsit:
>   
>>> It expands to
>>> <span id=3D"the_name"></span>
>>> which is a bit surprising, but it works.
>>>       
>> That's some Netscape-4 compatibility cruft, IIRC, which will probably
>> be removed before long.
>>     
>
> What will replace that?
>
>   
Probably IE cruft. ;-)

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> m.
>

[Mikolaj Machowski]
> What will replace that?

An id=3D"whatever" attribute on an actual element, maybe.
I don't know for sure; I'm just guessing.

--=20
David Goodger <http://python.net/~goodger>