Docutils: Documentation Utilities

Gerrit Holl wrote:
> are there easier ways to create tables that to do it by hand or learn
> Emacs (Vim-user speaking)? E.g., does there exist a tool that converts
> for example a HTML table to a ReST table? I'm having a table with 15
> columns and 9 rows, which is not exactly comfortable in ReST...

Hmm, I now used a Simple Table (which isn't comfortable either, but doable),
but somehow question marks get aligned at the bottom of a cell:

=========== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== =====
kmol/uur    1     2     3     4     5     6     7     8     9     10    11    12    13    14
=========== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== =====
synthesegas 100   200   100   0     0     0     0     0     100   100   ???   0     0     0
methanol    0     0     198   198   198   198   198   0     0     0     0     0     0     0
water       0     0     99    99    99    0     0     ???   0     0     0     0     99    0
heavy ends  0     0     0,5   0,5   0,5   0,5   0     0     0     0     0     0     0     0,5
light ends  0     0     0,5   0,5   0     0     0     0     0     0     0     0,5   0     0
totaal      100   200   398   298   297,5 199,5 198   ???   100   100   ???   0,5   99    0,5
=========== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== ===== =====

How come?

yours,
Gerrit.

-- 
63. If he transform waste land into arable fields and return it to its
owner, the latter shall pay him for one year ten gur for ten gan.
          -- 1780 BC, Hammurabi, Code of Law
-- 
Asperger Syndroom - een persoonlijke benadering:
	http://people.nl.linux.org/~gerrit/
Kom in verzet tegen dit kabinet:
	http://www.sp.nl/

Gerrit Holl <gerrit@...> writes:

> Hi,
>
> are there easier ways to create tables that to do it by hand or learn
> Emacs (Vim-user speaking)? E.g., does there exist a tool that converts
> for example a HTML table to a ReST table? I'm having a table with 15
> columns and 9 rows, which is not exactly comfortable in ReST...

Why don't you do a litle python script for this ? You can also use
Cheetah (http://cheetahtemplate.org)

-- 
William Dode - http://flibuste.net

William Dode wrote:
> Gerrit Holl <gerrit@...> writes:
> 
> > Hi,
> >
> > are there easier ways to create tables that to do it by hand or learn
> > Emacs (Vim-user speaking)? E.g., does there exist a tool that converts
> > for example a HTML table to a ReST table? I'm having a table with 15
> > columns and 9 rows, which is not exactly comfortable in ReST...
> 
> Why don't you do a litle python script for this ?

Because it's very possible that it already exists :-)

> You can also use Cheetah (http://cheetahtemplate.org)

Hmm, I'm not sure whether it is what I'm looking for, I'm not doing
anything with a website, I'm just writing a document, experimentally in
ReST rather than Linuxdoc SGML, what I usually do... Cheetah seems to be
something else...?

yours,
Gerrit.

-- 
132. If the "finger is pointed" at a man's wife about another man, but
she is not caught sleeping with the other man, she shall jump into the
river for her husband.
          -- 1780 BC, Hammurabi, Code of Law
-- 
Asperger Syndroom - een persoonlijke benadering:
	http://people.nl.linux.org/~gerrit/
Kom in verzet tegen dit kabinet:
	http://www.sp.nl/

Gerrit Holl <gerrit@...> writes:

> William Dode wrote:
>> Gerrit Holl <gerrit@...> writes:
>> 
>> > Hi,
>> >
>> > are there easier ways to create tables that to do it by hand or learn
>> > Emacs (Vim-user speaking)? E.g., does there exist a tool that converts
>> > for example a HTML table to a ReST table? I'm having a table with 15
>> > columns and 9 rows, which is not exactly comfortable in ReST...
>> 
>> Why don't you do a litle python script for this ?
>
> Because it's very possible that it already exists :-)
>
>> You can also use Cheetah (http://cheetahtemplate.org)
>
> Hmm, I'm not sure whether it is what I'm looking for, I'm not doing
> anything with a website, I'm just writing a document, experimentally in
> ReST rather than Linuxdoc SGML, what I usually do... Cheetah seems to be
> something else...?

If you want to write a ReST document with datas cheetah can help you, for
example you want to send a letter to somes peoples :

from Cheetah.Template import Template

t = Template("""Dear $name,

Look this table :

+-----+-----+
#for $i,$j in $mytable
#echo '!%-5s!%5s!' % ($i,$j)
+-----+-----+
#end for
""")

t.mytable = (('a',1),('b',6),('c',7))

for name in ('toto','titi','tata'):
    t.name = name
    print t.respond()


you'll have this beautiful ReST document :

Dear toto,

Look this table :

+-----+-----+
!a    !    1!
+-----+-----+
!b    !    6!
+-----+-----+
!c    !    7!
+-----+-----+

Dear titi,

Look this table :

+-----+-----+
!a    !    1!
+-----+-----+
!b    !    6!
+-----+-----+
!c    !    7!
+-----+-----+

Dear tata,

Look this table :

+-----+-----+
!a    !    1!
+-----+-----+
!b    !    6!
+-----+-----+
!c    !    7!
+-----+-----+


-- 
William Dode - http://flibuste.net

William Dode wrote:
> If you want to write a ReST document with datas cheetah can help you, for
> example you want to send a letter to somes peoples :
> 
> from Cheetah.Template import Template
> 
> t = Template("""Dear $name,
> 
> Look this table :
> 
> +-----+-----+
> #for $i,$j in $mytable
> #echo '!%-5s!%5s!' % ($i,$j)
> +-----+-----+
> #end for
> """)
> 
> t.mytable = (('a',1),('b',6),('c',7))
> 
> for name in ('toto','titi','tata'):
>     t.name = name
>     print t.respond()

[cut results]

Beatiful, thanks for the link!
I'll have a look at it asap...

yours,
Gerrit.

-- 
14. If any one steal the minor son of another, he shall be put to
death.
          -- 1780 BC, Hammurabi, Code of Law
-- 
Asperger Syndroom - een persoonlijke benadering:
	http://people.nl.linux.org/~gerrit/
Kom in verzet tegen dit kabinet:
	http://www.sp.nl/

Gerrit Holl wrote:
 > are there easier ways to create tables that to do it by hand or
 > learn Emacs (Vim-user speaking)?

I googled for "vim" & "table" and the first item looked promising.

I don't know of any other tools that would be useful.  I use Emacs
though, so I never had to look too hard ;-)

 > E.g., does there exist a tool that converts for example a HTML
 > table to a ReST table?  I'm having a table with 15 columns and 9
 > rows, which is not exactly comfortable in ReST...

This could help for simple tables: use a spreadsheet (like in
OpenOffice.org), set the typeface to Courier, and save the result to a
CSV-format file with spaces separating fields and no text delimiters.

 > Hmm, I now used a Simple Table (which isn't comfortable either, but
 > doable), but somehow question marks get aligned at the bottom of a
 > cell:
...
 > How come?

This was interesting!  I tried it, and found your description to be
correct.  Looking at the html produced, I saw table cells like this:

     <td>100</td>
     <td><p class="last">???</p>

Why are numeric cells raw text, but "???" is wrapped in a <p> tag?

Running publish.py told the story:

     <entry>
         <paragraph>
             100
     <entry>
         <system_message level="1" line="22" source="t" type="INFO">
             <paragraph>
                 Unexpected possible title overline or transition.
                 Treating it as ordinary text because it's so short.
         <paragraph>
             ???

So "???" being non-alphanumeric, it was interpreted as possible title
markup.  You never saw the system message because it's level-1/INFO,
which is normally filtered out.  The <p> tag is in the HTML because
the "???" paragraph wasn't an "only child and optimizable"; there are
two elements in the table cell, even though one (the system_message)
is filtered out (too late).

Solution?  Long-term, we'll implement a new transform to do the system
message filtering earler, before the document reaches the Writer.
It's been on the to-do list for a while, but I've upped its priority
(made it a bug):
<http://docutils.sf.net/spec/notes.html#filtering-system-messages>.

Short-term hack: add a backslash escape with the "???", and that will
convince the parser that it's not markup.

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv

[Gerrit Holl]
 >> Hmm, I now used a Simple Table (which isn't comfortable either, but
 >> doable), but somehow question marks get aligned at the bottom of a
 >> cell:

[David Goodger]
 > Solution?  Long-term, we'll implement a new transform to do the
 > system message filtering earler, before the document reaches the
 > Writer.

I have implemented the new transform.  It's available from current
CVS, but the snapshots aren't working right now because of SourceForge
server issues.  Anonymous CVS should work, but in case it doesn't I've
attached a patch which replaces 2 files.

If you remove the short-term hack (backslashes) and process your table
again, the misalignment should be gone.

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv

Gerrit Holl wrote:
> I'm trying to include a double arrow (chemical reaction). It works
> fine with HTML, but not with Latex:
...
 > I use |hArr| with .. include:: isoamsa.txt. Is there any way to
 > solve this?

The LaTeX writer defaults to the Latin-1 codec for output.  Latin-1 
doesn't include "⇔".  If TeX supports UTF-8, try it: use the
"-o utf-8" Docutils command-line option.

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv

David Goodger wrote:
> Gerrit Holl wrote:
> >I'm trying to include a double arrow (chemical reaction). It works
> >fine with HTML, but not with Latex:
> ...
> > I use |hArr| with .. include:: isoamsa.txt. Is there any way to
> > solve this?
> 
> The LaTeX writer defaults to the Latin-1 codec for output.  Latin-1 
> doesn't include "⇔".  If TeX supports UTF-8, try it: use the
> "-o utf-8" Docutils command-line option.

Ah, that works. Thanks!

yours,
Gerrit.

-- 
268. If any one hire an ox for threshing, the amount of the hire is
twenty ka of corn.
          -- 1780 BC, Hammurabi, Code of Law
-- 
Asperger Syndroom - een persoonlijke benadering:
	http://people.nl.linux.org/~gerrit/
Kom in verzet tegen dit kabinet:
	http://www.sp.nl/

This thread really should be on the developers' list, but since it
started here, I'm crossposting...

David Goodger <goodger@...> writes:

> David Abrahams wrote re nested inline markup:
>  > The question is, would you be OK with the resulting changes in
>  > semantics?
>
> I think so.  Depends on what the unanticipated side-effects are.
>
> Note the 7 inline markup recognition rules listed under
> <http://docutils.sf.net/spec/rst/reStructuredText.txt/inline-markup>.
> They may complicate matters somewhat.
>
>  > Is there a body of tests I can run to see what I've broken?
>
> Yes, run test/test_parsers/test_rst/test_inline_markup.py.  Some of
> these tests exercise the current behavior and are expected to fail if
> nested markup is implemented.
>
> Then run test/alltests.py for the full suite of unit tests.  There's
> some additional inline markup sprinkled around.

OK, I have something implemented which seems to handle most of the
logic (it's not really doing tokenization, but something that should
be semantically equivalent, and doesn't result in a complete rewrite)
but there are a few cases I need to get some feedback on.

1. *****

  gets "tokenized", naturally, as


      <**><*><**>

  And when the inliner re-parses <*>, it complains about an inline
  start-string without a corresponding end-string.  So, the question
  is, do we:

    a. turn off complaints inside inline markup about unmatched inline
       markup start-strings without corresponding end strings

    b. Make that an error and force the user to write 

         **\***

2. ``literal ``TeX quotes'' & \\backslash`` 

  This one is currently parsed as though tokenized this way:

     <``><literal ``TeX quotes'' & \\backslash><``>

  But my code tokenizes inside markup and so sees:

     <``><literal ><``>TeX quotes'' & \\backslash><``>

  Again, I see two choices:

     a. Turn off recognition of an inline markup start string within
        regions already using that markup.

     b. Make that an error and force the user to write 

          ``literal \``TeX quotes'' & \\backslash`` 

In both cases (a) is more backward-compatible but (b) is more
consistent, and, dare I say, Pythonic.

in-the-face-of-ambiguity-refuse-the-temptation-to-guess-ly y'rs,
-- 
Dave Abrahams
Boost Consulting
 http://www.boost-consulting.com

Beni Cherniavsky <cben@...> writes:

> David Goodger wrote on 2004-01-10:
>
>> You brought it up ;-).
>>
>> Seriously, the point is that the current parser doesn't do *any*
>> tokenization per se.  It parses by searching for a start-string (or
>> "token") and *then* for the corresponding end-string.  No end-strings
>> are identified beforehand.
>>
>> As I understand "tokenization", a parser will first split up its input
>> into "tokens" and *then* verify that the tokens make syntactical
>> sense.  The reST parser doesn't have this two-step split.  That
>> doesn't mean it couldn't be done, just that it isn't currently done.
>>
> I don't see any need for two steps.  I fact, I don't think a classical
> tokenize->parse scheme *can* parse nested inline markup at all because
> the tokenization depends on the pending unclosed markup.  In::
>
>     **strong *and emphasized***
>
> and
>
>     *emphasized **and strong***
>
> the ending ``***`` should tokenize differently.  

I was about to disagree, but my code does it the way you'd like, so I
guess I'll just agree with you ;-)

> A two-pass scheme can't know that.

I think you're right, unless you build lots of parsing knowledge into
the tokenizer (but then it's not really a tokenizer anymore, is it?)

>> David Abrahams wrote:
>>
>>  > The way I am using "tokenization", it doesn't change that algorithm,
>>  > just how we determine that corresponding close-markup is "found".
>>  > We wouldn't find close-emphasis here:
>>  >
>>  >      *Emphasis enclosing **strong** in the middle.*
>>  >                                   ^
>>  >
>>  > Because '**' would be tokenized as a "strong" delimiter.
>>
>> The current parser doesn't work that way because it isn't *looking*
>> for a "strong" end-string ("**").  It's looking for an "emphasis"
>> end-string, "*", which it finds at the end of "strong**".
>>
> However, it is able now to look simultaneously for the first
> start-string of any kind, isn't it?  All we need then is to look
> simultaneously for any (nested) start-string OR the pending end-string
> (we will need a stack of them).

It's a little more complicated than that, but I'm almost there.

>
>>  > It might be that the scope of required changes is much smaller than
>>  > you think.
>>
>> Perhaps.  The code itself is well-encapsulated, in the
>> "docutils.parsers.rst.states.Inliner" class; the entry point is the
>> "parse" method.
>>
> You also need to update the spec, DTD and writers of course...  For
> testing, quicktest.py should work as-is, I think.

I'm hoping to get some help from the community on those chores once I
have done the "hard part". I've certainly seen changes go into
docutils core without all the writers being updated by the same
person.  For example, there's a recent table title feature I can't
use because it's not in the latex2e writer ;^)


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

David Abrahams wrote:
 > This thread really should be on the developers' list, but since it
 > started here, I'm crossposting...

Moved it over to docutils-develop, subject "nested inline markup".

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv

Thorsten Bischoff wrote:
> I just have a question concerning the HTML Writer. Is there any
> possibility to create HTML output from reST as frameset: one frame
> for the table of contents and one for main documentation?
> 
> I need this for a better navigation. Is there anything or do I have
> to create it myself?

I don't know of any TOC-frameset-oriented HTML Writer.  I think you'll
have to create one yourself.  It ought to be easy to subclass the
existing HTML Writer's classes; if not, let us know.

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv

From: David Abrahams [mailto:dave@...]
> This is ridiculous.  I've enclosed a .zip of the file, encoded with
> Unix line endings.

Hmm, for what it's worth, I unzipped and ran that.  What I see is you have
this (everything here indented two spaces for readability):

  ::
      your stuff

when I think what David's saying is you need:

  ::

      your stuff

In other words:

  ::[new line]
  [new line]
      your stuff

you need two newlines after :: and before you start your PRE block.

I'm jumping in the middle of this so it's likely I don't have the context to
fully understand.

Cheers,

// m

"McEahern, Mark" <Mark.McEahern@...> writes:

> I'm jumping in the middle of this so it's likely I don't have the
> context to fully understand.

No, I'm just an idiot.  Sorry, everyone :(

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

David Abrahams <dave@...> wrote:

> This is ridiculous.  I've enclosed a .zip of the file, encoded with
> Unix line endings.

$ cat -A fu.rst 
``const`` reference unless we use the `Boost.Ref`_ library to$
indicate otherwise:$
$
.. _`Boost.Ref`: ../../bind/ref.hpp$
$
::$
    #include <boost/ref.hpp>$
$
    float x;$

The blank line is still missing.  It's your fault, not docutils'.

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