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

[Docutils-users] docutils.conf and rst2html5

[Matěj C. <mc...@ce...>]

Using “rst2html5 (Docutils 0.13.1 [release], Python 2.7.13, on 
linux2)” and this docutils.conf in the directory with my *.rst 
file:

[general]
input_encoding=utf-8
[html5 writer]
cloak_email_addresses: yes
stylesheet_path: minimal.css,plain.css,mystyle.css
template: layout.tpl

I get no stylesheet or template used. However, when I run 

    $ rst2html5 --template=layout.tpl \
        --stylesheet-path=minimal.css,plain.css,mystyle.css \
        source.rst >output.html

both template and stylesheets are used.

What’s the difference?

Best,

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
I love deadlines. I like the whooshing sound they make as they
fly by.
  -- Douglas Adams, The Salmon of Doubt

Re: [Docutils-users] Output rst comments to HTML5?

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

Dear Matěj,

On 2017-02-27, Matěj Cepl wrote:
> Would it be possible to persuade rst2html5 to output comments as 
><p class="comment"> (or something of that sort) in HTML? So, 
> that it would be possible to have comments visible in the draft 
> version of the document?

This is possible via subclassing the writer and overriding the 
  visist_comment/depart_comment
methods.

The simpler method would be to set the class in the rst source::

   .. class:: comment
   
      This is a paragraph with class="comment" in all export formats.

which becomes::

 <document source="/tmp/comm.rst">
    <paragraph classes="comment">
        This is a paragraph with class="comment" in all export formats.

(The class directive allows content, an empty class directive is applied to
the next element.)

Changing these comments to "real" rst comments is a simple replace-all task.

Günter 

[Docutils-users] Output rst comments to HTML5?

[Matěj C. <mc...@ce...>]

Would it be possible to persuade rst2html5 to output comments as 
<p class="comment"> (or something of that sort) in HTML? So, 
that it would be possible to have comments visible in the draft 
version of the document?

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
My opinions may have changed, but not the fact that I am right.
    --Ashleigh Brilliant

Re: [Docutils-users] kbd role

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

On 2017-02-16, Alan Isaac wrote:
> On 2/16/2017 3:05 PM, David Goodger wrote:
>> https://www.w3schools.com/tags/tag_kbd.asp lists the following "phrase tags":

>> <em> Renders as emphasized text
>> <strong> Defines important text
>> <code> Defines a piece of computer code
>> <samp> Defines sample output from a computer program
>> <kbd> Defines keyboard input
>> <var> Defines a variable

>> Currently Docutils outputs <em>, <strong>, and <code>, but not the
>> other three. If we add <kbd>, must we add the last two? If not, why
>> not?

http://www.html-5.com/tags/index.html#html-phrase-elements lists some more
phrase tags:

<abbr> <cite> <code> <dfn> <em> <figcaption> <kbd> <mark> <q> <s> <samp>
<strong> <sub> <sup> <time> <u> <var>

plus the change tracking tags <ins> and <del>.

The W3C specification
https://www.w3.org/TR/html5/dom.html#phrasing-content lists even more:

  3.2.4.1.5 Phrasing content

  Phrasing content is the text of the document, as well as elements that
  mark up that text at the intra-paragraph level. Runs of phrasing
  content form paragraphs.

  a abbr area (if it is a descendant of a map element) audio b bdi bdo br
  button canvas cite code data datalist del dfn em embed i iframe img
  input ins kbd keygen label map mark math meter noscript object output
  progress q ruby s samp script select small span strong sub sup svg
  template textarea time u var video wbr Text 

(see also
https://www.w3.org/TR/html5/text-level-semantics.html#text-level-semantics).


Not all of them need special support on all "Docutils levels":

a) reSt syntax
   
   *em* and **strong** are supported via special syntax as they are widely
   used basic text styles.
   
   :sub: and :sup: are standard roles because of wide use.
   
   :code:`code` is supported because we want syntax highlighting
   
   <figcaption> is the first paragraph of a figure directive content.
   
   The other tags have no corresponding standard roles but can be easily
   emulated via custom roles.

b) Docutils doctree

   There are elements for <emphasis>, <strong>, <subscript>, <superscript>,
   and the <figure>'s <caption> sub-element.
   
   "code" is represented as a <literal> element with class "code".

   Others can be represented with special class values to a suitable base
   element, too.

c) HTML output

   A <pre class="code"> Docutils doctree element is converted to <code>
   by the HTML writer.

...

> My personal reason for inquiring about `kbd` (but not about
> `samp` or `var`) is purely frequency of use.  I use a `kbd`
> role almost as often as a `code` role (and much more often
> than `strong`).

> I suppose the best general argument turns on the value of a semantic
> web. 

   
We could consider similar handling for other "obvious" classes like kbd,
abbr, cite, dfn, samp, var, del, or ins. Then the HTML writer would produce,
e.g.,
    
    <cite>Elements of style</cite>
    
instead of

    <span class="cite">Elements of style<span>
    
for the rst input::

  .. role:: cite
  
  :cite:`Elements of style`    


Günter

Re: [Docutils-users] kbd role

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

On 2/16/2017 3:05 PM, David Goodger wrote:
> https://www.w3schools.com/tags/tag_kbd.asp lists the following "phrase tags":
>
> <em> Renders as emphasized text
> <strong> Defines important text
> <code> Defines a piece of computer code
> <samp> Defines sample output from a computer program
> <kbd> Defines keyboard input
> <var> Defines a variable
>
> Currently Docutils outputs <em>, <strong>, and <code>, but not the
> other three. If we add <kbd>, must we add the last two? If not, why
> not?


It is easy to imagine an argument for adding all of these.
It is also easy to imagine an argument for having none of these.
Since no criterion for inclusion has been offered, it is difficult
to choose between these arguments.

My personal reason for inquiring about `kbd` (but not about
`samp` or `var`) is purely frequency of use.  I use a `kbd`
role almost as often as a `code` role (and much more often
than `strong`).

I suppose the best general argument turns on the value of a semantic web.
Here the `kbd` tag seems quite valuable in improving webpage accessibility.
But again, I was not motivated by general arguments, but simply
by my personal frequency of use.

Cheers,
Alan

Re: [Docutils-users] kbd role

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

On Wed, Feb 15, 2017 at 9:45 PM, Alan Isaac <ala...@gm...> wrote:
> On 2/15/2017 7:51 PM, David Goodger wrote:
>> What would :span:`text` do?
>
> Sorry; coffee wore off while fingers were typing.
>
>
>> What should :kbd:`text` do?
>
>
> For the HTML5 writer, it would add a `kbd` element,
> just like the `code` role produces a `code` element.

https://www.w3schools.com/tags/tag_kbd.asp lists the following "phrase tags":

<em> Renders as emphasized text
<strong> Defines important text
<code> Defines a piece of computer code
<samp> Defines sample output from a computer program
<kbd> Defines keyboard input
<var> Defines a variable

Currently Docutils outputs <em>, <strong>, and <code>, but not the
other three. If we add <kbd>, must we add the last two? If not, why
not?

I note that HTML doesn't have a generic "literal" tag, but up to 4
variations instead.

> The reasons for preferring this output to a `span` element
> with a `kbd` class is the same set of reasons that have
> led the `kbd` element not to be deprecated in HTML5.

Please provide a summary or a link, because I don't know what these
reasons are/were.

> But  I clearly do not understand the policy for roles.
> What motivated the current set of roles?

It's what made sense to me at the time, along with input from the
community over the years.

> Have the
> criteria for being a standard role been articulated?

No, except for what has been discussed and what is now being discussed
on these mailing lists.

> Is it something other than "convenience" for authors?

There's also the cost of implementation (parser, all writers, tests,
documentation), and the added cost of complexity for users (new roles
make reST bigger). That's balanced against the utility to
users/authors. If that utility is just "I don't want to write a
one-liner, .. role:: kbd, and a style", that's not enough (to me) to
counter the costs.

> Although I used the `code` role for comparison, I can see that
> it will often be subclassed while that would be less common
> with `kbd` role.  For that reason, I see that the the case
> is much weaker for a `kbd` standard role.
>
> I won't say anything more about this.  I just wanted to
> know if there might be developer interest.

Not from me, but maybe from others.

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

Re: [Docutils-users] kbd role

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

On Wed, Feb 15, 2017 at 6:33 PM, Alan Isaac <ala...@gm...> wrote:
> Might consideration be given to adding a `kbd` standard role?

What should :kbd:`text` do?

> I realize I can use a custom role.  But I am encountering the
> need for this so often that I wonder if it other are in the
> same situation, so that there might be support among the
> developers for including this as a standard role.
> (And if not something this specific, perhaps a simple
> `span` role to inherit from?)

What would :span:`text` do?

Simple interpreted text roles are already equivalent to HTML <span>
tags. Why would we add a "span" role?

I'm really just curious here.

> I realize that the multiplication of standard roles is not
> desirable.

True.

You'll need to provide some rationale for development work beyond
simple convenience. Especially when you can just write:

.. role:: kbd

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

[Docutils-users] kbd role

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

Might consideration be given to adding a `kbd` standard role?

I realize I can use a custom role.  But I am encountering the
need for this so often that I wonder if it other are in the
same situation, so that there might be support among the
developers for including this as a standard role.
(And if not something this specific, perhaps a simple
`span` role to inherit from?)

I realize that the multiplication of standard roles is not
desirable.

Cheers,
Alan Isaac

Re: [Docutils-users] background color experimentation...

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

On 2017-02-13, Paul Flint wrote:
> On Mon, 13 Feb 2017, David Goodger wrote:
...
>>> On Sun, 12 Feb 2017, David Goodger wrote:
>>>> On Fri, Feb 10, 2017 at 6:53 AM, Paul Flint <fl...@fl...> wrote:


>>>>> 1. Easy one - make the background color of your choice:

>>>>> .. raw:: html

>>>>>    <body style="background-color:#E6E6FA;">

>>>> You don't need to use the "raw" directive for this. This can be done
>>>> easily via a stylesheet:
>>>> http://docutils.sourceforge.net/docs/howto/html-stylesheets.html

...

>>> That said, my use case is that I have about 100 DVDs (Source Linux Format)
>>> that I am putting up on the web. Each DVD has a page that shows the original
>>> front and back cover.  What I wanted was that each of these pages display in
>>> a color of the season.  My idea was to put together these DVD "base pages"
>>> using a bash script (I am a registered bashist.  See http://visualbash.org
>>> :^) and cycling through some seasonally appropriate pastel colors to help
>>> the user differentiate between the various DVDs.

>>> The ".. raw" directive was wildly successful in allowing this page-by-page
>>> transition.  Could I advantage myself with the css approach?

>> You'd have to change the CSS for each page.

> Actually what I got to thinking about was a way to add a 
> reStructuredText element which would query the css for the appropriate 
> background shade...

> For example:

>    SEASON   BACKGROUND
>    spring = a warming color
>    summer = a warm color
>    fall   = a cooling color
>    winter = a cool colr

Use classes: 

The custom CSS sheet defines rules like::

  .figure.spring { background-color:#E6E6FA; }

(adapt the selector to the element you want to give the background).
and in bash script don't insert raw HTML but class values.

Günter

Re: [Docutils-users] background color experimentation...

[Paul F. <fl...@fl...>]

Greetings David Goodger,

On Mon, 13 Feb 2017, David Goodger wrote:

>> In your kind response, you make some interesting points.  I will respond
>> below.
>>
>> On Sun, 12 Feb 2017, David Goodger wrote:
>>
>>> On Fri, Feb 10, 2017 at 6:53 AM, Paul Flint <fl...@fl...> wrote:
>>>>
>>>> 1. Easy one - make the background color of your choice:
>>>>
>>>> .. raw:: html
>>>>
>>>>    <body style="background-color:#E6E6FA;">
>>>
>>>
>>> You don't need to use the "raw" directive for this. This can be done
>>> easily via a stylesheet:
>>> http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
>>>
>>
>> Very cool.  For openers, I did not know about rst2html.py - Thanks.  BTW
>> nice style in the python code!  I could learn a thing or two from you.
>>
>> That said, my use case is that I have about 100 DVDs (Source Linux Format)
>> that I am putting up on the web. Each DVD has a page that shows the original
>> front and back cover.  What I wanted was that each of these pages display in
>> a color of the season.  My idea was to put together these DVD "base pages"
>> using a bash script (I am a registered bashist.  See http://visualbash.org
>> :^) and cycling through some seasonally appropriate pastel colors to help
>> the user differentiate between the various DVDs.
>>
>> The ".. raw" directive was wildly successful in allowing this page-by-page
>> transition.  Could I advantage myself with the css approach?
>
> You'd have to change the CSS for each page.

Actually what I got to thinking about was a way to add a 
reStructuredText element which would query the css for the appropriate 
background shade...

For example:

   SEASON   BACKGROUND
   spring = a warming color
   summer = a warm color
   fall   = a cooling color
   winter = a cool colr

The Vermont version would of course, also contain:
   Mud Season
   Black Fly Season

> I'm not sure how your raw hack works, since you should end up with
> multiple <body> elements in your output HTML, unless you also changed
> the template. This might render in browsers but it's not valid HTML.
>
Na, I checked.  It over-rode .../_static/alabaster.css

>> This experience has led me to the very disturbing conclusion that you could
>> (and maybe should) write all web pages in reStructuredText.  Should I seek
>> professional help?
>
> No, I don't think so. :-) That's what I do as well, and what many of us do.
>

Hm...

>>>> 2. Less easy one - Postprocessing the html to get the image to open in a
>>>> new tab:
>>>
>>> This has been on the to-do list for a long time, but (a) it's not a
>>> high-frequency request (yours is the first I can recall), and (b) no
>>> obviously correct solution has been proposed. The to-do list has a
>>> proposal to emulate the MoinMoin wiki's use of "^" as a prefix for
>>> this purpose.
>>
>> Interesting bit of extended notation.  I need to think if this would work...
>>
>>> If you want this for every image in all of some subset of your
>>> documents, you could create a custom Writer deriving from the HTML
>>> Writer you already use (or its Sphinx equivalent).
>>>
>>
>> My fix for this was to go directly to the resultant html and patch it there:
>>
>> <start code>
>> sphinx-build -b html ./ test ;
>> sed -i 's/><img/ target="_blank" ><img/g' test/index.html
>> <end code>
>
> That's very risky. It's adding “ target="_blank"” to any tag
> immediately before an <img> tag. Are you sure that they are all <a>
> tags, and always will be?
>
I go away with it... but I was not happy with this monster.

>> (Note what we bashists lack in finesse we make up with gusto... :^)
>
> Reminds me of:
>
>    Some people, when confronted with a problem, think "I know, I'll
> use regular expressions." Now they have two problems.
>
>    — Jamie Zawinski
>
> The same could be said about sed & awk.
>

I shall cherish this and use it with attribution not retribution...

>> Obviously the "MoinMoin" notation would go a step towards a standard wiki
>> markup language, and why not extend ourselves into this maelstrom?
>
> I'm not following you, and I'm a native English speaker. Many on this
> list are not. Repeat in plainer language please?
>

Indeed I once was before I started to program.  MoinMoin being of German 
provenance, it no doubt contains it's own markup syntax.  How much to we 
adopt?  That is my point here.

>> Finally thanks for the Venn diagram, and I expect we should get together in
>> Portland to rub antennae...  Are you up in Montreal?  I love that city!
>
> I used to live near Montreal, now I live in a suburb of the Twin
> Cities of Minnesota. It's only slightly warmer here.
>
Nice, and...


Kindest Regards,



☮ Paul Flint
(802) 479-2360 Home
(802) 595-9365 Cell

/************************************
Based upon email reliability concerns,
please send an acknowledgement in response to this note.

Paul Flint
17 Averill Street
Barre, VT
05641

Re: [Docutils-users] background color experimentation...

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

On Mon, Feb 13, 2017 at 8:12 AM, Paul Flint <fl...@fl...> wrote:
> Greetings David Goodger,
>
> First, thanks for the response.  Up here in the North Country one of our
> hobbies is staying under-the-radar, and thus we live in cold, dark,
> ignorance most of the time...
>
> In your kind response, you make some interesting points.  I will respond
> below.
>
> On Sun, 12 Feb 2017, David Goodger wrote:
>
>> On Fri, Feb 10, 2017 at 6:53 AM, Paul Flint <fl...@fl...> wrote:
>>>
>>>
>>> 1. Easy one - make the background color of your choice:
>>>
>>> .. raw:: html
>>>
>>>    <body style="background-color:#E6E6FA;">
>>
>>
>> You don't need to use the "raw" directive for this. This can be done
>> easily via a stylesheet:
>> http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
>>
>
> Very cool.  For openers, I did not know about rst2html.py - Thanks.  BTW
> nice style in the python code!  I could learn a thing or two from you.
>
> That said, my use case is that I have about 100 DVDs (Source Linux Format)
> that I am putting up on the web. Each DVD has a page that shows the original
> front and back cover.  What I wanted was that each of these pages display in
> a color of the season.  My idea was to put together these DVD "base pages"
> using a bash script (I am a registered bashist.  See http://visualbash.org
> :^) and cycling through some seasonally appropriate pastel colors to help
> the user differentiate between the various DVDs.
>
> The ".. raw" directive was wildly successful in allowing this page-by-page
> transition.  Could I advantage myself with the css approach?

You'd have to change the CSS for each page.

I'm not sure how your raw hack works, since you should end up with
multiple <body> elements in your output HTML, unless you also changed
the template. This might render in browsers but it's not valid HTML.

> This experience has led me to the very disturbing conclusion that you could
> (and maybe should) write all web pages in reStructuredText.  Should I seek
> professional help?

No, I don't think so. :-) That's what I do as well, and what many of us do.

>>> 2. Less easy one - Postprocessing the html to get the image to open in a
>>> new
>>> tab:
>>
>>
>> This has been on the to-do list for a long time, but (a) it's not a
>> high-frequency request (yours is the first I can recall), and (b) no
>> obviously correct solution has been proposed. The to-do list has a
>> proposal to emulate the MoinMoin wiki's use of "^" as a prefix for
>> this purpose.
>>
>
> Interesting bit of extended notation.  I need to think if this would work...
>
>> If you want this for every image in all of some subset of your
>> documents, you could create a custom Writer deriving from the HTML
>> Writer you already use (or its Sphinx equivalent).
>>
>
> My fix for this was to go directly to the resultant html and patch it there:
>
> <start code>
> sphinx-build -b html ./ test ;
> sed -i 's/><img/ target="_blank" ><img/g' test/index.html
> <end code>

That's very risky. It's adding “ target="_blank"” to any tag
immediately before an <img> tag. Are you sure that they are all <a>
tags, and always will be?

> (Note what we bashists lack in finesse we make up with gusto... :^)

Reminds me of:

    Some people, when confronted with a problem, think "I know, I'll
use regular expressions." Now they have two problems.

    — Jamie Zawinski

The same could be said about sed & awk.

> Obviously the "MoinMoin" notation would go a step towards a standard wiki
> markup language, and why not extend ourselves into this maelstrom?

I'm not following you, and I'm a native English speaker. Many on this
list are not. Repeat in plainer language please?

>>> Note sphinx is a lot of fun...
>>
>>
>> Maybe tell the Sphinx folks that? This is Docutils/reStructuredText,
>> which Sphinx does use, but they aren't the same thing :-)
>>
>
> Gotcha.  The most fun was getting the reStructuredText editor "enki" to run
> under Ubuntu 16.04.  I need to figure out how to communicate my zaniness to
> the Sphinx community...
>
>> David Goodger
>> <http://python.net/~goodger>
>>
>
> Finally thanks for the Venn diagram, and I expect we should get together in
> Portland to rub antennae...  Are you up in Montreal?  I love that city!

I used to live near Montreal, now I live in a suburb of the Twin
Cities of Minnesota. It's only slightly warmer here.

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

Re: [Docutils-users] background color experimentation...

[Paul F. <fl...@fl...>]

Greetings David Goodger,

First, thanks for the response.  Up here in the North Country one of our 
hobbies is staying under-the-radar, and thus we live in cold, dark, 
ignorance most of the time...

In your kind response, you make some interesting points.  I will respond 
below.

On Sun, 12 Feb 2017, David Goodger wrote:

> On Fri, Feb 10, 2017 at 6:53 AM, Paul Flint <fl...@fl...> wrote:
>>
>> 1. Easy one - make the background color of your choice:
>>
>> .. raw:: html
>>
>>    <body style="background-color:#E6E6FA;">
>
> You don't need to use the "raw" directive for this. This can be done 
> easily via a stylesheet: 
> http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
>

Very cool.  For openers, I did not know about rst2html.py - Thanks.  BTW 
nice style in the python code!  I could learn a thing or two from you.

That said, my use case is that I have about 100 DVDs (Source Linux Format) 
that I am putting up on the web. Each DVD has a page that shows the 
original front and back cover.  What I wanted was that each of these pages 
display in a color of the season.  My idea was to put together these DVD 
"base pages" using a bash script (I am a registered bashist.  See 
http://visualbash.org :^) and cycling through some seasonally appropriate 
pastel colors to help the user differentiate between the various DVDs.

The ".. raw" directive was wildly successful in allowing this page-by-page 
transition.  Could I advantage myself with the css approach?

This experience has led me to the very disturbing conclusion that you 
could (and maybe should) write all web pages in reStructuredText.  Should 
I seek professional help?

>> 2. Less easy one - Postprocessing the html to get the image to open in a new
>> tab:
>
> This has been on the to-do list for a long time, but (a) it's not a
> high-frequency request (yours is the first I can recall), and (b) no
> obviously correct solution has been proposed. The to-do list has a
> proposal to emulate the MoinMoin wiki's use of "^" as a prefix for
> this purpose.
>

Interesting bit of extended notation.  I need to think if this would 
work...

> If you want this for every image in all of some subset of your
> documents, you could create a custom Writer deriving from the HTML
> Writer you already use (or its Sphinx equivalent).
>

My fix for this was to go directly to the resultant html and patch it 
there:

<start code>
sphinx-build -b html ./ test ;
sed -i 's/><img/ target="_blank" ><img/g' test/index.html
<end code>

(Note what we bashists lack in finesse we make up with gusto... :^)

Obviously the "MoinMoin" notation would go a step towards a standard wiki 
markup language, and why not extend ourselves into this maelstrom?

>> Note sphinx is a lot of fun...
>
> Maybe tell the Sphinx folks that? This is Docutils/reStructuredText,
> which Sphinx does use, but they aren't the same thing :-)
>

Gotcha.  The most fun was getting the reStructuredText editor "enki" to 
run under Ubuntu 16.04.  I need to figure out how to communicate my 
zaniness to the Sphinx community...

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

Finally thanks for the Venn diagram, and I expect we should get together 
in Portland to rub antennae...  Are you up in Montreal?  I love that city!

Kindest Regards,


☮ Paul Flint
(802) 479-2360 Home
(802) 595-9365 Cell

/************************************
Based upon email reliability concerns,
please send an acknowledgement in response to this note.

Paul Flint
17 Averill Street
Barre, VT
05641

Re: [Docutils-users] background color experimentation...

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

On Fri, Feb 10, 2017 at 6:53 AM, Paul Flint <fl...@fl...> wrote:
> Greetings Earthlings (and anyone else :^),
>
> The nice documentation page indicated that I should write to this list when
> I am using the "raw" command too much.  I have needed it twice so here goes:
>
> 1. Easy one - make the background color of your choice:
>
> .. raw:: html
>
>    <body style="background-color:#E6E6FA;">

You don't need to use the "raw" directive for this. This can be done
easily via a stylesheet:
http://docutils.sourceforge.net/docs/howto/html-stylesheets.html

> 2. Less easy one - Postprocessing the html to get the image to open in a new
> tab:

This has been on the to-do list for a long time, but (a) it's not a
high-frequency request (yours is the first I can recall), and (b) no
obviously correct solution has been proposed. The to-do list has a
proposal to emulate the MoinMoin wiki's use of "^" as a prefix for
this purpose.

If you want this for every image in all of some subset of your
documents, you could create a custom Writer deriving from the HTML
Writer you already use (or its Sphinx equivalent).

> Note sphinx is a lot of fun...

Maybe tell the Sphinx folks that? This is Docutils/reStructuredText,
which Sphinx does use, but they aren't the same thing :-)

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

[Docutils-users] background color experimentation...

[Paul F. <fl...@fl...>]

Greetings Earthlings (and anyone else :^),

The nice documentation page indicated that I should write to this list 
when I am using the "raw" command too much.  I have needed it twice so 
here goes:

1. Easy one - make the background color of your choice:

.. raw:: html

    <body style="background-color:#E6E6FA;">


2. Less easy one - Postprocessing the html to get the image to open in a 
new 
tab:

sphinx-build -b html ./ test ;
sed -i 's/><img/ target="_blank" ><img/g' test/index.html

Note sphinx is a lot of fun...

Kindest Regards,

☮ Paul Flint
(802) 479-2360
(802) 595-9365 Cell

/************************************
Based upon email reliability concerns,
please send an acknowledgment in response to this note.

Paul Flint, Director
Barre Open Systems Institute
17 Averill Street
Barre, VT
05641

http://www.bosivt.org
http://family.flint.com/flint
skype: flintinfotech
Work: (202) 537-0480

Consilium                                       _ 
gratuitum        .~.     ASCII ribbon campaign ( )
valet            /V\      against HTML e-mail   X
quanti          /( )\     www.asciiribbon.org  / \ 
numerantur      ^^-^^

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-04, Matěj Cepl wrote:
> On 2017-02-04, 21:41 GMT, Guenter Milde wrote:
>> Patch attached.

> When reapplying this patch to my Fedora package (and I got 
> http://paste.fedoraproject.org/546590/62467941/) I get these 
> errors in the testsuite 
> (https://paste.fedoraproject.org/546589/14862467/).

> Any thoughts?

A (temporary) complete patch is now available under
https://sourceforge.net/p/docutils/patches/99/#be1e

It will be discussed in docutils-devel and eventually a version of this or
some other solution be included in the repo.

Thanks,

Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-04, Matěj Cepl wrote:
> So, I have a document which should start like this:


>     Druhý život Petunie Dursleyové
>     ##############################

>     .. epigraph::

>         Co je nejvyšším cílem člověka?

>         Nejvyšším cílem člověka je oslavovat Boha a věčně se 
>         z Něj radovat.

>         -- Westminsterský katechismus, 1647

>     Na cizinecké policii
>     --------------------

>     Hustě sněžilo, obloha byla zatažená a cítila se mizerně. 
>     Její náladě ani nepřidalo to, že budova cizinecké policie 

> This works perfectly with rst2html (or rst2html5 for that 
> matter, which seems a way cooler ... thank you for that!), but 
> it completely breaks rst2xetex.

 I get this LaTeX code for the 
> epigraph:

>     \begin{quote}
>     \DUrole{epigraph}{
>     Co je nejvyšším cílem člověka?

>     Nejvyšším cílem člověka je oslavovat Boha a věčně se z Něj 
>     radovat.
>     \nopagebreak

>     \raggedleft —Westminsterský katechismus, 1647
>     }
>     \end{quote}

> And this error when run through xelatex:

>     Runaway argument?
>     { Co je nejvyšším cílem člověka? 
>     ! Paragraph ended before \DUrole was complete.
>     <to be read again> 
>                        \par 
>     l.71 

The reason for the error is a bug in the LaTeX writer:

\DUrole is a LaTeX macro to give some sort of support for styling via
class arguments in inline markup (Docutils roles).
See http://docutils.sourceforge.net/docs/user/latex.html#custom-interpreted-text-roles

It is defined with \providecommand* -- the starred version does not allow
paragraph breaks withing the argument to allow better error reporting.
This is good for inline markup.

Unfortunatly, this limitation was not accounted for when the "ersatz class
mechnism" was used for some block-level objects (e.g. "quote").


> How can I have a paragraph break inside of ..epigraph?

Unless you intend a special styling for epigraphs, using a standard quote
is the most simple workaround.

E.g. by removing the "directive dots"::

   .. epigraph (currently the LaTeX writer fails with epigraph)
    
        Co je nejvyšším cílem člověka?

        ...
	
Explanation:

The `epigraph` directive is just syntactic sugar for::

  .. class:: epigraph
  
  ..
  
      The epigraph text
    
i.e. the content is converted to a quote element with class argument
"epigraph" by Docutils during the parsing.


A fix will follow, but needs some more discussion and thougts about the
optimal approach.

Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-05, Alan G. Isaac wrote:
> On 2/5/2017 3:40 AM, Guenter Milde wrote:
>> Formatting block quotes will "spill over" to epigraphs by default.
>> *This is intended*, as an epigraph is a special quote.

> As you say: *by default*.
> But my question is:
> how can the *user* readily decouple them?

> In HTML+CSS this is trivial.
> My question is:
> how can this be made trivial with LaTeX output?

It cannot be made trivial, unfortunately.

> The problem is the different model in LaTeX:
> environments cannot truly be arbitrarily classed.

Nothing can be arbitrarily classed in LaTeX.
And "epigraph" is just one example. A user could set any class value to any
object -- is it unfeasable to have special environments and functions
prepared for all of them.

> I assume we agree that epigraphs are often
> indented differently in a document than
> regular block quotes.  For example, in a book
> I am now reading, the epigraphs have no indentation.

> Your proposal (if I understand it) is that LaTeX
> users somehow try to style the environment content
> rather than the environment.  Your example was::

>    \newcommand{\DUclassepigraph}{\em}

Yes.

> I do not see how a user can discard the surrounding
> quote environment with this approach (e.g., to
> achieve the formatting in the book mentioned above).

In most cases, there is no need to "swap" the complete environment. E.g.
changing margins (your above example) is relatively simple also "from
inside" an environment.

> Again, if this were done with environments, the use
> could just use ``\renewenvironment``.  Would such
> an approach create implementation difficulties?

The idea is to keep the LaTeX source as simple as possible while still
allowing customization.

With ::

  \begin{something}
    \DUclass{classvalue}

    content
  \end{something}

the redefintions by \DUclassclassvalue are confined to the environment
without further effort.
Alternatively, one could use an additional wrapper ::

   {
   \DUclass{classvalue}
     \begin{something}

       content
     \end{something}
   }

or a 2-arg class macro:

   \DUclass{classvalue}{%
     \begin{something}

       content
     \end{something}%
   }

This would allow a complete redefinition of the environments
in the \DUclass function at the cost of additional nesting.

Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-05, Alan G. Isaac wrote:
> On 2/5/2017 3:40 AM, Guenter Milde wrote:
>> LaTeX, the above epigraph becomes

>> \begin{quote}
>> \DUclass{epigraph}%

>> No matter where you go, there you are.
>> \nopagebreak

>> \raggedleft —Buckaroo Banzai

>> \end{quote}


> 1. Did things very recently change, or is that \DUrole not \DUclass?
>     I cannot update at the moment, but I suppose this changed in
>     response to Matěj.

It is \DUrole, a new function introduced in the patch I posted in my
first response.

> 2. Fixing that, this does not compile, because of the paragraph break.

This is what the OP reported.

> 3. That failure is linked to this ongoing discussion.  I.e., it
>     illustrates why environments should be used.
>     (Perhaps the change in response to Matěj fixes this.)

Yes, the change fixed this.

> 4. Also related, note that this structure makes no allowance for
>     separate formatting of the author (in contrast to the HTML output).

Just like in "normal" quotes and many other instances.

>     E.g., suppose I want the text in italic but not the author name?
>     (Easy in HTML+CSS. 

Yes, HTML/CSS works with the classes a lot better than LaTeX. The \DUrole
and \DUclass functions are a attempt to bring at least some of this
functionality to LaTeX.

OTOH, I can define something like ::

\let\origraggedleft\raggedleft
\newcommand{\DUclassepigraph}{%
  \em%
  \renewcommand{\raggedleft}{\origraggedleft\rm}
}

Untested.

> Would be easy here too if environments were used...)

I agree that the possibilities are limited, but I don't see how replacing
{quote} with another environment would help.

Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

[Alan G. I. <ai...@am...>]

On 2/5/2017 3:40 AM, Guenter Milde wrote:
> Formatting block quotes will "spill over" to epigraphs by default.
> *This is intended*, as an epigraph is a special quote.

As you say: *by default*.
But my question is:
how can the *user* readily decouple them?

In HTML+CSS this is trivial.
My question is:
how can this be made trivial with LaTeX output?

The problem is the different model in LaTeX:
environments cannot truly be arbitrarily classed.

I assume we agree that epigraphs are often
indented differently in a document than
regular block quotes.  For example, in a book
I am now reading, the epigraphs have no indentation.

Your proposal (if I understand it) is that LaTeX
users somehow try to style the environment content
rather than the environment.  Your example was::

   \newcommand{\DUclassepigraph}{\em}

I do not see how a user can discard the surrounding
quote environment with this approach (e.g., to
achieve the formatting in the book mentioned above).
Again, if this were done with environments, the use
could just use ``\renewenvironment``.  Would such
an approach create implementation difficulties?

Thanks,
Alan

PS Since I seem to quickly wear out my welcome on this
list (for reasons I do not quite understand), I will not
say anything more about this.

Re: [Docutils-users] broken ..epigraph in XeTeX?

[Alan G. I. <ai...@am...>]

On 2/5/2017 3:40 AM, Guenter Milde wrote:
> LaTeX, the above epigraph becomes
>
> \begin{quote}
> \DUclass{epigraph}%
>
> No matter where you go, there you are.
> \nopagebreak
>
> \raggedleft —Buckaroo Banzai
>
> \end{quote}


1. Did things very recently change, or is that \DUrole not \DUclass?
    I cannot update at the moment, but I suppose this changed in
    response to Matěj.
2. Fixing that, this does not compile, because of the paragraph break.
3. That failure is linked to this ongoing discussion.  I.e., it
    illustrates why environments should be used.
    (Perhaps the change in response to Matěj fixes this.)
4. Also related, note that this structure makes no allowance for
    separate formatting of the author (in contrast to the HTML output).
    E.g., suppose I want the text in italic but not the author name?
    (Easy in HTML+CSS.  Would be easy here too if environments were used...)

Thanks,
Alan Isaac

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-04, Alan G. Isaac wrote:
> On 2/4/2017 4:41 PM, Guenter Milde wrote:
>> Both "quote" and "quotation" provide for multiple paragraphs.

> I did not mean to call that into question
> Indeed, this is addressed at the link I provided:
> https://en.wikibooks.org/wiki/LaTeX/Paragraph_Formatting#Quoting_text

> My point was rather that these are **quotation** environments,
> not general indentation environments.  To use a quotation
> environment whenever indentation is needed is to disregard
> its intended use (semantics).  That is my point.

However, according to the wiktionary, an epigraph is

  1. an inscription, especially one on a building.
  2. a literary quotation placed at the beginning of a book or other
     text.
  3. (mathematics, of a function) the set of all points lying on or above
     the function's graph.

For Docutils, 2. is relevant and hence it defines the "epigraph" directive:

   Epigraph
   
   Directive Type
       “epigraph” 

   Doctree Element
       block_quote 

   Directive Arguments
       None. 

   Directive Options
       None. 

   Directive Content
       Interpreted as the body of the block quote. 
   
   An epigraph is an apposite (suitable, apt, or pertinent) short
   inscription, often a quotation or poem, at the beginning of a document
   or section.
   
   The “epigraph” directive produces an “epigraph”-class block quote. For
   example, this input:
   
   .. epigraph::
   
      No matter where you go, there you are.
   
      -- Buckaroo Banzai
   
   becomes this document tree fragment:
   
   <block_quote classes="epigraph">
       <paragraph>
           No matter where you go, there you are.
       <attribution>
           Buckaroo Banzai



>> Alan wrote:
>>> this again compromises the ability to separately style quotes
>>> and other content (in this case, epigraphs).

> On 2/4/2017 4:41 PM, Guenter Milde wrote:
>> Not if the class arguments are handled correctly.

> I thought that this makes it impossible to change the
> formatting of actual quotes without having that spilling
> over to other environments (such as epigraph).

Formatting block quotes will "spill over" to epigraphs by default. 
*This is intended*, as an epigraph is a special quote.

It can be offset by styling the quote environments with class value epigraph
(in HTML you use CSS rules, in LaTeX by defining a function \DUclassepigraph).

> Your response seems to suggest otherwise.  How for example
> would I style quotes to have an extra one inch margin on the left
> and right but epigraphs to have an extra two inches on the left only?
> (I am assuming that epigraphs continue to be wrapped in a ``quote``
> environment.)  Am I overlooking something obvious?

I LaTeX, the above epigraph becomes

\begin{quote}
\DUclass{epigraph}%

No matter where you go, there you are.
\nopagebreak

\raggedleft —Buckaroo Banzai

\end{quote}


I don't know the details of margin changing off by heart, but the idea is
to use the "class macro" to style the environments with the given class, e.g.
to set the epigraph in italics, you can write

 \newcommand{\DUclassepigraph}{\em}
 
in the preamble.

Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

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

On 2017-02-04, Matěj Cepl wrote:
> On 2017-02-04, 22:21 GMT, Matěj Cepl wrote:
>> On 2017-02-04, 21:41 GMT, Guenter Milde wrote:
>>> Patch attached.

>> When reapplying this patch to my Fedora package (and I got 
>> http://paste.fedoraproject.org/546590/62467941/) I get these 
>> errors in the testsuite 
>> (https://paste.fedoraproject.org/546589/14862467/).

The proposed patch to the LaTeX writer changed the output of the test samples.
This was expected. Now I have to check if these changes are as intended and
don't break other parts.

The complete patch will also contain an update of the testsuite and
documentation, of course.

> And yes, when I switch of the checking of the testsuite (which 
> I would rather not), then the patch really helps to solve the 
> problem.

Glad to hear this.


Günter

Re: [Docutils-users] broken ..epigraph in XeTeX?

[Matěj C. <mc...@ce...>]

On 2017-02-04, 22:21 GMT, Matěj Cepl wrote:
> On 2017-02-04, 21:41 GMT, Guenter Milde wrote:
>> Patch attached.
>
> When reapplying this patch to my Fedora package (and I got 
> http://paste.fedoraproject.org/546590/62467941/) I get these 
> errors in the testsuite 
> (https://paste.fedoraproject.org/546589/14862467/).

And yes, when I switch of the checking of the testsuite (which 
I would rather not), then the patch really helps to solve the 
problem.

Thanks,

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Reality is merely an illusion, albeit a very persistent one.
      -- Albert Einstein

Re: [Docutils-users] broken ..epigraph in XeTeX?

[Alan G. I. <ai...@am...>]

On 2/4/2017 4:41 PM, Guenter Milde wrote:
> Both "quote" and "quotation" provide for multiple paragraphs.

I did not mean to call that into question
Indeed, this is addressed at the link I provided:
https://en.wikibooks.org/wiki/LaTeX/Paragraph_Formatting#Quoting_text

My point was rather that these are **quotation** environments,
not general indentation environments.  To use a quotation
environment whenever indentation is needed is to disregard
its intended use (semantics).  That is my point.


> Alan wrote:
>> this again compromises the ability to separately style quotes
>> and other content (in this case, epigraphs).

On 2/4/2017 4:41 PM, Guenter Milde wrote:
> Not if the class arguments are handled correctly.

I thought that this makes it impossible to change the
formatting of actual quotes without having that spilling
over to other environments (such as epigraph).
Your response seems to suggest otherwise.  How for example
would I style quotes to have an extra one inch margin on the left
and right but epigraphs to have an extra two inches on the left only?
(I am assuming that epigraphs continue to be wrapped in a ``quote``
environment.)  Am I overlooking something obvious?

Thanks,
Alan

Re: [Docutils-users] broken ..epigraph in XeTeX?

[Matěj C. <mc...@ce...>]

On 2017-02-04, 21:41 GMT, Guenter Milde wrote:
> Patch attached.

When reapplying this patch to my Fedora package (and I got 
http://paste.fedoraproject.org/546590/62467941/) I get these 
errors in the testsuite 
(https://paste.fedoraproject.org/546589/14862467/).

Any thoughts?

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
How many Bavarian Illuminati does it take to screw in a light
bulb?
Three: one to screw it in, and one to confuse the issue.