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

On Wed, 18 Dec 2002, David Goodger wrote:
>     Allow for compound enumerators, such as "1.1." or "1.a." or
>     "1(a)", to allow for nested enumerated lists without indentation?
...
> I wouldn't be averse to including it, were a well-implemented patch to
> appear.  I'm not interested enough to write it though.

Thanks.  I'll contribute it if I end up going this route.

> Perhaps what you want is the "include" directive, and a master
> document::

Maybe, although I'm trying to avoid this because large docs are
too slow to process and some parts are generated dynamically and/or
rendered by my writer differently based on context.

Thanks for the pointers, anyway!

- Stephan

------------------------------------------------------------------------
Wing IDE for Python                          Archaeopteryx Software, Inc
www.wingide.com                              Take Flight!

Stephan R.A. Deibel wrote:
> Are there any plans that anyone here knows of to recognize lists
> in the following form in reST?
> 
> 1 Top level
>   1.1 Next level
>   1.2 Another item

That's the first entry in the "... Or Not To Do?" list (with a
trailing "."): <http://docutils.sf.net/spec/rst/alternatives.html>::

    Allow for compound enumerators, such as "1.1." or "1.a." or
    "1(a)", to allow for nested enumerated lists without indentation?

It hasn't found a champion or much interest.

> Also, would this be in contradiction with the accepted spec for
> what reST is?

I wouldn't be averse to including it, were a well-implemented patch to
appear.  I'm not interested enough to write it though.

> (BTW, what I'm doing is creating a table of contents on my own
> because I'm dynamically assembling it to span many reST docs and
> possibly other resources that get presented to the user as if they
> were one doc).

Perhaps what you want is the "include" directive, and a master
document::

    =======================
     Master Document Title
    =======================

    .. contents::

    .. include:: part1.txt
    .. include:: part2.txt
    .. include:: part3.txt

This will merge several source files and process them as one.  The
table of contents can now be automatically generated.  Eventually
there will be a mechanism to split up that one large document into
several smaller ones, with navigation in-between (see
<http://docutils.sf.net/spec/notes.html#document-splitting>), but it
hasn't been implemented yet.

-- 
David Goodger  <go...@py...>  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,

Are there any plans that anyone here knows of to recognize lists
in the following form in reST?

1 Top level
  1.1 Next level
  1.2 Another item
2 Next Top Level
  2.1 Again
    2.1.1 Third level
    2.1.2 And so forth
  2.2 And so forth

This doesn't seem to work now even if I add '.' after the #.#'s.

Also, would this be in contradiction with the accepted spec for
what reST is?

(BTW, what I'm doing is creating a table of contents on my own because
I'm dynamically assembling it to span many reST docs and possibly other
resources that get presented to the user as if they were one doc).

Thanks for any info!

- Stephan

------------------------------------------------------------------------
Wing IDE for Python                          Archaeopteryx Software, Inc
www.wingide.com                              Take Flight!

David Abrahams wrote:
> I can think of one way to beautify cases like this: introduce a kind
> of quotation which removes all spaces in what it surrounds as a
> postprocessing step.
> 
>     ''*re* ``Structured`` *Text''
> 
> This would be analogous to re.VERBOSE, if memory serves.

I'll add it to the character processing discussion in the To Do list,
but I doubt the feature is worth the cost.

-- David Goodger    go...@py...

David Abrahams <da...@bo...> writes:

> I can think of one way to beautify cases like this: introduce a kind
> of quotation which removes all spaces in what it surrounds as a
> postprocessing step.
>
>      ''*re* ``Structured`` *Text''

Oops.

      ''*re* ``Structured`` *Text*''
                                 ^
of course.

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

David Goodger <go...@py...> writes:

> [David Abrahams]
>> Rock me, Amadeus.
>
> Never thought I'd hear that again.  Now I kinda wish I hadn't.

Sorry ;-)

>>> I don't see a good way to allow for arbitrary text *before* inline
>>> markup though.  Is there a need?  We can't use a simple backslash,
>>> since that says "the following is *not* markup".
>> 
>> But... inline markup doesn't happen within markup does it?
>
> Inline markup doesn't nest.  Is that what you mean?

Yeah.

>> the simple backslash outside of markup could mean "begin markup" if it
>> precedes "``".
>> 
>> 'course I'm probably missing something.
>
> The main reason for backslash-escapes to exist is to *prevent* markup
> recognition when it's not wanted::
>
>     Various forms of \*ML abound.
>
> The backslash "escapes" the normal meaning of whatever follows it.  In this
> case::
>
>     Use brackets for Python ``list``\s
>
> we've extended the meaning of the backslash to escape the normal "text"
> meaning of the "s" to make it into a word-boundary.  To do the same thing
> before the inline markup, I can only think of introducing a "disappearing
> escape sequence", like this:
>
>     *re*\'``Structured``\'*Text*
>     (italic "re" + monospaced "Structured" + italic "Text")
>
> That's awfully ugly though.

It could be worse.

I can think of one way to beautify cases like this: introduce a kind
of quotation which removes all spaces in what it surrounds as a
postprocessing step.

     ''*re* ``Structured`` *Text''

This would be analogous to re.VERBOSE, if memory serves.

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

[David Goodger]
>> So I've checked it in.  Available now from CVS or in 20 minutes from
>> the snapshot.

[David Abrahams]
> Rock me, Amadeus.

Never thought I'd hear that again.  Now I kinda wish I hadn't.

>> I don't see a good way to allow for arbitrary text *before* inline
>> markup though.  Is there a need?  We can't use a simple backslash,
>> since that says "the following is *not* markup".
> 
> But... inline markup doesn't happen within markup does it?

Inline markup doesn't nest.  Is that what you mean?

> the simple backslash outside of markup could mean "begin markup" if it
> precedes "``".
> 
> 'course I'm probably missing something.

The main reason for backslash-escapes to exist is to *prevent* markup
recognition when it's not wanted::

    Various forms of \*ML abound.

The backslash "escapes" the normal meaning of whatever follows it.  In this
case::

    Use brackets for Python ``list``\s

we've extended the meaning of the backslash to escape the normal "text"
meaning of the "s" to make it into a word-boundary.  To do the same thing
before the inline markup, I can only think of introducing a "disappearing
escape sequence", like this:

    *re*\'``Structured``\'*Text*
    (italic "re" + monospaced "Structured" + italic "Text")

That's awfully ugly though.

-- 
David Goodger  <go...@py...>  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 Ascher wrote:
> Is there already something somewhere that does that?

Indeed there is.  Use an internal hyperlink target::

    .. _permanent name:

    Requirement 123123: This part may change
    ----------------------------------------

    Ordinary text here.

The target text will be converted to an ID by lowcasing and converting
all punctuation and whitespace to dashes.  The above target could be
referred to as:

    http:/.../foo.html#permanent-name

The form of the permanent name can be whatever you like.

-- 
David Goodger  <go...@py...>  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 <go...@py...> writes:

> [David Abrahams]
>> When I try your workaround I still get a grammatically incorrect
>> apostrophe in the word "lists".
>
> The apostrophe was inserted to provide a word boundary, but has no
> other meaning as markup.  In other words, it's not supposed to
> disappear, so it doesn't.
>
>> Would it break anything if you added the backslash to the list of
>> "certain punctuation characters"?  That way, I could write
>> ``list``\s and get exactly the effect I want.
>
> [David Goodger]
>> Interesting idea.  May work.  I'll have to think it through.  There
>> may be adverse side-effects due to the way backslash-escapes are
>> handled internally (they're converted to \x00 null bytes, which I've
>> always thought was a bit of a kludge, but it's worked thus far).
>
> I tried it, it does work, and I can't think of any nasty side-effects.
> This neat trick allows for arbitrary text after inline markup:
>
>     Those bracketed expressions are Python ``list``\s.
>
> So I've checked it in.  Available now from CVS or in 20 minutes from
> the snapshot.

Rock me, Amadeus.

> I don't see a good way to allow for arbitrary text *before* inline
> markup though.  Is there a need?  We can't use a simple backslash,
> since that says "the following is *not* markup".

But... inline markup doesn't happen within markup does it?

the simple backslash outside of markup could mean "begin markup" if it
precedes "``".

'course I'm probably missing something.

>  Perhaps a certain
> escape sequence can be defined as "disappearing", like "\-" or "\." or
> "\'".  ("\ " has already been proposed as a way to indicate
> non-breaking space; not implemented yet.  After looking this up, it
> seems the "disappearing" idea isn't new either:
> <http://docutils.sf.net/spec/notes.html#character-processing>.)


> -- 
> David Goodger  <go...@py...>  Open-source projects:
>   - Python Docutils: http://docutils.sourceforge.net/
>     (includes reStructuredText: http://docutils.sf.net/rst.html)
>   - The Go Tools Project: http://gotools.sourceforge.net/
>
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by:
> With Great Power, Comes Great Responsibility 
> Learn to use your power at OSDN's High Performance Computing Channel
> http://hpc.devchannel.org/

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

In some documents, I'd like the id tags associated with anchors to remain 
constant in the face of section name changes.  In other words, I'd like to mark up

Requirement 123123: This part may change
----------------------------------------

With something, so that I could always refer to http:/.../foo.html#something

and have it point to the <a> tag which docutils currently generates with the 
id "requirement-this-part-may-change" or something like that.

A proposal would be to use markup like:

	#permanent: Changeable title

which would produce:

	<div class="section" id="permanent">
	<h1>
	<a id="permanent" name="changeable-title">permanent: Changeable 	title</a>
	</h1>

Is there already something somewhere that does that?

--david

David Ascher wrote:
> I'm trying to bundle together a python script that uses docutils
> using Gordon McMillan's Installer tool.  The standard code analysis
> is missing some files.

There are some dynamic imports in the code, but only of modules within
the Docutils package.  A simple list of all files should suffice.

> Has someone written a hook file for docutils yet?

Not that I know of.  But I've never used the McMillan Installer.

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

Tony Vignaux wrote:
> I am using reST to produce html with html.py. One of the author
> names I need to produce is Muller with an u-umlaut(i.e. in html:
> Müller). I assume I can use some sort of substitution but I
> seem to have missed it in the documentation. How do I do it in ReST?

You don't need to use substitutions or entities for accented
characters.  Just tell Docutils the encoding of the input file (and
the desired encoding of the output; default UTF-8).  Use the
"--input-encoding" command-line option, or set it up permanently in a
configuration file.  See <http://docutils.sf.net/docs/tools.html> for
details.

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

Beni Cherniavsky wrote:
>>   <document source="<stdin>">
>>       <bullet_list bullet="*">
>
> Never thought that the bullet is recorded of the DOM.  doctree.html
> confirms that and notes that it may be ignored in processing.
> What's the implication?

It's just stored there to help round-trip conversion.  From PEP 258:

    The DTD retains all information necessary to reconstruct the
    original input text, or a reasonable facsimile thereof.

> Is it ignored currently?

Yes.  I don't think it's used for anything now.

> Will it?

It may be used for text-output Writers, such as the one Stephan Diebel
reported on here a few days ago.

> Are there any guidelines in choosing bullets when writing rST?

Not really.  I like * for first-level, and - for lower levels.  But
that's just me.

-- 
David Goodger  <go...@py...>  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 bundle together a python script that uses docutils using Gordon 
McMillan's Installer tool.  The standard code analysis is missing some files.

Has someone written a hook file for docutils yet?

--david

I am using reST to produce html with html.py. One of the author names I need to produce is 
Muller with an u-umlaut(i.e. in html: Müller). I assume I can use some sort of 
substitution but I seem to have missed it in the documentation. How do I do it in ReST?

Tony Vignaux

On 2002-12-16, David Goodger wrote:

>   <document source="<stdin>">
>       <bullet_list bullet="*">
>
Never thought that the bullet is recorded of the DOM.  doctree.html
confirms that and notes that it may be ignored in processing.  What's the
implication?  Is it ignored currently?  Will it?  Are there any guidelines
in choosing bullets when writing rST?

-- 
Beni Cherniavsky <cb...@tx...>

On Monday 16 December 2002 08:38 pm, David Goodger wrote:
> I looked at the DeveloperWorks tutorial DTD (dwtut.dtd) and
> supporting docs.  It seems quite straightforward: a custom set of
> structural elements wrapping an HTML core.  It would require a few
> directives (like "example-column", "image-column", perhaps
> "xml-listing" etc.) and a mapping of document -> tutorial, top-level
> section -> section, next-level section -> panel.  Ideally the
> Toot-O-Matic Writer component should check that no unsupported
> elements are present (lower-level sections, tables, etc.).  It looks
> doable.  You may want to subclass the writers/html4css1.py module,
> although your XML is so different that copy&paste may be easier.
>  I'll be happy to answer any questions.

Great. You've confirmed my impressions. Thank you. I'll plan to work on 
this as I have time available.

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

David Abrahams wrote:
> Ouch, that didn't work:

Forgot to mention that the nested list requires a blank line before
& after.  Only blank lines between items are optional.

If you haven't read the Primer, please do:
<http://docutils.sf.net/docs/rst/quickstart.html#lists>.  If you
have read it, maybe you should read it again. ;)

-- 
David Goodger  <go...@py...>  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 <go...@py...> writes:

> David Abrahams wrote:
>> When I format the following as HTML with the current CVS
>> 
>> ---
>> * User Guided wrapping
>>    * Require minimal user intervention
>>    * But intervention must be possible when needed
>> ---
>> 
>> It looks like:
>> 
>> ---
>> *
>>         User Guided wrapping
>>                 * Require minimal user intervention
>>                 * But intervention must be possible when needed
>> ---
>> 
>> Is that to be expected?
>
> Pretty much.  The indentation of nested lists is critical.  It's informative
> to see how the parser interprets this input.  I use the command::
>
>     python tools/quicktest.py
>
> And feed the above as input to stdin, this is what comes out
> (wrapped a bit)::
>
>     <document source="<stdin>">
>         <bullet_list bullet="*">
>             <list_item>
>                 <definition_list>
>                     <definition_list_item>
>                         <term>
>                             User Guided wrapping
>                         <definition>
>                             <bullet_list bullet="*">
>                                 <list_item>
>                                     <paragraph>
>                                         Require minimal user
>                                         intervention
>                                 <list_item>
>                                     <paragraph>
>                                         But intervention must be
>                                         possible when needed
>
> You've got a bullet list item containing a definition list item
> containing a bullet list in the definition.  Reduce the indentation of
> lines 2 & 3 by one space each and I think you'll get what you want.

Ouch, that didn't work:

quicktest.py results:

<document source="<stdin>">
    <bullet_list bullet="*">
        <list_item>
            <paragraph>
                User Guided wrapping
                * Require minimal user intervention
                * But intervention must be possible when needed

--

HTML snippet:

<div class="document">
<ul class="simple">
<li>User Guided wrapping
* Require minimal user intervention
* But intervention must be possible when needed</li>
</ul>
</div>

>> Why the CR after the initial bullet?
>
> That I can't tell you.  What browser?  

IE6

> What stylesheet?

The one from your tools/ subdirectory

>> The command I used was:
>> 
>>     python /src/docutils/tools/html.py --embed-stylesheet -gdts \
>>         fu.txt fu.html
>
> Was the stylesheet successfully embedded?  Please check.

Yup.

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

I looked at the DeveloperWorks tutorial DTD (dwtut.dtd) and supporting
docs.  It seems quite straightforward: a custom set of structural
elements wrapping an HTML core.  It would require a few directives
(like "example-column", "image-column", perhaps "xml-listing" etc.)
and a mapping of document -> tutorial, top-level section -> section,
next-level section -> panel.  Ideally the Toot-O-Matic Writer
component should check that no unsupported elements are present
(lower-level sections, tables, etc.).  It looks doable.  You may want
to subclass the writers/html4css1.py module, although your XML is so
different that copy&paste may be easier.  I'll be happy to answer any
questions.

-- 
David Goodger  <go...@py...>  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 Abrahams wrote:
> When I format the following as HTML with the current CVS
> 
> ---
> * User Guided wrapping
>    * Require minimal user intervention
>    * But intervention must be possible when needed
> ---
> 
> It looks like:
> 
> ---
> *
>         User Guided wrapping
>                 * Require minimal user intervention
>                 * But intervention must be possible when needed
> ---
> 
> Is that to be expected?

Pretty much.  The indentation of nested lists is critical.  It's informative
to see how the parser interprets this input.  I use the command::

    python tools/quicktest.py

And feed the above as input to stdin, this is what comes out
(wrapped a bit)::

    <document source="<stdin>">
        <bullet_list bullet="*">
            <list_item>
                <definition_list>
                    <definition_list_item>
                        <term>
                            User Guided wrapping
                        <definition>
                            <bullet_list bullet="*">
                                <list_item>
                                    <paragraph>
                                        Require minimal user
                                        intervention
                                <list_item>
                                    <paragraph>
                                        But intervention must be
                                        possible when needed

You've got a bullet list item containing a definition list item
containing a bullet list in the definition.  Reduce the indentation of
lines 2 & 3 by one space each and I think you'll get what you want.

> Why the CR after the initial bullet?

That I can't tell you.  What browser?  What stylesheet?

> The command I used was:
> 
>     python /src/docutils/tools/html.py --embed-stylesheet -gdts \
>         fu.txt fu.html

Was the stylesheet successfully embedded?  Please check.

-- 
David Goodger  <go...@py...>  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 Abrahams]
> When I try your workaround I still get a grammatically incorrect
> apostrophe in the word "lists".

The apostrophe was inserted to provide a word boundary, but has no
other meaning as markup.  In other words, it's not supposed to
disappear, so it doesn't.

> Would it break anything if you added the backslash to the list of
> "certain punctuation characters"?  That way, I could write
> ``list``\s and get exactly the effect I want.

[David Goodger]
> Interesting idea.  May work.  I'll have to think it through.  There
> may be adverse side-effects due to the way backslash-escapes are
> handled internally (they're converted to \x00 null bytes, which I've
> always thought was a bit of a kludge, but it's worked thus far).

I tried it, it does work, and I can't think of any nasty side-effects.
This neat trick allows for arbitrary text after inline markup:

    Those bracketed expressions are Python ``list``\s.

So I've checked it in.  Available now from CVS or in 20 minutes from
the snapshot.

I don't see a good way to allow for arbitrary text *before* inline
markup though.  Is there a need?  We can't use a simple backslash,
since that says "the following is *not* markup".  Perhaps a certain
escape sequence can be defined as "disappearing", like "\-" or "\." or
"\'".  ("\ " has already been proposed as a way to indicate
non-breaking space; not implemented yet.  After looking this up, it
seems the "disappearing" idea isn't new either:
<http://docutils.sf.net/spec/notes.html#character-processing>.)

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

When I format the following as HTML with the current CVS

---
* User Guided wrapping
   * Require minimal user intervention
   * But intervention must be possible when needed
---

It looks like:

---
*
        User Guided wrapping
                * Require minimal user intervention
                * But intervention must be possible when needed

---

Is that to be expected?  Why the CR after the initial bullet?

The command I used was:

    python /src/docutils/tools/html.py --embed-stylesheet -gdts fu.txt fu.html 


Thanks,

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

Stephan R.A. Deibel wrote:
> If this looks like something potentially useful for the docutils project,
> please let me know and I can clean it up and contribute it.

Haven't looked at the code yet, but it sounds very cool.  Yes, please, and
thank you!

-- David Goodger    go...@py...

David Abrahams wrote:
> Thanks for your reply.  When I try your workaround I still get a
> grammatically incorrect apostrophe in the word "lists".  Would it
> break anything if you added the backslash to the list of "certain
> punctuation characters"?  That way, I could write ``list``\s and get
> exactly the effect I want.

Interesting idea.  May work.  I'll have to think it through.  There
may be adverse side-effects due to the way backslash-escapes are
handled internally (they're converted to \x00 null bytes, which I've
always thought was a bit of a kludge, but it's worked thus far).

-- David Goodger    go...@py...