docutils-users

[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/

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

[TP <wi...@gm...>]

Well that was an amazingly rambling post that I won't even bother to
quote, but will randomly answer :P

http://asciidoc.org/

http://asciidoctor.org/

https://atlas.oreilly.com/

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

[Peter F. <pf...@ar...>]

TP wrote on Fri 12.02.2016 at 20:25:
> Well that was an amazingly rambling post that I won't even bother to
> quote, but will randomly answer :P
> 
> http://asciidoc.org/
> 
> http://asciidoctor.org/
> 
> https://atlas.oreilly.com/

Hmmm... 
Personally I like the reStructuredText markup better than AsciiDoc.

Especially in longer documents the section heading markup of AsciiDoc
looks too subtle compared to that of reStructuredText.

But this is a matter of taste and of personal preference and needs
not to be discussed here further.

Regards, Peter Funk
-- 
Peter Funk, home: ✉Oldenburger Str.86, D-27777 Ganderkesee
mobile:+49-179-640-8878 phone:+49-421-20419-0 <http://www.artcom-gmbh.de/>
office: ArtCom GmbH, ✉Haferwende 2, D-28357 Bremen, Germany

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

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.

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

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

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/

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

[Matthias G. <mat...@gm...>]

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.