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

Re: [Docutils-users] rst2html for partial HTML generation [Was: Re: 2015: reStructuredText implementations in other programming languages?]

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

Ahoj Matěj,

On 2015-06-26, Matěj Cepl wrote:

> However, I have decided to make The Right Thing™ and wrote my 
> hexo renderer using rst2html 
> (https://gitlab.com/mcepl/hexo-renderer-restructuredtext) except 
> now I have a different problem (issue #1 in that repository).  
> rst2html generates only complete HTML documents and relies on 
> tons of CSS stylesheets.

To get parts of the HTML document, the "publish_parts()" convenience
function can be used. It is described in
http://docutils.sourceforge.net/docs/api/publisher.html#publisher-convenience-functions
with example code in
http://docutils.sourceforge.net/docutils/examples.py

> Would it be possible to somehow persuade rst2html to produce 
> just as plain HTML as possible without dependency on too much of 
> CSS?

This depends on what you intend:

* the default html4css2 writer uses one stylesheet¹, default.css 
  (which is very long)
  
* the new html_base writer (!! to be renamed !!)² in the SVN repository
  uses two stylesheets¹:
  
  * minimal.css   required basic rules
  * plain.css	  rules for easier reading and pleasant layout
  
  This writer also gets rid of IE 6 compatibility hacks to achieve a cleaner
  HTML output.

* the html4trans__ writer in the sandbox does not depend on CSS
  It uses hard-coded HTML-styling (bad!) instead for rST elements that
  have no real equivalent in HTML.
  
  __ http://docutils.sourceforge.net/sandbox/html4trans/

¹ + ``math.css``, if you have maths in the document and the "math-output"
  setting is html

² cf. http://repo.or.cz/w/docutils.git/blob_plain/HEAD:/docutils/docs/user/html.txt


Günter

Re: [Docutils-users] rst2html for partial HTML generation [Was: 2015: reStructuredText implementations in other programming languages?]

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

On 2015-06-26, 14:25 GMT, Roberto Alsina wrote:
> Maybe something like
>
> https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/__init__.py#L233 

Thanks, I'll take a look.

Matěj

-- 
http://www.ceplovi.cz/matej/, Jabber: mcepl<at>ceplovi.cz
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
<"}}}><

Re: [Docutils-users] rst2html for partial HTML generation [Was: 2015: reStructuredText implementations in other programming languages?]

[Roberto A. <ra...@ne...>]

On 26/06/15 11:09, Matěj Cepl wrote:
> On 2015-06-26, 13:58 GMT, Roberto Alsina wrote:
>> No, that was perfectly fine. We do extract body because we support a
>> bunch of "compilers" and not all of them play as nice.
>>
>> Actual code for rst is like this:
>>
>> return pub.writer.parts['docinfo'] + pub.writer.parts['fragment']
>>
>> I don't quite recall the specifics of how it ended up like that ;-)
> Could somebody be able to write a simple example of such script?
> (/me gets a bit lost while diving into
> /usr/lib/python2.7/site-packages/docutils/)

Maybe something like

https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/__init__.py#L233 

Re: [Docutils-users] rst2html for partial HTML generation [Was: 2015: reStructuredText implementations in other programming languages?]

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

On 2015-06-26, 13:58 GMT, Roberto Alsina wrote:
> No, that was perfectly fine. We do extract body because we support a 
> bunch of "compilers" and not all of them play as nice.
>
> Actual code for rst is like this:
>
> return pub.writer.parts['docinfo'] + pub.writer.parts['fragment']
>
> I don't quite recall the specifics of how it ended up like that ;-)

Could somebody be able to write a simple example of such script?  
(/me gets a bit lost while diving into 
/usr/lib/python2.7/site-packages/docutils/)

Thanks,

Matěj

-- 
http://www.ceplovi.cz/matej/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
Of course I'm respectable. I'm old. Politicians, ugly buildings,
and whores all get respectable if they last long enough.
      --John Huston in "Chinatown."

Re: [Docutils-users] rst2html for partial HTML generation [Was: 2015: reStructuredText implementations in other programming languages?]

[Roberto A. <ra...@ne...>]

On 26/06/15 10:43, Marcelo Huerta wrote:
> Roberto Alsina decía, en el mensaje "Re: [Docutils-users] rst2html for partial
> HTML generation [Was: Re: 2015: reStructuredText implementations in other
> programming languages?]" del 26/6/2015 9:34:16:
>
>> In Nikola I just extract the body element using lxml and put it in the
>> template where I want it.
> Maybe I'm being silly, but wasn't it possible to simply call publish_parts and
> use the returned parts['html_body'], as indicated in
> http://docutils.sourceforge.net/docs/api/publisher.html#publish-parts-details
> ? Tell me if I'm missing something.

No, that was perfectly fine. We do extract body because we support a 
bunch of "compilers" and not all of them play as nice.

Actual code for rst is like this:

return pub.writer.parts['docinfo'] + pub.writer.parts['fragment']

I don't quite recall the specifics of how it ended up like that ;-)

Re: [Docutils-users] rst2html for partial HTML generation [Was: 2015: reStructuredText implementations in other programming languages?]

[Marcelo H. <mar...@gm...>]

Roberto Alsina decía, en el mensaje "Re: [Docutils-users] rst2html for partial
HTML generation [Was: Re: 2015: reStructuredText implementations in other
programming languages?]" del 26/6/2015 9:34:16:

> In Nikola I just extract the body element using lxml and put it in the 
> template where I want it.

Maybe I'm being silly, but wasn't it possible to simply call publish_parts and
use the returned parts['html_body'], as indicated in
http://docutils.sourceforge.net/docs/api/publisher.html#publish-parts-details
? Tell me if I'm missing something.

-- 
   o-=< Marcelo >=-o

Re: [Docutils-users] rst2html for partial HTML generation [Was: Re: 2015: reStructuredText implementations in other programming languages?]

[Roberto A. <ra...@ne...>]

On 26/06/15 09:25, Matěj Cepl wrote:
> On 2015-04-23, 08:01 GMT, Peter Funk wrote:
>> BTW: Who can contribute reports about her/his experiences
>> with pandoc ( https://github.com/jgm/pandoc ) to this discussion?
>> I've experimented in a project with the following makefile rule but
>> later decided to manually edit the resulting .rst files a lot.
> https://github.com/jgm/pandoc/issues/2231#issuecomment-111875559
>
> rST processor which cannot process .. image: elements is kind of
> difficult to use. And now, I cannot upgrade pandoc (more recent
> one doesn't build on my system, and I don't want to use
> unpackaged programs anyway).
>
> However, I have decided to make The Right Thing™ and wrote my
> hexo renderer using rst2html
> (https://gitlab.com/mcepl/hexo-renderer-restructuredtext) except
> now I have a different problem (issue #1 in that repository).
> rst2html generates only complete HTML documents and relies on
> tons of CSS stylesheets.
>
> Would it be possible to somehow persuade rst2html to produce
> just as plain HTML as possible without dependency on too much of
> CSS?

In Nikola I just extract the body element using lxml and put it in the 
template where I want it.

The CSS ...

we have a rst.css which is extracted from docutils and a code.css 
generated by pygments.

The rst.css ... it's very old fashioned, with the 3-d sidebars and such, 
so we have an outstanding improvement request to redo via LESS so it can 
be easier to tweak, but haven't got around to hacking on it yet.

[Docutils-users] rst2html for partial HTML generation [Was: Re: 2015: reStructuredText implementations in other programming languages?]

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

On 2015-04-23, 08:01 GMT, Peter Funk wrote:
> BTW: Who can contribute reports about her/his experiences
> with pandoc ( https://github.com/jgm/pandoc ) to this discussion?
> I've experimented in a project with the following makefile rule but
> later decided to manually edit the resulting .rst files a lot.

https://github.com/jgm/pandoc/issues/2231#issuecomment-111875559

rST processor which cannot process .. image: elements is kind of 
difficult to use. And now, I cannot upgrade pandoc (more recent 
one doesn't build on my system, and I don't want to use 
unpackaged programs anyway).

However, I have decided to make The Right Thing™ and wrote my 
hexo renderer using rst2html 
(https://gitlab.com/mcepl/hexo-renderer-restructuredtext) except 
now I have a different problem (issue #1 in that repository).  
rst2html generates only complete HTML documents and relies on 
tons of CSS stylesheets.

Would it be possible to somehow persuade rst2html to produce 
just as plain HTML as possible without dependency on too much of 
CSS?

I guess proper template (and --template parameter) could cover 
multitude of sins. Did anybody prepare such a template?

Best,

Matěj

-- 
http://www.ceplovi.cz/matej/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
The world is coming to an end!  Repent and return those library
books!

Re: [Docutils-users] power in reStructuredText

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

On Sun, Jun 14, 2015 at 3:48 PM, Guenter Milde <mi...@us...> wrote:
> On 2015-06-14, mansour amini wrote:
>
>> hihow can i show power function in reStructedText (for exapmle instead
>> of 2 * 2 = 4 write 2^2 =4)? i don't want to use ^, i want show like
>> mathematics expression
>
> Then you can use a mehtematical expression in a "math" role or directive.
> The input syntax is "LaTeX math", the output is properly typeset (if the
> aoutput format supports math (html and latex do, see the reStructuredText
> documentation for details).)
>
> Aternatively, you can use superscript Unicode characters or the "sup" role
> for the exponent.

For simple expressions (x² etc), I like to use Unicode superscript
characters: ¹²³⁴⁵⁶⁷⁸⁹⁰. There are also subscript characters:
₁₂₃₄₅₆₇₈₉₀. And lots of others besides.

To type these, I enable the Compose Key on my systems. Native support
on Linux, WinCompose on Windows.

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

Re: [Docutils-users] (I'm not subscribed) Fwd: traceback error report for `KeyError: 'refid'`

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

Thank you for your report,

On 2015-06-09, Jeroen Wiert Pluimers wrote:

> File having issues:
> https://raw.githubusercontent.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/master/README.rst

The current version of this file (2015-06-15) compiles without problems here
(rst2html (Docutils 0.13 [repository], Python 2.7.10, on linux2))

> $ rst2html.py README.rst readme.html
> README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0
> corresponding footnotes available.

It seems the footnote-text/footnote-reference mismatch was solved in the
meantime.

> KeyError: 'refid'
> Exiting due to error.  Use "--traceback" to diagnose.
...

This seems to be an aftereffect.
I did not encounter this in a minimal test, though.
Do you still have a file that exhibits the KeyError on compiling?

...
> Traceback (most recent call last):
...
>   File
> "/Library/Python/2.7/site-packages/docutils/writers/html4css1/__init__.py",
> line 986, in visit_footnote_reference
>     href = '#' + node['refid']
>   File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 567, in
> __getitem__
>     return self.attributes[key]
> KeyError: 'refid'

Unfortunately, I don't know how we landed here with a footnote-reference
node without refid. and what should/could be done to it.

Thanks,
Günter

Re: [Docutils-users] power in reStructuredText

[Ben F. <ben...@be...>]

mansour amini <ms_...@ya...> writes:

> i don't want to use ^, i want show like mathematics expression

It is worth observing that reStructuredText is a markup format designed
for widespread use, rendering to many different output formats.

Not all the output formats Docutils targets are capable of rendering
complex mathematical expressions.

With that said, the “math” interpreted text role and directive
<URL:http://docutils.sourceforge.net/docs/ref/rst/roles.html#math>
<URL:http://docutils.sourceforge.net/docs/ref/rst/directives.html#math>
are available in Docutils version 0.8 and later::

    The input format is LaTeX math syntax[1] with support for Unicode
    symbols […]

    Support is limited to a subset of LaTeX math by the conversion
    required for many output formats.

I hope that helps.

-- 
 \             “I believe our future depends powerfully on how well we |
  `\     understand this cosmos, in which we float like a mote of dust |
_o__)                 in the morning sky.” —Carl Sagan, _Cosmos_, 1980 |
Ben Finney

Re: [Docutils-users] power in reStructuredText

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

On 2015-06-14, mansour amini wrote:

> hihow can i show power function in reStructedText (for exapmle instead
> of 2 * 2 = 4 write 2^2 =4)? i don't want to use ^, i want show like
> mathematics expression

Then you can use a mehtematical expression in a "math" role or directive.
The input syntax is "LaTeX math", the output is properly typeset (if the
aoutput format supports math (html and latex do, see the reStructuredText
documentation for details).)

Aternatively, you can use superscript Unicode characters or the "sup" role
for the exponent.

Günter

[Docutils-users] power in reStructuredText

[mansour a. <ms_...@ya...>]

hihow can i show power function in reStructedText (for exapmle instead of 2 * 2 = 4 write 2^2 =4)? i don't want to use ^, i want show like mathematics expression
 

[Docutils-users] (I'm not subscribed) Fwd: traceback error report for `KeyError: 'refid'`

[Jeroen W. P. <jer...@gm...>]

Just read at http://docutils.sourceforge.net/docs/user/mailing-lists.html
that my previous email might not have reached the list as I'm not
subscribed so I should send to Doc...@li...

Note that my gmail address goes around my hosts spam filters, so that is a
better place to CC.

Groet,
--
Jeroen W. Pluimers - specialist in .NET, Win32, SQL, Visual Studio & Delphi
tel: +31 20 610 8322
fax: +31 20 610 8323
GSM: +31 654 385 135
mailto:je...@pl...
Pluimers Software Ontwikkeling BV, Amsterdam, Trade-register 34152606
http://www.pluimers.com

---------- Forwarded message ----------
From: Jeroen Pluimers <je...@pl...>
Date: Mon, Jun 8, 2015 at 11:01 PM
Subject: traceback error report for `KeyError: 'refid'`
To: doc...@li...



File having issues:
https://raw.githubusercontent.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/master/README.rst

$ rst2html.py README.rst readme.html
README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0
corresponding footnotes available.
KeyError: 'refid'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <doc...@li...>.
Include "--traceback" output, Docutils version (0.12 [release]),
Python version (2.7.5), your OS type & version, and the
command line used.


$ rst2html.py README.rst readme.html --traceback
README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0
corresponding footnotes available.
Traceback (most recent call last):
  File "/usr/local/bin/rst2html.py", line 23, in <module>
    publish_cmdline(writer_name='html', description=description)
  File "/Library/Python/2.7/site-packages/docutils/core.py", line 352, in
publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/Library/Python/2.7/site-packages/docutils/core.py", line 219, in
publish
    output = self.writer.write(self.document, self.destination)
  File "/Library/Python/2.7/site-packages/docutils/writers/__init__.py",
line 80, in write
    self.translate()
  File
"/Library/Python/2.7/site-packages/docutils/writers/html4css1/__init__.py",
line 176, in translate
    self.document.walkabout(visitor)
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in
walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in
walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in
walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in
walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 166, in
walkabout
    visitor.dispatch_visit(self)
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 1882, in
dispatch_visit
    return method(node)
  File
"/Library/Python/2.7/site-packages/docutils/writers/html4css1/__init__.py",
line 986, in visit_footnote_reference
    href = '#' + node['refid']
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 567, in
__getitem__
    return self.attributes[key]
KeyError: 'refid'


Groet,
--
Jeroen W. Pluimers - specialist in .NET, Win32, SQL, Visual Studio & Delphi
tel: +31 20 610 8322
fax: +31 20 610 8323
GSM: +31 654 385 135
mailto:je...@pl...
BeSharp.net is a trademark of Pluimers Software Ontwikkeling BV, Amsterdam,
Trade-register 34152606
http://wiert.me ; http://jwpluimers.myplaxo.com/

Re: [Docutils-users] how to modify reST parsing?

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

On 2015-06-04, Tom Roche wrote:

> I use `restview`[1] mostly to locally preview reST documents before I
> push them to Bitbucket (BB). BB's reST parser accepts 4-char-length
> header/title underlines, e.g.,

>> summary
>> ====

> I prefer those, since they are easier to produce and search for.

However, they are not valid rST.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

Whether to call the Bitbucket rST parser broken or forgiving, is up to you.

> However my (Debian) laptop's `restview` does not: I get (e.g.)

>> System Message: WARNING/2 (./README.rst, line 13)xm
>> Title underline too short.
>>     summary
>>     ====

> I have put an issue on `restview`[2] regarding this. However, I
> strongly suspect the relevant parsing is being done by my laptop's
> `docutils` (which is a `restview` install dependency).  Am I missing
> something? 

This seems to be the case. The above System Message is another indicator:
it is a typical Docutils warning.

> If not: can I configure my system `docutils` so as *not* to emit this
> warning?

This is easily possible via a configuration file. 
See http://docutils.sourceforge.net/docs/user/config.html#report-level

However, this will not change parsing but only reporting: The above markup
example will still not be parsed as a section header.


Changing the parsing rules is far more difficult. It would imply writing a
custom parser (inheriting from the standard rST parser) and front-end
(calling the custom parser).

I'd rather recommend using an `editor that supports rST`__ and can insert a
section underline of correct lenght on the press of a key-combo.

__ http://docutils.sourceforge.net/docs/user/links.html#editors


Günter

[Docutils-users] how to modify reST parsing?

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

I use `restview`[1] mostly to locally preview reST documents before I push them to Bitbucket (BB). BB's reST parser accepts 4-char-length header/title underlines, e.g.,

> summary
> ====

I prefer those, since they are easier to produce and search for. However my (Debian) laptop's `restview` does not: I get (e.g.)

> System Message: WARNING/2 (./README.rst, line 13)xm
> Title underline too short.
>     summary
>     ====

I have put an issue on `restview`[2] regarding this. However, I strongly suspect the relevant parsing is being done by my laptop's `docutils` (which is a `restview` install dependency). Am I missing something? 

If not: can I configure my system `docutils` so as *not* to emit this warning?

If feasible please reply to me as well as to the list, and TIA, Tom Roche <Tom...@po...>

[1]: https://pypi.python.org/pypi/restview
[2]: https://github.com/mgedmin/restview/issues/31

Re: [Docutils-users] Python 3.4 StandardError problem

[Vladimir P. <vla...@gm...>]

Hi Günter,

On 6/3/2015 3:31 PM, Guenter Milde wrote:
>> NameError: name 'StandardError' is not defined
>
> It looks like you are trying to use the Python 2 version with Python 3.
>
> The Py3 code has
>
>    class ApplicationError(Exception):
>
> on line 68 of docutils/__init__.py
>

Yep, you're right.

>> Is there anything I'm doing wrong, or shall I use earlier version of
>> Python, or is it possible to fix this problem?
>
> To use Docutils with Python 3, you need to install it:
>
> * unpack and call setup.py with a py3 version, or

This worked for me. Thanks for catching my mistake!

- Volodya

Re: [Docutils-users] Python 3.4 StandardError problem

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

On 2015-06-02, Vladimir Prus wrote:
> Hi,

> I'm trying to use docutils on Windows, with Python 3.4, and I get an
> error like this:

> Traceback (most recent call last):
>    File "C:/Users/Vladimir/Local/docutils-0.12/tools/rst2html.py", line 17, in <module>
>      from docutils.core import publish_cmdline, default_description
>    File "C:\Users\Vladimir\Local\docutils-0.12\docutils\__init__.py", line 68, in <module>
>      class ApplicationError(StandardError):
> NameError: name 'StandardError' is not defined

It looks like you are trying to use the Python 2 version with Python 3.

The Py3 code has 

  class ApplicationError(Exception):
  
on line 68 of docutils/__init__.py


> Is there anything I'm doing wrong, or shall I use earlier version of
> Python, or is it possible to fix this problem?

To use Docutils with Python 3, you need to install it:

* unpack and call setup.py with a py3 version, or
* use pip to download and install a pre-build "Wheel" from the Pypi.

See also http://docutils.sourceforge.net/README.html#python-3-compatibility

Günter

Re: [Docutils-users] Python 3.4 StandardError problem

[Aahz <aa...@py...>]

On Tue, Jun 02, 2015, Vladimir Prus wrote:
> 
> I'm trying to use docutils on Windows, with Python 3.4, and I get an error like this:
> 
> Traceback (most recent call last):
>    File "C:/Users/Vladimir/Local/docutils-0.12/tools/rst2html.py", line 17, in <module>
>      from docutils.core import publish_cmdline, default_description
>    File "C:\Users\Vladimir\Local\docutils-0.12\docutils\__init__.py", line 68, in <module>
>      class ApplicationError(StandardError):
> NameError: name 'StandardError' is not defined

This looks like an improper 2to3 conversion:

https://docs.python.org/3/library/2to3.html#2to3fixer-standarderror

I haven't really used Python3 yet, so I have no idea what's going on,
just felt like testing my research skills.  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Times are bad.  Children no longer obey their parents, and everyone is
writing a book."  --Cicero

[Docutils-users] Python 3.4 StandardError problem

[Vladimir P. <vla...@gm...>]

Hi,

I'm trying to use docutils on Windows, with Python 3.4, and I get an error like this:

Traceback (most recent call last):
   File "C:/Users/Vladimir/Local/docutils-0.12/tools/rst2html.py", line 17, in <module>
     from docutils.core import publish_cmdline, default_description
   File "C:\Users\Vladimir\Local\docutils-0.12\docutils\__init__.py", line 68, in <module>
     class ApplicationError(StandardError):
NameError: name 'StandardError' is not defined

The command line is nothing interesting:

     "C:\Python34\python" "C:/Users/Vladimir/Local/docutils-0.12/tools/rst2html.py"  --link-stylesheet 
--traceback --trim-footnote-reference-space --footnote-references=superscript --stylesheet=../../rst.css 
unix-variants.rst ..\..\bin.v2\more\getting_started\msvc-12.0\debug\threading-multi\unix-variants.html

I have tried both 0.12 release and the latest snapshot as of today, whose RELEASE-NOTES.txt say:

     :Date: $Date: 2015-03-15 17:16:30 +0000 (Sun, 15 Mar 2015) $
     :Revision: $Revision: 7837 $

Is there anything I'm doing wrong, or shall I use earlier version of Python, or is it possible
to fix this problem?

Thanks in advance,
Volodya

Re: [Docutils-users] RST cross referencing not working in code highlighting

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

On Thu, May 21, 2015 at 4:34 AM, Masood Azizi <ma...@gt...> wrote:
> Hello,
>
> I use docutils in order to produce documents via rst file.
>
> In my document, I need to add and highlight some source code. Also I use
> cross referencing to make some keywords (section names) hyperlink to the
> respective section. So, simply append an underline to the end of the word,
> e.g mysection_ which refers to:
>
> mysection
> ---------
>
> Some text...
>
> The problem occurs when I use the format of code highlighting. That is, if I
> use .. code:: C and then a block of C code, cross referencing in the source
> code does not work:
>
> .. code:: C
>
>     #include "example.h"
>     int main()
>     {
>         printf("My Section is:");
>         mysection_();
>         return 0;
>     }
>
> So, how can I have both code highlighting and cross referencing?

I believe the answer is: you cannot have both.

The "code" directive parses its content (a code block) via the
Pygments library, which doesn't understand reStructuredText. Pygments
only understands code, in one language at a time. So the trailing
underscore in "mysection_" is just seen as part of the identifier.
Which is perfectly valid; "mysection_" is a legal Python identifier,
as is "_this" and even "_".

You can get a literal block with inline markup, such as hyperlink
references, using the "parsed-literal" directive. It doesn't do code
highlighting though. And "care must be taken with the text, because
inline markup is recognized and there is no protection from parsing".
See http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

You have to choose one or the other. If you choose code highlighting,
a workaround is to include the hyperlink references outside of the
code block, in explanatory text (e.g. "see mysection_ ...").

-- David Goodger

> Thank you in advance,
>
> Masood
>
>
> PS. I am not a subscribed user.

[Docutils-users] RST cross referencing not working in code highlighting

[Masood A. <ma...@gt...>]

Hello,

I use docutils in order to produce documents via rst file.

In my document, I need to add and highlight some source code. Also I use
cross referencing to make some keywords (section names) hyperlink to the
respective section. So, simply append an underline to the end of the
word, e.g |mysection_| which refers to:

|mysection
---------

Some text...
|

The problem occurs when I use the format of code highlighting. That is,
if I use |.. code:: C| and then a block of C code, cross referencing in
the source code does not work:

|.. code:: C

    #include "example.h"
    int main()
    {
        printf("My Section is:");
        mysection_();
        return 0;    
    }|

So, how can I have both /code highlighting/ and /cross referencing/?


Thank you in advance,

Masood


PS. I am not a subscribed user.

Re: [Docutils-users] Will new HTMLWriter change the H1, H1 issue?

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

On 2015-05-16, Tony Narlock wrote:

> Regarding
> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
> .

> I am using docutils trunk on a personal website that uses an ordinary css
> framework.  I am using the ``html-base`` writer.

> I have taken a look at the two workarounds:

>    1. If you don't want the top section heading to be interpreted as a
>    title at all, disable the doctitle_xform
>    <http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform>
> setting
>    (--no-doc-title option). *This will interpret your document differently
>    from the standard settings, which might not be a good idea. *

>    2. If you don't like the reuse of the H1 in the HTML output, you can
>    tweak the initial_header_level
>    <http://docutils.sourceforge.net/docs/user/config.html#initial-header-level>
> setting
>    (--initial-header-level option) -- *but unless you match its value to
>    your specific document, you might end up with bad HTML (e.g. H3 without
>    H2).*

> Does the new HTMLWriter do anything to change this?

No. I assume this to be a design decision which was taken with careful
consideration by David and should not be changed without need.

> This is a pretty big deal, I guess it looks like I'm going to need to add
> custom CSS for h1.title, h1, h2, h3, h4, h5... because of this.

If you changed from a system/work-flow that uses h1 for title and h2+ for
section headings and don't want to use the "doctitle-xform" setting, yes.

OTOH, adding a pair of CSS rules does not seem a "big deal" to me.
Especially as Docutils HTML output requires some CSS rules in any case.


"doctitle-xform: False" might be another option -- if you happen to use
source documents with one as well as two top-level headings, this would
make the rendering more consistent. E.g.

  my-site/doc1.txt::

     Thema
     -----

     irgendwas

     Sub-Thema
     ~~~~~~~~~

  my-site/doc2.txt::

     Thema 1
     -------

     irgendwas

     Thema 2
     -------

     noch was.
     
  my-site/doc3.txt::
     
     Thema
     -----
     Untertitel
     ~~~~~~~~~~
     
     irgendwas

With the default settings, doc1 would be a document with title and one
top-level section, doc2 would be a document without title but with two
top-level sections, and doc2 would be a document with title, subtitle and no
sections at all.

¹ Beware: you will need to "manually" set the <title> in this case
  (either via the .. title:: directive, in a template, or in your custom
  Python wrapper).


> The two solutions given sound like hacks with big trade-offs

I'd interpret the caveats in the FAQ rather as minders to consider accepting
the default choice as sensible than as a pointer to a hackish nature of the
options.

> that don't justify bothering to pass those options through,

The easiest way to have consistent local configuration is a
project-specific configuration file, located in the current directory.
See docutils/docs/user/config.html#configuration-files

> but for the sake of asking:

>    1. If I am using docutils via the python API (not the front-end), how
>    could I pass ``inital_header_level`` and ``no-doc-title`` into
>    ``docutils.core.publish_parts``?

See the documentation and code of the publish* functions.
Also, see the examples in the test suite (test/test_functional/tests/*.py).

>    2. What is the internal issue that makes it difficult to give an option
>    to just render h1, h2, h3, h4, h5, h6?*

I suppose you mean: to convert top-level section titles to h1 if there is no
document title but to h2 if there is a document title and let the other
section titles follow suit?

I don't know whether it would be more difficult to implement than the
current behaviour.

This is a design decision taken long before I started working on
Docutils. I may have decided otherwise, but it does not itch me in a
manner that I am going to challenge it.

If I were to implement (or accept) this, then not as a new option but
rather as a special value (e.g. 0 or -1) for the "initial_header_level"
setting.

>    3. Does this happen in HTMLWriter?

Partially.

The doctitle transformation creates a document title out of "lonely" section
headings. This is before the writer kicks in. E.g., the doctree of the above
example looks like::

  <document ids="thema" names="thema" source="/tmp/doc1.txt" title="Thema">
      <title>
          Thema
      <paragraph>
          irgendwas
      <section ids="sub-thema" names="sub-thema">
          <title>
              Sub-Thema

This transform can be deactivated by the doctitle-xform setting,
resulting in::

  <document source="/tmp/doc1.txt">
      <section ids="thema" names="thema">
          <title>
              Thema
          <section ids="untertitel" names="untertitel">
              <title>
                  Untertitel
              <paragraph>
                  irgendwas
              <section ids="sub-thema" names="sub-thema">
                  <title>
                      Sub-Thema


The html writer converts the doctree into HTML. "title" nodes are processed
depending on the parent node. (see the visit_title() method of the html
writer(s)).

>    If so, how much work would it be to create a config option / python
>    interface to configure html element + class for each level?

This depends. In any case, it would be considerably more work
than adding a pair of CSS rules or using the existing options. And it
would interpret your document even more "differently from the standard
settings", so you gain nothing compared to "doctitle-xform: False".

> Here's an
>    example of how bootstrap would render a title + subtitle::

>    <h1>h1. Bootstrap heading <small>Secondary text</small></h1>

Aside: "html-base" and its descendants place sub-title and sub-headings
in paragraph objects with the "subtitle"/"section-subtitle" class
argument because the standard says:

    # h1–h6 elements must not be used to markup subheadings, subtitles,
    # alternative titles and taglines unless intended to be the heading for a
    # new section or subsection.
    # -- http://www.w3.org/TR/html/sections.html#headings-and-sections

For CSS styling, see "html_base/minimal.css" and the rendering examples under
http://www.w3.org/TR/html/common-idioms.html#common-idioms

> I do recognize the issue is complicated, there's no universal default that
> can make everyone happy. What is your thoughts making the html element
> *and* class / id of title, subtitle, header level 1, 2, 3...  configurable
> via options?

Is there a problem with the existing options that would be better solved
via a more specific/intrusive option?

> Is there a an example you have of how the html element and class of title,
> subtitle, h1, h2, h3...  output could be set via Python / subclassing
> HTMLWriter?

Not that I know of. Seems to be a seldom asked question nowadays.

hope that helps,

Günter

[Docutils-users] Will new HTMLWriter change the H1, H1 issue?

[Tony N. <to...@gi...>]

Hi Günter,

Regarding
http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
.

I am using docutils trunk on a personal website that uses an ordinary css
framework.  I am using the ``html-base`` writer.

I have taken a look at the two workarounds:


   1. If you don't want the top section heading to be interpreted as a
   title at all, disable the doctitle_xform
   <http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform>
setting
   (--no-doc-title option). *This will interpret your document differently
   from the standard settings, which might not be a good idea. *
   2. If you don't like the reuse of the H1 in the HTML output, you can
   tweak the initial_header_level
   <http://docutils.sourceforge.net/docs/user/config.html#initial-header-level>
setting
   (--initial-header-level option) -- *but unless you match its value to
   your specific document, you might end up with bad HTML (e.g. H3 without
   H2).*



Does the new HTMLWriter do anything to change this?

This is a pretty big deal, I guess it looks like I'm going to need to add
custom CSS for h1.title, h1, h2, h3, h4, h5... because of this.

The two solutions given sound like hacks with big trade-offs that don't
justify bothering to pass those options through, but for the sake of asking:



   1. If I am using docutils via the python API (not the front-end), how
   could I pass ``inital_header_level`` and ``no-doc-title`` into
   ``docutils.core.publish_parts``?
   2. What is the internal issue that makes it difficult to give an option
   to just render h1, h2, h3, h4, h5, h6?*
   3. Does this happen in HTMLWriter?

   If so, how much work would it be to create a config option / python
   interface to configure html element + class for each level? Here's an
   example of how bootstrap would render a title + subtitle::

   <h1>h1. Bootstrap heading <small>Secondary text</small></h1>

   4.


   5.

   Considering that title + subtitle is a special case, it would be
nice to offer a

   6.

    way to configure output of it that doesn't result in the
trade-offs of those

   7.

   config options.

   8.


   9.

   source: http://getbootstrap.com/css/#h1.-bootstrap-heading-secondary-text


I do recognize the issue is complicated, there's no universal default that
can make everyone happy. What is your thoughts making the html element
*and* class / id of title, subtitle, header level 1, 2, 3...  configurable
via options?

Is there a an example you have of how the html element and class of title,
subtitle, h1, h2, h3...  output could be set via Python / subclassing
HTMLWriter?

* Even if it would chop stuff off - I think that covers 90% of my cases.  I
do not use lone subtitle.  I typically will make a title header, then
immediately go down to h2-section style headers (I follow this convention
in my reST projects, and I see it in many other projects as well)

[Docutils-users] Reminder Docutils outstanding questions on External Websites

[Tony N. <to...@gi...>]

Greetings Documentation Utilities Users,

We do have reStructuredText and docutils technical questions on external
websites like StackOverflow and Quora:


- http://stackoverflow.com/questions/tagged/docutils
- http://stackoverflow.com/questions/tagged/restructuredtext
- http://www.quora.com/reStructuredText-1

New questions do come in now and then. :)