Re: [Docutils-users] problem with substitution_reference

[David Goodger <goodger@py...>]

[Steven Bird]
> The following restructured text document processes cleanly only when either
> of the last two lines is omitted.

Thanks for the bug report.  It's a known bug:
http://docutils.sourceforge.net/BUGS.html#doubly-indirect-substitutions

Until the bug is fixed, you'll have to work around the limit on
doubly-indirect substitutions.

Your bug report showed me another bug that was *not* known.  Now it is:
http://docutils.sourceforge.net/BUGS.html#inline-literals-in-substitutions

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

[Docutils-users] problem with substitution_reference

[Steven Bird <stevenbird1@gm...>]

The following restructured text document processes cleanly only when either
of the last two lines is omitted.

--snip--
.. |l| unicode:: U+00AB .. left chevron
.. |r| unicode:: U+00BB .. right chevron
.. |.| replace:: |l|\ ``.``\ |r|

.. Delete either of the following lines, and there is no error.

Regular expression |.| will match any character

.. Note:: Note that |.| matches *exactly* one character
--snip--


Here's the full traceback:

--snip--
% rst2html.py --traceback re.txt
Traceback (most recent call last):
  File "/usr/bin/rst2html.py", line 25, in ?
    publish_cmdline(writer_name=3D'html', description=3Ddescription)
  File "/usr/lib/python2.4/site-packages/docutils/core.py", line 312,
in publish_cmdline
    config_section=3Dconfig_section, enable_exit_status=3Denable_exit_statu=
s)
  File "/usr/lib/python2.4/site-packages/docutils/core.py", line 196, in pu=
blish
    output =3D self.writer.write(document, self.destination)
  File "/usr/lib/python2.4/site-packages/docutils/writers/__init__.py",
line 72, in write
    self.translate()
  File "/usr/lib/python2.4/site-packages/docutils/writers/html4css1.py",
line 122, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python2.4/site-packages/docutils/nodes.py", line 155,
in walkabout
    child.walkabout(visitor)
  File "/usr/lib/python2.4/site-packages/docutils/nodes.py", line 155,
in walkabout
    child.walkabout(visitor)
  File "/usr/lib/python2.4/site-packages/docutils/nodes.py", line 147,
in walkabout
    visitor.dispatch_visit(self)
  File "/usr/lib/python2.4/site-packages/docutils/nodes.py", line
1443, in dispatch_visit
    return method(node)
  File "/usr/lib/python2.4/site-packages/docutils/writers/html4css1.py",
line 1198, in visit_substitution_reference
    self.unimplemented_visit(node)
  File "/usr/lib/python2.4/site-packages/docutils/writers/html4css1.py",
line 1429, in unimplemented_visit
    raise NotImplementedError('visiting unimplemented node type: %s'
NotImplementedError: visiting unimplemented node type: substitution_referen=
ce
--snip--

Software versions:
Docutils 0.3.9
Python 2.4.1
OS: Linux 2.6.8-24.11-default #1 Fri Jan 14 13:01:26 UTC 2005 i686
i686 i386 GNU/Linux

Re: [Docutils-users] punctuation

[David Goodger <goodger@py...>]

[Alan G Isaac]
> Following up on my earlier email, here's a starting point.

And it's a good start.  How about checking it in as
trunk/docutils/docutils/parsers/rst/include/punctuation.txt?
Please get a BerliOS.de account & send me or Felix your user
name.

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

Re: [Docutils-users] endash and emdash

[David Goodger <goodger@py...>]

[Alan G Isaac]
> If you go to the FAQ question 2.7 and follow the link to
> http://docutils.sourceforge.net/docs/ref/rst/substitutions.html
> you get a list of files that are not linked.

They're linked now; thanks for the clarification.

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

Re: [Docutils-users] option list wrongly detected?

[David Goodger <goodger@py...>]

[Alan G Isaac]
> What I meant to ask is:
> should those items be option lists?
> I.e., should option list break the
> blank-line+indentation rule for nested lists?
> Or have I misunderstood the rule?
>
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists

No rule is being broken.  Perhaps the spec could use some
clarification/simplification...  Done:

    Examples of nested enumerated lists::

        1. Item 1 initial text.

           a) Item 1a.
           b) Item 1b.

        2. a) Item 2a.
           b) Item 2b.

There's no blank line requirement for nesting lists.  A blank line is
required above a list itself, to separate it from other body elements.
Item 2a above begins at the beginning of list item 2, and no blank
line is necessary because it is unambiguously the beginning of an
indented block.

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

Re: [Docutils-users] snapshot stylesheet search

[David Goodger <goodger@py...>]

[Alan G Isaac]
>>> 2. Why isn't it sought using urllib?
>>
>> Because it isn't.  (IOW, such functionality has never been
>> implemented.)  I don't think that it should, either.
>
> I do not understand.
> If the stylesheet is specified as a URL and embedding is
> requested, is this considered a user error?

No, not a user error, just a bug resulting from an unanticipated
combination.  The assumption was that a stylesheet to be embedded
should exist as a file on your system, and you should use the
"stylesheet_path" setting.  Thinking it over though, perhaps the
"stylesheet" setting (a URL, to be used verbatim) should be allowed to
be combined with "embed_stylesheet", using urllib.  I will add this to
the list of known bugs.

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

Re: [Docutils-users] Re: figure that is not an image

[David Goodger <goodger@py...>]

[Guenter Milde]
> I would propose an auto-numbering similar to the foonotes, e.g. with
>
>     .. figure:: Figure #: auto-numbered figure
>        [options]
>
>        content
>
> the caption label is "Figure" and auto-numbering is on.

Yes, except the "Figure #: " part would be auto-generated.

> So, "figure" and "table" would become special cases of "sequence"?

Yes, sort of.  The "figure" and "table" directives would use implicit
pre-defined sequences, unless an explicitly named sequence is given.

> Another option would be to use "figure" as generic 'sequence
> directive' (with "table" as special case).

The "sequence" directive would define a named sequence, nothing more.
Specifically, it wouldn't generate any doctree elements.  The
"sequence" directive is *not* a generic form of the "figure" and
"table" directives.

> :pattern: defaults to "Figure #." Every different :pattern:
> starts a separate counter.
>
> Combined with my above proposal this becomes::
>
>   .. figure:: Diagram #: auto-numbered diagramm
>
>      .. image:: diagram.eps

Too verbose (repetition required), fragile (a misspelled caption would
start a new sequence), and implicit/magic (caption parsing required)
for my taste.

>   .. figure:: title              + standard rst directive syntax
>      :pattern: Figure #.         - does not resemble final appearance

This last example is the closest to what I envisage, although I would
not put the pattern directive in the figure directive.  And actually,
it *does* resemble the final appearance: ".. figure:: title" looks a
lot like "Figure 1. title".

Here are some concrete examples of what I'd like to see:

    .. figure:: Caption

       .. image:: figure.png

This results in "Figure 1. Caption".  The sequence and pattern are
implicit and pre-defined.

    .. sequence:: screenshot
       :pattern: Screenshot ${value}. $title

    .. figure:: Input dialog
       :sequence: screenshot

       .. image:: input.png

Here, the ":pattern:" value uses string.Template syntax (new in Python
2.4).  The explicit ":sequence:" specified in the "figure" directive
overrides the default implicit sequence and pattern.

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

Re: [Docutils-users] option list wrongly detected?

[David Goodger <goodger@py...>]

[Martin Blais]
> Unrelated note, but those option_list document elements seem so
> weird to me.  They represent such a specialized case of "document
> structure" that I have to wonder why they appear within the document
> tree.

The document tree grew organically.  The original raison d'etre was
for inline documentation of software, where option lists are apropos.

> (unless we're documenting man pages)

They're included too ;-)

> (which only make sense for computer geeks, really)

Who, me?  You?  Us?

> Call me a sucker,

You're a sucker.  :-)

> but I've come to think of docutils as a truly generic document
> processing system and some of the document nodes seem to me quite
> out-of-place

It's practical first, generic second.  And as we all know,
practicality beats purity.

> (is it generic?  Is it not?  Knowing Dave's no-nonsense style I
> guess in person his answer would be that ultimately docutils is just
> defined by what docutils is :-) ).

Not too far off the mark :-).  I'd say that Docutils is what Docutils
*says* it is.  In other words, the docs are the spec, not the code.
Having said that though, nothing's written in stone, and there's
always room for change.  Lessons have been learned, mistakes have been
made (and will probably continue to be made, unfortunately); hopefully
the project will benefit from this experience.

> Say, for example, could I get a special node for my book references?

If you code it into a private patch, sure.  ;-)

> (Incidentally, LaTeX contains special structures for litterary
> references, and not for options lists.)

Yay for LaTeX.  I suppose every documentation system has its biases.

> Oh, and how about bird feathers?  I have a large collection of bird
> feathers, and I was wondering if I could get a special node for it,
> say, when "~~~ peacock" appears on a line by itself, to have it
> create a
>
>   <bird_feather>
>       peacock
>
> node.  Can I get it please please please?

When a payment with enough zeros appears in my PayPal account, sure.
It'll be coded on the "martin-blais-tweet-tweet-tweet" branch.

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

Re: [Docutils-users] reStructuredText wiki?

[Phil Schumm <pschumm@uc...>]

At 10:19 AM +0200 7/28/05, Jens Jorgen Mortensen wrote:
>I have some documentation written in reStructuredText.  It is stored 
>in cvs, and a simple script does a nightly checkout and generates 
>html.  I would like to use a wiki for this.  I looked for wikis with 
>reStructuredText support, and found these:
>
>http://wiki.webwareforpython.org/thiswiki.html
>http://www.edgewall.com/trac/
>http://moinmoin.wikiwikiweb.de/
>http://mithrandr.moria.org/code/stikiwiki/
>http://zwiki.org
>
>Does anyone have experience with these and reStructuredText?


We use ZWiki a fair amount, almost exclusively with reStructuredText 
for markup.  This is mainly because it permits us to integrate our 
Wikis easily within the context of existing Zope-based websites. 
ZWiki is fairly mature and stable, though I haven't used MoinMoin so 
I can't comment in relation to that.  The default user interface is 
perhaps not the most attractive, however several good skins are 
available, and it's not difficult to write your own (if you know 
ZPT).  The development cycles are pretty quick (1 release per month), 
which can be a bit frustrating if you're carrying along any 
substantial customization.  But, to speak directly to your question, 
we do move large batches of pages in and out of our Wikis 
programmatically (in via FTP, out using the urlretrieve method from 
Python's urllib module).

So, if you have reasons to look for a Zope-based solution, I'd 
definitely take a look at ZWiki.  If all you're looking for is a 
stand-alone Wiki however, I'm not sure it would be the best 
alternative.


-- Phil

Re[2]: [Docutils-users] Re: figure that is not an image

[Alan G Isaac <aisaac@am...>]

On Fri, 29 Jul 2005, "G. Milde" apparently wrote: 
> "figure" and "table" would become special cases of "sequence"? 

This sounds useful to me, and it reminds me of LaTeX where 
figure and table are special kinds of 'float'.  For example, 
I often have figures, tables, and "listings" in a single 
document, and I want them all numbered separately.

Cheers,
Alan Isaac

Re[2]: [Docutils-users] option list wrongly detected?

[Alan G Isaac <aisaac@am...>]

On Thu, 28 Jul 2005, David Goodger apparently wrote: 
> Note that it's not an option list, it's a bullet list 
> whose first two items contain option lists. 

Right; sorry.
What I meant to ask is:
should those items be option lists?
I.e., should option list break the
blank-line+indentation rule for nested lists?
Or have I misunderstood the rule?
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists

Cheers,
Alan Isaac

PS I understand the workarounds.

Re[2]: [Docutils-users] snapshot stylesheet search

[Alan G Isaac <aisaac@am...>]

> [Alan G Isaac] 
>> 1. Where is this default stylesheet being set? 

On Thu, 28 Jul 2005, David Goodger apparently wrote: 
> Probably in your config file.

Oh yes; set *long* ago.

>  I'd guess that you're getting this behavior because of 
>  a combination with the embed_stylesheet setting, which 
>  now defaults to true/on. 

Aha.  That's the change that got me.
Thanks!



>> 2. Why isn't it sought using urllib? 

> Because it isn't.  (IOW, such functionality has never been implemented.) 
> I don't think that it should, either. 

I do not understand.
If the stylesheet is specified as a URL and embedding is 
requested, is this considered a user error?

Cheers,
Alan Isaac

Re[2]: [Docutils-users] endash and emdash

[Alan G Isaac <aisaac@am...>]

>> On Thu, 28 Jul 2005, David Goodger apparently wrote: 
>>> http://docutils.sourceforge.net/FAQ.html, question 2.7: 


> [Alan G Isaac] 
>> It would be nice if the filenames were linked to the files. 


On Thu, 28 Jul 2005, David Goodger apparently wrote: 
> I don't understand; please explain. 


If you go to the FAQ question 2.7 and follow the link to
http://docutils.sourceforge.net/docs/ref/rst/substitutions.html
you get a list of files that are not linked.
(Of course if you choose 
http://docutils.sourceforge.net/tmp/charents/ instead then 
you do get links to the actual files.)

Cheers,
Alan Isaac

[Docutils-users] Re: endash and emdash

[Mikolaj Machowski <mikmach@wp...>]

David Goodger scripsit:
> This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
> --------------enig84038D8F45CB550D13CC32CE
> Content-Type: text/plain; charset=ISO-8859-1
> Content-Transfer-Encoding: 7bit
>
> [Alan G Isaac]
>> On Thu, 28 Jul 2005, David Goodger apparently wrote:
>>> http://docutils.sourceforge.net/FAQ.html, question 2.7:
>>
>> It would be nice if the filenames were linked to the files.
>
> I don't understand; please explain.

For example in table of substitution files.

m.

Re: [Docutils-users] Re: figure that is not an image

[G. Milde <g.milde@we...>]

On 28.07.05, David Goodger wrote:
> [Martin Blais]
> >> Is it possible to create a figure that does not consist of an image?
 
> I don't think the figure name should cause numbering.  The name should
> just be a name, to refer to.  Instead, an explicit option should cause
> numbering, such as ":numbered:" and/or ":sequence: name" (which
> implies ":numbered:"; the name allows for multiple independent
> sequences).

I would propose an auto-numbering similar to the foonotes, e.g. with

    .. figure:: Figure #: auto-numbered figure
       [options]

       content

the caption label is "Figure" and auto-numbering is on.
 
 
> > * Besides i18n, what if the user wants to use a different term than
> >   "Figure", e.g. "Image", "Table", or "Diagram"?
> 
> I think providing two directives, "figure" and "table", will suffice
> for most users.  For example, a new "sequence" directive could be
> added for user-defined a terms or patterns, and "figure" could be
> extended to support it.  For example::
> 
>     .. sequence:: diagram
>        :pattern: Diagram #.


 
> "sequence" could also allow for arbitrary initial values, enumerations
> (1/a/A/i/I), and relationships (figure sequence depends on chapter
> sequence, restarting at 1 whenever chapter changes, and rendered as
> <chapter>.<figure>).

So, "figure" and "table" would become special cases of "sequence"?

Another option would be to use "figure" as generic 'sequence directive'
(with "table" as special case). 

:pattern: defaults to "Figure #." Every different :pattern:
starts a separate counter.

Combined with my above proposal this becomes::

  .. figure:: Diagram #: auto-numbered diagramm
  
     .. image:: diagram.eps


The syntax for the pattern specification needs carefull consideration.
Some thoughts::

  .. figure:: Figure #: title    + simple
                                 + close to appearance in the output
                                 ? should the colon be part of :pattern:?
                                 
  .. figure:: Figure #. title    + close to appearance in the output
                                 - maybe ambiguous (Where does the
                                   :pattern: end and the title start?)
                                 
  .. figure:: Figure #.: title   + explicit
                                 - ugly
                                 
  .. figure:: [Figure #.] title  + explicit
                                 + precedence case: optional labels in LaTeX
                                 - square brackets are hard to type on
                                   German keyboards

  .. figure:: title              + standard rst directive syntax
     :pattern: Figure #.         - does not resemble final appearance
     

Sincerely

Guenter
     
-- 
G.Milde web.de

Re: [Docutils-users] option list wrongly detected?

[Martin Blais <martin.blais@gm...>]

On 7/28/05, David Goodger <goodger@...> wrote:
> [Alan G Isaac]
> > Should the following be detected as an option list?
> > I would think not, but the first two items are.
>=20
> > Ordinary list:
> >
> > * -1  not an option
> > * -2  not an option
> > * -12 not an option
>=20
> Note that it's not *an* option list, it's a bullet list whose first two i=
tems
> contain option *lists*.  Here's a diagnostic tool:

Unrelated note, but those option_list document elements seem so weird
to me.  They represent such a specialized case of "document structure"
that I have to wonder why they appear within the document tree.  Call
me a sucker, but I've come to think of docutils as a truly generic
document processing system and some of the document nodes seem to me
quite out-of-place  (is it generic?  Is it not?  Knowing Dave's
no-nonsense style I guess in person his answer would be that
ultimately docutils is just defined by what docutils is :-) ).

Say, for example, could I get a special node for my book references? =20
If you see "G=F6del, Escher, Bach: An Eternal Golden Braid", Douglas R.
Hofstadter, Ed. Basic Books, 1999, in a sentence, just like you've
just seen, shouldn't that be detected and have some kind of document
nodes for a book reference?  Referencing other written works is a more
common occurence in documents than documenting options lists IMO
(unless we're documenting man pages).  It seems to me that a document
node for litterature references belongs more in a document structure
than "program option lists" (which only make sense for computer geeks,
really).  (Incidentally, LaTeX contains special structures for
litterary references, and not for options lists.)

Oh, and how about bird feathers?  I have a large collection of bird
feathers, and I was wondering if I could get a special node for it,
say, when "~~~ peacock" appears on a line by itself, to have it create
a

  <bird_feather>
      peacock

node.  Can I get it please please please?  It kinda looks like a
feather too, those cute tilde characters (bird-feather characters,
really).  I'm sure everyone on this list cares a lot about bird
feathers and therefore you should all write special code in all your
writers to support them.

*wink*

cheers,

Re: [Docutils-users] option list wrongly detected?

[David Goodger <goodger@py...>]

[Alan G Isaac]
> Should the following be detected as an option list?
> I would think not, but the first two items are.

> Ordinary list:
>
> * -1  not an option
> * -2  not an option
> * -12 not an option

Note that it's not *an* option list, it's a bullet list whose first two items
contain option *lists*.  Here's a diagnostic tool:

$ rst2pseudoxml.py <<EOF
Ordinary list:

* -1  not an option
* -2  not an option
* -12 not an option
EOF
<document source="<stdin>">
    <paragraph>
        Ordinary list:
    <bullet_list bullet="*">
        <list_item>
            <option_list>
                <option_list_item>
                    <option_group>
                        <option>
                            <option_string>
                                -1
                    <description>
                        <paragraph>
                            not an option
        <list_item>
            <option_list>
                <option_list_item>
                    <option_group>
                        <option>
                            <option_string>
                                -2
                    <description>
                        <paragraph>
                            not an option
        <list_item>
            <paragraph>
                -12 not an option

If you insist on having multiple spaces following the negative numbers,
you'll have to escape the hyphens:

$ rst2pseudoxml.py <<EOF
Ordinary list:

* \-1  not an option
* \-2  not an option
* -12 not an option
EOF
<document source="<stdin>">
    <paragraph>
        Ordinary list:
    <bullet_list bullet="*">
        <list_item>
            <paragraph>
                -1  not an option
        <list_item>
            <paragraph>
                -2  not an option
        <list_item>
            <paragraph>
                -12 not an option

But now, you don't need those extra spaces any more, do you? :-)

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

Re: [Docutils-users] snapshot stylesheet search

[David Goodger <goodger@py...>]

[Alan G Isaac]
> 1. Where is this default stylesheet being set?

Probably in your config file.  I'd guess that you're getting this behavior
because of a combination with the embed_stylesheet setting, which now defaults
to true/on.

If you want more than a guess, please provide more info.  See
http://docutils.sourceforge.net/BUGS.html#how-to-report-a-bug

> 2. Why isn't it sought using urllib?

Because it isn't.  (IOW, such functionality has never been implemented.)
I don't think that it should, either.

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

Re: [Docutils-users] reStructuredText wiki?

[David Goodger <goodger@py...>]

[Jens Jorgen Mortensen]
> http://wiki.webwareforpython.org/thiswiki.html
> http://www.edgewall.com/trac/
> http://moinmoin.wikiwikiweb.de/
> http://mithrandr.moria.org/code/stikiwiki/
> http://zwiki.org
>
> * Does anyone have experience with these and reStructuredText?
> * Are there other alternatives?

Question 2.10 in the FAQ lists what we know:
http://docutils.sourceforge.net/FAQ.html

I wasn't aware of the webware wiki; added to the FAQ.

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

Re: [Docutils-users] endash and emdash

[David Goodger <goodger@py...>]

[Alan G Isaac]
> On Thu, 28 Jul 2005, David Goodger apparently wrote:
>> http://docutils.sourceforge.net/FAQ.html, question 2.7:
>
> It would be nice if the filenames were linked to the files.

I don't understand; please explain.

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

Re: [Docutils-users] Non-breaking space

[David Goodger <goodger@py...>]

> [Mikolaj Machowski]
>>> I think that also reST could benefit from this element.
>
> On Thu, 28 Jul 2005, David Goodger apparently wrote:
>> We've discussed this extensively, and decided against.
>> See
>> http://docutils.sf.net/docs/dev/rst/alternatives.html#character-processing

[Alan G Isaac]
> With all respect to Mikolaj, I think it is hard for people
> new to reST to understand how much time has been spent
> discussing such aspects.

My docutils-users mbox is 14MB; docutils-develop is 20MB.

> The existing reST is much more
> mature and more deeply considered than I realized when
> I discovered it, and as a non-programmer user I now assume
> that I will continue to "get" the reasons for apparently
> peculiar design decisions over time.

Thank you.  Not all such peculiar design decisions are justified
though, so keep your eyes open.

> The punctuation issue has been a tough one for me too, for
> a couple reasons.
>
> - A LaTeX background made me favorable to LaTeX markup
>   conventions, which seem tidy and useful.
> - I like writing my documents in ASCII (or if absolutely
>   necessary Latin1) for the usual reasons (especially the
>   ease of exchange implied by a universally supported
>   encoding)
> - The proposal to just enter the real character does not
>   seem very realistic to me at this point, especially since
>   the em-dash and en-dash are not in Latin1 yet are widely
>   needed.
>
> It seems that there are two basic proposals to deal with us
> primitives who resist the idea that we should always edit in
> UTF-8.

UTF-8 is becoming the world's ASCII.

> (I notice, by the way, that essentially all email on this
> list, including David's, is Latin1.)

That's just Thunderbird's default.  If I use a non-Latin-1 character,
it switches to UTF-8 automatically.  We try to keep compatibility with
luddites for as long as possible (but not longer ;-)

Actually, we do get quite a bit of mail in various Chinese encodings.
That's why the list is now subscriber-post-only (with moderator
intervention for the rare genuine non-subscriber post).

> 1. Choose some markup for punctuation in our documents and
>    do not call them reST.  Then add a preprocessor to remove
>    the non-reST punctuation and produce an reST document.

Yes, that's a good, clean solution that won't inconvenience anyone
else.  The problem is that such a preprocessor would inevitably mess
up *someone's* docs, so it can't be universally deployed.

> 2. Add a punctuation set to the entity definition files.

A "trimmed punctuation set", you mean?  Sure.

>    I take it that
>    http://docutils.sourceforge.net/tmp/charents/html4-special.txt
>    is the current version of this,

Not quite, but close.  It's
http://docutils.sf.net/docutils/parsers/rst/include/xhtml1-special.txt
(the W3C changed the spec on us).

>    but I think most people would regret e.g. the lack of trimming
>    for dashes and the lack of a non-breaking space.

A bit of copy & paste is all that's needed to get a custom-tailored
set of definitions.

> In this context, I would hope that Mikolaj will work on
> a punctuation defintion file rather than introducing
> incompatibilities with reST.

Me too!  Contributions are always welcome.

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

Re: [Docutils-users] Re: figure that is not an image

[David Goodger <goodger@py...>]

(catching up on backlogged email -- sorry for the delay)

[Martin Blais]
>> Is it possible to create a figure that does not consist of an image?

[Felix Wiemann]
> Not currently.
>
> The document model allows that *almost* (just a change to the DTD
> and probably to the writers).
>
> In my opinion the current syntax of the figure directive is overly
> specific to images and too complicated (width and figwidth, etc.);
> and it's too much duplication with the image directive.

No wonder... the "figure" code calls "image" to do most of its work!

> The document model looks pleasantly generic, though.  :-)
>
> I propose the following new syntax for a figure directive [1]_:
>
> * If there is an argument to the figure directive, use the current
>   syntax, but raise a deprecation warning.
>
> * If there is no argument to the figure directive, create a figure
>   node and insert the directive contents into the figure node.
>   Recognize the following options:
>
>   :width: Figure width (as opposed to :figwidth: before).
>   :class: Figure class (as opposed to :figclass: before).
>   :align: Figure alignment.
>   :caption: Figure caption.
>
>   The caption node, if the caption option is given, is inserted as
>   the last child of the figure node.

I think the ideal syntax would be:

    .. figure:: [caption]
       [options]

       content

The caption and options are all optional.  The blank line before the
content is required.

>   No support for a legend is added.  I've never seen a legend below
>   the caption in a real figure.  I.e., the legend is always part of
>   the figure contents.

That sounds fine to me.

The content model would look like this:

    <!ELEMENT figure (caption?, (%body.elements;)+) >

I think the caption is better up front, as a title equivalent.  Heck,
we could even use the "title" element.  Writers can re-order the
elements such that the caption comes after the content.

>> with numbering?  Hmm, I just noticed... the figures don't seem to
>> have automatic numbering either (like in LaTeX).
>
> No, sorry.  It's on the to-do list; see
>
<http://docutils.sf.net/docs/dev/todo.html#object-numbering-and-object-references>;.
>
> I think a generic figure directive could be a first step into the
> right direction.  Since ``figure`` is the only element that supports
> captions at the moment

Tables can have a title, which is just like a caption (except before
the table).

> and you can only place numbers inside a caption,

?  Not following you.

> we might only have to implement numbering for figures.
>
> So this ::
>
>     .. figure::
>        :name: test figure                <--- This causes numbering.
>        :caption: This is a test figure.
>
>        Figure contents.
>
> would be rendered like this::
>
>     Figure contents.
>
>     Figure 1: This is a test figure.

I don't think the figure name should cause numbering.  The name should
just be a name, to refer to.  Instead, an explicit option should cause
numbering, such as ":numbered:" and/or ":sequence: name" (which
implies ":numbered:"; the name allows for multiple independent
sequences).

Without a ":name:" option, the default name of a figure should be
taken from its caption.

> Numbering tables would mean nesting the table inside a figure::

There's a table directive which should also allow numbering &
sequences.  Formal documents often have independent "figure" and
"table" sequences.  Of course, a figure's content may be a table.

> We might end up with nested directives here, but I think it's worth
> the genericness.  After all, we might want to mix directives and
> text in one figure, or have multiple images inside one figure.

Yes, nested directives are not a problem.

> * Make :caption: mandatory for numbered figures?

No.  In any case, "mandatory options" is an oxymoron!

> * Besides i18n, what if the user wants to use a different term than
>   "Figure", e.g. "Image", "Table", or "Diagram"?

I think providing two directives, "figure" and "table", will suffice
for most users.  For example, a new "sequence" directive could be
added for user-defined a terms or patterns, and "figure" could be
extended to support it.  For example::

    .. sequence:: diagram
       :pattern: Diagram #.

"sequence" could also allow for arbitrary initial values, enumerations
(1/a/A/i/I), and relationships (figure sequence depends on chapter
sequence, restarting at 1 whenever chapter changes, and rendered as
<chapter>.<figure>).

>   * We could defer this issue and add support for it later.

Yes.

>   * We could also add a special "figname" role to be used only
>     inside figures::
...
>     The caption is "Table 1: A test table."

No, too much magic.

>     and it can be referenced as "table :figref:`some table`".

That's fine though.

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

Re: [Docutils-users] Re: No Stylesheet Error

[David Goodger <goodger@py...>]

(catching up on backlogged email -- sorry for the delay)

>> Michael Foord wrote:
>>> A user has reported a problem with rest2web - docutils generates a
>>> 'no stylesheet' warning.

> David Goodger wrote:
>> Felix, this seems like good evidence that the warning ought to be
>> removed altogether.

[Felix Wiemann]
> Yes, I didn't have in mind that it would break existing scripts
> which use Docutils programmatically.  The best thing to do would be
> to raise the warning only when Docutils is used
> non-programmatically, IMO, because when used from the command-line,
> chances are high that the missing stylesheet can be easily fixed
> (which is not the case for scripts like rest2web).

The long-term solution is for rest2web to set "_stylesheet_required"
to False/0 in the "settings_overrides" parameter.

> Fiddling with HTML writer settings in process_programmatic_settings
> smells veeery bad.

Agreed.  Don't do that.

> What about adding a "_programmatic" setting, automatically set by
> process_programmatic_settings?  The HTML writer could query this
> setting then.

I don't think "programmatic context" implies anything about the
stylesheet, or vice-versa.  As I said before, a "_programmatic"
setting would be painting with far too broad a brush to be useful.
Rather than adding more complicated logic to the Docutils itself,
let's rely on the application to provide appropriate logic and/or
settings.  IOW, applications that absolutely require a stylesheet
should set "_stylesheet_required" to True/1, and those that don't use
a stylesheet at all should set "_stylesheet_required" to False/0.

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

Re: [Docutils-users] Simple Templating System

[David Goodger <goodger@py...>]

(catching up on backlogged email -- sorry for the delay)

[Michael Foord]
> Is anyone interested in a *simpler* template system - that simply
> inserts the body and title of generated HTML into a page template ?
>
> I could easily implement one that will do single pages (or directories)
> - but does nothing more dynamic than insert the body/title into a single
> template.

I suspect that many people would be interested in such a system.  I also
suspect that it's so easy to do, that any developer who wants one would
roll one themselves.  Non-developer users of reST would certainly be able
to benefit.

Please give it a go, and we'll add a link in the appropriate place(s).
(If you have checkin rights, please go ahead & add the link yourself.
If you don't have checkin rights, just ask.)

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

[Docutils-users] punctuation

[Alan G Isaac <aisaac@am...>]

Following up on my earlier email,
here's a starting point.

Cheers,
Alan Isaac


.. |--|  unicode:: U+02013 .. EN DASH
   :trim:
.. |---| unicode:: U+02014 .. EM DASH
   :trim:
.. |..|  unicode:: U+02025 .. TWO DOT LEADER
.. |`|   unicode:: U+02018 .. LEFT SINGLE QUOTATION MARK
   :rtrim:
.. |'|   unicode:: U+02019 .. RIGHT SINGLE QUOTATION MARK
   :ltrim:
.. |``|  unicode:: U+0201C .. LEFT DOUBLE QUOTATION MARK
   :rtrim:
.. |''|  unicode:: U+0201D .. RIGHT DOUBLE QUOTATION MARK
   :ltrim:
.. |...| unicode:: U+02026 .. HORIZONTAL ELLIPSIS
.. |<|   unicode:: U+02039 .. SINGLE LEFT-POINTING ANGLE QUOTATION MARK
   :rtrim:
.. |>|   unicode:: U+0203A .. SINGLE RIGHT-POINTING ANGLE QUOTATION MARK
   :ltrim: