docutils-users Mailing List for Docutils: Documentation Utilities (Page 326)

To serve as an instructional sample I'm making a very simply Wiki -- I'd
like to use reST as the markup, since it's not an example in parsing
(and I like the reST markup more than most Wiki markups to boot).

So, to do this I need to convert reST to HTML.  I looked around in
buildhtml.py to get an idea, but I found it surprisingly difficult to
figure out just what I would need to do.  This is the (not working) code
I came up with:

        pub = core.Publisher()
        pub.set_reader(reader_name='standalone',
                       parser_name='restructuredtext', parser=None)
        pub.set_writer(writer_name='html')
        pub.source = io.FileIO(None, source_path=sourceFile)
        pub.destination = io.FileIO(
            None, destination_path=destFile)

Could someone perhaps tell me what the easiest way to do this is?  I'm
not sure of the relevance of the options, the importance of FileIO, or
some of the other abstractions involved in this operation.

Also -- is there a good hook in reST that I can use for Wiki links?  The
linking mechanism reST has is fine for internal and external links, but
doesn't fit right for Wiki links (which fall somewhere in between).  If
I could capture failed internal links and turn them into inter-wiki-page
links, that would be perfect.  Failing that, if there was some way I
could introduce another markup easily that would be great.

If there isn't an easy way, I'll probably just look for WikiNames in the
generated HTML, and do the substitution then.  I'll have to do some
dynamic fixup anyway, to distinguish between existent Wiki pages and
to-be-created links.

Thanks,
  Ian

Mark McEahern wrote:
> Forgive me if this is a FAQ.

Well, since up to now there hasn't *been* an official FAQ, you're
forgiven. ;-)

> In StructuredText, you can do:
> 
>   1.  a
> 
>   1.  b
> 
>   1.  c
> 
> and you'll get an ordered list (<ol><li>a</li><li>b</li><li>c</li>).
> The advantage of this approach is that I don't need to manage the
> numbers (e.g., if I move c between a and b, I don't have to
> "renumber" them).
> 
> With reStructuredText, OTOH, the above generates three ordered
> lists:

... omitted ...

> There's probably a good reason for this.  I realize this is part of
> the specification:
> 
> http://docutils.sf.net/spec/rst/reStructuredText.html#enumerated-lists
> 
> Any insight on why the implicit sequence approach is avoided (which
> seems usable at least in isolation) is greatly appreciated.

There's a discussion here:

  http://docutils.sf.net/spec/rst/alternatives.html#auto-enumerated-lists

It's lingering there, awaiting a champion.  I introduced a
colleague to Docutils recently, let him loose, and his first
suggestion was exactly this extension; the evidence is mounting that
this would be a good change.  I'm partial to alternative 2, since it
establishes the enumeration sequence (arabic numerals, letters, etc.),
and reduces the "line noise".

> Perhaps the answer is simply:
> 
>   Explicit is better than implicit.

That's a big part of it!  I put auto-enumerated lists on to the to-do
list (with a "?"), so it won't be forgotten, but it's not my priority
right now.  If you're interested, patches are gratefully accepted!

-- 
David Goodger  <go...@us...>  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/

Mark McEahern wrote:
> If I were to try to express the wherefore of it myself, I'd say, ...

Thanks, Mark, well put.  This was enough to put the FAQ I've slowly
been working on over the top.  See it in all its glory here:

    http://docutils.sf.net/FAQ.html

I invite questions and suggestions for more FAQ entries.

-- 
David Goodger  <go...@us...>  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/

Forgive me if this is a FAQ.

In StructuredText, you can do:

  1.  a

  1.  b

  1.  c

and you'll get an ordered list (<ol><li>a</li><li>b</li><li>c</li>).  The
advantage of this approach is that I don't need to manage the numbers (e.g.,
if I move c between a and b, I don't have to "renumber" them).

With reStructuredText, OTOH, the above generates three ordered lists:

  <ol>
    <li>a</li>
  </ol>
  <ol>
    <li>b</li>
  </ol>
  <ol>
    <li>c</li>
  </ol>

There's probably a good reason for this.  I realize this is part of the
specification:


http://docutils.sourceforge.net/spec/rst/reStructuredText.html#enumerated-li
sts

Any insight on why the implicit sequence approach is avoided (which seems
usable at least in isolation) is greatly appreciated.

Perhaps the answer is simply:

  Explicit is better than implicit.

Thanks,

// mark

-

[David Goodger [mailto:go...@us...]]
> Check the "class" attribute on the "h1" tags, and you will see a
> difference.

It took a while for this to sink in.  I mean, I saw the class="title".  I
know how to use CSS.  But I just didn't get it.  The aha moment came when I
saw Greg Ward's reply.  I think I just needed to know someone else had
struggled with this too.  And then I got over it, just like that.

If I were to try to express the wherefore of it myself, I'd say, "The first
section is special--there's only one of those.  Rather than use a plain H1
for that, we use <H1 class="title"/> so that we can use H1 again within the
document.  The reason we do this?  HTML only has H1-H6, so by making H1 do
double duty, we effectively reserve these tags to provide 6 levels of
heading beyond the single document title."

Cheers,

// mark

-

On 09 October 2002, David Goodger said:
> Mark McEahern wrote:
> > When I run it through tools/html.py, I get unexpected results (below).  I
> > was expecting H1, H2, then H3; instead, I get H1, H1, H2.
> 
> Check the "class" attribute on the "h1" tags, and you will see a difference.
> 
> The first title becomes the document title.  From the markup specification:

For the record, I thought the duelling <h1>s was kind of bogus at first
too.  But then I put default.css in place, and it all made sense.

In fact, I think I like the Docutils way so much -- duplicate the title
as a centred <h1>, with regular <h1>s below it -- that I might just
start using it myself.

        Greg
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org

Mark McEahern wrote:
> When I run it through tools/html.py, I get unexpected results (below).  I
> was expecting H1, H2, then H3; instead, I get H1, H1, H2.

Check the "class" attribute on the "h1" tags, and you will see a difference.

The first title becomes the document title.  From the markup specification:

    Specifically, there is no way to specify a document title and
    subtitle explicitly in reStructuredText.  Instead, a lone
    top-level section title (see Sections_ below) can be treated as
    the document title.  Similarly, a lone second-level section title
    immediately after the "document title" can become the document
    subtitle.  See the `DocTitle transform`_ for details.

    (http://docutils.sf.net/spec/rst/reStructuredText.html#document)

HTML is being used for dumb formatting; it isn't meant for anything but
final display.  A stylesheet *is* required, and you're welcome to roll your
own.  HTML is limited with only H1..H6, so we need to use them sparingly.
The HTML Writer uses H1 for document title and H2 for document subtitle, and
starts over at H1 for section titles.

This will definitely go into the FAQ, being the most frequently asked
question so far.

-- 
David Goodger  <go...@us...>  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/

Hi, I have this text:

<text>

Heading 1
=========

All my life, I wanted to be H1.

Heading 1.1
-----------

But along came H1, and so now I must be H2.

Heading 1.1.1
*************

Yeah, imagine me, I'm stuck at H3!

</text>

(excluding the <text> start and end tags.)

When I run it through tools/html.py, I get unexpected results (below).  I
was expecting H1, H2, then H3; instead, I get H1, H1, H2.

Thanks,

// mark

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.2.5:
http://docutils.sourceforge.net/" />
<title>Heading 1</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="heading-1">
<h1 class="title">Heading 1</h1>
<p>All my life, I wanted to be H1.</p>
<div class="section" id="heading-1-1">
<h1><a name="heading-1-1">Heading 1.1</a></h1>
<p>But along came H1, and so now I must be H2.</p>
<div class="section" id="heading-1-1-1">
<h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
<p>Yeah, imagine me, I'm stuck at H3!</p>
</div>
</div>
</div>
</body>
</html>

-

Greg Ward wrote:
> I like to start playing with stable code.  ;-)

Isn't "stable" just a euphemism for "fixed/unchanging"? :-)  The
current CVS is at 0.2.4 and continually improving.  I try to keep bugs
from creeping in.  Have you tried running the test suite?

    http://docutils.sf.net/README.html#running-the-test-suite

> Please lemme know when I can put my lovely precious whitespace back!

Try it now.

-- 
David Goodger  <go...@us...>  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/

On 02 October 2002, David Goodger said:
> It looks like your Docutils installation is out of date.  Reporter output
> doesn't look like that any more.  Get the latest snapshot here:
> http://docutils.sf.net/docutils-snapshot.tgz

Yeah, that was the 0.2 release.  I like to start playing with stable
code.  ;-)  I'm using the latest CVS now.

> Perhaps the entire term line should be checked for inline markup first, and
> only then split on a top-level " : "?  The terms in the cases given won't be
> split because the " : " would already be inside an inline literal element,
> and thus not at the top level.  This will have to be thought through to see
> if there are any hidden gotchas.

That sounds sensible to me.  The error message I get -- namely, "Inline
literal start-string without end-string" -- and the place where it comes
from (at the end of the definition paragraph) make it sound like
something is out of order.  I suspect looking for " : " should come
later in the game, but that's all I can say without looking at the code
or making a fool of myself.

> In the interim, how about this?
> 
>     set_name(name \: string)
>         use this to change the widget...

I settled for this:

  ``set_name(name:string)``
    use this to change the ...

instead.  Please lemme know when I can put my lovely precious whitespace
back!  ;-)

        Greg
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org

Greg Ward wrote:
> I'm trying to document a collection of methods like this:
...
> ``set_name(name : string)``
>   use this to change the widget name supplied to the constructor.
...
> but Docutils doesn't seem to like my notation for argument types:
> 
> Reporter: WARNING (2) Inline literal start-string without end-string at line
> 10.
> Reporter: WARNING (2) Inline literal start-string without end-string at line
> 15.

It looks like your Docutils installation is out of date.  Reporter output
doesn't look like that any more.  Get the latest snapshot here:
http://docutils.sf.net/docutils-snapshot.tgz

> If I remove the whitespace around the colons, it doesn't complain.
> 
> Oh... bugger... I seem to have run afoul of the "classifier" feature of
> definition lists.

Yes, it seems so.  The " : " structural markup (delimiting the term line
into "term" and "classifier" elements) is picked up before the "``" inline
markup.  That's a tricky case, one I hadn't anticipated.  I think this is
the only case of structural markup in the middle of text; in every other
case, the markup is either at the beginning or at the end of a text block.

> (Have I mentioned how nice it is that reST has a semi-formal spec?)

Glad you like it.  It certainly helps to be able to occasionally say "RTFM!"
and have a "fine manual" to refer to.

> This would be only slightly annoying if it weren't
> for the fact that that feature appears to have been at least vaguely
> inspired by the type syntax that I invented for Grouch.  That raises it
> from "slightly annoying" to "richly ironic", I think.

More than vaguely.  Grouch is mentioned in the spec.  Ironic indeed! :-)

> So is there a way to work around that feature?  I tried backslashing the
> colons, and they just came out backslashed in the HTML output.

Backslash-escaping the colons does indeed prevent the term/classifier split,
but then the inline literals take over and the backslashes stay in.
Dilemma.

Perhaps the entire term line should be checked for inline markup first, and
only then split on a top-level " : "?  The terms in the cases given won't be
split because the " : " would already be inside an inline literal element,
and thus not at the top level.  This will have to be thought through to see
if there are any hidden gotchas.

In the interim, how about this?

    set_name(name \: string)
        use this to change the widget...

You don't get the inline literal effect, but it's better than nothing.

-- 
David Goodger  <go...@us...>  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/

Greg Ward wrote:
> Just doing my first mass restructuredtextification (is that the
> appropriate terminology?)

If you like. :-)

> of some docs, and I noticed that Konqueror 2.2.2 formats HTML
> documents slightly differently if they have
> 
> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
> 
> -- in particular, the vertical line spacing is too much.  If I edit
> out the "charset=utf-8", then it looks perfectly ordinary.  Ditto if
> I s/utf-8/us-ascii/ -- that looks fine.
> 
> Anyone else seen this?  Guess I'll just use "-o us-ascii" for now.

I haven't seen it myself, but it sounds like Konqueror may be using a
different font for Unicode text, with different whitespace
metrics.  If your documents are exclusively ASCII, and you don't use
symbol footnotes (which may produce Unicode symbols; references look
like this: [*]_), you should be fine.  You could use "-o latin-1" to
allow a little more latitude.  You could even put "output-encoding:
latin-1" in your config file and be done with it; see
http://docutils.sf.net/docs/tools.html#configuration-files .

-- 
David Goodger  <go...@us...>  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/

I'm trying to document a collection of methods like this:

"""
Common widget methods
---------------------

The Widget base class also provides a couple of useful
methods:

``set_name(name : string)``
  use this to change the widget name supplied to the constructor.
  Unless you know what you're doing, you should do this before
  rendering or parsing the widget.

``set_value(value : any)``
  use this to set the widget value; this is the same as supplying
  a value to the constructor (and the same type rules apply, ie.
  the type of 'value' depends on the widget class).

``clear()``
  clear the widget's current value.  Equivalent to
  ``widget.set_value(None)``.
"""

but Docutils doesn't seem to like my notation for argument types:

Reporter: WARNING (2) Inline literal start-string without end-string at line 10.
Reporter: WARNING (2) Inline literal start-string without end-string at line 15.

If I remove the whitespace around the colons, it doesn't complain.  

Oh... bugger... I seem to have run afoul of the "classifier" feature of
definition lists.  (Have I mentioned how nice it is that reST has a
semi-formal spec?)  This would be only slightly annoying if it weren't
for the fact that that feature appears to have been at least vaguely
inspired by the type syntax that I invented for Grouch.  That raises it
from "slightly annoying" to "richly ironic", I think.

So is there a way to work around that feature?  I tried backslashing the
colons, and they just came out backslashed in the HTML output.

        Greg
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org

Just doing my first mass restructuredtextification (is that the
appropriate terminology?) of some docs, and I noticed that Konqueror
2.2.2 formats HTML documents slightly differently if they have

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

-- in particular, the vertical line spacing is too much.  If I edit out
the "charset=utf-8", then it looks perfectly ordinary.  Ditto if I
s/utf-8/us-ascii/ -- that looks fine.

Anyone else seen this?  Guess I'll just use "-o us-ascii" for now.

        Greg

<=1B$B;v6H<TL>=1B(B>=1B$B-k=1B(BExcis<=1B$BAw?.<TL>=1B(B>=1B$B-k=1B(BExci=
s <=1B$BAw?.<T!&;v6H<T=1B(BURL>http://plaza15.mbn.or.jp/~1234/=1B$B!!"($3=
$N=1B(B=D2=B0=D9=1B$B$O9-9p$G$9!#G[?.ITMW$NJ}$O=1B(B in...@uk...  =1B$=
BKx$4O"Mm2<$5$$!#G[?.$rDd;_CW$7$^$9=1B(B(=1B$BI,$:G[?.Dd;_$9$k%"%I%l%9$G$=
4JV?.2<$5$$!K=1B(B

=1B$B?75,%*!<%W%s!*%A%g%C%H=1B(BH=1B$B$J=3DP2q$$%5%$%H$@$h!*=1B(B
http://uki-2.net
=1B$B:#$J$i%*!<%W%s5-G0$G$$$/$i=3Dq$-9~$s$G$bL5NA!*=1B(B
http://uki-2.net
=1B$B$3$N%A%c%s%9$K=3Dw$N;R$r=1B(BGET=1B$B$7$F$M!*=1B(B
http://uki-2.net

<=1B$B;v6H<TL>=1B(B>=1B$B-k%(%/%7%9=1B(B<=1B$BAw?.<T=1B(B>=1B$B-k%(%/%7%9=
=1B(B<=1B$BAw?.<T!&;v6H<T=1B(BURL>=1B$B!!=1B(Bhttp://plaza15.mbn.or.jp/~1=
234/ =1B$B$3$N=1B(B=D2=B0=D9=1B$B$O9-9p$G$9!#G[?.ITMW$NJ}$O=1B(B mailstop=
@melcon-c.com  =1B$BKx$4O"Mm2<$5$$!#G[?.$rDd;_CW$7$^$9=1B(B(=1B$BI,$:G[?.=
Dd;_$9$k%"%I%l%9$G$4JV?.2<$5$$!K=1B(B

H=1B$B$J=3Dw$N;R5^A}Cf!*:#$,%A%c%s%9!*=1B(B
http://www.melcon-c.com
=1B$BB(%"%]B3=3DP!*=1B(B
http://www.melcon-c.com
=1B$B$^$:$OEPO?$7$F$M!*=1B(B
http://www.melcon-c.com

[Dean]
> a. reSTX implementation (and plans) in Zope and CMF.

[David]
> Richard Jones has implemented a "ReStructuredText "...

Sorry, I meant to finish that.  Should read:

    Richard Jones has implemented ZReST, a "ReStructuredText Document
    for Zope" application that is complete and ready to install.  It's
    on Richard's Zope pages at:

        http://www.zope.org/Members/richard/ZReST/

    The raw files are on the Docutils site at:

        http://docutils.sf.net/sandbox/richard/ZReST/

-- 
David Goodger  <go...@us...>  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/

Dean Goodmanson wrote:
> I'm looking for the proper place to find past discussions and
> discuss the following (without annoying cross posting):

Discussions take place on the Python Doc-SIG list and the
Docutils-develop list.  Doc-SIG archive:

    http://www.python.org/pipermail/doc-sig/

Docutils-develop archive:

    http://sourceforge.net/mailarchive/forum.php?forum_id=8812

The Doc-SIG archive should be searchable at ActiveState or one of the
other list mirrors.  The SourceForge archive seems searchable too.

> a. reSTX implementation (and plans) in Zope and CMF.

Richard Jones has implemented a "ReStructuredText "...

> b. StructuredText to reStructuredText conversion code, discussion,
> etc.

Not that I know of.

> Similarly, HTML to reSTX as a potential migration tool:
> STX->HTML->reSTX.

Ditto.  Contributions are welcome!

> I'm looking to gather these resources and discussions
> for supporting the implementation of reSTX in ZWiki (
> http://www.zwiki.org/ReStructuredText )

I looked at the page.  Some corrections:

    Abbreviation : reSTX

I've only seen this used in Zope-land, and I don't much like it.  I
prefer RST, but the most commonly used abbreviation is reST.

    Cons: Still requires double space "paragraph" seperation.

I don't see how comparing equal counts a "con" against
reStructuredText.  :-)  Add this to "Pros": Doesn't need blank lines
between list items.

    Problems with STX

Please use the permanent, up-to-date URL:
http://docutils.sourceforge.net/spec/rst/problems.html

Perhaps it's time for a Docutils FAQ.

-- 
David Goodger  <go...@us...>  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/

Greetings!

I'm looking for the proper place to find past
discussions and discuss the following (without
annoying cross posting):

a. reSTX implementation (and plans) in Zope and CMF.

b. StructuredText to reStructuredText conversion code,
discussion, etc.  Similarly, HTML to reSTX as a
potential migration tool: STX->HTML->reSTX.

I'm looking to gather these resources and discussions
for supporting the implementation of reSTX in ZWiki (
http://www.zwiki.org/ReStructuredText )

The motivation is similar to the "Problems with
StructuredText" descriptions (
http://mail.python.org/pipermail/doc-sig/2000-November/001240.html
) , primarily indentation (#3) which is very
cumbersome from a Browser Text Box interface and
surprise formatting.

Best Regards,

Dean Goodmanson
goo...@ya...
http://www.pycs.net/sqr






__________________________________________________
Do you Yahoo!?
Yahoo! News - Today's headlines
http://news.yahoo.com

[David Goodger]
> Is it really such a hardship?  Is it not something you would do
> anyhow, in a text file?

Nope, it's not that much of a hardship.

> I don't know of a better way.  If there is one, I'm receptive.
> Nothing I've seen so far comes close though.

I never mastered the old StructuredText, but its approach, using merely
indentation and whether text was a single line or more than one line (was
that is?) to indicate H1 vs. H2 for instance seemed too fuzzy for my taste.
So, in contrast, I like the precision of reStructuredText.

Thanks for the warning about suppressing errors.

Cheers,

// mark

-

Mark McEahern wrote:
>> Because anything *less* than a full underline looks wrong.
> 
> I agree, it does look unfinished.  However, I keep thinking about all the
> useless work involved in this scenario:
> 
> 1.  Type "The Political Landscape"
> 2.  Type "-----------------------"
> 3.  Change the title to "The Political Landscape of the US"
> 4.  Add underscores to the underline to match the new section title.
> 5.  Change the title to "Politics in the US"
> 6.  etc.
> 
> Why should I have to keep adjusting the length of the line?

Is it really such a hardship?  Is it not something you would do anyhow, in a
text file?  The core of reStructuredText is merely a formalization of common
long-standing conventions for plaintext documents.  I didn't invent this
particular convention, just chose and codified it (and wrote the code to
parse it).  The plaintext medium simply has limitations that we have to live
with.

I don't know of a better way.  If there is one, I'm receptive.  Nothing I've
seen so far comes close though.

Perhaps someday someone will write a reStructuredText mode for Emacs, which
will automatically take care of such mundane issues.  That would be great!
Won't be me though; I can hack Emacs Lisp but not well enough to write a
major mode.

> I know you pointed out that I can just type 80 of the underline characters
> (or 79 or whatever) and leave that alone--as long as it's longer than the
> title.

If it bugs you, this solution seems reasonable.

> I'm reminded of Scott McConnell's comments on Commenting Efficiently in Code
> Complete (pp 464-367):
> 
> He writes of this:
> 
> ###########
> # globals #
> ###########
> 
> "Use styles that don't break down or discourage modification."

Good advice.  Whenever I've done something like that in a source file, I
would write it like this::

    #####################################################################
    # Globals
    #####################################################################

Easy to edit. :-)

> Perhaps I'm making mountains out of molehills, though?

*I* think so, yes. ;-)

>> In reStructuredText, section titles are underlined.  Only full
>> underlines get full marks.  Are you seriously proposing some other
>> behavior?  If so, please be explicit.
> 
> As it is, the current dev snapshot seems to intuit that I want an underline
> in this case:
> 
> The Political Landscape of the US
> ----

The parser knows enough to assume you want an underline, but then it makes
it very clear what the error is and where.  I'd say that it's the assumption
that's closer to being a "bug" than the error message.

> The only thing I guess I'm asking is, "Can we at least make the error
> suppressible?"  And, it turns out, we can:  -r3 does the trick just fine.

-r3 does indeed suppress that error.  Unfortunately, it also suppresses all
other errors, and all warnings as well.  Dangerous and not recommended.  If
you use -r3, you'll regret it in the long run.

The error is meant as diagnostic feedback to the user, and isn't meant to be
ignored.  That's what the ERROR/3 level means: "a major issue that should be
addressed.  If ignored, the output will contain unpredictable errors."  See
http://www.python.org/peps/pep-0258.html#error-handling for details.

I'm not inclined to remove the generated error.  Asking if the error can be
suppressed is approaching the issue from the wrong direction.  If pressed,
I'd rather remove the leniency: leave just the error and omit the section &
title recognition.

> I really like reStructuredText.  Thank you for developing it!

You're most welcome.

-- 
David Goodger  <go...@us...>  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/

[David Goodger]
> You omitted this sentence:
>
>     An underline/overline is a single repeated punctuation character
>     that begins in column 1 and forms a line extending at least as far
>     as the right edge of the title text.
>
> The "at least as far" is significant.

My apologies.  I missed that sentence.  So the behavior is by design, I see.

> Because anything *less* than a full underline looks wrong.

I agree, it does look unfinished.  However, I keep thinking about all the
useless work involved in this scenario:

1.  Type "The Political Landscape"
2.  Type "-----------------------"
3.  Change the title to "The Political Landscape of the US"
4.  Add underscores to the underline to match the new section title.
5.  Change the title to "Politics in the US"
6.  etc.

Why should I have to keep adjusting the length of the line?

I know you pointed out that I can just type 80 of the underline characters
(or 79 or whatever) and leave that alone--as long as it's longer than the
title.

I'm reminded of Scott McConnell's comments on Commenting Efficiently in Code
Complete (pp 464-367):

He writes of this:

  ###########
  # globals #
  ###########

"Use styles that don't break down or discourage modification."

Perhaps I'm making mountains out of molehills, though?

> In reStructuredText, section titles are underlined.  Only full
> underlines get full marks.  Are you seriously proposing some other
> behavior?  If so, please be explicit.

As it is, the current dev snapshot seems to intuit that I want an underline
in this case:

The Political Landscape of the US
----

The only thing I guess I'm asking is, "Can we at least make the error
suppressible?"  And, it turns out, we can:  -r3 does the trick just fine.

I really like reStructuredText.  Thank you for developing it!

Cheers,

// mark

-

Gunnar Schwant has contributed DocFactory, a wxPython GUI application for
Docutils.  It is in the preliminary stages.  For details, please see

    http://docutils.sf.net/sandbox/gschwant/docfactory/README.html

I have begun a "To Do" list:

    http://docutils.sf.net/sandbox/gschwant/docfactory/NOTES.html

The code is available via CVS or snapshot:

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

Please try it out.  Feedback is welcome: bug reports, patches, feature
ideas, etc.

-- 
David Goodger  <go...@us...>  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/

Mark McEahern wrote:
> The documentation says:
> 
> "An underline/overline must be at least 4 characters long (to avoid
> mistaking ellipses ["..."] for overlines). When an overline is used, the
> length and character used must match the underline."

You omitted this sentence:

    An underline/overline is a single repeated punctuation character
    that begins in column 1 and forms a line extending at least as far
    as the right edge of the title text.

The "at least as far" is significant.

> http://docutils.sourceforge.net/spec/rst/reStructuredText.html#sections
> 
> However, when I use this:
> 
>   My section is longer than the underline
>   ====
> 
> (left-aligned in actual source, indented for readability)
> 
> I get this:
> 
>   System Message: WARNING/2 (user_task_matrix.rst, line 4)
> 
>   Title underline too short.
> 
> Is that a bug?

No, it's a diagnostic message, warning you that the markup is
questionable.  The parser assumes that a section title is intended,
but the inserted warning is such an eyesore that you're sure to fix
the underline.

> Why make users type all those extra underline characters and
> then have to keep adjusting them as the section title changes?

Because anything *less* than a full underline looks wrong.  There's no
reason to limit your underlines to the exact length of the title
though (thus "at least as far" above).  You're welcome to use 80
column underlines for all titles, no matter how long.

In reStructuredText, section titles are underlined.  Only full
underlines get full marks.  Are you seriously proposing some other
behavior?  If so, please be explicit.

Coincidentally, currently there is a proposal to remove the
4-character minimum on over- & underlines, for short titles.  It and
other proposed changes & additions to the markup are discussed on the
Doc-SIG list:

    http://mail.python.org/mailman/listinfo/doc-sig

Docutils implementation issues are discussed on the docutils-develop
list:

    http://lists.sourceforge.net/lists/listinfo/docutils-develop

Interested parties should subscribe to both since there is some
overlap.

-- 
David Goodger  <go...@us...>  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/

The documentation says:

"An underline/overline must be at least 4 characters long (to avoid
mistaking ellipses ["..."] for overlines). When an overline is used, the
length and character used must match the underline."

http://docutils.sourceforge.net/spec/rst/reStructuredText.html#sections

However, when I use this:

  My section is longer than the underline
  ====

(left-aligned in actual source, indented for readability)

I get this:

  System Message: WARNING/2 (user_task_matrix.rst, line 4)

  Title underline too short.

Is that a bug?  Why make users type all those extra underline characters and
then have to keep adjusting them as the section title changes?

Cheers,

// m

-