docutils-users — General discussions, questions, help requests.

[Docutils-users] BackTalk-like Product Using ReST

[Mohsen M. <mo...@sc...>]

Hello !

I am investigating the feasibility of developing a BackTalk-like
Zope product using ReST. Zope BackTalk [1]_ product allows 
readers of the content to make inline comments on the content
they are reading. It's used to develope online versions of Zope
and Zope-Dev books [2]. BackTalk uses STX as its internal
format. The inline comments are just some "in-place" paragraphs
with special format which makes them distinguishable from the
main content.

. [1] http://backtalk.sourceforge.net/
. [2] http://www.zope.org/Documentation/Books/ZopeBook/

While it's just a little time since I started learning ReST,
I found it a more convenient tool to achieve the same purpose.
Here are two main advantages for using ReST instead of STX 
in this regard:

- Inline-comments can be separated from the main content by using
  substitution directives. This makes further edition of the main 
  content easier and more error-prune.

- Inline-comments can be nested. A user can comment another's 
  comment. This feature is not provides by BackTalk where all
  comments live in the same level.

Okay, here I am going to share my idea about the way a product
like that can be developed using ReST. It's just my idea and 
my main intention is to seek others feedbacks and ideas.

The first step must be adding a directive for inline comments.
Let's call it quote for now. The quote directive is used
in the following example::

 some main content
 some main content

 .. quote::
    :id: 1
    :author: Mohsen
    :date: 2003-07-16T19:20:30+01:00

    Good Idea
    But Also mention Blah

    .. quote::
       :id: 2
       :author: John
       :date: 2003-07-17T15:47:30+01:00

       agree with mohsen

 .. quote::
    :id: 3
    :author: Aida
    :date: 2004-01-16T19:20:30+01:00

    I don't like it

There are 3 comments in the example. Comment 2 answers
comment 1 while comment 3 is in the same level as comment 1.
Okay so far so good. 

Next step would be developing a python module to manipulate quote
directives. An interface like this can be considered::

  def quote_paragraph(src, p_id, quote, author, date):
      """ Places a quote on paragraph p_id;
          src is the ReST source
      """

  def quote_quote(src, q_id, quote, author, date):
      """ Places a quote on quote q_id;
          quote Ids in the above example are 1, 2 and 3        
      """
          
  def edit_quote(src, q_id, quote, author, date):
      """ Updating quote q_id """

  def remove_quote(src, q_id):
      """ Deleting quote q_id """


And the final step would be developing a Zope Product (*QReST* 
for *Quoted ReST* ?) based on this module, which does the real
thing.

And Here are some questions which I am interested to know:

- Firstly if I make sense at all in this regard? Is this the/a
  right way?

- Secondly, in quote_paragraph function above, you have paragraph
  id as p_id. I doubt ReST paragraphs have any id. Any idea on how
  to distinguish paragraphs?

- Lastly, There should be a "Quote" mark after each **paragraph**
  or **quote** in the rendered *QReST* content. The user clicks
  on this mark to quote the paragraph or the quote just above. How
  one can insert this quote marks after each paragraph. Does it
  need writing a brand new "writer" which outputs a quote mark in
  the appropriate places or is there easier way for that.

Cheers,
Mohsen,

Re: [Docutils-users] example extraction and testing

[David A. <da...@bo...>]

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

> David Abrahams wrote:
>  > Not yet.  Tell you what, though: you're going to have a hard time
>  > convincing me it's worth trying to do that, now that I have this
>  > beautiful comment interpretation syntax:
>  >
>  > .. @ example.append('typedef two_pointers<int>::type intstar2;')
>  >      compile(all = True, expect_error = True, save = -1)
>  >
>  > I'm so pleased with the system now that I think I'd rather fight
>  > than switch ;-)
>
> Just don't try to check that into the codebase! :-)
> In sandboxes anything goes, of course.

It's totally non-intrusive.  I don't have the slightest desire to put
it in your repository!

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] example extraction and testing

[David G. <go...@py...>]

David Abrahams wrote:
 > Not yet.  Tell you what, though: you're going to have a hard time
 > convincing me it's worth trying to do that, now that I have this
 > beautiful comment interpretation syntax:
 >
 > .. @ example.append('typedef two_pointers<int>::type intstar2;')
 >      compile(all = True, expect_error = True, save = -1)
 >
 > I'm so pleased with the system now that I think I'd rather fight
 > than switch ;-)

Just don't try to check that into the codebase! :-)
In sandboxes anything goes, of course.

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

Re: [Docutils-users] example extraction and testing

[David A. <da...@bo...>]

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

> Get it?  I'd be pleasantly surprised if you did, first time; I always
> have to read through the docstrings a couple of times to get all the
> connections straight.  Read it through again, maybe twice, then ask
> away.

Not yet.  Tell you what, though: you're going to have a hard time
convincing me it's worth trying to do that, now that I have this
beautiful comment interpretation syntax:

.. @ example.append('typedef two_pointers<int>::type intstar2;')
     compile(all = True, expect_error = True, save = -1)

I'm so pleased with the system now that I think I'd rather fight than
switch ;-)

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] example extraction and testing

[David G. <go...@py...>]

I just remembered something that should be useful to you.  You've been
using the "raw" directive to get litre-specific output, like this:

     .. raw:: litre

        do.whatever()

But that's really kind of abusing the system.  Even better would be
like this:

     .. litre:: do.whatever()

But how to identify the content as Litre-specific without confusing
all the other Writers?

There's a comparable case with another directive: "meta".  It's a
directive that produces output for HTML only.  The way it works is
like this (it's tricky, so please bear with me):

* The docutils.parsers.rst.directives.html.meta directive function
   hands off parsing to a special-purpose d.p.r.states.SpecializedBody
   subclass, MetaBody, which parses a field list.  Don't worry about
   the details.

* The MetaBody.parsemeta method constructs a "pending" node.  From
   docutils.nodes:

       The "pending" element is used to encapsulate a pending
       operation: the operation (transform), the point at which to
       apply it, and any data it requires.  Only the pending
       operation's location within the document is stored in the public
       document tree (by the "pending" object itself); the operation
       and its data are stored in the "pending" object's internal
       instance attributes.

       For example, say you want a table of contents in your
       reStructuredText document.  The easiest way to specify where to
       put it is from within the document, with a directive::

           .. contents::

       But the "contents" directive can't do its work until the entire
       document has been parsed and possibly transformed to some
       extent.  So the directive code leaves a placeholder behind that
       will trigger the second phase of its processing, something like
       this::

           <pending ...public attributes...> + internal attributes

       Use `document.note_pending()` so that the
       `docutils.transforms.Transformer` stage of processing can run
       all pending transforms.

   docutils.nodes.pending has the following initializer:

     def __init__(self, transform, details=None,
                  rawsource='', *children, **attributes):

   The first two are special: a docutils.transforms.Transform class
   implementing the pending operation, and detail data (dictionary)
   required by the pending operation.  The "meta" directive constructs
   a "pending" node like this:

         pending = nodes.pending(components.Filter,
                                 {'component': 'writer',
                                  'format': 'html',
                                  'nodes': [node]})

   ``node`` is a "meta" node, defined locally, and only known to the
   HTML Writer.

   Your "litre" directive could construct a "pending" node in exactly
   the same way, but with format 'litre' instead of 'html'.  Your
   ``node`` would be the ``litre`` directive's content, as a literal
   block or a litre-specific node of your own making.

* The transform in the last step is the key:
   docutils.transforms.components.Filter.  From its docstring:

       Include or exclude elements which depend on a specific Docutils
       component.

       For use with `nodes.pending` elements.  A "pending" element's
       dictionary attribute ``details`` must contain the keys
       "component" and "format".  The value of ``details['component']``
       must match the type name of the component the elements depend on
       (e.g. "writer").  The value of ``details['format']`` is the name
       of a specific format or context of that component (e.g. "html").
       If the matching Docutils component supports that format or
       context, the "pending" element is replaced by the contents of
       ``details['nodes']`` (a list of nodes); otherwise, the "pending"
       element is removed.

       For example, the reStructuredText "meta" directive creates a
       "pending" element containing a "meta" element (in
       ``pending.details['nodes']``).  Only writers
       (``pending.details['component'] == 'writer'``) supporting the
       "html" format (``pending.details['format'] == 'html'``) will
       include the "meta" element; it will be deleted from the output
       of all other writers.

   You indicate what format your writer supports with the ``supported``
   class attribute, a list of strings to match against.

The end result is, the contents of pending.details['nodes'] will be
included for your Litre Writer, but removed for any other Writer.  The
"pending" node basically hides the Writer-specific stuff until the
Filter transform (which is applied late in the game) can expose it
safely.

Get it?  I'd be pleasantly surprised if you did, first time; I always
have to read through the docstrings a couple of times to get all the
connections straight.  Read it through again, maybe twice, then ask
away.

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

[Docutils-users] Re: example extraction and testing

[David A. <da...@bo...>]

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

>      compile(2); # compile the last two literal blocks together
>
>   That is, *mlt*\ :sup:`-2`.  However, if we want to get dimensions into the
>   type system these arrays won't do the trick: they're all
>   the same type!  Instead we need types that *themselves* represent
>   sequences of numbers, so that two masses have the same type and a
>   mass is a different type from a length.
>
>
> That compile(2) isn't Python's usual compile.  It invokes a C++
> compiler on some subset of the examples the writer has seen before.

Err, but it is Python code.  The semicolon is just an artifact from
bouncing back and forth between languages too quickly ;-)

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] Re: example extraction and testing

[David A. <da...@bo...>]

eng...@ss... writes:

> On Mon, 21 Jun 2004, David Abrahams wrote:
>
>> Aahz <aa...@py...> writes:
>>
>> > On Mon, Jun 21, 2004, David Abrahams wrote:
>> >> Aahz <aa...@py...> writes:
>> >>>
>> >>> What I did was invent my own little ``include-output`` directive for
>> >>> external code -- I think code inside reST files should be kept to a
>> >>> minimum, so that the code is run every time the document is generated.
>> >>> See my sandbox if you're interested.
>> >>
>> >> What I'm worried about with adding a directive is that it will trip up
>> >> ordinary writers unless I go out of my way to make them aware of it.
>> >> My litre tool uses raw becase that directive is ignored unless the
>> >> format (litre) is recognized by the writer.  I wish I was missing
>> >> something here; please tell me I am!  I'd like to make litre's
>> >> intrusion on my ReST as minimal as possible.
>> >
>> > If that's your goal, make sure that the ``litre`` directive emits only
>> > elements found in nodes.py.  IOW, make the ``litre`` directive a
>> > subclass of the ``literal`` directive.
>>
>> Aaaaahz!
>> Very cute trick.
>>
>> But then, how will my writer recognize my litre-generated literal
>> nodes?
>
> couldnt you check for an attribute in literal nodes (class ?).
>
> this way the code parts would be printed literal, and not ignored by
> other writers. a feature not a bug ?

I'm not worried about the literal blocks *themselves*; all literal
blocks are getting handled by litre _right now_.  I need to stick in
material that every other writer will ignore.  For example, here's a
snippet from the book, with embedded litre:

  In general, a composite dimension is the product of powers of
  fundamental dimensions [#divisor]_.  If we were going to represent
  these powers for manipulation at runtime, we could use an array of
  seven ``int``\ s, with each position in the array holding the power
  of a different fundamental dimension::

    typedef int dimension[7]; // m  l  t  ...
    dimension const mass      = {1, 0, 0, 0, 0, 0, 0};
    dimension const length    = {0, 1, 0, 0, 0, 0, 0};
    dimension const time      = {0, 0, 1, 0, 0, 0, 0};
    ...

  .. [#divisor] divisors just contribute negative exponents, since
     1/*x* = *x*\ :sup:`-1`.

  In that representation, force would be::

    dimension const force  = {1, 1, -2, 0, 0, 0, 0};

  .. raw:: litre

     compile(2); # compile the last two literal blocks together

  That is, *mlt*\ :sup:`-2`.  However, if we want to get dimensions into the
  type system these arrays won't do the trick: they're all
  the same type!  Instead we need types that *themselves* represent
  sequences of numbers, so that two masses have the same type and a
  mass is a different type from a length.


That compile(2) isn't Python's usual compile.  It invokes a C++
compiler on some subset of the examples the writer has seen before.

By using a .. raw:: block I accomplish the following:

1. Other writers will be utterly undisturbed by the invocation of
   compile.  They will ignore the raw block because it isn't for them.

2. I don't need to do anything special (such as installing a
   directive) before using a different kind of writer on my ReST.

As far as I know, there's no other syntax besides comments that can
be hijacked in this way.  Now, maybe it would be a good idea to
hijack comments.

.. @compile(2)

would be a whole lot terser, that's for sure.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] section numbering problem

[David G. <go...@py...>]

Peter Dobcsanyi wrote:
 > I am using the most recent docutils-snapshot and having problem with
 > section numbering. In each section header there is some garbage
 > between the number and the actual title.

What you're seeing is not garbage, it's UTF-8-encoded non-breaking
spaces (3 each).

 > As far as I know this problem has been around for quite a while. Am
 > I doing something wrong or this really is a problem.

You have an decoding problem in your browser and/or editor.  The
encoding of the output is set to "utf-8", but your browswer and/or
editor isn't recognizing that.  (Your message looks fine in my email
client, Mozilla; I see 3 spaces between "1" and "First".)  You can
either try to fix your browser (enable "UTF-8 character set",
sometimes called "Unicode"), or choose a different encoding.  If
you're using Python 2.3+, try
"--output-encoding=ascii:xmlcharrefreplace" for HTML (doesn't work for
non-XMLish outputs).

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

[Docutils-users] section numbering problem

[Peter D. <pe...@de...>]

Hi,

I am using the most recent docutils-snapshot and having problem with
section numbering. In each section header there is some garbage
between the number and the actual title. Here is an example:

source:

    hello
    ======

    .. sectnum::
    .. contents::

    First
    ------

    Hello world. Hello world.

result:

    <?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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="generator" content="Docutils 0.3.4: http://docutils.sourceforge.net/" />
    <title>hello</title>
    <link rel="stylesheet" href="default.css" type="text/css" />
    </head>
    <body>
    <h1 class="title">hello</h1>
    <div class="document" id="hello">
    <div class="contents topic" id="contents">
    <p class="topic-title first"><a name="contents">Contents</a></p>
    <ul class="auto-toc simple">
    <li><a class="reference" href="#first" id="id1" name="id1">1   First</a></li>
    </ul>
    </div>
    <div class="section" id="first">
    <h1><a class="toc-backref" href="#id1" name="first">1   First</a></h1>
    <p>Hello world. Hello world.</p>
    </div>
    </div>
    </body>
    </html>

As far as I know this problem has been around for quite a while. Am I
doing something wrong or this really is a problem.

Thanks,
    Peter

Re: [Docutils-users] Help with tables

[<gr...@us...>]

On Tue, 22 Jun 2004, Stephen Boulet wrote:

> The backslash seems to be causing problems. How would I fix the following
> snippet?:
>
> If necessary, you could combine it with find to rename all .phtml files in
> /home/httpd/htdocs to .php
>
> +-------------------------------------------------------------------------+
> | Code Listing 9.3:                                                       |
> | for and find                                                            |
> +-------------------------------------------------------------------------+
  |::                                                                       |
  |                                                                         |
  |  # cd /home/httpd/htdocs                                                |
  +-------------------------------------------------------------------------+

you should use a literal block.

-- 
 BINGO: revolutionary Review

[Docutils-users] Help with tables

[Stephen B. <st...@th...>]

The backslash seems to be causing problems. How would I fix the following 
snippet?:

If necessary, you could combine it with find to rename all .phtml files in 
/home/httpd/htdocs to .php 
 
+-------------------------------------------------------------------------+
| Code Listing 9.3:                                                       |
| for and find                                                            |
+-------------------------------------------------------------------------+
|                                                                         |
|# cd /home/httpd/htdocs                                                  |
|# for n in `find -type f -name '*.phtml'`;  \                            |
|    do mv $n `basename $n .phtml`.php; done                              |
|                                                                         |
+-------------------------------------------------------------------------+

-- 
Stephen      

If your desktop gets out of control easily,
you probably have too much stuff on it that
doesn't need to be there.
         Donna Smallin, "Unclutter Your Home"

Re: [Docutils-users] Re: example extraction and testing

[<eng...@ss...>]

On Mon, 21 Jun 2004, David Abrahams wrote:

> Aahz <aa...@py...> writes:
>
> > On Mon, Jun 21, 2004, David Abrahams wrote:
> >> Aahz <aa...@py...> writes:
> >>>
> >>> What I did was invent my own little ``include-output`` directive for
> >>> external code -- I think code inside reST files should be kept to a
> >>> minimum, so that the code is run every time the document is generated.
> >>> See my sandbox if you're interested.
> >>
> >> What I'm worried about with adding a directive is that it will trip up
> >> ordinary writers unless I go out of my way to make them aware of it.
> >> My litre tool uses raw becase that directive is ignored unless the
> >> format (litre) is recognized by the writer.  I wish I was missing
> >> something here; please tell me I am!  I'd like to make litre's
> >> intrusion on my ReST as minimal as possible.
> >
> > If that's your goal, make sure that the ``litre`` directive emits only
> > elements found in nodes.py.  IOW, make the ``litre`` directive a
> > subclass of the ``literal`` directive.
>
> Aaaaahz!
> Very cute trick.
>
> But then, how will my writer recognize my litre-generated literal
> nodes?

couldnt you check for an attribute in literal nodes (class ?).

this way the code parts would be printed literal, and not ignored by
other writers. a feature not a bug ?

-- 
 BINGO: objects, objects, objects (r.racko)
 --- Engelbert Gruber -------+
  SSG Fintl,Gruber,Lassnig  /
  A6170 Zirl   Innweg 5b   /
  Tel. ++43-5238-93535 ---+

Re: [Docutils-users] Re: example extraction and testing

[Aahz <aa...@py...>]

On Mon, Jun 21, 2004, David Abrahams wrote:
> Aahz <aa...@py...> writes:
>> 
>> If that's your goal, make sure that the ``litre`` directive emits only
>> elements found in nodes.py.  IOW, make the ``litre`` directive a
>> subclass of the ``literal`` directive.
> 
> But then, how will my writer recognize my litre-generated literal
> nodes?

Why should it care how they were generated?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Typing is cheap.  Thinking is expensive."  --Roy Smith, c.l.py

Re: [Docutils-users] Re: example extraction and testing

[David A. <da...@bo...>]

Aahz <aa...@py...> writes:

> On Mon, Jun 21, 2004, David Abrahams wrote:
>> Aahz <aa...@py...> writes:
>>> 
>>> What I did was invent my own little ``include-output`` directive for
>>> external code -- I think code inside reST files should be kept to a
>>> minimum, so that the code is run every time the document is generated.
>>> See my sandbox if you're interested.
>> 
>> What I'm worried about with adding a directive is that it will trip up
>> ordinary writers unless I go out of my way to make them aware of it.
>> My litre tool uses raw becase that directive is ignored unless the
>> format (litre) is recognized by the writer.  I wish I was missing
>> something here; please tell me I am!  I'd like to make litre's
>> intrusion on my ReST as minimal as possible.
>
> If that's your goal, make sure that the ``litre`` directive emits only
> elements found in nodes.py.  IOW, make the ``litre`` directive a
> subclass of the ``literal`` directive.

Aaaaahz!
Very cute trick.

But then, how will my writer recognize my litre-generated literal
nodes?

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] Re: example extraction and testing

[Aahz <aa...@py...>]

On Mon, Jun 21, 2004, David Abrahams wrote:
> Aahz <aa...@py...> writes:
>> 
>> What I did was invent my own little ``include-output`` directive for
>> external code -- I think code inside reST files should be kept to a
>> minimum, so that the code is run every time the document is generated.
>> See my sandbox if you're interested.
> 
> What I'm worried about with adding a directive is that it will trip up
> ordinary writers unless I go out of my way to make them aware of it.
> My litre tool uses raw becase that directive is ignored unless the
> format (litre) is recognized by the writer.  I wish I was missing
> something here; please tell me I am!  I'd like to make litre's
> intrusion on my ReST as minimal as possible.

If that's your goal, make sure that the ``litre`` directive emits only
elements found in nodes.py.  IOW, make the ``litre`` directive a
subclass of the ``literal`` directive.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Typing is cheap.  Thinking is expensive."  --Roy Smith, c.l.py

[Docutils-users] Re: example extraction and testing

[David A. <da...@bo...>]

Aahz <aa...@py...> writes:

> What I did was invent my own little ``include-output`` directive for
> external code -- I think code inside reST files should be kept to a
> minimum, so that the code is run every time the document is generated.
> See my sandbox if you're interested.

What I'm worried about with adding a directive is that it will trip up
ordinary writers unless I go out of my way to make them aware of it.
My litre tool uses raw becase that directive is ignored unless the
format (litre) is recognized by the writer.  I wish I was missing
something here; please tell me I am!  I'd like to make litre's
intrusion on my ReST as minimal as possible.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] example extraction and testing

[David A. <da...@bo...>]

Aahz <aa...@py...> writes:

> On Sat, Jun 19, 2004, David Abrahams wrote:
>> 
>> I want to test all the code snippets in ReST files that are full of
>> C++ examples.  Some of the examples are of course only partials.  I've
>> been thinking about implementing a (parsed) literal block extraction
>> writer plus something that processes comments beginning with, say, '@'
>> by executing them as python code... but I don't want to reinvent the
>> wheel.  If there's something suitable already hanging around out
>> there, please tell me so!
>
> What I did was invent my own little ``include-output`` directive for
> external code -- I think code inside reST files should be kept to a
> minimum, so that the code is run every time the document is generated.
> See my sandbox if you're interested.

Nice, but not what I'm after.  Your jobbies insert ReST into the
document stream; I'm interested in extracting bits of ReST (in literal
blocks) and sending them through compilers, etc.  It looks like the

.. raw:: litre 

   do.whatever()

directive is working pretty well, but I guess it would be
a lot terser if I had a custom directive to work with:

.. litre:: do.whatever()

Maybe I'll look at your code for ways to do that.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] example extraction and testing

[Aahz <aa...@py...>]

On Sat, Jun 19, 2004, David Abrahams wrote:
> 
> I want to test all the code snippets in ReST files that are full of
> C++ examples.  Some of the examples are of course only partials.  I've
> been thinking about implementing a (parsed) literal block extraction
> writer plus something that processes comments beginning with, say, '@'
> by executing them as python code... but I don't want to reinvent the
> wheel.  If there's something suitable already hanging around out
> there, please tell me so!

What I did was invent my own little ``include-output`` directive for
external code -- I think code inside reST files should be kept to a
minimum, so that the code is run every time the document is generated.
See my sandbox if you're interested.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Typing is cheap.  Thinking is expensive."  --Roy Smith, c.l.py

Re: [Docutils-users] table syntax (usage of "-"-char)?

[David G. <go...@py...>]

chr...@e-... wrote:
 > i want to use ReST text inside of XML comments
...
 > tables on on the other hand are more problematic as docutils seem to
 > handle only the following markup

There's an alternate table syntax, simple tables
(http://docutils.sf.net/docs/ref/rst/restructuredtext.html#simple-tables):

     ===  ===
      1    2
     ===  ===
      1    2
      1    2
     ===  ===

Lines of hyphens ("-") are used for column spans, but if you don't
have any, you'll be OK.

 > (what i read from the docs that the docutils syntax comes from the
 > emacs table module.)

They were developed independently and without knowledge of each other.
That they use the same (or similar) syntax is either coincidence or
evidence that the syntax is obvious.

 > but for XML comments i would like to use "~" instead of "-" ("~"
 > seemed the most logical character, any other would be fine too)
...
 > would it be possible to tweak or add a replacement character for the
 > "-" char?

Possible, yes.  I see three implementation possibilities:

1. Make the table syntax characters into "table" directive options.
    This is the most flexible but most difficult, and we probably don't
    need that much flexibility.

2. Substitute "~" for "-" with a specialized directive option
    (e.g. ":tildes:").

3. Make the standard table syntax recognize "~" as well as "-", even
    without a directive option.  Individual tables would have to be
    internally consistent.

Directive options are preferable to configuration settings, because
tables are document-specific.  A pragma directive would be another
approach, to set the syntax once for a whole document.

I'll add this to the to-do list
(http://docutils.sf.net/docs/dev/todo.html).  Can't say when it will
be implemented though.  Contributions welcome!

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

[Docutils-users] table syntax (usage of "-"-char)?

[<chr...@e-...>]

hello,
i just finished the really exhausting but good to read documentation for =
docutils. great work! for a project i am working on i was looking for a =
kind of wiki-style markup thing and docutils is certainly more than what =
i'd hoped for.


there is one question i have though (for the moment at least):

i want to use ReST text inside of XML comments (in this special case in =
XSLT comments to generate an xsldoc). this does work reasonbably well =
(even before i read the docutils doc ;).=20
ReST being inside an XML comment does have one major limitation as there =
in XML there are no two or more "-" characters allowed directly after =
another. this is easy to come by with headline or transition markup, i =
can just use other characters like "~" or "_".

tables on on the other hand are more problematic as docutils seem to =
handle only the following markup

+---+---+
| 1 | 2 |
+=3D=3D=3D+=3D=3D=3D+
| 1 | 2 |
+---+---+
| 1 | 2 |
+---+---+

(what i read from the docs that the docutils syntax comes from the emacs =
table module.)
but for XML comments i would like to use "~" instead of "-" ("~"  seemed =
the most logical character, any other would be fine too)

+~~~+~~~+
| 1 | 2 |
+=3D=3D=3D+=3D=3D=3D+
| 1 | 2 |
+~~~+~~~+
| 1 | 2 |
+~~~+~~~+

would it be possible to tweak or add a replacement character for the "-" =
char?=20
or is there any workaround i was just to blind to find?

thanks a lot
chris

Re: [Docutils-users] Re: example extraction and testing

[<gr...@us...>]

On Sun, 20 Jun 2004, David Abrahams wrote:

> Michele Simionato <mic...@pa...> writes:
>
> > OTOH, having a standard solution as Dave Abrahams would like is not such a
> > bad idea. I leave others discuss on that
>
> What I did was to build a simple writer/translator pair that hijacks
> the "raw" directive.
>
> If I write:
>
>   .. raw:: python
>
>      # python code goes here
>
> in my ReST document, the Python code executes in the context of a
> method of my writer.  I can use that to add any example processing I
> want to the file.  As a shortcut, I'm also responding to:
>
>   .. raw:: c++
>
>      // C++ code goes here
>
> which inserts C++ code into my example stream that doesn't show up in
> any literal block.  Combined with storing up the text in literal
> blocks I can build just about any kind of literate programming system
> I could want.  It's working pretty well so far.

whatfore is the programming language statement.

literate programming like noweb, e.g. ::

  .. raw:: <<test.cpp>>

     <<includes>>
     <<main>>

  .. raw:: <<includes>>

     #include this

weaving would be done with docutils.

tangling is another programm, ``.. raw:: <<x>>`` corresponds to
nowebs ``<<x>>=`` AFAIR. with the assumption that top chunks that
could be files are files.

noweb chunks end on ``@`` these would on indentation end.

but noweb chunk ends can take identifiers, which tells noweave that
these are defined in this chunk, and noweave marks them for indexing
in all chunks. these need to go into ::

  .. raw:: <<main variables>>
     :defs: i filename

cheers

-- 
 BINGO: objects, objects, objects (r.racko)

[Docutils-users] Re: example extraction and testing

[David A. <da...@bo...>]

Michele Simionato <mic...@pa...> writes:

> OTOH, having a standard solution as Dave Abrahams would like is not such a
> bad idea. I leave others discuss on that

What I did was to build a simple writer/translator pair that hijacks
the "raw" directive.

If I write:

  .. raw:: python

     # python code goes here

in my ReST document, the Python code executes in the context of a
method of my writer.  I can use that to add any example processing I
want to the file.  As a shortcut, I'm also responding to:

  .. raw:: c++

     // C++ code goes here

which inserts C++ code into my example stream that doesn't show up in
any literal block.  Combined with storing up the text in literal
blocks I can build just about any kind of literate programming system
I could want.  It's working pretty well so far.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

Re: [Docutils-users] Re: example extraction and testing

[David G. <go...@py...>]

Michele Simionato wrote:
> BTW, does reST have a directive to include blocks of code

Yes,

     .. include:: path/to/file
        :literal:

See <http://docutils.sf.net/docs/ref/rst/directives.html#include>

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

[Docutils-users] Re: example extraction and testing

[Michele S. <mic...@pa...>]

David Abrahams wrote:

> I want to test all the code snippets in ReST files that are full of
> C++ examples.  Some of the examples are of course only partials.  I've
> been thinking about implementing a (parsed) literal block extraction
> writer plus something that processes comments beginning with, say, '@'
> by executing them as python code... but I don't want to reinvent the
> wheel.  If there's something suitable already hanging around out
> there, please tell me so!
>
> Thanks,
> Dave
>
>  
>
I have done it, but for Python snippets, not for C++ examples.
I have a script called doct.py that scans a reStructuredText source
and extracts blocks of Python code of the form

#<modulename.py>
...
#</modulename.py>

(it just uses a regular expression for it).

Then it runs all the code starting with >>> by using doctest. Here is an
example assuming you are writing an article teaching new-style classes:

Section 1: About type/class unification
------------------------------------------------------

In this section we will show a possible way to recognize
new-style classes (more bla-bla).

::

 #<type_class.py>

 def isnewstyle(obj):
     try: #some objects may lack a __class__ attribute
         obj.__class__
     except AttributeError:
         return False
     else: #look if there is unification type/class
         return type(obj) is obj.__class__

 #</type_class.py>

 >>> from type_class import isnewstyle
 >>> class C: pass
....
 >>> isnewstyle(C)
False
 >>> class C(object): pass
...
True

I run the article and I make sure that all the tests pass before submitting
the article for publication. Idem when I write docs about modules I write.
For what concerns C++, you can do the same way, you just have to
take care of compilation issues that will slow down the process.

BTW, does reST have a directive to include blocks of code and if not, 
should it
be considered ? BTW, I think this has been discussed in the past.  I am 
quite
happy with my home-grown solution and want to keep reST simple.

OTOH, having a standard solution as Dave Abrahams would like is not such a
bad idea. I leave others discuss on that


                Michele Simionato

[Docutils-users] example extraction and testing

[David A. <da...@bo...>]

I want to test all the code snippets in ReST files that are full of
C++ examples.  Some of the examples are of course only partials.  I've
been thinking about implementing a (parsed) literal block extraction
writer plus something that processes comments beginning with, say, '@'
by executing them as python code... but I don't want to reinvent the
wheel.  If there's something suitable already hanging around out
there, please tell me so!

Thanks,
Dave

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com