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

[Docutils-users] how to correct reStructuredText markup batchly.

[Jeffery <jef...@gm...>]

hey,  recently i review the translation project that translate English reST
document into chinese reST document  use gettext tools on transifex
platform.

a you know, there have no bank need in chinese, and most translator no
sense with reST markup, so that the no bank around reST markup.  now, i
want a tools/or scripts that can correct this issue batch process po file.

thanks.

-- 
Jeffery        -odoo expert form kunshan, suzhou, china

[Docutils-users] Failing testsuite, Windows 10, python 2.7.11, docutils 0.12

[Christian A. <chr...@gm...>]

Eight failures reported, report enclosed.


-- 
Hilsen Christian Aastorp
920 12 096

Re: [Docutils-users] Is there a DTD or Schema for the resulting reStructruredText XML?

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

On 2016-05-11, Mikhail Edoshin wrote:

Dear Michail,

> Is there a DTD or Schema for the reStructuredText XML or any other 
> complete and maybe formal description of it?

Yes, see the Documentation overview and
http://docutils.sourceforge.net/docs/
especially http://docutils.sourceforge.net/docs/ref/docutils.dtd

Günter

[Docutils-users] Is there a DTD or Schema for the resulting reStructruredText XML?

[Mikhail E. <mik...@gm...>]

Hi,

Is there a DTD or Schema for the reStructuredText XML or any other 
complete and maybe formal description of it?

-- 
Mikhail Edoshin
mik...@gm...
Skype: mikhail_edoshin (GMT+3)

Re: [Docutils-users] Literal blocks within Option Lists (for man pages)

[engelbert g. <eng...@gm...>]

i tried it with manpage writer

<RST-TEXT>
an option block, and within it, a part of the text block indented.
the rest of the text ("More lines 1", etc.) isn't aligned at the same
level as "Line1".  Instead, they're flush left to the screen

-l, --color-limit limit
        Line1.
        Line2.
        Line3.

        ::

                Indented line 1.
                Indented line 2.
                Indented line 3.

                Indented line 4.
                Indented line 5.
                Indented line 6.

        More lines 1.
        More lines 2.
        More lines 3.

</RST-TEXT>

produces this manpage::

()
()

NAME
        -  an  option  block,  and  within  it, a part of the text block
indented.  the rest of the text
       ("More lines 1", etc.) isn't aligned at the same level as "Line1".
Instead, they're  flush  left
       to the screen

       -l,--color-limit limit
              Line1.  Line2.  Line3.

                 Indented line 1.
                 Indented line 2.
                 Indented line 3.

                 Indented line 4.
                 Indented line 5.
                 Indented line 6.

              More lines 1.  More lines 2.  More lines 3.


()

?

On 8 May 2016 at 11:14, Guenter Milde <mi...@us...> wrote:

> On 2016-05-07, Thomas Adam wrote:
> > Hi all,
>
> > I'm writing a man page using RST and have come across a situation I can't
> > solve.  I have an option block, and within it, I'd like to have a part
> of the
> > text block indented.   To achieve that, I've done the following:
>
> ><RST TEXT>
> > -l, --color-limit limit
> >       Line1.
> >       Line2.
> >       Line3.
>
> >       ::
>
> >               Indented line 1.
> >               Indented line 2.
> >               Indented line 3.
>
> >               Indented line 4.
> >               Indented line 5.
> >               Indented line 6.
>
> ></RST TEXT>
>
> The indentation of a literal block is a layout setting, not an intrinsic
> feature.
>
> For indented text, the simplest representation would be a block-quote.
> If line-breaks are to be kept a line-block::
>
>  -l, --color-limit limit
>         Pragraph 1
>
>                 Indented block
>
>                 | line 1
>                 | line 2
>
> Only if you really want "literal" text (no markup parsing, teletype font),
> use the literal block.
>
> > This all works fine, and the indented lines are rendered as I'd expect
> them
> > to.  However, I also have further lines which are part of the
> description for
> > the '-l' option.  However, those lines are not indented at the same
> level as
> > lines "Line1", "Line2", etc.
>
> > Here's the code as I've written it including the additional text:
>
>
> ><RST TEXT>
> -l, --color-limit limit
>         Line1.
>         Line2.
>         Line3.
>
>         ::
>
>                 Indented line 1.
>                 Indented line 2.
>                 Indented line 3.
>
>                 Indented line 4.
>                 Indented line 5.
>                 Indented line 6.
>
>         More lines 1.
>         More lines 2.
>         More lines 3.
> ></RST TEXT>
>
> > However, the rest of the text ("More lines 1", etc.) isn't aligned at
> > the same level as "Line1".  Instead, they're flush left to the screen,
> > which isn't something I'd expect.
>
> I cannot reproduce. Here, I get
>
> * lines in the "normal paragraphs" merged
> * paragraphs "line1 ... line3" and "More lines 1 ... 3" aligned
>   in the HTML output.
>
> rst2html (Docutils 0.13 [repository], Python 2.7.11+, on linux2)
>
>
> Maybe there is something in your original source but missing in the minimal
> example?
>
> Günter
>
>
>
> ------------------------------------------------------------------------------
> Find and fix application performance issues faster with Applications
> Manager
> Applications Manager provides deep performance insights into multiple
> tiers of
> your business applications. It resolves application problems quickly and
> reduces your MTTR. Get your free trial!
> https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
> _______________________________________________
> 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] Literal blocks within Option Lists (for man pages)

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

On 2016-05-07, Thomas Adam wrote:
> Hi all,

> I'm writing a man page using RST and have come across a situation I can't
> solve.  I have an option block, and within it, I'd like to have a part of the
> text block indented.   To achieve that, I've done the following:

><RST TEXT>
> -l, --color-limit limit
> 	Line1.
> 	Line2.
> 	Line3.

> 	::

> 		Indented line 1.
> 		Indented line 2.
> 		Indented line 3.

> 		Indented line 4.
> 		Indented line 5.
> 		Indented line 6.

></RST TEXT>

The indentation of a literal block is a layout setting, not an intrinsic
feature. 

For indented text, the simplest representation would be a block-quote.
If line-breaks are to be kept a line-block::

 -l, --color-limit limit
 	Pragraph 1

 		Indented block
		
		| line 1
		| line 2

Only if you really want "literal" text (no markup parsing, teletype font),
use the literal block.

> This all works fine, and the indented lines are rendered as I'd expect them
> to.  However, I also have further lines which are part of the description for
> the '-l' option.  However, those lines are not indented at the same level as
> lines "Line1", "Line2", etc.

> Here's the code as I've written it including the additional text:


><RST TEXT>
-l, --color-limit limit
	Line1.
	Line2.
	Line3.

	::

		Indented line 1.
		Indented line 2.
		Indented line 3.

		Indented line 4.
		Indented line 5.
		Indented line 6.

	More lines 1.
	More lines 2.
	More lines 3.
></RST TEXT>

> However, the rest of the text ("More lines 1", etc.) isn't aligned at
> the same level as "Line1".  Instead, they're flush left to the screen,
> which isn't something I'd expect.

I cannot reproduce. Here, I get

* lines in the "normal paragraphs" merged
* paragraphs "line1 ... line3" and "More lines 1 ... 3" aligned
  in the HTML output.
  
rst2html (Docutils 0.13 [repository], Python 2.7.11+, on linux2)
  
  
Maybe there is something in your original source but missing in the minimal
example?

Günter

[Docutils-users] Literal blocks within Option Lists (for man pages)

[Thomas A. <tho...@gm...>]

Hi all,

I'm writing a man page using RST and have come across a situation I can't
solve.  I have an option block, and within it, I'd like to have a part of the
text block indented.   To achieve that, I've done the following:

<RST TEXT>
-l, --color-limit limit
	Line1.
	Line2.
	Line3.

	::

		Indented line 1.
		Indented line 2.
		Indented line 3.

		Indented line 4.
		Indented line 5.
		Indented line 6.

</RST TEXT>

This all works fine, and the indented lines are rendered as I'd expect them
to.  However, I also have further lines which are part of the description for
the '-l' option.  However, those lines are not indented at the same level as
lines "Line1", "Line2", etc.

Here's the code as I've written it including the additional text:


<RST TEXT>
-l, --color-limit limit
	Line1.
	Line2.
	Line3.

	::

		Indented line 1.
		Indented line 2.
		Indented line 3.

		Indented line 4.
		Indented line 5.
		Indented line 6.

	More lines 1.
	More lines 2.
	More lines 3.
</RST TEXT>

However, the rest of the text ("More lines 1", etc.) isn't aligned at the same
level as "Line1".  Instead, they're flush left to the screen, which isn't
something I'd expect.

Is what I'm trying to achieve possible?  Am I using the correct means of
indenting the block of lines in the first place?  Or is this type of thing not
supported within option lists?

Any pointers much appreciated.

Kindly,
Thomas Adam

Re: [Docutils-users] Letters in reST?

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

On 2016-04-26, 19:26 GMT, Guenter Milde wrote:
> If you are prepared to 

Thanks for hints: I will take a look.

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
"Goodbye," said the fox. "And now here is my secret, a very
simple secret: It is only with the heart that one can see
rightly; what is essential is invisible to the eye."
   -- Antoine de Saint-Exupery

Re: [Docutils-users] Letters in reST?

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

Ahoj,

On 2016-04-25, Matěj Cepl wrote:

> I am using LyX and LaTeX class scrlttr2 for writing my business 
> letters. However, whenever I start to write a new letter, I am 
> painfully reminded that it is actually last use of LyX I have 
> (with the help of zrst2* tools I can now use Zotero for writing 
> documents in rST; thank you!).  Of course, I could easily write 
> those letters just in a plain LaTeX in my $EDITOR, but it seems 
> that highly form-like documents like business letters could be 
> with benefit written in rST. I guess it is just question of 
> defining proper roles and some kind of templating.

If you are prepared to 

* do some "creative writing" (using rST objects for different purpose via
  re-defining the generated LaTeX macros)
  
* use some roles

* use a "heavy" custom LaTeX preamble,

* eventually use some raw LaTeX

this should be possible.

Remember, you can set the documentclass, a custom template file, a custom
preamble, loaded packages etc in the config file or via command line
options. (See the latex writer doc which also applies to the XeTeX writer
(generating LaTeX suited for LuaLaTeX and XeLaTeX processing.)


Some hints: 

* all fixed data can go into the custom preamble::

     \setkomavar{fromname}{Matěj Cepl}
     
     \setkomavar{fromaddress}{27 Golden Leaf Lane\\
     A5G 28 Minas Tirith 5} 
     
     \setkomavar{fromemail}{ma...@ex...}
     
     \setkomavar{signature}{Matěj Cepl}
     
     \setkomavar{place}{V Praze}
     
     \setkomavar{date}{\today}
     
     \setkomavar{signature}{Matěj Cepl}

* With some role definitions and redefinitions in the preamble::

      \newcommand{\DUroleopening}{\opening}
      \newcommand{\DUroleclosing}{\closing}
      \newcommand{\DUrolesubject}{\setkomavar{subject}}

  you can write::

     .. role:: subject
     .. role:: opening
     .. role:: closing
     
     :subject:`Žádost o změnu registrace smlouvy`
     
     .. raw:: latex
     
        \begin{letter}{ČSOB Penzijní společnost\\
	Radlická 333/150\\
	150 57 Praha 5\\
	tel.: +420 495 800 600\\
	email: \url{cs...@cs...}}
     
     :opening:`Žádost o změnu registrace smlouvy`
     
     Letter content
     
     :closing:`S pozdravem`


There is currently no easy way to get line-breaks in exported LaTeX.

Handling of the :address: docinfo field is currently hard-coded towards use
in an article. This could be improved to allow for a more versatile use by
intermediate macros...


Günter

[Docutils-users] Letters in reST?

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

Hi,

I am using LyX and LaTeX class scrlttr2 for writing my business 
letters. However, whenever I start to write a new letter, I am 
painfully reminded that it is actually last use of LyX I have 
(with the help of zrst2* tools I can now use Zotero for writing 
documents in rST; thank you!).  Of course, I could easily write 
those letters just in a plain LaTeX in my $EDITOR, but it seems 
that highly form-like documents like business letters could be 
with benefit written in rST. I guess it is just question of 
defining proper roles and some kind of templating.

As an example this document in LyX
https://mcepl.fedorapeople.org/tmp/lorem-ipsum-LyX-edited.png 
(with some details obscured, of course), leads more or less to 
this generated LaTeX 
https://mcepl.fedorapeople.org/tmp/lorem-ipsum.tex, which ends 
up in this PDF 
https://mcepl.fedorapeople.org/tmp/lorem-ipsum.pdf

Did anybody do such macros? Is it necessary to use 
a preprocessor or would be possible to do just macros in 
.docutils or some other configuration file?

Thank you for any tips,

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
Ask yourself whether you’ve really obtained fullness of the Holy
Spirit, followed by gifts needed for your service.
    -- Francis MacNutt

Re: [Docutils-users] Link bookmark

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

On 2016-04-19, Sergio wrote:
> Sergio <sergio.am.spina <at> gmail.com> writes:


>> I would know what is the way to implement in ReST an internal link bookmark
>> like in the <a> tag in this example:


>     # file: test.htm

>     <html>
>     <body>

>     <p>This text stand for an example of text containing
>     a <a name="B3Pa9-5ZRIx-1">bookmarked target</a> bookmark.</p>

>     <p>So let's go all together to visit the bookmarked target
>     clicking on <a href="#B3Pa9-5ZRIx-1">this link</a>.</p>

>     </body>
>     </html>

...

> Is there a better way ?

This depends on what is the important part of your task and what can be
changed to match the way Docutils structures things.

Do you want convert HTML documents to rST or write rST?


AFAI can see, there is no way to have an *inline* anchor with specified but
invisible name or id (except for a raw HTML role).


The following alternatives exist.

This text stand for an example of text containig
a _`target` bookmark. An inline target must be
uniquely named and mapped to the desired
non-visible string in a separate step.

.. _B3Pa9-5ZRIx-1: target_


.. _B3Pa9-5ZRIx-2:

This paragraph is given the 
id "b3pa9-5zrix-2" (see name conversions).
>From the same document, it can be reached under the given spelling.
>From other documents, ist is reaced as ``<filename>#b3pa9-5zrix-2``


So let's go all together to visit the targets clicking on 
`this link <B3PA9-5ZRIX-1_>`__ 
or `this link <B3PA9-5ZRIX-2_>`__.

Alternative syntax: visit the targets clicking on 
`this link`__  or `this link`__.

__ B3PA9-5ZRIX-1_
__ B3PA9-5ZRIX-2_


Next alternative: link to of the `tagged paragraph <#b3pa9-5zrix-2>`__ via
its URL.


See also
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-references
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-targets


hope this helps

Günter

Re: [Docutils-users] Link bookmark

[Sergio <ser...@gm...>]

Sergio <sergio.am.spina <at> gmail.com> writes:

> 
> I would know what is the way to implement in ReST an internal link bookmark
> like in the <a> tag in this example:
> 
> > <html>
> > <body>
> >
> > <p>This text stand for an example of text containing a
> > <a name="B3Pa9-5ZRIx-1">bookmarked target</a> bookmark.</p>
> >
> > <p>So let's go all together to visit the bookmarked target
> > clicking on <a href="#B3Pa9-5ZRIx-1">this link</a>.</p>
> >
> > </body>
> > </html>
> 
> The string that is the name of the anchor ("B3Pa9-5ZRIx-1") is produced by
> an algorithm and 1) cannot be left away and 2) cannot be seen in the printed
> document, just as it was an html bookmark link.
> 
> Thanks. 

I've tried some experiments looking for a hint:

    # file: test.htm

    <html>
    <body>
    
    <p>This text stand for an example of text containing
    a <a name="B3Pa9-5ZRIx-1">bookmarked target</a> bookmark.</p>
    
    <p>So let's go all together to visit the bookmarked target
    clicking on <a href="#B3Pa9-5ZRIx-1">this link</a>.</p>
    
    </body>
    </html>

First try:

    # test.htm converted at http://www.siafoo.net/html.xml
    
    This text stand for an example of text containig a `target <>`_ bookmark.

    So let's go all together to visit the target clicking on `this
    link <#B3Pa9-5ZRIx-1>`_ .

that is not what I'm looking for;

    # pandoc -f html test.htm -s -o test.rst
    
    This text stand for an example of text containig a target bookmark.
    
    So let's go all together to visit the target clicking on `this
    link <#B3Pa9-5ZRIx-1>`__.

that is not what I'm looking for;

    # html2rst.py taken from
http://docutils.sourceforge.net/sandbox/cliechti/html2rst/html2rst.py
    # python html2rst.py test.htm > test.rst
    
    This text stand for an example of text containig a target bookmark.
    
    So let's go all together to visit the target clicking on `this
    link`_.
    
    .. _this link: #B3Pa9-5ZRIx-1

Not a good try.

Is there a better way ?

[Docutils-users] Link bookmark

[Sergio <ser...@gm...>]

I would know what is the way to implement in ReST an internal link bookmark
like in the <a> tag in this example:

> <html>
> <body>
>
> <p>This text stand for an example of text containing a
> <a name="B3Pa9-5ZRIx-1">bookmarked target</a> bookmark.</p>
>
> <p>So let's go all together to visit the bookmarked target
> clicking on <a href="#B3Pa9-5ZRIx-1">this link</a>.</p>
>
> </body>
> </html>

The string that is the name of the anchor ("B3Pa9-5ZRIx-1") is produced by
an algorithm and 1) cannot be left away and 2) cannot be seen in the printed
document, just as it was an html bookmark link.

Thanks. 

Re: [Docutils-users] Force line breaks

[Bram G. <br...@br...>]

The pseudoxml writer shows that the intention of your RST code is
correctly parsed:

> <enumerated_list enumtype="arabic" prefix="" suffix=".">
>     <list_item>
>         <line_block>
>             <line>
>                 First line
>             <line>
>                 Second line
>             <line>
>                 Third line
>     <list_item>
>         <paragraph>
>             Item with only one line
>     <list_item>
>         <paragraph>
>             Another item

This is what the RST "really means". How it gets turned into HTML/LaTeX
is subjective; you can use many stylesheets or even HTML trees for HTML,
and many document types for LaTeX. You might need to configure/tweak
either writer for your purposes.

Cheers, Bram


On Tue, 5 Apr 2016, at 04:35 PM, Guenter Milde wrote:
> On 2016-04-05, <Ste...@te...> wrote:
> 
> > [-- Type: text/plain, Encoding: quoted-printable --]
> 
> > Hi all,
> 
> > Is there a markup in reStructuredText, that forces a line break only,
> > and is not interpreted as a block quote with indentation like line block?
> 
> > I would like to force line breaks in a numerated list.
> 
> > #. | First line
> >    | Second line
> >    | Third line
> > #. Item with only one line
> > #. Another item
> 
> > Looking at restructuredText examples and the rtd theme, the line block
> > markup seems to be expected to be rendered with a left margin in html,
> > while it does not produce a margin with latex.
> > As a consequence, the first item will be indented by 24px and the one line
> > Items are not indented.
> 
> In my setup, the line-block in a list is not indented further but aligns
> with the following item. Did you try your markup? Do you already use a
> custom CSS?
> 
> 
> > Is there an alternative markup, or do I have to customise the css?
> 
> There is nothing like ::
> 
>   #. First line <br>
>      Second line <br>
>      Third line <br>
>   #. Item with only one line
> 
> 
> You can, however write paragraphs, say:
> 
> #. First line
> 
>    Second line
>    
>    Third line
>    
> #. Item with only one line
> 
> 
> With the html5 writer (in the development version of Docutils) you can
> remove spacing between the paragraphs and list items whith the class
> value
> "compact" for the list:
> 
> .. class:: compact
> 
> #. First line
> 
>    Second line
>    
>    Third line
>    
> #. Item with only one line
> 
> 
> The following works in most browsers but does not validate (<style> is
> only
> allowed in the document head)::
> 
>  .. raw:: html
> 
>   <style type="text/css"><!--
>        li div.line-block {
>        margin-left: 0px;
>        color: red; /* for testing */
>      }
>    --></style>
> 
> 
> hope this helps,
> 
> Günter
> 
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> 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] Force line breaks

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

On 2016-04-05, <Ste...@te...> wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Hi all,

> Is there a markup in reStructuredText, that forces a line break only,
> and is not interpreted as a block quote with indentation like line block?

> I would like to force line breaks in a numerated list.

> #. | First line
>    | Second line
>    | Third line
> #. Item with only one line
> #. Another item

> Looking at restructuredText examples and the rtd theme, the line block
> markup seems to be expected to be rendered with a left margin in html,
> while it does not produce a margin with latex.
> As a consequence, the first item will be indented by 24px and the one line
> Items are not indented.

In my setup, the line-block in a list is not indented further but aligns
with the following item. Did you try your markup? Do you already use a
custom CSS?


> Is there an alternative markup, or do I have to customise the css?

There is nothing like ::

  #. First line <br>
     Second line <br>
     Third line <br>
  #. Item with only one line


You can, however write paragraphs, say:

#. First line

   Second line
   
   Third line
   
#. Item with only one line


With the html5 writer (in the development version of Docutils) you can
remove spacing between the paragraphs and list items whith the class value
"compact" for the list:

.. class:: compact

#. First line

   Second line
   
   Third line
   
#. Item with only one line


The following works in most browsers but does not validate (<style> is only
allowed in the document head)::

 .. raw:: html

  <style type="text/css"><!--
       li div.line-block {
       margin-left: 0px;
       color: red; /* for testing */
     }
   --></style>


hope this helps,

Günter

Re: [Docutils-users] Force line breaks

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

On 2016-04-05, 11:24 GMT, <Ste...@te...> wrote:
> I would like to force line breaks in a numerated list.
>
> #. | First line
>    | Second line
>    | Third line
> #. Item with only one line
> #. Another item

I am afraid you hold the phone wrong ;). Really, what you want 
here is embedded list inside of the first item.

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
..every Man has a Property in his own Person. This no Body has
any Right to but himself. The Labour of his Body, and the Work of
his Hands, we may say, are properly his. .... The great and chief
end therefore, of Mens uniting into Commonwealths, and putting
themselves under Government, is the Preservation of their
Property.
    -- John Locke, "A Treatise Concerning Civil Government"

[Docutils-users] Force line breaks

[<Ste...@te...>]

Hi all,

Is there a markup in reStructuredText, that forces a line break only,
and is not interpreted as a block quote with indentation like line block?

I would like to force line breaks in a numerated list.

#. | First line
   | Second line
   | Third line
#. Item with only one line
#. Another item

Looking at restructuredText examples and the rtd theme, the line block
markup seems to be expected to be rendered with a left margin in html,
while it does not produce a margin with latex.
As a consequence, the first item will be indented by 24px and the one line
Items are not indented.

Is there an alternative markup, or do I have to customise the css?

BR,

Stefan

Re: [Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

[Tom R. <Tom...@po...>]

one more mistake to correct :-(

> Tom Roche[1]
> >> Small reST document[2] 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.

- Marc 'BlackJack' Rintsch[3]
+ Günter Milde[3]

> > Here is the problem: you define an external target with the URL "#long-term-bodywear" (which happens to point to the same document) therefore also: "reference-external".

> Doh! Thanks for clarifying. I had assumed all links were created in the same way.

> > The following works here as expected::
  
> >   .. howto style a link (e.g., make it italic): see http://docutils.sourcefor
> >   .. |long-term bodywear| replace:: *long-term bodywear*
> >   .. |short-term bodywear| replace:: *short-term bodywear*
  
> >   short-term bodywear
> >   -------------------
  
> >   *see also* |long-term bodywear|_
  
> >   long-term bodywear
> >   ------------------
  
> >   *see also* |short-term bodywear|_

> ... and that renders correctly locally via `restview` and remotely via Bitbucket[4].

> thanks again, Tom Roche <Tom...@po...>

> [1]: https://sourceforge.net/p/docutils/mailman/message/34982519/
> [2]: flawed version @ https://bitbucket.org/!api/2.0/snippets/tlroche/LR9oL/9277baf6d61904d1725c39dae4df8b7550192ebc/files/problematic_naming_of_internal_anchors.rst
> [3]: https://sourceforge.net/p/docutils/mailman/message/34984893/
> [4]: fixed version @ https://bitbucket.org/!api/2.0/snippets/tlroche/LR9oL/HEAD/files/problematic_naming_of_internal_anchors.rst

Re: [Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

[Tom R. <Tom...@po...>]

[footnotes follow .sig]

Tom Roche[1]
>> Small reST document[2] 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.

Marc 'BlackJack' Rintsch[3]
> Here is the problem: you define an external target with the URL "#long-term-bodywear" (which happens to point to the same document) therefore also: "reference-external".

Doh! Thanks for clarifying. I had assumed all links were created in the same way.

> The following works here as expected::
  
>   .. howto style a link (e.g., make it italic): see http://docutils.sourcefor
>   .. |long-term bodywear| replace:: *long-term bodywear*
>   .. |short-term bodywear| replace:: *short-term bodywear*
  
>   short-term bodywear
>   -------------------
  
>   *see also* |long-term bodywear|_
  
>   long-term bodywear
>   ------------------
  
>   *see also* |short-term bodywear|_

... and that renders correctly locally via `restview` and remotely via Bitbucket[4].

thanks again, Tom Roche <Tom...@po...>

[1]: https://sourceforge.net/p/docutils/mailman/message/34982519/
[2]: flawed version @ https://bitbucket.org/!api/2.0/snippets/tlroche/LR9oL/9277baf6d61904d1725c39dae4df8b7550192ebc/files/problematic_naming_of_internal_anchors.rst
[3]: https://sourceforge.net/p/docutils/mailman/message/34984893/
[4]: fixed version @ https://bitbucket.org/!api/2.0/snippets/tlroche/LR9oL/HEAD/files/problematic_naming_of_internal_anchors.rst

Re: [Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

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

On 2016-03-31, Tom Roche wrote:

> 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?

...

> 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 :-)

...

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

> 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>

Here is the problem: you define an external target with the URL
"#long-term-bodywear" (which happens to point to the same document)
therefore also: "reference-external".

Moreover, you define this external link *before* the equally named section.
Now, when Docutils reaches the section header, the name is already "used up"
and the standard fallback naming (via id-number) kicks in.

> 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>

Yes, as is common for name duplication.


> 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? 

The point is, this could only be done for "link names", a common namespace
for section names and other targets.


The following works here as expected::

  
  .. howto style a link (e.g., make it italic): see http://docutils.sourcefor
  .. |long-term bodywear| replace:: *long-term bodywear*
  .. |short-term bodywear| replace:: *short-term bodywear*
  
  
  short-term bodywear
  -------------------
  
  *see also* |long-term bodywear|_
  
  long-term bodywear
  ------------------
  
  *see also* |short-term bodywear|_



Günter

Re: [Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

[Marc 'B. R. <ma...@ri...>]

On 01/04/16 00:54, Tom Roche wrote:

> 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?

I would not rely on the way id attributes are generated at all.  That's
an implementation detail IMHO and it's also a HTML thing, so this breaks
when generating a PDF via LaTeX anyway.

In the case presented you don't even have to do this because the link
text matched the heading linked, so you can simply omit the link
directives.  Those are also responsible for the "reference external"
instead of "reference internal" classes on the links.

A workaround would be to move the link directives after the headlines,
then docutils sees the headlines first and generates the ID(s) as you
expect them to be.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“Give a man a fire and he's warm for a day,
 but set fire to him and he's warm for the rest of his life.”
                                    -- Terry Pratchett, Jingo

[Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

[Tom R. <Tom...@po...>]

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
~~~~~~~~

Re: [Docutils-users] problem with image and section header

[Tom R. <Tom...@po...>]

[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/

Re: [Docutils-users] problem with image and section header

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

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

[Docutils-users] problem with image and section header

[Tom R. <Tom...@po...>]

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