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

Re: [Docutils-users] How to see the output of my rst text file

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

I use Sphinx, which (if you're interested in it) can output a tree view
if you build 'make pseudoxml'. 

--
Bram Geron
Doctoral researcher in computer science

On Fri, 5 Aug 2016, at 05:04 PM, Francesco Ariis wrote:
> On Fri, Aug 05, 2016 at 06:13:44AM +0000, Deshpande, Vinita wrote:
> > I have created a txt file,with some content, which is formatted using
> > rst (for ex:, headings using "=", table etc).  I would like to see, how
> > this would look as an html page. Can I please know how to do this?
> 
> Hello Vinita,
> I use pandoc to convert from/to .rst (and a bunch of other formats).
> 
>     pandoc -o file.html file.rst
> 
> Remember that you can add a .css stylesheet to modify the formatting
> as you see fit.
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> 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] How to see the output of my rst text file

[Francesco A. <fa...@ar...>]

On Fri, Aug 05, 2016 at 06:13:44AM +0000, Deshpande, Vinita wrote:
> I have created a txt file,with some content, which is formatted using
> rst (for ex:, headings using "=", table etc).  I would like to see, how
> this would look as an html page. Can I please know how to do this?

Hello Vinita,
I use pandoc to convert from/to .rst (and a bunch of other formats).

    pandoc -o file.html file.rst

Remember that you can add a .css stylesheet to modify the formatting
as you see fit.

[Docutils-users] How to see the output of my rst text file

[Deshpande, V. <Vin...@em...>]

Hi,
I have created a txt file,with some content, which is formatted using rst (for ex:, headings using "=", table etc).  I would like to see, how this would look as an html page. Can I please know how to do this?
Sample txt file content:

==========
My heading
==========

Introduction
~~~~~~~~~~~~
My custome introduction

.. table:: **Default flavors**

============  =========  ===============  =============
  Flavor         VCPUs      Disk (in GB)     RAM (in MB)
============  =========  ===============  =============
  m1.tiny        1          1                512
  m1.small       1          20               2048
  m1.medium      2          40               4096
  m1.large       4          80               8192
  m1.xlarge      8          160              16384
============  =========  ===============  =============


I would like to know, how this would appear after formatting is applied.

Thanks,
Vinita

Re: [Docutils-users] New version V1.5.0 of rst.el

[Stefan M. <st...@me...>]

Hi Oleksandr!

Yesterday Oleksandr Gavenko wrote:
> Hi! I actively use rst.el (which come with official Emacs).

Over the time different versions of rst.el have been bundled with
official Emacs versions. In more recent versions of rst.el you could
try ``C-h v rst-version`` for the version you are using.

> Only one downside I have. For one long file (700 KiB, 20 kLOC).
> 
> When I open it I have 2-5 sec delay first time and when I mark line as header
> (C-c C-= / M-x rst-adjust) it take 1-2 sec to complete action.
> 
> File has near 660 headers (notes for future blog posts).

I guess you are using font locking. Some years ago with the help of
Emacs developers I spent some effort to enable using `jit-lock-mode`.
Please check ``C-h v font-lock-support-mode``. The value should be
`jit-lock-mode` (the default).

If that makes a difference then fine. If not you may send me your file
by private mail. You may want to use rot13 for privacy reasons.

You can also try loading your file without font locking switched on.
This should not result in any delay.

> I have not tried new version yet.

There should be no changes in this regard.


						Grüße

						Stefan

Re: [Docutils-users] New version V1.5.0 of rst.el

[Oleksandr G. <gav...@gm...>]

On 2016-07-31, Stefan Merten wrote:

> Today I uploaded a new version of `rst.el` - the reStructuredText
> major mode for Emacs. This is a very big patch which is basically a
> major refactoring introducing some abstractions reflecting
> reStructuredText concepts.

Hi! I actively use rst.el (which come with official Emacs).

Only one downside I have. For one long file (700 KiB, 20 kLOC).

When I open it I have 2-5 sec delay first time and when I mark line as header
(C-c C-= / M-x rst-adjust) it take 1-2 sec to complete action.

File has near 660 headers (notes for future blog posts).

I have not tried new version yet.

-- 
http://defun.work/

[Docutils-users] New version V1.5.0 of rst.el

[Stefan M. <st...@me...>]

Hi!

Today I uploaded a new version of `rst.el` - the reStructuredText
major mode for Emacs. This is a very big patch which is basically a
major refactoring introducing some abstractions reflecting
reStructuredText concepts.

Indeed I developed this for some years now and I'm using the current
version for quite some time. Given this and the array of unit tests I
added I consider this version production ready.

I also pushed this version to the Emacs development tree but at the
moment have no idea in which Emacs version it will finally appear. May
be it is 25.2.

Please find the log entry for this version below.


						Grüße

						Stefan

=== 8< === 8< === 8< === 8< === 8< === 8< === 8< === 8< === 8< === 8< ===

Major refactoring:

* Introduce classes `rst-Ado', `rst-Hdr', `rst-Ttl' and `rst-Stn'
  representing reStructuredText section header concepts.

* Introduce use case approach for systematic testing of section header
  adjustment (files `tests/adjust-uc.el` and
  `tests/adjust-uc_doc.rst`).

* Revise and refactor some old code.

* Add lots of unit tests.

* Replace `set (make-local-variable 'VAR)` by `setq-local VAR`.

* Fix minor bugs.

Minor feature changes and fixes:

* Link final newline in a toc buffer so navigating at the end of the
  line works.

* Improve section header adjustment slightly.

* Integrate and update tutorial.

Re: [Docutils-users] MathJax configuration

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

On 2016-07-03, Alan Isaac wrote:
> By default, MathJax recognizes back ticks as math delimiters:
> http://docs.mathjax.org/en/latest/asciimath.html

> Might it be a good idea for the HTML writers to changes this configuration?

Could you please elaborate a bit or give a minimal example?

Do you want to *use* asciimath or *prevent* accidential interpretation of
text containing ` as asciimath?

Günter

[Docutils-users] naming conventions for custom roles?

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

Custom roles are registered without changing their case,
but case is changed when the roles are located.

This seems inconsistent?

Alan Isaac

[Docutils-users] MathJax configuration

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

By default, MathJax recognizes back ticks as math delimiters:
http://docs.mathjax.org/en/latest/asciimath.html

Might it be a good idea for the HTML writers to changes this configuration?

Alan Isaac

[Docutils-users] ISBN URL?

[Matej C. <mc...@ce...>]

Hi,

I still cannot shake off a bad habit of reading pieces of dead
wood, so I refer in my writing quite often to ISBNs. So, normally
it looks like this:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Phasellus at tellus sollicitudin, pellentesque orci a, ornare
    risus. Vivamus et quam a felis aliquet sollicitudin quis ac
    orci “`Four loves`_”.  Vestibulum pretium dui dolor, ac
    ullamcorper sapien suscipit sed.

    .. _`Four loves`:
        https://en.wikipedia.org/wiki/Special:BookSources?isbn=0156329301

I would prefer to be able either to use the reference like

    .. _`Four loves`:
        isbn:0156329301

and docutils would generate proper URL, or to go all the way to
(how to make docutils role with two parameters?):

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Phasellus at tellus sollicitudin, pellentesque orci a, ornare
    risus. Vivamus et quam a felis aliquet sollicitudin quis ac
    orci isbn::``“Four loves”``,``0156329301``.  Vestibulum
    pretium dui dolor, ac ullamcorper sapien suscipit sed.

Do you know about something like this already made? If I am
reading correctly the documentation_, does it mean that I have to
write some Python? And if yes (I am a Python programmer, so it is
not that big obstacle), could I somehow package it as
a standalone Python package uploadable to PyPI? Are there any
such packages already available on PyPI? I cannot find any.

Thanks for any replies,

Matěj

.. _documentation:
    http://docutils.sourceforge.net/docs/howto/rst-roles.html

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

[Docutils-users] Custom Directives

[Paul V. <pc...@gm...>]

Hello everyone,

I have a question about creating custom directives. My approach thus far
has been to iterate through self.content and wrap HTML around it. I then
convert the HTMLto rST using nodes.raw(). Is this a valid approach or
frowned upon when creating custom directives?

Here is a bit of sample code:

class eCard(Directive):
    """
    usage:
    .. ecard::

        [name]
        [image]
        [name]
        [image]
    """
    has_content = True
    optional_arguments = 0
    def run(self):
        this =  "<h2 id=\"da_header\">Desk Attendants</h2>\n <div
id=\"da_ecard_container\">\n"
        count = 0
        for item in range(0, len(self.content)/2):
            name = self.content[count]
            image = self.content[count+1]
            count += 2
            this += "<div class=\"ecard\">\n"
            this += '<img class="da_image" src=' + image + ' alt="' + name
+ '"/>\n'
            this += "<span>" + name + "</span\n>"
            this += "</div>\n"
        this += "</div>\n"
        this = nodes.raw('', this, format='html')
        return [this]
directives.register_directive('ecard', eCard)

I haven't run into anything wrong with this approach, I'm mostly just
curious if this way will cause problems in the future.

Re: [Docutils-users] How to get rst preview tools on CentOS7?

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

On 2016-06-06, 09:50 GMT, Oleksandr Gavenko wrote:
> You should contact RH/CentOS packaging team and ask them for 
> inclusion of
> rst2pdf utility.

rst2pdf is part of Fedora/EPEL ...  
https://admin.fedoraproject.org/pkgdb/package/rpms/rst2pdf/

You just file a bug against the package asking for what you 
want. Of course, you may be asked to maitain the branch 
yourself, in which case, welcome to the Fedora packaging world!  
:)

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
The American Republic will endure, until politicians realize they
can bribe the people with their own money.
    -- based on a statement of Alexander Fraser Tytler

Re: [Docutils-users] How to get rst preview tools on CentOS7?

[Oleksandr G. <gav...@gm...>]

On 2016-06-03, Oleksandr Gavenko wrote:
> From: "David M. Karr"
>> What I can't figure out is how to get the various RST preview tools, 
>> like "rst2pdf".  I see that "rst2pdf" is available on Ubuntu, but I 
>> don't see it in the default repos for CentOS7.
>
> I don't use RH, just make web search for Debian "apt-file" alternative:
>
>   sudo yum install yum-utils
>   repoquery --whatprovides '*bin/rst2pdf'

On Debian 'rst2pdf' is provided by external project:

  $ apt-file search bin/rst2pdf
  rst2pdf: /usr/bin/rst2pdf

  $ apt-cache show rst2pdf
  Version: 0.93-4
  Maintainer: Elena Grandi <val...@tr...>
  Homepage: http://code.google.com/p/rst2pdf/

It seems that docutils team is not responsible for that utility.

You should contact RH/CentOS packaging team and ask them for inclusion of
rst2pdf utility.

================================================================

I managed to install CentOS in LXC container:

  sudo lxc-create -t centos -n centos2 -- --release 6.8
  sudo lxc-create -t centos -n centos2 -- --release 7

Even "yum" utility provide built-in ability to query for packages which have
certain files:

  [root@centos media]# cat /etc/redhat-release 
  CentOS release 6.8 (Final)

  [root@centos media]# yum whatprovides '*/bin/rst2pdf*'

  No Matches found

  [root@centos media]# yum whatprovides '*/bin/rst2*'
  python-docutils-0.6-1.el6.noarch : A system for processing plaintext documentation
  Matched from:
  Filename    : /usr/bin/rst2html
  Filename    : /usr/bin/rst2odt
  Filename    : /usr/bin/rst2xml
  Filename    : /usr/bin/rst2s5
  Filename    : /usr/bin/rst2latex
  Filename    : /usr/bin/rst2man
  Filename    : /usr/bin/rst2pseudoxml
  Filename    : /usr/bin/rst2newlatex
  Filename    : /usr/bin/rst2odt_prepstyles


  [root@centos2 media]# cat /etc/redhat-release 
  CentOS Linux release 7.2.1511 (Core) 

  [root@centos2 media]# yum whatprovides '*/bin/rst2pdf*'

  No Matches found


  [root@centos2 media]# yum whatprovides '*/bin/rst2*'
  Loaded plugins: fastestmirror
  Loading mirror speeds from cached hostfile
   * base: mirror.mirohost.net
   * extras: mirror.mirohost.net
   * updates: mirror.mirohost.net
  python-docutils-0.11-0.2.20130715svn7687.el7.noarch : System for processing plaintext documentation
  Repo        : base
  Matched from:
  Filename    : /usr/bin/rst2odt
  Filename    : /usr/bin/rst2html
  Filename    : /usr/bin/rst2pseudoxml
  Filename    : /usr/bin/rst2xml
  Filename    : /usr/bin/rst2s5
  Filename    : /usr/bin/rst2latex
  Filename    : /usr/bin/rst2man
  Filename    : /usr/bin/rst2odt_prepstyles
  Filename    : /usr/bin/rst2xetex

-- 
http://defun.work/

Re: [Docutils-users] How to get rst preview tools on CentOS7?

[Oleksandr G. <gav...@gm...>]

On 2016-06-01, David M. Karr wrote:

> I'm just starting to look at ReST.  I'll likely be editing rst files in 
> Emacs, although I could use Eclipse if a suitable editor was available.  
> As it's just simple text formatting, I could probably get by with a 
> plain text view in Eclipse if I had to. The Emacs mode appears to be a 
> little more functional.
>
I probably use

  docutils-common: /usr/share/emacs/site-lisp/rst.el

On "C-c C-t C-t" it shows TOC for easy navigation and on "C-c C-=" it fixes
and cycles through header declarations.

I never use any other commands. Full command list is available on C-h m.

I miss indenting and text wrapping in definition list declaration but except
this and syntax highlighting issues in "verbatim" text it works fine

> What I can't figure out is how to get the various RST preview tools, 
> like "rst2pdf".  I see that "rst2pdf" is available on Ubuntu, but I 
> don't see it in the default repos for CentOS7.

I don't use RH, just make web search for Debian "apt-file" alternative:

  sudo yum install yum-utils
  repoquery --whatprovides '*bin/rst2pdf'

In this way you be able to find any package that contain specific file. See:

  http://stackoverflow.com/questions/1133495/how-do-i-find-which-rpm-package-supplies-a-file-im-looking-for

While I build RST files with GNU make there are command C-c C-c C-c
(M-x rst-compile).

If you work with Java (I assume that because you are mentioning Eclipse) it is
possible to build Java project documentation in Maven project with:

   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-site-plugin</artifactId>
       <version>3.2</version>
       <dependencies>
           <dependency>
               <groupId>org.nuiton.jrst</groupId>
               <artifactId>doxia-module-jrst</artifactId>
               <version>1.5</version>
           </dependency>
       </dependencies>
   </plugin>

-- 
http://defun.work/

Re: [Docutils-users] How to get rst preview tools on CentOS7?

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

On 2016-05-31, 21:19 GMT, David M. Karr wrote:
> I'm just starting to look at ReST.  I'll likely be editing rst files in 
> Emacs, although I could use Eclipse if a suitable editor was available.  
> As it's just simple text formatting, I could probably get by with a 
> plain text view in Eclipse if I had to. The Emacs mode appears to be a 
> little more functional.

Try to run

yum list \*docutil\*

That's where plenty of rST related programs are packaged.

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8

How many Bavarian Illuminati does it take to screw in a light
bulb?
Three: one to screw it in, and one to confuse the issue.

[Docutils-users] How to get rst preview tools on CentOS7?

[David M. K. <dav...@gm...>]

I'm just starting to look at ReST.  I'll likely be editing rst files in 
Emacs, although I could use Eclipse if a suitable editor was available.  
As it's just simple text formatting, I could probably get by with a 
plain text view in Eclipse if I had to. The Emacs mode appears to be a 
little more functional.

What I can't figure out is how to get the various RST preview tools, 
like "rst2pdf".  I see that "rst2pdf" is available on Ubuntu, but I 
don't see it in the default repos for CentOS7.

Re: [Docutils-users] Maybe a bug in rst2latex

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

On 2016-05-28, Sergio wrote:
> If I run rst2html test.rst > test.html I obtain a file with the links
> correctly setted as one can expect.

> But if I run

>     $ rst2latex test.rst > test.tex
>     $ pdflatex test.tex

> I obtain a series of warnings:

>     LaTeX Warning: Hyper reference `chunk3' on page 2
>     undefined on input line 150.

> and the links there are not into the resultin pdf.

> I can correct this behaviour adding into "test.tex" a series of macro
> "\phantomsection\label{chunk1}", but I think this should be done by
> rst2latex.

You are right. There is no provision for handling of targets for a row of
block element (including literal block and lists) in the latex writer.

Thank you for the report. I am working on a fix.

Günter

Re: [Docutils-users] how to correct reStructuredText markup in batch.

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

On 2016-05-30, Jeffery wrote:

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

> hello,,

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

I suppose you mean blank (or whitespace), do you?

> now, i want a tools/or scripts that can correct this issue batch
> process po file.

I don't know of any such ready-made tool.

I see two possible ways:

a) Use a text editor or script language and regular expressions to convert
   e.g. "a*" to "a\ *" and "*a" to "*\ a" (a stands for any chinese letter
   around the inline markup).

b) Download a daily snapshot of Docutils from the SVN repository
   (http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/)
   
   In the configuration file
   set the new setting "character-level-inline-markup: True" 
   or use the command line option ``--character-level-inline-markup``
   (see the SVN version of docutils/docs/user/cofig.txt).
   
   Of course, this only works if you can install this version at the
   target system.
   
Hope this helps

Günter   
   
   

[Docutils-users] how to correct reStructuredText markup in batch.

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

hello,,


 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] Maybe a bug in rst2latex

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

If I run rst2html test.rst > test.html I obtain a file with the links
correctly setted as one can expect.

But if I run

    $ rst2latex test.rst > test.tex
    $ pdflatex test.tex

I obtain a series of warnings:

    LaTeX Warning: Hyper reference `chunk3' on page 2
    undefined on input line 150.

and the links there are not into the resultin pdf.

I can correct this behaviour adding into "test.tex" a series of macro
"\phantomsection\label{chunk1}", but I think this should be done by rst2latex.

The file "test.tex" has the corrections into a comment block.

==file test.rst=========================
=========
pipe test
=========

A little benchmark to study the behavior of noweb.

.. contents:: Table of Contents

|

The name of this program is "pipe" and has two blocks of code.

.. _chunk1:

::

  <pipe>=
    <Add two terms>
    <Say hallo>

The first block of code takes two parameters and return the sum of
them. Think of it as a ``graeting code`` between two column of beer.

.. _chunk2:

::

  <Add two terms>=
    def add(a, b):
        result = a + b
        return result

*[defines <add> used in chunk3_]*

.

then open the list and return the result.

.. _chunk3:

::

  <Add two terms>+=
        result = result - []
        return result

The second and last block of code takes one parameter, uses the add
function previously defined, and finally say hallo.

.. _chunk4:

::

  <Say hallo>=
    def sayhallo(s):
        v = add(s, s+1)
        print "Hallo %d" % (v)

*[defines <sayhallo>]*

.

So has come the end of the program.

List of chunks
--------------

| ``<pipe>``, defined at chunk1_
| ``<Add two terms>``, defined at chunk2_, used at chunk1_
| ``<Say hallo>``, defined at chunk3_, used at chunk1_

List of identifiers
-------------------

|  *add*, defined at chunk2_, used at chunk3_
|  *sayhallo*, defined at chunk3_
==end of file test.rst==================

==file test.tex=========================
\documentclass[a4paper]{article}
% generated by Docutils <http://docutils.sourceforge.net/>
\usepackage{fixltx2e} % LaTeX patches, \textsubscript
\usepackage{cmap} % fix search and cut-and-paste in Acrobat
\usepackage{ifthen}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\setcounter{secnumdepth}{0}

%%% Custom LaTeX preamble
% PDF Standard Fonts
\usepackage{mathptmx} % Times
\usepackage[scaled=.90]{helvet}
\usepackage{courier}

%%% User specified packages and stylesheets

%%% Fallback definitions for Docutils-specific commands

% providelength (provide a length variable and set default, if it is new)
\providecommand*{\DUprovidelength}[2]{
  \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
}

% lineblock environment
\DUprovidelength{\DUlineblockindent}{2.5em}
\ifthenelse{\isundefined{\DUlineblock}}{
  \newenvironment{DUlineblock}[1]{%
    \list{}{\setlength{\partopsep}{\parskip}
            \addtolength{\partopsep}{\baselineskip}
            \setlength{\topsep}{0pt}
            \setlength{\itemsep}{0.15\baselineskip}
            \setlength{\parsep}{0pt}
            \setlength{\leftmargin}{#1}}
    \raggedright
  }
  {\endlist}
}{}

% hyperlinks:
\ifthenelse{\isundefined{\hypersetup}}{
  \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
}{}
\hypersetup{
  pdftitle={pipe test},
}

%%% Title Data
\title{\phantomsection%
  pipe test%
  \label{pipe-test}}
\author{}
\date{}

%%% Body
\begin{document}
\maketitle

A little benchmark to study the behavior of noweb.

\phantomsection\label{table-of-contents}
\pdfbookmark[1]{Table of Contents}{table-of-contents}
\renewcommand{\contentsname}{Table of Contents}
\tableofcontents

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

The name of this program is \textquotedbl{}pipe\textquotedbl{} and has two
blocks of code.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% HERE SHOULD BE THE LINE
%%
%% \phantomsection\label{chunk1}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{quote}{\ttfamily \raggedright \noindent
<pipe>=\\
~~<Add~two~terms>\\
~~<Say~hallo>
}
\end{quote}

The first block of code takes two parameters and return the sum of
them. Think of it as a \texttt{graeting code} between two column of beer.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% HERE SHOULD BE THE LINE
%%
%% \phantomsection\label{chunk2}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{quote}{\ttfamily \raggedright \noindent
<Add~two~terms>=\\
~~def~add(a,~b):\\
~~~~~~result~=~a~+~b\\
~~~~~~return~result
}
\end{quote}

\emph{{[}defines <add> used in chunk3\_{]}}

.

then open the list and return the result.
%
\begin{quote}{\ttfamily \raggedright \noindent
<Add~two~terms>+=\\
~~~~~~result~=~result~-~{[}{]}\\
~~~~~~return~result
}
\end{quote}

The second and last block of code takes one parameter, uses the add
function previously defined, and finally say hallo.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% HERE SHOULD BE THE LINE
%%
%% \phantomsection\label{chunk3}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{quote}{\ttfamily \raggedright \noindent
<Say~hallo>=\\
~~def~sayhallo(s):\\
~~~~~~v~=~add(s,~s+1)\\
~~~~~~print~\textquotedbl{}Hallo~\%d\textquotedbl{}~\%~(v)
}
\end{quote}

\emph{{[}defines <sayhallo>{]}}

.

So has come the end of the program.


\section{List of chunks%
  \label{list-of-chunks}%
}

\begin{DUlineblock}{0em}
\item[] \texttt{<pipe>}, defined at \hyperref[chunk1]{chunk1}
\item[] \texttt{<Add two terms>}, defined at \hyperref[chunk2]{chunk2}, used
at \hyperref[chunk1]{chunk1}
\item[] \texttt{<Say hallo>}, defined at \hyperref[chunk3]{chunk3}, used at
\hyperref[chunk1]{chunk1}
\end{DUlineblock}


\section{List of identifiers%
  \label{list-of-identifiers}%
}

\begin{DUlineblock}{0em}
\item[] \emph{add}, defined at \hyperref[chunk2]{chunk2}, used at
\hyperref[chunk3]{chunk3}
\item[] \emph{sayhallo}, defined at \hyperref[chunk3]{chunk3}
\end{DUlineblock}

\end{document}
==end of file test.tex==================

Re: [Docutils-users] MathJax

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

On 2016-02-21, Alan Isaac wrote:
> If I request MathJax output from rst2html,
> it is included as an http request.
> This means the content won't display (by default)
> in browsers that care about mixed content if the
> page is securely served.  (Examples: FireFox, Edge.)

> As I understand it, MathJax recommends using https:
> http://mathjax.readthedocs.org/en/latest/misc/faq.html#how-do-i-access-the-mathjax-cdn-using-a-https-secure-connection

> Can this be changed in the source (rather than
> relying on user configuration)?

Then, the abovementioned Browsers would refuse to show the page if it is
served via "normal" html...

> I am grateful for the configuration option, but it seems
> the default is wrong?

I recommend setting the mathjax URL in the docutils configuration file.

> PS I am confused about why the documentation
> http://docutils.sourceforge.net/docs/user/config.html#math-output
> reads::

>    math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js

> instead of::

>    --math-output="MathJax file:/usr/share/javascript/mathjax/MathJax.js"

> In my experience, the quotes are essential for this to work.

The example shows the use in a config file.
The quotes are essential for command line arguments. They are not required
in the configuration file. (Also a colon will not work on the command line.)


Günter

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

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

On 2016-05-21, Aahz wrote:
> On Thu, May 19, 2016, Jeffery wrote:

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

> Can you provide more information or at least a link?

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

> What is a "bank"?

I suppose this should be "blank" (i.e. whitespace).

rST `inline markup recognition rules`__ require whitespace or punctuation
around inline markup. This is a problem for languages that dont't use
whitespace to separate words (Chinese, Japanese, ...).

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules

There is already a bug report and patch for this issue.
https://sourceforge.net/p/docutils/patches/103/


--conservative-inline-markup
                        Require whitespace or punctuation around inline
                        markup. Enabled by default.
--simple-inline-markup  No restrictions on characters around inline markup.


> If you want a batch process, you need to identify some kind of text
> that you can use to delimit reST markup.

This might be solved via a set of regular expression replacements, but I
don't know a ready solution.

It might be simpler to apply the patch 
https://sourceforge.net/p/docutils/patches/_discuss/thread/e5337656/6356/attachment/simple-inline-rules.patch
or wait for the config setting to
be in the SVN version and use it.

Günter

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

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

On Thu, May 19, 2016, Jeffery wrote:
>
> hey,  recently i review the translation project that translate English reST
> document into chinese reST document  use gettext tools on transifex
> platform.

Can you provide more information or at least a link?

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

What is a "bank"?  Do you mean "backquote"?  If you want a batch process,
you need to identify some kind of text that you can use to delimit reST
markup.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"There are three kinds of lies: Lies, Damn Lies, and Statistics."  --Disraeli

Re: [Docutils-users] [Feature/Bug] If a role content is empty, it's never called?

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

On 2016-05-20, Anil Lakhman wrote:
> Hi,

> I'm not subscribed to the mailing list, please CC me if possible on the
> issue.

> I have filed a github issue here replicating the issue:

> https://github.com/sphinx-doc/sphinx/issues/2562

> Basically, If I add a custom role and pass an empty string within the
> backticks, the role is never called, so I don't have a chance to show a
> warning or error message. 

This is the same for standard roles::

  das ist `interpreted`

  das ist ` ` nichts

becomes ::

   <paragraph>
        das ist 
        <title_reference>
            interpreted
    <paragraph>
        das ist ` ` nichts

and is a consequence of the ``rST inline markup recognition rules`__

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules


> For example the :download: role shows a warning
> message if we pass an empty string or space within the backticks.

Really? Then parsing happens somehow differently from Docutils
implementation of rst.

> Am I missing something or is this not possible? (I'm using sphinx)

...

> # Now say I forget to pass through some text or empty space
> # (accidently deleted, forget I had it, etc..)
>:icon:``    # No text
>:icon:` `   # Space empty text

> #= :icon:``
> #= :icon:` `

> # Notice how it just outputs the role raw, it doesn't seem to even
> call `icon_role`
> # so I don't have a chance to check the value (and throw a warning)

> If the content with backticks is empty, I would like to decide what to do
> with the role (output a empty node, throw a warning, place a default icon).

> Am I missing something?

> The :download: role does this, but I'm finding it confusing as to who it's
> implemented. It throws the following error if you pass an empty string.

> # Throws an error: WARNING: Inline literal start-string without end-string.
>:download:``

Does this really happen with

 :download:``

It usually happens if there is no end string (and also nothing else), e.g.

 :math:`
 
but not with

 :funny:` more text

> # Just outputs the raw role text (I don't have a chance to do anything)
>:icon:``

Yes, this is not recognized as rST markup (just like e.g. ::

  x*y* or :math:` x+2 `

)

I am afraid this is an issue to stay, as it concerns defines rST rules.
You may file an enhancement ticket for recognition of
:something:`` or :something` ` but there is no chance of a quick fix
unfortunately.

Günter

[Docutils-users] [Feature/Bug] If a role content is empty, it's never called?

[Anil L. <ani...@gm...>]

Hi,

I'm not subscribed to the mailing list, please CC me if possible on the
issue.

I have filed a github issue here replicating the issue:

https://github.com/sphinx-doc/sphinx/issues/2562

Basically, If I add a custom role and pass an empty string within the
backticks, the role is never called, so I don't have a chance to show a
warning or error message. For example the :download: role shows a warning
message if we pass an empty string or space within the backticks.

Am I missing something or is this not possible? (I'm using sphinx)

Here it is in code:


Say I have the following role which converts an icon role into an inline
font awesome icon:

# e.g: Create an inline <span class="fa fa-rocket fa-2x"></span>def
icon_role(role, rawtext, text, lineno, inliner, options={},
content=[]):
    options.update({'classes': ["fa-" + x for x in text.split(",")]})
    options['classes'].append('fa')
    set_classes(options)
    node = nodes.inline(**options)
    return [node], []
# ... add it - Note i'm using sphinx hence `app`

app.add_role('icon', icon_role)

# Now I use it like so:
:icon:`rocket,2x`

#= <span class="fa fa-rocket"></span>

Issue

# Now say I forget to pass through some text or empty space
# (accidently deleted, forget I had it, etc..)
:icon:``    # No text
:icon:` `   # Space empty text

#= :icon:``
#= :icon:` `

# Notice how it just outputs the role raw, it doesn't seem to even
call `icon_role`
# so I don't have a chance to check the value (and throw a warning)

If the content with backticks is empty, I would like to decide what to do
with the role (output a empty node, throw a warning, place a default icon).

Am I missing something?

The :download: role does this, but I'm finding it confusing as to who it's
implemented. It throws the following error if you pass an empty string.

# Throws an error: WARNING: Inline literal start-string without end-string.
:download:``

# Just outputs the raw role text (I don't have a chance to do anything)
:icon:``

Any Ideas?


You can also reply to this github ticket on sphinx:


https://github.com/sphinx-doc/sphinx/issues/2562


Any help would be very much appreciated! - This could be an excellent
feature for validation, if it doesn't exist already.


Thanks!