docutils-users Mailing List for Docutils: Documentation Utilities

summary
=======

Small reST document (linked and attached) has sections with unique names. When I use docutils/restview to convert it to HTML, all but one section id is created by (speaking `sed`ishly) `s/ /-/g`. However *one* section id is "hashed" (i.e., created like a backref), which breaks an explicit internal anchor. Why not create all section IDs in the same way? More importantly, how to fix this (presuming as I do that it's a problem)?

details
=======

background
----------

I frequently generate HTML from reStructuredText, either directly or indirectly. I also frequently do internal linking: i.e., I create explicit links from text in one section of a document to another section. I'm currently working on a reST document which also exhibits the following problem (and have also experienced this previously), which I have "boiled down" to a relatively simple file name=problematic_naming_of_internal_anchors.rst , which I have mounted @

https://bitbucket.org/!api/2.0/snippets/tlroche/LR9oL/HEAD/files/problematic_naming_of_internal_anchors.rst

That is linked in "raw mode" (i.e., no rendering by Bitbucket) so you should see just the characters in the file, as in a text editor. (If you can't follow the link, note I have also attached the contents of the file to this post, following my .sig.) Please also note that the following is NOT about how Bitbucket renders reST (though BB reproduces the problem), since BB has its own problems with {section naming, internal anchors} as detailed here:

https://bitbucket.org/site/master/issues/11314/restructuredtext-link-fragments-require

However, presuming this problem is caused by docutils (as detailed below), fixing it would also improve the lives of everyone writing reST for display "in the cloud."

problem
-------

The problem I wish to raise here is exhibited by `restview <https://pypi.python.org/pypi/restview>`_, which I believe renders by just driving docutils. (Specifically, my version of `restview` renders with docutils-0.12, per header in generated HTML.) The document (problematic_naming_of_internal_anchors.rst) has the following section names, all of which are unique:

for further processing
integrate
move
short-term
next hardware run
short-term bodywear
long-term
long-term bodywear
long-term house goods
lighting

The problem can be illustrated by comparing the section IDs generated for the section names={long-term bodywear, short-term bodywear} and the success of hand-coded links and generated/TOC links to those sections in the text.

1. reST section name='short-term bodywear' generates HTML=

> <div class="section" id="short-term-bodywear">
> <h2><a class="toc-backref" href="#id8">short-term bodywear</a></h2>

   Note the form of the div attribute='id': it is the section name with all spaces replaced by dashes, aka 's/ /-/g'. This is as I expect (therefore good :-)

1.1. My hand-coded internal link to that section

> .. |short-term bodywear| replace:: *short-term bodywear*
> .. _short-term bodywear: #short-term-bodywear
>
> *see also* |short-term bodywear|_

     works as expected, since the following HTML is generated:

> <p><em>see also</em> <a class="reference external" href="#short-term-bodywear"><em>short-term bodywear</em></a></p>

     (I dunno why 'class="reference external"', since this is an internal link, but that's a quibble.)

1.2. The generated TOC link to that section also works as expected:

> <li><a class="reference internal" href="#short-term-bodywear" id="id8">short-term bodywear</a></li>

2. reST section name='long-term bodywear' generates HTML=

> <div class="section" id="id1">
> <h2><a class="toc-backref" href="#id10">long-term bodywear</a></h2>

  Note the form of the div attribute='id', which is NOT as I expect. I expect the generated ID to use the same rule (s/ /-/g) as was used to generate the ID from section name='short-term bodywear'; instead the div/section ID is "hashed" by appending a serial number to string='id'.

2.1. This unexpected behavior breaks my hand-coded internal reference to section name='long-term bodywear'

> .. |long-term bodywear| replace:: *long-term bodywear*
> .. _long-term bodywear: #long-term-bodywear
>
> *see also* |long-term bodywear|_

    which generates (correctly) the following HTML:

> <p><em>see also</em> <a class="reference external" href="#long-term-bodywear"><em>long-term bodywear</em></a></p>

2.2. However the generated TOC link to that section works by reproducing the unexpected behavior:

> <li><a class="reference internal" href="#id1" id="id10">long-term bodywear</a></li>

solution/questions
------------------

ISTM docutils should _always_

1. for unique section names: generate `div id`s by `s/ /-/g`
2. for duplicate section names (and all backrefs): generate `div id`s by serial numbering, i.e. appending a serial number to string='id'

So my first question is, am I missing something? Is there a reason to *not* behave thusly? If not:

My second question is, is there any reason to believe that docutils is *not* producing the above behavior? If so, please lemme know and I'll put an `issue on restview <https://github.com/mgedmin/restview/issues>`_. If not:

My third question presumes this behavior is due to a problem with docutils: is there anything else I should do to help get this fixed? Do I need to make an issue in a tracker? or do something to further debug the problem? or Something Completely Different?

conclusion/attachment
---------------------

If possible, please reply to me (directly) as well as to the list, and
TIA, Tom Roche <Tom...@po...>-----problematic_naming_of_internal_anchors.rst follows to EOF

===
foo
===

.. contents:: **Table of Contents**

for further processing
======================

integrate
---------

move
----
  
short-term
==========

next hardware run
-----------------

short-term bodywear
-------------------

.. howto style a link (e.g., make it italic): see http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
.. |long-term bodywear| replace:: *long-term bodywear*
.. _long-term bodywear: #long-term-bodywear

*see also* |long-term bodywear|_

long-term
=========

long-term bodywear
------------------

.. |short-term bodywear| replace:: *short-term bodywear*
.. _short-term bodywear: #short-term-bodywear

*see also* |short-term bodywear|_

long-term house goods
---------------------

lighting
~~~~~~~~

[footnotes follow .sig]

Tom Roche[1]
>> I have a reST doc[2] with an image followed by a section header. I want the header to render below the image, but it sometimes renders {to the right of, on the same line as} the image[3]. How to fix?

Günter Milde[4]
> The recommended way for this is to style the output with CSS[, which] may become hard if the processing is done somewhere on the net,

That is indeed the target.

> You could define CSS rules in the source in an "raw" role. However, this is not nice,

... and moreover I know from previous experience[5] that Bitbucket ignores reST directive='raw'.

>> I'm not seeing options for this @ http://docutils.sourceforge.net/docs/ref/rst/directives.html#image : am I missing something?

> There is no provision in rST regarding this layout detail.

>> Alternatively, is this something for which I should make a DocUtils feature request? If so, where?

your assistance is appreciated, Tom Roche <Tom...@po...>

[1]: https://sourceforge.net/p/docutils/mailman/message/34938193/
[2]: The file's name=Home.rst; its full text can be seen by either

* `git clone`ing its Bitbucket (BB) repository, with either

gi...@bi...:epa_n2o_project_team/aqmeii-na_n2o.git/wiki
https://tl...@bi.../epa_n2o_project_team/aqmeii-na_n2o.git/wiki

* downloading the copy I uploaded to

https://drive.google.com/file/d/0BzDAFHgIxRzKcC1YNzFpQk0tLUk/view?usp=sharing

The relevant text (IIUC) is at the top of the file, through the second section header='overview'.

[3]: Bitbucket currently renders Home.rst as I want (see

https://bitbucket.org/epa_n2o_project_team/aqmeii-na_n2o/wiki/Home#rst-header-open-source-notice

) with an image (the AGPL3 badge) above the section header='overview', as if they were on separate lines of a page. By contrast, `restview`

https://mg.pov.lt/restview/

which seems more DocUtils-compliant, renders the image to the *left* of the header='overview', as if they were on the same line of the page: see, e.g.,

https://drive.google.com/file/d/0BzDAFHgIxRzKNEpKOWV6RVdDRnc/view?usp=sharing

[4]: https://sourceforge.net/p/docutils/mailman/message/34938375/
[5]: https://sourceforge.net/p/docutils/mailman/message/34894260/

On 2016-03-15, Tom Roche wrote:

> summary:
>========

> I have a reST doc with an image followed by a section header. I want
> the header to render below the image, but it sometimes renders {to the
> right of, on the same line as} the image. How to fix?

The usual fix would be to fix the CSS rules for display (assuming this is
about HTML output).

There is no provision in rST regarding this layout detail.


> details:
>========

> document
> --------

...

>> This project's content is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the `GNU Affero General Public License <./COPYING>`_ for more details.

>> .. image:: ./images/Affero_badge__agplv3-155x51.png
>>    :scale: 100 %
>>    :alt: distributed under the GNU Affero General Public License
>>    :align: left

>> overview
>> ========

> rendering
> ---------

> BB currently renders this as I want: see

> https://bitbucket.org/epa_n2o_project_team/aqmeii-na_n2o/wiki/Home#rst-header-open-source-notice

> You should see (please lemme know if not--I'm using Firefox on Linux)
> an image (the AGPL3 badge) above the section header='overview', as if
> they were on separate lines of the page.

> However, in my experience, BB's renderer is quirky. By contrast, `restview`

> https://mg.pov.lt/restview/

> seems more DocUtils-compliant; moreover it runs locally, so I use it to
> check my documents before commiting them to my local repo and `git
> push`ing the repo to BitBucket. And `restview` renders the image to the
> *left* of the header='overview', as if they were on the same line of
> the page

...

> So I'm guessing `restview`s rendering is more faithful to "the
> standard" (am I missing something?) and I'm fearing that BB's renderer
> will in future become more standard-compliant.

There is no "standard" regarding the layout, just a default behaviour due to
the shipped CSS files.
You may try to compile your file (or a minimal example) with Docutils'
rst2html and inspec the result.


> solution
> --------

> (I'm not quite sure what the appropriate terminology is for what I
> want: please correct as needed.)

> Is there a way to

> * cause an image to break text flow, so that no other document text
>   (including section headers) appears left or right of the image, but
>   only above and below?

> * force text (including section headers) to start on a new line, with
>   nothing to its left or right?

The recommended way for this is to style the output with CSS.

This may become hard if the processing is done somewhere on the net, you
might have to ask there for possibilities to use custom CSS files.

You could define CSS rules in the source in an "raw" role. However, this
is not nice, must be done in every document and results in non-valid HTML
(defining CSS in the <body> is not allowed) (while still rendered as
desired in most browsers).

You can also play with the :align: option of the image directive. 
Centered images are on a line of their own by default.


Hope this gets you started,

Günter

summary:
========

I have a reST doc with an image followed by a section header. I want the header to render below the image, but it sometimes renders {to the right of, on the same line as} the image. How to fix?

details:
========

document
--------

I have a reST doc which I am using as the "home page" for a portfolio project. The file's name=Home.rst; its full text can be seen by either

* `git clone`ing its Bitbucket (BB) repository, with either

gi...@bi...:epa_n2o_project_team/aqmeii-na_n2o.git/wiki
https://tl...@bi.../epa_n2o_project_team/aqmeii-na_n2o.git/wiki

* downloading the copy I uploaded to

https://drive.google.com/file/d/0BzDAFHgIxRzKcC1YNzFpQk0tLUk/view?usp=sharing

The relevant text (IIUC) is at the top of the file:

> ==========================================================================================
> Simulation of N₂O Production and Transport in North America Compared to Tower Measurements
> ==========================================================================================

> .. contents:: **Table of Contents**

> open-source notice
> ==================

> Copyright 2013, 2014, 2015, 2016 ``Tom Roche <Tom...@po...>``

> This project's content is free software: you can redistribute it and/or modify it provided that you do so as follows:

> * under the terms of the `GNU Affero General Public License <https://www.gnu.org/licenses/agpl.html>`_ as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
> * preserving attribution of this author in the redistributed and/or modified material. You may do so in any reasonable manner, but not in any way that suggests this author endorses you or your use.

> This project's content is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the `GNU Affero General Public License <./COPYING>`_ for more details.

> .. image:: ./images/Affero_badge__agplv3-155x51.png
>    :scale: 100 %
>    :alt: distributed under the GNU Affero General Public License
>    :align: left

> overview
> ========

rendering
---------

BB currently renders this as I want: see

https://bitbucket.org/epa_n2o_project_team/aqmeii-na_n2o/wiki/Home#rst-header-open-source-notice

You should see (please lemme know if not--I'm using Firefox on Linux) an image (the AGPL3 badge) above the section header='overview', as if they were on separate lines of the page.

However, in my experience, BB's renderer is quirky. By contrast, `restview`

https://mg.pov.lt/restview/

seems more DocUtils-compliant; moreover it runs locally, so I use it to check my documents before commiting them to my local repo and `git push`ing the repo to BitBucket. And `restview` renders the image to the *left* of the header='overview', as if they were on the same line of the page: see, e.g., this image

https://drive.google.com/file/d/0BzDAFHgIxRzKNEpKOWV6RVdDRnc/view?usp=sharing

or view the file in your local `restview` install. 

So I'm guessing `restview`s rendering is more faithful to "the standard" (am I missing something?) and I'm fearing that BB's renderer will in future become more standard-compliant.

solution
--------

(I'm not quite sure what the appropriate terminology is for what I want: please correct as needed.)

Is there a way to

* cause an image to break text flow, so that no other document text (including section headers) appears left or right of the image, but only above and below?

* force text (including section headers) to start on a new line, with nothing to its left or right?

I'm not seeing options for this @ http://docutils.sourceforge.net/docs/ref/rst/directives.html#image : am I missing something? Alternatively, is this something for which I should make a DocUtils feature request? If so, where?

TIA, Tom Roche <Tom...@po...>

On 2016-02-29, Oleksandr Gavenko wrote:

...

> RST have regular syntax for block level elements:

>   .. contents:: My TOC
>      :local:
>      :depth: 1

> But I can't find relevant mentioning about support of parameters by roles:

>   http://docutils.sourceforge.net/docs/ref/rst/directives.html
>   http://docutils.sourceforge.net/docs/ref/rst/roles.html
>   http://docutils.sourceforge.net/docs/ref/doctree.html

> I think about exploiting finite number of parameters so it is possible
> just to register necessary amount of roles.

Currently, there is no support for role parameters when using a role.

You can, however define custom roles (eventually inheriting from a base
role). 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#role


With most roles, the ":class:" option can be used to set a "classes"
attribute. By default, a classes attribute equalling the role name is given
to instances of custom roles.

See the reStructuredText Interpreted Text Roles document for details.
http://docutils.sourceforge.net/docs/ref/rst/roles.html

Specific base roles may support other options and/or directive content.
This is, e.g., recommended for inline code highlighting::

For example, the following creates a LaTeX-specific "latex" role:

.. role:: latex(code)
   :language: latex
   
http://docutils.sourceforge.net/docs/ref/rst/roles.html#code   



>================================================================

> Also I don't understand if additional parameters to directive will be
> accessible from Python RST parser for inline substitution, like:

>   This is a |myref|.

>   .. |myref| data:: TEXT
>      :attr1: val1, val2
>      :attr2: no
>      :attrn: http://.../...

This is only supported for a limited set of optins of some directives for
substitution__ :

image
  directive argument and options also supported in a
  substitution (with special values for align)
  http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
  
unicode
  options trim, rtrim, ltrim
  
date
  optional argument (date format)

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions


Günter