Re: [Docutils-users] reStructuredText for notes, blogs, scientific articles and programming documentation?

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

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