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

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

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.