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

Re: [Docutils-users] Difference in custom roles between 0.13 and 0.14?

[Guenter M. <mi...@us...>]

On 2018-06-05, Guenter Milde via Docutils-users wrote:
> On 2018-06-02, Tim Landscheidt wrote:

...

>>| […]
>>| ! Undefined control sequence.
>>| <write> ...re your \protect \texttt  {\DUrolefile
>>|                                                   {.emacs}} file}{\thepage }...

...

Fixed in revision 8218.
https://sourceforge.net/p/docutils/code/8218/

Thanks for the report,

Günter

Re: [Docutils-users] escaping Text so that's docutils doesn't try to format it?

[Erik S. <st...@ma...>]

On 04.06.2018 17:48, David Goodger wrote:
> It should be safe.
>
> But if you're going to escape everything to prevent parsing, why
> bother using Docutils?
Certainly not everything, in this case I'm assembling figure-directives 
with captions from an image database. Had to hack Docutils 0.14 because 
substitutions cannot be used with block-only directives like 'figure'.

-- erik

Re: [Docutils-users] Difference in custom roles between 0.13 and 0.14?

[Guenter M. <mi...@us...>]

Dear Tim,

thank you for reporting the problem with the Docutils LaTeX writer.

On 2018-06-02, Tim Landscheidt wrote:
> Hi,

> I'm investigating a build failure in Fedora for Pymacs
> (https://github.com/pinard/Pymacs) that occurs with (Fedora 28's)
> Docutils 0.14, but not with (Fedora 27's) Docutils 0.13.1
> (https://bugzilla.redhat.com/show_bug.cgi?id=1555730).

> The .rst file in question 
...
> starts with defining custom roles as "aliases":

>| .. role:: code(strong)
>| .. role:: file(literal)
>| .. role:: var(emphasis)

> Docutils 0.13.1 is fine with this, Docutils 0.14 causes a
> TeX error
> (https://bugzilla.redhat.com/attachment.cgi?id=1443162):

>| […]
>| ! Undefined control sequence.
>| <write> ...re your \protect \texttt  {\DUrolefile
>|                                                   {.emacs}} file}{\thepage }...
...

> The .tex files differ (inter alia) by:

>| --- /tmp/f27.tex        2018-06-02 10:10:17.035844460 +0000
>| +++ /tmp/f28.tex        2018-06-02 10:10:02.937009242 +0000
>| @@ -1,6 +1,5 @@
>|  \documentclass[a4paper]{article}
>|  % generated by Docutils <http://docutils.sourceforge.net/>
>| -\usepackage{fixltx2e} % LaTeX patches, \textsubscript
>|  \usepackage{cmap} % fix search and cut-and-paste in Acrobat
>|  \usepackage{ifthen}
>|  \usepackage[T1]{fontenc}
>| @@ -37,14 +36,11 @@
>|  % inline markup (custom roles)
>|  % \DUrole{#1}{#2} tries \DUrole#1{#2}
>|  \providecommand*{\DUrole}[2]{%
>| -  \ifcsname DUrole#1\endcsname%
>| +  % backwards compatibility: try \docutilsrole#1{#2}
>| +  \ifcsname docutilsrole#1\endcsname%
>| +    \csname docutilsrole#1\endcsname{#2}%
>| +  \else
>|      \csname DUrole#1\endcsname{#2}%
>| -  \else% backwards compatibility: try \docutilsrole#1{#2}
>| -    \ifcsname docutilsrole#1\endcsname%
>| -      \csname docutilsrole#1\endcsname{#2}%
>| -    \else%
>| -      #2%
>| -    \fi%
>|    \fi%
>|  }

...

> Is this a bug in Docutils, or does Pymacs need to add dummy
> "\newcommand{\DUrolefile}{}"s as raw LaTex?

You actually found a bug. I simplified the definition of the ``\DUrole``
macro, this worked fine in the standard tests but it turns out to be failing
in cases where roles have defaults and with roles in section headings.

Restoring the old definition helps (patch below). Dummy definitions in
the document preamble or in raw LaTeX should help as a stop-gap measure,
too.

Thanks again,

Günter


diff --git a/trunk/docutils/docutils/writers/latex2e/__init__.py b/trunk/docutils/docutils/writers/latex2e/__init__.py
index a11a98f3c..0463e3504 100644
--- a/trunk/docutils/docutils/writers/latex2e/__init__.py
+++ b/trunk/docutils/docutils/writers/latex2e/__init__.py
@@ -565,11 +565,15 @@ PreambleCmds.inline = r"""
 % inline markup (custom roles)
 % \DUrole{#1}{#2} tries \DUrole#1{#2}
 \providecommand*{\DUrole}[2]{%
-  % backwards compatibility: try \docutilsrole#1{#2}
-  \ifcsname docutilsrole#1\endcsname%
-    \csname docutilsrole#1\endcsname{#2}%
-  \else
+  \ifcsname DUrole#1\endcsname%
     \csname DUrole#1\endcsname{#2}%
+  \else
+    % backwards compatibility: try \docutilsrole#1{#2}
+    \ifcsname docutilsrole#1\endcsname%
+      \csname docutilsrole#1\endcsname{#2}%
+    \else%
+      #2%
+    \fi%
   \fi%
 }"""

Re: [Docutils-users] Removing docinfo in "body" part with html5 writer

[Guenter M. <mi...@us...>]

On 2018-05-26, Cédric Van Rompay wrote:
> Hi,

> When switching from "html" to "html5" writer, I got the following
> problem: the docinfo is now included in the "body" parts when using
> "publish_parts".

> For details see my question of StackOverflow:
> https://stackoverflow.com/q/50423279/3025740

> As I say in StackOverflow it seems to contradict the documentation
> which says that "body" should not contain the docinfo.

You found a bug in the html5 writer.

I have a local fix (patch below). Unfortunately, work on Docutils stalled
(still waiting for a go-ahead for the patch fixing
 https://sourceforge.net/p/docutils/bugs/342/ and
 https://sourceforge.net/p/docutils/bugs/332/ ).

> Searching in docutils mailing list, I found this message suggesting to
> use "strip_elements_with_classes":
> https://sourceforge.net/p/docutils/mailman/message/35973538/

> But it does not seem to work for me.

This was an untested suggestion. It turns out that class arguments are lost
during the docinfo transformation (this may be another bug) and therefore
the proposed option does not work in this case.


Günter


diff --git a/trunk/docutils/docutils/writers/_html_base.py b/trunk/docutils/docutils/writers/_html_base.py
index d9275d846..bca1db922 100644
--- a/trunk/docutils/docutils/writers/_html_base.py
+++ b/trunk/docutils/docutils/writers/_html_base.py
@@ -681,6 +681,7 @@ class HTMLTranslator(nodes.NodeVisitor):
         self.body.append('</dd>\n')
 
     def visit_docinfo(self, node):
+        self.context.append(len(self.body))
         classes = 'docinfo'
         if (self.is_compactable(node)):
             classes += ' simple'
@@ -688,6 +689,9 @@ class HTMLTranslator(nodes.NodeVisitor):
 
     def depart_docinfo(self, node):
         self.body.append('</dl>\n')
+        start = self.context.pop()
+        self.docinfo = self.body[start:]
+        self.body = []
 
     def visit_docinfo_item(self, node, name, meta=True):
         if meta:
@@ -1403,14 +1407,14 @@ class HTMLTranslator(nodes.NodeVisitor):
             classes = 'sidebar-subtitle'
         elif isinstance(node.parent, nodes.document):
             classes = 'subtitle'
-            self.in_document_title = len(self.body)
+            self.in_document_title = len(self.body)+1
         elif isinstance(node.parent, nodes.section):
             classes = 'section-subtitle'
         self.body.append(self.starttag(node, 'p', '', CLASS=classes))
 
     def depart_subtitle(self, node):
         self.body.append('</p>\n')
-        if self.in_document_title:
+        if isinstance(node.parent, nodes.document):
             self.subtitle = self.body[self.in_document_title:-1]
             self.in_document_title = 0
             self.body_pre_docinfo.extend(self.body)

Re: [Docutils-users] escaping Text so that's docutils doesn't try to format it?

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

It should be safe.

But if you're going to escape everything to prevent parsing, why
bother using Docutils?

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


On 4 June 2018 at 10:28, Erik Stein <st...@ma...> wrote:
>
> Thanks, David. One additional question: Is it safe to just prefix every
> string like this (which shouldn't be interpreted by docutils), or might
> there be cases where the backslash ends up in the resulting document?
>
> Best
>
> -- erik
>
>
>
> On 04.06.2018 17:16, David Goodger wrote:
>>
>> On 4 June 2018 at 09:39, Erik Stein <st...@ma...> wrote:
>>>
>>> Hello --
>>>
>>> I'm using docutils to semi-automatically construct certain content pages.
>>> I've got the problem that sometimes people enter text which in the
>>> context
>>> of a restructured text file has some semantical meaning, but this is not
>>> the
>>> intention in the actual case.
>>>
>>> E.g.
>>>
>>> "v. l. Donald Trump, Kim Jong UN"
>>>
>>> where "v. l." means "from left to right" in a photo.
>>>
>>> Docutils interprets this as a roman numbered list (my guess, this is in
>>> the
>>> context of a figure
>>
>> You are correct that Docutils is interpreting this text as a list. In
>> fact, this specific text will be interpreted as two nested
>> lowercase-alphabetic enumerated lists.
>>
>>> is there a (python) function in docutils which allows to escape a string
>>> in
>>> a way that docutils simply renders it as text?
>>
>> There is no generic "escape all" function in Docutils.
>>
>> In many cases, simply prefixing a backslash to the text will escape it:
>>
>> $ rst2pseudoxml.py <<EOF
>>>
>>> \v. l. a b c
>>>
>>> EOF
>>
>> <document source="<stdin>">
>>      <paragraph>
>>          v. l. a b c
>>
>> David Goodger
>> <http://python.net/~goodger>
>>
>>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Docutils-users mailing list
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>
>> Please use "Reply All" to reply to the list.
>
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] escaping Text so that's docutils doesn't try to format it?

[Erik S. <st...@ma...>]

Thanks, David. One additional question: Is it safe to just prefix every 
string like this (which shouldn't be interpreted by docutils), or might 
there be cases where the backslash ends up in the resulting document?

Best

-- erik


On 04.06.2018 17:16, David Goodger wrote:
> On 4 June 2018 at 09:39, Erik Stein <st...@ma...> wrote:
>> Hello --
>>
>> I'm using docutils to semi-automatically construct certain content pages.
>> I've got the problem that sometimes people enter text which in the context
>> of a restructured text file has some semantical meaning, but this is not the
>> intention in the actual case.
>>
>> E.g.
>>
>> "v. l. Donald Trump, Kim Jong UN"
>>
>> where "v. l." means "from left to right" in a photo.
>>
>> Docutils interprets this as a roman numbered list (my guess, this is in the
>> context of a figure
> You are correct that Docutils is interpreting this text as a list. In
> fact, this specific text will be interpreted as two nested
> lowercase-alphabetic enumerated lists.
>
>> is there a (python) function in docutils which allows to escape a string in
>> a way that docutils simply renders it as text?
> There is no generic "escape all" function in Docutils.
>
> In many cases, simply prefixing a backslash to the text will escape it:
>
> $ rst2pseudoxml.py <<EOF
>> \v. l. a b c
>>
>> EOF
> <document source="<stdin>">
>      <paragraph>
>          v. l. a b c
>
> David Goodger
> <http://python.net/~goodger>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] escaping Text so that's docutils doesn't try to format it?

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

On 4 June 2018 at 09:39, Erik Stein <st...@ma...> wrote:
>
> Hello --
>
> I'm using docutils to semi-automatically construct certain content pages.
> I've got the problem that sometimes people enter text which in the context
> of a restructured text file has some semantical meaning, but this is not the
> intention in the actual case.
>
> E.g.
>
> "v. l. Donald Trump, Kim Jong UN"
>
> where "v. l." means "from left to right" in a photo.
>
> Docutils interprets this as a roman numbered list (my guess, this is in the
> context of a figure

You are correct that Docutils is interpreting this text as a list. In
fact, this specific text will be interpreted as two nested
lowercase-alphabetic enumerated lists.

> is there a (python) function in docutils which allows to escape a string in
> a way that docutils simply renders it as text?

There is no generic "escape all" function in Docutils.

In many cases, simply prefixing a backslash to the text will escape it:

$ rst2pseudoxml.py <<EOF
> \v. l. a b c
>
> EOF
<document source="<stdin>">
    <paragraph>
        v. l. a b c

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

[Docutils-users] escaping Text so that's docutils doesn't try to format it?

[Erik S. <st...@ma...>]

Hello --

I'm using docutils to semi-automatically construct certain content 
pages. I've got the problem that sometimes people enter text which in 
the context of a restructured text file has some semantical meaning, but 
this is not the intention in the actual case.

E.g.

"v. l. Donald Trump, Kim Jong UN"

where "v. l." means "from left to right" in a photo.

Docutils interprets this as a roman numbered list (my guess, this is in 
the context of a figure

is there a (python) function in docutils which allows to escape a string 
in a way that docutils simply renders it as text?

thanks and best regards
-- erik

[Docutils-users] Difference in custom roles between 0.13 and 0.14?

[Tim L. <ti...@ti...>]

Hi,

I'm investigating a build failure in Fedora for Pymacs
(https://github.com/pinard/Pymacs) that occurs with (Fedora
28's) Docutils 0.14, but not with (Fedora 27's) Docutils
0.13.1
(https://bugzilla.redhat.com/show_bug.cgi?id=1555730).

The .rst file in question is
https://github.com/pinard/Pymacs/blob/master/pymacs.rst.in
with two instances of "@VERSION@" replaced by "0.25".  It
gets processed with "rst2latex --use-latex-toc
--input-encoding=UTF-8 $rst $tex".  It starts with defining
custom roles as "aliases":

| .. role:: code(strong)
| .. role:: file(literal)
| .. role:: var(emphasis)

| ================================================================
| Pymacs version @VERSION@
| ================================================================

| […]

Docutils 0.13.1 is fine with this, Docutils 0.14 causes a
TeX error
(https://bugzilla.redhat.com/attachment.cgi?id=1443162):

| […]
| ! Undefined control sequence.
| <write> ...re your \protect \texttt  {\DUrolefile
|                                                   {.emacs}} file}{\thepage }...
| l.580 F
|        rom Pymacs 0.23 and upwards, Python 2.2 or better is likely needed,
| ?
| ! Emergency stop.
| […]

The .tex files differ (inter alia) by:

| --- /tmp/f27.tex        2018-06-02 10:10:17.035844460 +0000
| +++ /tmp/f28.tex        2018-06-02 10:10:02.937009242 +0000
| @@ -1,6 +1,5 @@
|  \documentclass[a4paper]{article}
|  % generated by Docutils <http://docutils.sourceforge.net/>
| -\usepackage{fixltx2e} % LaTeX patches, \textsubscript
|  \usepackage{cmap} % fix search and cut-and-paste in Acrobat
|  \usepackage{ifthen}
|  \usepackage[T1]{fontenc}
| @@ -37,14 +36,11 @@
|  % inline markup (custom roles)
|  % \DUrole{#1}{#2} tries \DUrole#1{#2}
|  \providecommand*{\DUrole}[2]{%
| -  \ifcsname DUrole#1\endcsname%
| +  % backwards compatibility: try \docutilsrole#1{#2}
| +  \ifcsname docutilsrole#1\endcsname%
| +    \csname docutilsrole#1\endcsname{#2}%
| +  \else
|      \csname DUrole#1\endcsname{#2}%
| -  \else% backwards compatibility: try \docutilsrole#1{#2}
| -    \ifcsname docutilsrole#1\endcsname%
| -      \csname docutilsrole#1\endcsname{#2}%
| -    \else%
| -      #2%
| -    \fi%
|    \fi%
|  }

| […]

My TeX is rusty, and I do not completely understand
http://docutils.sourceforge.net/docs/user/latex.html#custom-interpreted-text-roles.
Is this a bug in Docutils, or does Pymacs need to add dummy
"\newcommand{\DUrolefile}{}"s as raw LaTex?

TIA,
Tim

[Docutils-users] Removing docinfo in "body" part with html5 writer

[Cédric V. R. <ced...@gm...>]

Hi,

When switching from "html" to "html5" writer, I got the following
problem: the docinfo is now included in the "body" parts when using
"publish_parts".

For details see my question of StackOverflow:
https://stackoverflow.com/q/50423279/3025740

As I say in StackOverflow it seems to contradict the documentation
which says that "body" should not contain the docinfo.

Searching in docutils mailing list, I found this message suggesting to
use "strip_elements_with_classes":
https://sourceforge.net/p/docutils/mailman/message/35973538/

But it does not seem to work for me.

Code example:

    import docutils.core

    SOURCE = '''\
    :key: value

    Title
    ========

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod
    tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua. At
    vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren,
    no sea takimata sanctus est Lorem ipsum dolor sit amet.
    '''

    docutils_params = {
        'input_encoding': 'utf-8',
        'strip_elements_with_classes': ['docinfo simple']
    }

    body = docutils.core.publish_parts(
        SOURCE,
        writer_name='html5',
        settings_overrides=docutils_params
    )['body']

    print(body)

(using Python 3)

Any idea ?

-- 
Cédric Van Rompay

Re: [Docutils-users] Book template

[<seb...@ch...>]

Le 07/05/2018 à 08:22, Nicolas Rougier a écrit :
> Hi all,
>
> I just released an open-access book on "Python & OpenGL for Scientific Visualization” (http://www.labri.fr/perso/nrougier/python-opengl/).
>
> The book has been written using rst and I wrote a slightly modified rst2html and a css to give the book a modern look (IMHO). Code is available at https://github.com/rougier/python-opengl.
>
Hello,

I just want to say that your work is amazing. As much on the form as on 
the content.

Can you explain what changed did you do in the rst2html code ?

Re: [Docutils-users] Book template

[Nicolas R. <Nic...@in...>]

Thanks.

I mostly modified the code to take movies into account (both in image and figure directive) with some options.
I wanted to be able to write something like:

```
.. figure:: movies/chapter-05/color-cube.mp4
   :loop:
   :autoplay:
   :controls:
   :figwidth: 35%
            
   Figure

   The RGB rotating cube 
```
   

The code is here: https://github.com/rougier/python-opengl/blob/master/rst2html.py

Nicolas


> On 24 May 2018, at 20:44, seb...@ch... wrote:
> 
> 
> 
> Le 07/05/2018 à 08:22, Nicolas Rougier a écrit :
>> Hi all,
>> 
>> I just released an open-access book on "Python & OpenGL for Scientific Visualization” (http://www.labri.fr/perso/nrougier/python-opengl/).
>> 
>> The book has been written using rst and I wrote a slightly modified rst2html and a css to give the book a modern look (IMHO). Code is available at https://github.com/rougier/python-opengl.
>> 
> Hello,
> 
> I just want to say that your work is amazing. As much on the form as on the content.
> 
> Can you explain what changed did you do in the rst2html code ?

[Docutils-users] Book template

[Nicolas R. <Nic...@in...>]

Hi all,

I just released an open-access book on "Python & OpenGL for Scientific Visualization” (http://www.labri.fr/perso/nrougier/python-opengl/). 

The book has been written using rst and I wrote a slightly modified rst2html and a css to give the book a modern look (IMHO). Code is available at https://github.com/rougier/python-opengl.


Nicolas

Re: [Docutils-users] kbd role

[Yuri D'E. <wa...@th...>]

On Wed, Feb 15 2017, Alan Isaac wrote:
> Might consideration be given to adding a `kbd` standard role?

I'd like to resurrect this thread.

Github added `kbd` as a standard role for documentation purposes, since
it's very frequently used in READMEs along with code sections. They
translate it into <kbd> tags in the html writer.

Now I'm a bit thorn if I should add a non-standard role into my READMEs
just to have fancier formatting.

I admit, I'd use `kbd` quit a bit too. I write almost everything in rst
these days, and showing "stuff to type" scores pretty high for me.

Re: [Docutils-users] Replace bug

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

On 17 April 2018 at 16:05,  <mic...@gm...> wrote:
> The following fails:
>
> replace_bug.rst:
>
>     |Bug|_
>
>     .. |Bug| replace::
>         A. Bug: the initial causes problems.
>     .. _Bug:
>
>
> Failure:
>
>     $ rst2html.py --version
>     rst2html.py (Docutils 0.14, Python 2.7.13, on darwin)
>
>     $ rst2html.py replace_bug.rst > replace_bug.html
>     replace_bug.rst:3: (ERROR/3) Error in "replace" directive: may contain a single paragraph only.
>     replace_bug.rst:3: (WARNING/2) Substitution definition "Bug" empty or invalid.
>
>     .. |Bug| replace::
>              A. Bug: the initial causes problems.
>     replace_bug.rst:1: (ERROR/3) Undefined substitution referenced: "Bug".

This is expected behavior. Try processing just the content of the
replace directive (without the directive itself) to see why this
happens.

> This was based on the replacement example from the documentation:
>
>
> |Python|_
>
> .. |Python| replace::
>          Python: A great language!
> .. _Python:
>
> A workaround is to escape the space *and* include an additional space, but this is very ugly.  Is there a better solution?

Yes. A single backslash-escape will do, to prevent the "A." from being
parsed as a list item::

    |Bug|_

    .. |Bug| replace::
        \A. Bug: the initial causes problems.
    .. _Bug:

> Am I misreading the documentation/misusing replacements or should I file a bug report?

I don't know if you're misusing replacements; depends on what you're
trying to do. Not a bug AFAIC. Do you understand why?

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

[Docutils-users] Replace bug

[<mic...@gm...>]

The following fails:

replace_bug.rst:

    |Bug|_
    
    .. |Bug| replace::
        A. Bug: the initial causes problems.
    .. _Bug: 


Failure:

    $ rst2html.py --version
    rst2html.py (Docutils 0.14, Python 2.7.13, on darwin)
    
    $ rst2html.py replace_bug.rst > replace_bug.html
    replace_bug.rst:3: (ERROR/3) Error in "replace" directive: may contain a single paragraph only.
    replace_bug.rst:3: (WARNING/2) Substitution definition "Bug" empty or invalid.
    
    .. |Bug| replace::
             A. Bug: the initial causes problems.
    replace_bug.rst:1: (ERROR/3) Undefined substitution referenced: "Bug".


This was based on the replacement example from the documentation:

			
|Python|_ 

.. |Python| replace::
	 Python: A great language!
.. _Python:

A workaround is to escape the space *and* include an additional space, but this is very ugly.  Is there a better solution?

|Workaround|_

 .. |Workaround| replace::
	 A.\  Bug: the initial causes problems.

.. _Workaround:

Am I misreading the documentation/misusing replacements or should I file a bug report?

Re: [Docutils-users] How to create and reference custom heading ids with reStructuredText?

[Guenter M. <mi...@us...>]

On 2018-02-20, Alan Isaac wrote:
> On 2/18/2018 4:45 PM, Guenter Milde via Docutils-users wrote:
>> The separate div is the HTML4-compatible representation of the section
>> element (with the HTML5 writer this will eventually become a <section>
>> element, too).

> Yea! (Although by "too" I hope you mean "instead".)

No, I mean "too": the "section" node should be represented by a <section>
element not only in Docutils-XML but also in HTML5.

> Please announce when you do this.

Currently, I stopped working on Docutils while waiting for the green light
to commit the fixes to keep info about escape characters in the doctree.

Günter

Re: [Docutils-users] How to create and reference custom heading ids with reStructuredText?

[Alan I. <ala...@gm...>]

On 2/18/2018 4:45 PM, Guenter Milde via Docutils-users wrote:
> The separate div is the HTML4-compatible representation of the section
> element (with the HTML5 writer this will eventually become a <section>
> element, too).

Yea! (Although by "too" I hope you mean "instead".)
Please announce when you do this.
Cheers,
Alan

Re: [Docutils-users] many-character option list

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

On Tue, Feb 27, 2018 at 11:53 AM, Gary Mamon <ga...@ia...> wrote:
> * How can I make a many-character non-POSIX (i.e. single dash signs) option
> list, i.e.
>
> -data file # data filename
>
> OR
>
> -data file -> data filename

You cannot, per the reStructuredText Markup Specification:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

The 4 types of option markup allowed are:

* Short POSIX
* Long POSIX
* Old GNU-style "plus"
* DOS/VMS "slash"

> where the first data is highlighted as a literal, the “file” is highlighted
> as emphasis (italics), and the tabulation between “file” and “#” or “->” is
> a real tab so that subsequent lines are vertically aligned?

Note: tabs are not used. Tables or other markup are used.

> Using standard option lists doesn’t work:
> 1) multiple-character options have their first letter in literal and the
> next ones in emphasis, which is weird.

Not weird once you understand what's going on. A line like:

    -option    description

is simply interpreted as the short POSIX option "-o" followed by the
argument "ption" and a description.

Trying to mix single-dash long options with short options is ambiguous
at best, and not supported by reStructuredText.

> 2) some lines with arguments fail to process correctly.

See the spec for correct syntax. Non-POSIX styles are not supported though.

> * As an alternative, I could enclose all lines in a literal block. But then,
> how can I place emphasis on some of the words within the literal block?

You could use a parsed literal block:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

> * A 3rd possibility is do the mark-up word by word. But then, how can I
> insert tabs to enforce vertical alignment?

Again, there are no tabs. You could use a table.

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

[Docutils-users] many-character option list

[Gary M. <ga...@ia...>]

* How can I make a many-character non-POSIX (i.e. single dash signs) option list, i.e.

-data file	# data filename

OR

-data file	-> data filename

where the first data is highlighted as a literal, the “file” is highlighted as emphasis (italics), and the tabulation between “file” and “#” or “->” is a real tab so that subsequent lines are vertically aligned?

Using standard option lists doesn’t work: 
1) multiple-character options have their first letter in literal and the next ones in emphasis, which is weird. 
2) some lines with arguments fail to process correctly.

* As an alternative, I could enclose all lines in a literal block. But then, how can I place emphasis on some of the words within the literal block?

* A 3rd possibility is do the mark-up word by word. But then, how can I insert tabs to enforce vertical alignment?

	thanks in advance

	Gary Mamon

Re: [Docutils-users] How to create and reference custom heading ids with reStructuredText?

[Guenter M. <mi...@us...>]

On 2018-02-14, Ciro Santilli wrote:

> Please CC.

This doesn't work with slrn via GMANE, sorry.

> Cross post:
> https://stackoverflow.com/questions/48759542/how-to-create-and-reference-custom-heading-ids-with-restructuredtext

> Currently, if I have:

>     My header
>     =========

>     `My header`_
 
> `rst2html` Docutils 0.14 produces:

>     <div class="document" id="my-header">
>     <h1 class="title">My header</h1>

>     <p><a class="reference internal" href="#my-header">My header</a></p>

> Is it possible to obtain the following ouptut instead:

>     <h1 class="title" id="my-custom-header">My header</h1>

>     <p><a class="reference internal" href="#my-custom-header">My
> header</a></p>

Not easily, but see below.

> So note how I want two changes:

> - the id to be inside the heading, not on a separate div

The separate div is the HTML4-compatible representation of the section
element (with the HTML5 writer this will eventually become a <section>
element, too). With Docutils, the id is given to the <section>, not the
section's <title>.

> - control over the actual id

In Docutils, an element can have multiple ids but for the HTML
representation these need to be put on separate elements.
The current mechanism works for most practical purposes -- you may create a
custom HTML writer or propose a patch (and good resons for a change) to have
the custom id replacing the auto-generated one.

> The closest I could get was:

>     <div class="document" id="my-header">
>     <span id="my-custom-header"></span>
>     <h1 class="title">My header</h1>

>     <p><a class="reference external" href="my-custom-header">My
> header</a></p>

> but this is still not ideal, as I now have multiple ids floating around,
> and not inside the `h1`.

> Asciidoc for example has that covered with:

>     [[my-custom-header]]
>     == My header

>     <<my-custom-header>>

Well, the input is quite similar to the rST you probably used to get the
"close version"::


    .. _my custom header:
    
    My header
    =========
  
    `my custom header`_

This is translated to the internal representation::

  <document source="/tmp/foo.rst">
      <target refid="my-custom-header"></target>
      <section ids="my-header my-custom-header" 
               names="my\ header my\ custom\ header">
          <title>My header</title>
          <paragraph><reference name="my custom header"
                                refid="my-custom-header">my custom
                     header</reference></paragraph>
      </section>
  </document>

So everything is there to get the desired HTML output via a custom writer.
But is it worth the effort?


Günter

   

[Docutils-users] How to create and reference custom heading ids with reStructuredText?

[Ciro S. <cir...@gm...>]

Please CC.

Cross post:
https://stackoverflow.com/questions/48759542/how-to-create-and-reference-custom-heading-ids-with-restructuredtext

Currently, if I have:

    My header
    =========

    `My header`_

`rst2html` Docutils 0.14 produces:

    <div class="document" id="my-header">
    <h1 class="title">My header</h1>

    <p><a class="reference internal" href="#my-header">My header</a></p>

Is it possible to obtain the following ouptut instead:

    <h1 class="title" id="my-custom-header">My header</h1>

    <p><a class="reference internal" href="#my-custom-header">My
header</a></p>

So note how I want two changes:

- the id to be inside the heading, not on a separate div
- control over the actual id

The closest I could get was:

    <div class="document" id="my-header">
    <span id="my-custom-header"></span>
    <h1 class="title">My header</h1>

    <p><a class="reference external" href="my-custom-header">My
header</a></p>

but this is still not ideal, as I now have multiple ids floating around,
and not inside the `h1`.

Asciidoc for example has that covered with:

    [[my-custom-header]]
    == My header

    <<my-custom-header>>

Re: [Docutils-users] citation syntax

[Guenter M. <mi...@us...>]

On 2018-01-12, Alan Isaac wrote:
> Might it be possible to consider supporting an extension
> to the citation syntax?

I cannot tell how simple or difficult this becomes but I'd rather
concentrate on an integrated `Footnote & Citation Gathering`__.
Would you like to cooperate on this?

__ http://docutils.sourceforge.net/docs/dev/todo.html#unimplemented-transforms

Meanwhile I tried to turn your example into an MWE and think about a
temporary workaround.

Thanks Günter


At the moment, I find myself often supporting anonymous links to
citations like `Isaac and Jass (2011)`__.

The reason is that the standard citation reference must occur in the
document if we are to extract the references for processing into
a citation list (e.g., with bibstuff).

__ isaac-2011-jasss_
.. [isaac-2011-jasss]_


__ http://docutils.sourceforge.net/docs/dev/todo.html#unimplemented-transforms

An alternative workaround would be to use aliases like `Milde and Monecke (1989)
<ref:the_bib_key_>`__. A reference manager (extended bibstuff, say) would
need to scan for `ref: ...` links and insert the citation target.

The references section would be inserted by the reference manager

References
==========

.. [isaac-2011-jasss] fist example reference, 2011.
.. _`ref:the_bib_key`:
.. [mm89] second example reference, 1989.

[Docutils-users] citation syntax

[Alan I. <ala...@gm...>]

Might it be possible to consider supporting an extension
to the citation syntax?  At the moment, I find myself
often supporting anonymous links to citations by e.g.

   __ isaac-2011-jasss_
   .. [isaac-2011-jasss]_

The reason is that the standard citation reference must occur in the
document if we are to extract the references for processing into
a citation list (e.g., with bibstuff).  It would be nice if we
could just write

   __ [isaac-2011-jasss]_

Would allowing the identifier of indirect links to be in brackets
break things?

Thanks for considering,
Alan Isaac

Re: [Docutils-users] Slide Presentations In RestructuredText?

[Gour <go...@at...>]

On Sat, 16 Aug 2014 11:41:38 +0200
Valentin Haenel <val...@gm...> wrote:

It's an old thread, but the question is really the same, iow. what would you
recommend **today** to create slide-show presentations by using rst markup, preferrably
PDF-based so that I can use e.g. pdfpc (https://pdfpc.github.io/) to easily
incorporate speaker notes.

> I do have my own fork on github and use a custom template, but
> wouldn't recommend it actually.

What about this one: https://github.com/myint/rst2beamer ?

> And lastly -- this is my favorite option right now -- you can use
> pandoc to make beamer slides from RST:

Hmm, I thought that e.g. it's not possible to do:

rst –> beamer 

with pandoc?

I have also found the following projects:

- hieroglyph: https://github.com/nyergler/hieroglyph and

- rst2html5:https://github.com/marianoguerra/rst2html5

but both projects create HTML/JS-powered presentations, while I'd prefer PDF
although I abandoned idea to learn & use ConTeXt.

Any recent experience?


Sincerely,
Gour

-- 
For him who has conquered the mind, the mind is the best of
friends; but for one who has failed to do so, his mind will
remain the greatest enemy.