[Docutils-users] problem with image and section header

[Tom Roche]

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

***@bitbucket.org:epa_n2o_project_team/aqmeii-na_n2o.git/wiki
https://***@bitbucket.org/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

==========================================================================================
Simulation of N₂O Production and Transport in North America Compared to Tower Measurements
==========================================================================================
.. contents:: **Table of Contents**
open-source notice
==================
* 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 <***@pobox.com>

[Guenter Milde]

Post by Tom Roche
========
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.

Post by Tom Roche
========
document
--------

...

Post by Tom Roche

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

...

Post by Tom Roche
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.

Post by Tom Roche
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


------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785231&iu=/4140
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Pleas

[Tom Roche]

[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'.

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 <***@pobox.com>

[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

***@bitbucket.org:epa_n2o_project_team/aqmeii-na_n2o.git/wiki
https://***@bitbucket.org/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/

------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785231&iu=/4140
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

P