docutils-users Mailing List for Docutils: Documentation Utilities

Tom Roche Sun, 28 Feb 2016 16:00:32 -0700
>> Can one style a non-link replacement (e.g., emphasize text with a subscript) without a `raw` directive?

David Goodger Sun, 28 Feb 2016 17:19:47 -0600
> that is not currently possible, no. [Instead], use the Unicode subscript characters, e.g. CO₂, FFCO₂, H₂O. Superscripts too: E=mc². These can be styled with emphasis:

Thanks, I ended up doing that: `restview` rendered my `raw` directive correctly, but the Bitbucket reST renderer currently does not.

> For easy character entry,

Like Oleksandr Gavenko in this thread, I use Emacs, so Unicode entry is not usually a problem (though I just use `C-x 8 RET <name/>`).

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

Most feature rich competitor to RST syntax is AsciiDoc and it has regular
syntax for passing additional parameters to macros::

  http://asciidoc.org/asciidoc.css-embedded.html#_macros

For block level syntax looks like:

  [quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
  ____________________________________________________________________
  As he spoke there was the sharp sound of horses' hoofs and
  grating wheels against the curb, followed by a sharp pull at the
  bell. Holmes whistled.
  ...
  ____________________________________________________________________

For inline::

  image::images/logo.png[scaledwidth="75%",alt="Company Logo"]

RST have regular syntax for block level elements:

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

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

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

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

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

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

  This is a |myref|.

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

-- 
http://defun.work/

On 2016-02-29, Tom Roche wrote:

> However I want to combine inline markup and a substitution providing a
> subscript, for something like the following reST:
>
> fail1> Cities produce more than 70% of global fossil-fuel |CO2| emissions
> fail1> (*|FFCO2|*). We have cutting-edge science relating how cities and
> fail1> regions settle and use their land (LULC) to their |FFCO2| emissions.
>
> fail1> .. |CO2| replace:: CO\ :sub:`2`
> fail1> .. |FFCO2| replace:: FFCO\ :sub:`2`

Recently I take notes for Coursera classes in RST and I like :math:
role/directive rendering:

  $ cat in.rst

  This is :math:`CO_2`.

  $ rst2html --math-output=HTML in.rst out.html

  $ cat out.html

  <span class="formula"><i>CO</i><sub>2</sub></span>

As you see default rendering enclose text in italic tag - so text will look
emphasised.

You source code will be readable in plain text.

:math: try to interpret included text as TeX formula, so relatively complex
typography can be represented with this syntax.

I don't use much of \LaTeX syntax in flavor of Emacs editor abilities for
easy entering complex text.

With binding:

  (setq my-russian-input-method 'russian-computer)
  (setq my-ukranian-input-method 'ukrainian-computer)
  (setq my-ipa-input-method 'ipa-x-sampa)
  (when (<= emacs-major-version 21)
    (setq my-russian-input-method 'cyrillic-jcuken)
    (setq my-ukranian-input-method 'cyrillic-jcuken))
  (setq default-input-method my-russian-input-method)

  (defun my-toggle-input-method (&optional arg)
    (interactive "P")
    (if (numberp arg)
        (cond
         ((eq arg 1)
          (activate-input-method nil))
         ((eq arg 2)
          (activate-input-method my-russian-input-method))
         ((eq arg 3)
          (activate-input-method my-ukranian-input-method))
         ((eq arg 4)
          (activate-input-method 'greek))
         ((eq arg 5)
          (activate-input-method my-ipa-input-method))
         ((eq arg 6)
          (activate-input-method 'TeX)) )
      (toggle-input-method arg)) )

  (global-set-key (kbd "C-\\") 'my-toggle-input-method)

I able to enter Ru/Ua/Greek/IPA/TeX symbols without effort. For:

  :def:`Chebyshev inequality`: if :math:`X` is a random variable with mean
  :math:`μ` and variance :math:`σ²` then

  .. math::

    P(|X-μ| ≥ c) ≤ σ²/c²

  for all :math:`c > 0`.

with TeX input method when I type [^] [2] Emacs automatically place superscript
number 2. Same for [_] [2] which may be useful in your chemistry text.
[\] [s] [u] [m] produces ∑ sign, there are hundreds of symbols can be entered
in such way.

Note that Unicode doesn't hold all subscript/superscript for English alphabet,
so I use LeTeX syntax which look nice in plain text and HTML:

  Z_n = ((∑_{1≤i≤n} X_i) - n·μ) / (σ·sqrt(n))

"1≤i≤n" become subscript in HTML.

If you prefer to use limited editor I may suggest you to make file with list
of interesting Unicode chars and copy-paste them.

I don't like --math-output=MathJax because it link to external CDN and it
really slow in may part of world )) --math-output=HTML just fine.

Recently I found that option in form

  --math-output=MathJax:http://you.domain/context/mathjax.js

allow link to your own copy of mathjax library but again built-in
--math-output=HTML just fine.

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

I check:

  http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles

If define:

  .. role:: chem(math)
     :class: chem

  This is :chem:`H_2O`.

you unfortunately get:

  <span class="formula"><i>CO</i><sub>2</sub></span>

There are no additional class "chem" but it would be great to have to
customise chemical and mathematical formulas.

I file a bug:

  https://sourceforge.net/p/docutils/bugs/295/
    #295 Custom text role with inheritence on math role should respect additional class

-- 
http://defun.work/

On Sun, Feb 28, 2016 at 5:00 PM, Tom Roche <Tom...@po...> wrote:
>
> [footnotes follow .sig]
>
> Can one style a non-link replacement (e.g., emphasize text with a subscript) without a `raw` directive? What I mean:

What you're asking for is nested inline markup via substitution, and
that is not currently possible, no.

Suggestion: rather than a substitution, use the Unicode subscript
characters, e.g. CO₂, FFCO₂, H₂O. Superscripts too: E=mc². These can
be styled with emphasis: *CO₂*, **FFCO₂**, etc. For easy character
entry, explore the "compose key" functionality
(https://en.wikipedia.org/wiki/Compose_key) standard in Linux distros
and easily added to MacOS & Windows systems.

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


> I see FAQ section 2.16[1]:
>> Inline markup can be combined with hyperlinks using substitution definitions and references with the "replace" directive. For example:
>
> However I want to combine inline markup and a substitution providing a subscript, for something like the following reST:
>
> fail1> Cities produce more than 70% of global fossil-fuel |CO2| emissions (*|FFCO2|*). We have cutting-edge science relating how cities and regions settle and use their land (LULC) to their |FFCO2| emissions.
>
> fail1> .. |CO2| replace:: CO\ :sub:`2`
> fail1> .. |FFCO2| replace:: FFCO\ :sub:`2`
>
> to show (when rendered, e.g., by `restview`) "FFCO2"
>
> * the first time in italic, the second time not
> * both times with '2' subscripted
> * neither times with the '|' showing
>
> The above fragment fails, as
>
> - only the second "FFCO2" is subscripted
> - the first "FFCO2" both shows the pipes and does not subscript
>
> I also tried
>
> fail2> Cities produce more than 70% of global fossil-fuel |CO2| emissions (|iFFCO2|). We have cutting-edge science relating how cities and regions settle and use their land (LULC) to their FFCO2 emissions.
>
> fail2> .. |CO2| replace:: CO\ :sub:`2`
> fail2> .. |FFCO2| replace:: FFCO\ :sub:`2`
> fail2> .. |iFFCO2| replace:: *|FFCO2|*
>
> which produces identical (failed results). Thanks to FAQ section 2.16[1] I learned I could do the following, which works:
>
> works> Cities produce more than 70% of global fossil-fuel |CO2| emissions (|iFFCO2|). We have cutting-edge science relating how cities and regions settle and use their land (*LULC*) to their |FFCO2| emissions.
>
> works> .. |CO2| replace:: CO\ :sub:`2`
> works> .. |FFCO2| replace:: FFCO\ :sub:`2`
> works> .. |iFFCO2| raw:: html
> works>
> works>    <em>FFCO<sub>2</sub></em>
>
> but I'd prefer to do this (and similar simple styling of replacements) without `raw` directives. Is that currently possible?
>
> If possible please reply to me (directly) as well as the list, and
> TIA, Tom Roche <Tom...@po...>
>
> [1]: http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
>

[footnotes follow .sig]

Can one style a non-link replacement (e.g., emphasize text with a subscript) without a `raw` directive? What I mean:

I see FAQ section 2.16[1]:
> Inline markup can be combined with hyperlinks using substitution definitions and references with the "replace" directive. For example:

However I want to combine inline markup and a substitution providing a subscript, for something like the following reST:

fail1> Cities produce more than 70% of global fossil-fuel |CO2| emissions (*|FFCO2|*). We have cutting-edge science relating how cities and regions settle and use their land (LULC) to their |FFCO2| emissions.

fail1> .. |CO2| replace:: CO\ :sub:`2`
fail1> .. |FFCO2| replace:: FFCO\ :sub:`2`

to show (when rendered, e.g., by `restview`) "FFCO2"

* the first time in italic, the second time not
* both times with '2' subscripted
* neither times with the '|' showing

The above fragment fails, as

- only the second "FFCO2" is subscripted
- the first "FFCO2" both shows the pipes and does not subscript

I also tried

fail2> Cities produce more than 70% of global fossil-fuel |CO2| emissions (|iFFCO2|). We have cutting-edge science relating how cities and regions settle and use their land (LULC) to their FFCO2 emissions.

fail2> .. |CO2| replace:: CO\ :sub:`2`
fail2> .. |FFCO2| replace:: FFCO\ :sub:`2`
fail2> .. |iFFCO2| replace:: *|FFCO2|*

which produces identical (failed results). Thanks to FAQ section 2.16[1] I learned I could do the following, which works:

works> Cities produce more than 70% of global fossil-fuel |CO2| emissions (|iFFCO2|). We have cutting-edge science relating how cities and regions settle and use their land (*LULC*) to their |FFCO2| emissions.

works> .. |CO2| replace:: CO\ :sub:`2`
works> .. |FFCO2| replace:: FFCO\ :sub:`2`
works> .. |iFFCO2| raw:: html
works>
works>    <em>FFCO<sub>2</sub></em>

but I'd prefer to do this (and similar simple styling of replacements) without `raw` directives. Is that currently possible?

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

[1]: http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible

On 2015-10-19, Sandra wrote:

> Hi, I am using reST for some of my documentation and tried the link to the
> public domain reST to HTML converter.
>
>>From http://docutils.sourceforge.net/rst.html#try-it-online
> Converter https://www.tele3.cz/jbar/rest/rest.html
>
> The converter itself gives an error when I enter text and press ``Render``:
> 405 Not Allowed
> nginx/1.4.6 (Ubuntu)
>
> As a side note, the about link is a good idea!
>
I have filled bug with suggestion to remove "Try it Online" section:

  https://sourceforge.net/p/docutils/bugs/293/

Actually RST should have JS parser and so host online editor on home page
which is always alive (filed request):

  https://sourceforge.net/p/docutils/bugs/294/
    #294 JavaScript parser for official RST specification (for online live preview).

-- 
http://defun.work/

On 2016-02-22, Oleksandr Gavenko wrote:

> Modern HTML5 text usually have:
>
>   <meta name=viewport content="width=device-width, initial-scale=1">
>
> in <head>.
>
> I can't understand how can I pass this line to resulted template.
>
> In ``rst2html --help`` there is:
>
>   HTML-Specific Options
>   ---------------------
>   --template=<file>       Specify the template file (UTF-8 encoded).  Default is
>                           "/usr/share/docutils/writers/html4css1/template.txt".
>
> ``template.txt`` is:
>
>   %(head_prefix)s
>   %(head)s
>   %(stylesheet)s
>   %(body_prefix)s
>   %(body_pre_docinfo)s
>   %(docinfo)s
>   %(body)s
>   %(body_suffix)s
>

Makefile rule:

  RST_WARNING_FLAGS := --halt warning
  RST_RENDER_FLAGS := --strip-comments --embed-stylesheet --no-xml-declaration --math-output=MathJax
  RST_FLAGS := $(RST_WARNING_FLAGS) $(RST_RENDER_FLAGS)

  $(HTML_DIR)/%.html: %.rst HEADER.rst rst.css rst.tmpl $(MAKEFILE_LIST) | $(HTML_DIR)
      $(RST2HTML) $(RST_FLAGS) --stylesheet=rst.css --template=rst.tmpl $*.rst
      $@

rst.tmpl:

  <!DOCTYPE html>
  <html>
  <head>
  <meta name=viewport content="width=device-width, initial-scale=1">
  %(head)s
  %(stylesheet)s
  %(body_prefix)s
  %(body_pre_docinfo)s
  %(docinfo)s
  %(body)s
  %(body_suffix)s

I replace %(head_prefix)s with above tags. This makes generated files HTML 5
compliant.

Firefox source browser warn (highlight by red) default substitution:

  <?xml version="1.0" encoding="utf-8" ?>             ## Attempt to use XML
                                                      ## processing instructions in HTML

  <!DOCTYPE html PUBLIC                               ## Almost standard mode doctype
     "-//W3C//DTD XHTML 1.0 Transitional//EN"         ## Expected <!DOCTYPE html>
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

Problem resolved.

-- 
http://defun.work/

Modern HTML5 text usually have:

  <meta name=viewport content="width=device-width, initial-scale=1">

in <head>.

I can't understand how can I pass this line to resulted template.

In ``rst2html --help`` there is:

  HTML-Specific Options
  ---------------------
  --template=<file>       Specify the template file (UTF-8 encoded).  Default is
                          "/usr/share/docutils/writers/html4css1/template.txt".

``template.txt`` is:

  %(head_prefix)s
  %(head)s
  %(stylesheet)s
  %(body_prefix)s
  %(body_pre_docinfo)s
  %(docinfo)s
  %(body)s
  %(body_suffix)s

What changes make to template in order to include additional <meta> tag?

*PS* I can precess HTML files with sed as quick solution.

-- 
http://defun.work/

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)?
I am grateful for the configuration option, but it seems
the default is wrong?

Thanks,
Alan Isaac

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.

On 2016-02-16, Alan G. Isaac wrote:
> I often use the ``include`` directive with the ``start-after``
> and ``end-before`` options.  However, my delimiters are
> generally on their own lines, which means that I end up with
> undesired prepended and appended eols.  Is there any way
> around this?

Not to my knowledge.

Günter

I often use the ``include`` directive with the ``start-after``
and ``end-before`` options.  However, my delimiters are
generally on their own lines, which means that I end up with
undesired prepended and appended eols.  Is there any way
around this?

Thanks!




-- 
"I believe that anyone who claims to know what's going on
will lie about the little things too."
-- Sam Black Crow, in American Gods by Neil Gaiman, p.139

Which is probably a good thing: the math directive compiles to a
display:block in HTML; the math role compiles to a display:inline in
HTML. The compiled HTML would break if you could (easily) put a math
directive in a paragraph.

Cheers, Bram


On Tue, 16 Feb 2016, at 11:40 AM, Guenter Milde wrote:
> On 2016-02-15, Oleksandr Gavenko wrote:
> > This:
> 
> >   .. |fib| replace:: :math:`fib(n) = fib(n-1)+fib(n-2)`
> 
> > works in:
> 
> >   Substitution of mathematic formula: |fib|.
> 
> > But this:
> 
> >   .. |fib| math:: fib(n) = fib(n-1)+fib(n-2)
> 
> > produced error:
> 
> >   main.rst:211: (WARNING/2) Substitution definition "fib" empty or invalid.
> 
> >   ..    |fib| math:: fib(n) = fib(n-1)+fib(n-2)
> 
> >   main.rst:209: (ERROR/3) Undefined substitution referenced: "fib".
> 
> > HTML output from rst2html have marked |fib| and formula shown only for
> > directive.
> 
> > It that correct?
> 
> Yes, the second syntax is invalid. There is a limited set of replacement
> options, only the directives listed in
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions
> and image are supported.
> 
> Günter
> 
> 
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

On 2016-02-15, Oleksandr Gavenko wrote:
> This:

>   .. |fib| replace:: :math:`fib(n) = fib(n-1)+fib(n-2)`

> works in:

>   Substitution of mathematic formula: |fib|.

> But this:

>   .. |fib| math:: fib(n) = fib(n-1)+fib(n-2)

> produced error:

>   main.rst:211: (WARNING/2) Substitution definition "fib" empty or invalid.

>   ..    |fib| math:: fib(n) = fib(n-1)+fib(n-2)

>   main.rst:209: (ERROR/3) Undefined substitution referenced: "fib".

> HTML output from rst2html have marked |fib| and formula shown only for
> directive.

> It that correct?

Yes, the second syntax is invalid. There is a limited set of replacement
options, only the directives listed in
http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions
and image are supported.

Günter

On 2016-02-15, Oleksandr Gavenko wrote:
> How can I highlight interactive REPL sessions? Like:

>   bash# cd ~/sql
>   bash# mysql
>   Password:

>   [mariadb]> select 1;

> Among:

>   http://pygments.org/docs/lexers/

> I see possibility to use various:

>   .. code:: bash
>   .. code:: console
>   .. code:: pycon
>   .. code:: postgresql-console

The last one seems quite near to me...

> but even with Bash it only highlight "$" sign and think my "bash#" prompt as
> output...

> I see a way to add to "code" additional parameter (prompt regex):

>   http://docutils.sourceforge.net/docs/ref/rst/directives.html#code

> and implement parser in pygments

This should work - maybe postgresql-console is a good starting point.
Look/ask the Pygments community for details.

With a new parser/lexer "repl-console", the rst syntax would be::

   .. code:: postgresql-console

      bash# cd ~/sql

As docutils calls the external Pygments for syntax highlight, this should be
available to Docutils if it works with Pygments.
There is no need to
>  make own directive


Günter

Hi Oleksandr.

I don't know if that's what you're after, but I want to mention the
Jupyter Notebook: http://jupyter.org/.

It allows you to mix text, images, equations, code (and its output) in
one "document".

I supports R, Octave, Bash and many more languages:
https://github.com/ipython/ipython/wiki/IPython-kernels-for-other-languages

Jupyter notebooks can be included in Sphinx projects by means of the
"nbsphinx" extension: http://nbsphinx.readthedocs.org/.
With that, you can seamlessly mix your reST content and Jupyter notebooks.

cheers,
Matthias

On Mon, Feb 15, 2016 at 11:31 PM, Oleksandr Gavenko wrote:
> On 2016-02-13, Guenter Milde wrote:
>
>>> Can arbitrary code be run during document generation?
>>
>>> Recently I see books/cources/sci reports like:
>>
>>>   https://github.com/bcaffo/courses
>>
>>> which uses "R Markdown":
>>
>>>   http://rmarkdown.rstudio.com/
>>
>>> So final document have result of running R language on pages.
>>
>>> I would like to run Bash example.
>>
>>> Or instead of afraid to make mistake place bc, octave-cli or R code and/or
>>> values in resulted document in place.
>>
>> With standard docutils, you can use a Makefile to run/update examples that
>> generate files to include in rST.
>>
>> There are contributed extensions/pre-processors/frameworks for some
>> other input format inclusions.
>
> Ok. I see:
>
>   http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#code-execution
>
>   It's too dangerous (or too complicated in the case of "eval"). We do not
>   want to have such things in the core.
>
> With include directive and build scripts that would be easy::
>
>   http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment
>
>   $ python example.py >example.out
>
>   .. include:: example.py
>      :code: python
>
>   .. include:: example.out
>      :code: python
>
> For placing example.py inside RST document and rendering both text and result
> of run I think I should add support for custom directive.
>
> --
> http://defun.work/
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

On 2016-02-15, Oleksandr Gavenko wrote:
> With text:


> I expect that TOC points to book.html#sec-xxx, but instead it refer to
> book.html#section-level-1:

The manually set anchor/target/id is always applied to the *following*
element. If you write::

.. contents:: 

.. _sec-xxx:

Section level 1
===============

.. _par-xxx:

This is a paragraph.


you will get a section heading that can be linked to with both names:


...
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#section-level-1" id="id1">Section level 1</a></li>
</ul>
</div>
<div class="section" id="section-level-1">
<span id="sec-xxx"></span><h1><a class="toc-backref" href="#id1">Section level 1</a></h1>
<p id="par-xxx">This is a paragraph.</p>
</div>
</div>
...


> I use Cyrillic RST texts and ``rst2html`` doesn't generate meaningful hashes
> as "section-level-1" is.

There is a TODO item to use a latin transliteration for non-ASCII
characters...


Günter

thank you Chris,
maybe I've found another solution;: I've installed a dokuwiki pluginm, that
let me export the entir Wiki, as a .pdf. So, with the regular Dokuwiki
formatting, I can have either the wiki and the pdf.
I've considered .rst just to be able to produce html and pdf from the same
source. Maybe this way could work

Renato

Il giorno mar 16 feb 2016 alle ore 11:57 Chris Green <cl...@is...> ha
scritto:

> On Tue, Feb 16, 2016 at 09:30:06AM +0000, Renato Pontefice wrote:
> >    Hi, I'm little bit confused...I thought that I can use the normal wiki
> >    function, and finaly export varrious page as .rst (then use the .rst
> to
> >    create .pdf or HTML by rst2pdf or rst2html macro).IT seems that it is
> >    not the way. I need to create a new link as a .rst page.
> >    Is this the way? Or do I made some mistake?
>
> You just create pages in the Wiki and access them as a Wiki, there's
> no explicit exporting involved the pages are generated dynamically by
> the Dokuwiki 'engine'.
>
> So, if it's an ordinary Dokuwiki syntax page the Dokuwiki engine
> converts it from Dokuwiki syntax to HTML for the web server to send.
> If it's some RST then the Dokuwiki engine passes it to my RST plugin
> which converts it to HTML for the web server.
>
> You can either embed RST in a normal Dokuwiki page using the <rst> and
> </rst> directives or you can create pages with .rst as a suffix and
> the whole page will be treated as RST.
>
> So my RST plugin just provides a way to write your wiki pages in a
> different mark-up language from the default Dokuwiki markup, they are
> still Wiki pages just liek the rest of your wiki.
>
>
> --
> Chris Green
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

On Tue, Feb 16, 2016 at 09:30:06AM +0000, Renato Pontefice wrote:
>    Hi, I'm little bit confused...I thought that I can use the normal wiki
>    function, and finaly export varrious page as .rst (then use the .rst to
>    create .pdf or HTML by rst2pdf or rst2html macro).IT seems that it is
>    not the way. I need to create a new link as a .rst page.
>    Is this the way? Or do I made some mistake?

You just create pages in the Wiki and access them as a Wiki, there's
no explicit exporting involved the pages are generated dynamically by
the Dokuwiki 'engine'.

So, if it's an ordinary Dokuwiki syntax page the Dokuwiki engine
converts it from Dokuwiki syntax to HTML for the web server to send.
If it's some RST then the Dokuwiki engine passes it to my RST plugin
which converts it to HTML for the web server.

You can either embed RST in a normal Dokuwiki page using the <rst> and
</rst> directives or you can create pages with .rst as a suffix and
the whole page will be treated as RST.

So my RST plugin just provides a way to write your wiki pages in a
different mark-up language from the default Dokuwiki markup, they are
still Wiki pages just liek the rest of your wiki.


-- 
Chris Green

Hi, I'm little bit confused...I thought that I can use the normal wiki
function, and finaly export varrious page as .rst (then use the .rst to
create .pdf or HTML by rst2pdf or rst2html macro).IT seems that it is not
the way. I need to create a new link as a .rst page.
Is this the way? Or do I made some mistake?

Renato

Il giorno lun 15 feb 2016 alle ore 11:39 Chris Green <cl...@is...> ha
scritto:

> On Mon, Feb 15, 2016 at 10:15:00AM +0000, Renato Pontefice wrote:
> >    where  do can I look for ocumentation?
> >    Renato
> >
> It's not very extensive (it's a very simple plugin), but it's here:-
>
>     https://www.dokuwiki.org/plugin:rst
>
>
> --
> Chris Green
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

With text:

  Section level 1
  ===============

  .. _sec-xxx:

  This is a paragraph.

I expect that TOC points to book.html#sec-xxx, but instead it refer to
book.html#section-level-1:

  <a class="reference internal" href="#section-level-1" id="id9">Section level 1</a>
   ...
  <a class="toc-backref" href="#id9">Section level 1</a>
  <p id="sec-xxx">This is a paragraph.</p>

I use Cyrillic RST texts and ``rst2html`` doesn't generate meaningful hashes
as "section-level-1" is.

Also for long running documents I would prefer to assign fixed links that
doesn't depends on changes in section title.

-- 
http://defun.work/

How can I highlight interactive REPL sessions? Like:

  bash# cd ~/sql
  bash# mysql
  Password:
  
  [mariadb]> select 1;

Among:

  http://pygments.org/docs/lexers/

I see possibility to use various:

  .. code:: bash
  .. code:: console
  .. code:: pycon
  .. code:: postgresql-console

but even with Bash it only highlight "$" sign and think my "bash#" prompt as
output...

I see a way to add to "code" additional parameter (prompt regex):

  http://docutils.sourceforge.net/docs/ref/rst/directives.html#code

and implement parser in pygments or make own directive:

  .. repl::
     :prompt1: "^bash# "
     :prompt2: "^$ "
     :prompt3: "^mysql> "

Does anyone work on this?

-- 
http://defun.work/

This:

  .. |fib| replace:: :math:`fib(n) = fib(n-1)+fib(n-2)`

works in:

  Substitution of mathematic formula: |fib|.

But this:

  .. |fib| math:: fib(n) = fib(n-1)+fib(n-2)

produced error:

  main.rst:211: (WARNING/2) Substitution definition "fib" empty or invalid.

  ..    |fib| math:: fib(n) = fib(n-1)+fib(n-2)

  main.rst:209: (ERROR/3) Undefined substitution referenced: "fib".

HTML output from rst2html have marked |fib| and formula shown only for
directive.

It that correct?

-- 
http://defun.work/

On 2016-02-13, Guenter Milde wrote:

>> Can arbitrary code be run during document generation?
>
>> Recently I see books/cources/sci reports like:
>
>>   https://github.com/bcaffo/courses
>
>> which uses "R Markdown":
>
>>   http://rmarkdown.rstudio.com/
>
>> So final document have result of running R language on pages.
>
>> I would like to run Bash example.
>
>> Or instead of afraid to make mistake place bc, octave-cli or R code and/or
>> values in resulted document in place.
>
> With standard docutils, you can use a Makefile to run/update examples that
> generate files to include in rST.
>
> There are contributed extensions/pre-processors/frameworks for some
> other input format inclusions.

Ok. I see:

  http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#code-execution

  It's too dangerous (or too complicated in the case of "eval"). We do not
  want to have such things in the core.

With include directive and build scripts that would be easy::

  http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

  $ python example.py >example.out

  .. include:: example.py
     :code: python

  .. include:: example.out
     :code: python

For placing example.py inside RST document and rendering both text and result
of run I think I should add support for custom directive.

-- 
http://defun.work/

So far, I am writing parts of my PhD thesis in ReST using Sphinx. It
works on a project basis rather than a per-file basis, and I find it has
good defaults for a lot of use cases (and a project configuration file
otherwise), a number of themes, and it should be pretty easy to enable
third-party Sphinx extensions. I think it should also be rather easy to
convert plain docutils extensions to Sphinx. I have written a number of
(unpublished) custom roles and directives myself; it's easy if you know
Python and once you get the hang of it.

Regarding high-quality printed output: you'll want to generate a PDF,
and it is my impression that most or all PDF generators from RST
generate input for LaTeX, and let LaTeX generate the PDF. LaTeX is
insanely versatile and configurable, but rather quirky as well if you do
want to configure it or if you hand-write LaTeX yourself. The standard
PDF output via Sphinx et al is easy to obtain, but you will encounter
problems if you go further than that. That said, there is a lot of help
available online on LaTeX. 

Cheers, Bram

On Sat, 13 Feb 2016, at 08:33 PM, Guenter Milde wrote:
> On 2016-02-13, Oleksandr Gavenko wrote:
> > I am a long running ReST fan-boy 
> ...
> 
> ... with a lot of questions.
> 
> Many of them can be answered by following the links in
> http://docutils.sourceforge.net/docs/user/links.html
> 
> ...
> 
> 
> > But I don't understand how to get high quality printed output?
> 
> > "For dummies" book series have a lot of outlined notes and fanny styling. How
> > that can be achieved? Do authors made own writer to Latex or Docbook and apply
> > publisher styling?
> 
> > How well supported modern reader formats? fb2, epub, mobi?
> 
> Not with standard docutils. There is an epub writer in Sphinx.
> 
> >================================================================
> 
> > I would like to include foreign formats. What sources is good example for
> > reference?
> 
> > What formats are already managed by ReST writers? lilypond (music notation),
> > graphviz (graph), gnuplot (graphing), ImageMagick/GraphicsMagick?
> 
> No other source format is managed by standard docutils. You can include
> images/graphics in a variety of vector and bitmap formats (see the docs).
> 
> Also, there are contributed extensions/pre-processors/frameworks for some
> other input format inclusions.
> 
> >================================================================
> 
> > Can arbitrary code be run during document generation?
> 
> > Recently I see books/cources/sci reports like:
> 
> >   https://github.com/bcaffo/courses
> 
> > which uses "R Markdown":
> 
> >   http://rmarkdown.rstudio.com/
> 
> > So final document have result of running R language on pages.
> 
> > I would like to run Bash example.
> 
> > Or instead of afraid to make mistake place bc, octave-cli or R code and/or
> > values in resulted document in place.
> 
> With standard docutils, you can use a Makefile to run/update examples
> that
> generate files to include in rST.
> 
> There are contributed extensions/pre-processors/frameworks for some
> other input format inclusions.
> 
> >================================================================
> 
> > Can literate programming be done in ReST?
> 
> There is a semi-literate framework:
> 
>   PyLit__ provides a bidirectional text <--> code converter for literate
>   programming with reStructuredText.
> 
>   __ http://repo.or.cz/pylit.git
> 
> >================================================================
> 
> > Can I introduce foreign syntax in place, like:
> 
> >   ... see :man:`open(1)` and :man:`read(1)` ...
> 
> This would require a definition of the role "man".
> 
> >   ... pythagorean theorem is :math:`a^2 + b^2 = c^2` ...
> 
> This works out of the box.
> 
> >   ... :lisp:`(defun (x) ((lambda (y) (* y y)) x))` is better then
> >       :java:`public static void main(String args[]) { }`
> 
> This would require a definition of custom roles
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
> (if you want syntax highlight, see 
> http://docutils.sourceforge.net/docs/ref/rst/roles.html#code
> ).
> 
> 
> 
> > What writer are useful? 
> 
> Depends on the use-case.
> 
> > I check shpinx docs and see that I capable produce HTML with built-in JS
> > search index for offline searching.
> 
> > Any other notable implementation?
> 
> Follow the links in http://docutils.sourceforge.net/docs/user/links.html
> 
> Günter
> 
> 
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

On Mon, Feb 15, 2016 at 10:15:00AM +0000, Renato Pontefice wrote:
>    where  do can I look for ocumentation?
>    Renato
> 
It's not very extensive (it's a very simple plugin), but it's here:- 

    https://www.dokuwiki.org/plugin:rst


-- 
Chris Green