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

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

I am a long running ReST fan-boy and uses markup mostly for managing personal tips:

  http://tips.defun.work/frame.html

and uses this notes mostly in text editor as remainder. But also publish them
online for personal advertising.

Also I use rst for personal projects man pages and documentation, for example:

  http://2048.defun.work/HACKING.html

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

I checked specs of many plain text markup syntax and found that extensibility
presents only in ReST.

Most markups even can't handle TOCs or have scary syntax (like mediawiki) and
made without analysis:

  http://docutils.sourceforge.net/docs/dev/rst/alternatives.html
  http://docutils.sourceforge.net/docs/dev/rst/problems.html

expect resent efforts for CommonMark:

  http://spec.commonmark.org/

But CommonMark directly focused only on HTML output and any time you want
something special your should use HTML, like:

  <hr>

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

My usage of ReST doesn't go far then styling python-docutils HTML output or
generating man pages.

I am interested in publishing.

Previously I take lessons directly from reading SVN source of
https://github.com/jacobian-archive/djangobook.com

Currently I see effort:

  https://github.com/mariuz/django-book
  http://django-book.readthedocs.org/en/latest/

This looks great in 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?

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

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?

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

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.

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

Can literate programming be done in ReST?

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

Can I introduce foreign syntax in place, like:

  ... see :man:`open(1)` and :man:`read(1)` ...

  ... pythagorean theorem is :math:`a^2 + b^2 = c^2` ...

  ... :lisp:`(defun (x) ((lambda (y) (* y y)) x))` is better then
      :java:`public static void main(String args[]) { }`

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

Can I define foreign expression elsewhere and put via reference in place?

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

What writer are useful? 

I check shpinx docs and see that I capable produce HTML with built-in JS
search index for offline searching.

Any other notable implementation?

-- 
http://defun.work/