docutils-users

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Omer S. <os...@gm...>]

Thanks Chris. So, is it safe to say that SPHINX uses DOCUTILS to convert
plain text files into reStructuredText (.rst) files?

Thanks

On Wed, Sep 23, 2020 at 7:06 AM <
doc...@li...> wrote:

> Send Docutils-users mailing list submissions to
>         doc...@li...
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.sourceforge.net/lists/listinfo/docutils-users
> or, via email, send a message with subject or body 'help' to
>         doc...@li...
>
> You can reach the person managing the list at
>         doc...@li...
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Docutils-users digest..."
> Today's Topics:
>
>    1. Is reStructuredText required for conversion to HTML (Omer Shommo)
>    2. Re: Is reStructuredText required for conversion to HTML
>       (Guenter Milde)
>    3. Re: Is reStructuredText required for conversion to HTML
>       (chris sewell)
>
>
>
> ---------- Forwarded message ----------
> From: Omer Shommo <os...@gm...>
> To: docutils-users <doc...@li...>
> Cc:
> Bcc:
> Date: Tue, 22 Sep 2020 22:02:05 -0500
> Subject: [Docutils-users] Is reStructuredText required for conversion to
> HTML
> Hello Everybody,
>
> I am new to docutils. I need to know if Docutils need source files to be
> in reStructuredText format before converting them to HTML, LaTeX,
> man-pages, open-document or XML
>
> Thanks
>
>
>
> ---------- Forwarded message ----------
> From: Guenter Milde <mi...@us...>
> To: doc...@li...
> Cc:
> Bcc:
> Date: Wed, 23 Sep 2020 06:36:18 -0000 (UTC)
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> On 2020-09-23, Omer Shommo wrote:
>
> > Hello Everybody,
>
> > I am new to docutils. I need to know if Docutils need source files to be
> in
> > reStructuredText format before converting them to HTML, LaTeX, man-pages,
> > open-document or XML
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
>
>
>
> ---------- Forwarded message ----------
> From: chris sewell <chr...@ho...>
> To: Guenter Milde <mi...@us...>
> Cc: "doc...@li..." <
> doc...@li...>
> Bcc:
> Date: Wed, 23 Sep 2020 06:54:35 +0000
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx, but
> the base renderer is purely docutils.
> It also underpins https://myst-nb.readthedocs.io
> <https://myst-nb.readthedocs.io/en/latest/> and http://jupyterbook.org,
> to render Jupyter notebooks to docutils AST
>
> Kind Regards,
> Chris
>
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users <
> doc...@li...> wrote:
>
> On 2020-09-23, Omer Shommo wrote:
>
> Hello Everybody,
>
>
> I am new to docutils. I need to know if Docutils need source files to be in
>
> reStructuredText format before converting them to HTML, LaTeX, man-pages,
>
> open-document or XML
>
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Marc R. <ma...@ri...>]

On 23.09.20 23:31, Omer Shommo wrote:
> […] So, is it safe to say that SPHINX uses DOCUTILS to convert 
> plain text files into reStructuredText (.rst) files?

No, not at all.  Docutils converts reStructuredText into different 
output formats like HTML and LaTeX (which in turn can be converted to 
PDF).  Sphinx extends Docutils by some roles and directives and 
generates things like index pages.

Sphinx/Docutils doesn't convert *into* reStructuredText but *from* 
reStructuredText.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“A designer knows he has achieved perfection not when there is
  nothing left to add, but when there is nothing left to take away.”
   -- Antoine de Saint-Exupéry

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Chris S. <chr...@ho...>]

Indeed, the Docutils maintainers may be able to offer a better explanation, but IMO there are a few distinct aspects of Docutils to bare in mind:

- The Docutils Abstract Syntax Tree (AST, aka doctree): this is the structure that holds the document in an input/output agnostic format.
   It has (in principal) nothing to do with the input format reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc
-  The input parser, which converts a (text) file to the AST, of which is the reStructuredText parser is the primary example.
    MyST does the same for Markdown, and also “shares" reStructuredText’s  role/directive syntax extension system
- The output renderer, which converts the AST to the output format

What sphinx does is, in essence, extend the Docutils render process to better deal with multiple, inter-connected, documents (e.g.  a full website/book). For example, adding cross-document referencing and AST caching.

> On 24 Sep 2020, at 01:29, Marc Rintsch <ma...@ri...> wrote:
> 
> On 23.09.20 23:31, Omer Shommo wrote:
>> […] So, is it safe to say that SPHINX uses DOCUTILS to convert plain text files into reStructuredText (.rst) files?
> 
> No, not at all.  Docutils converts reStructuredText into different output formats like HTML and LaTeX (which in turn can be converted to PDF).  Sphinx extends Docutils by some roles and directives and generates things like index pages.
> 
> Sphinx/Docutils doesn't convert *into* reStructuredText but *from* reStructuredText.
> 
> Ciao,
> 	Marc 'BlackJack' Rintsch
> -- 
> “A designer knows he has achieved perfection not when there is
> nothing left to add, but when there is nothing left to take away.”
>  -- Antoine de Saint-Exupéry
> 
> 
> _______________________________________________
> 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] Docutils-users Digest, Vol 143, Issue 1

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

On 2020-09-24, Chris Sewell wrote:

> Indeed, the Docutils maintainers may be able to offer a better
> explanation, but IMO there are a few distinct aspects of Docutils to
> bare in mind:

> - The Docutils Abstract Syntax Tree (AST, aka doctree): this is the
>   structure that holds the document in an input/output agnostic format.
>   It has (in principal) nothing to do with the input format
>   reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc

The specification https://www.python.org/dev/peps/pep-0258/#document-tree
describes the `Document Tree` as a data structure is similar to a DOM tree,
but with specific node names (classes) instead of DOM's generic nodes.
The schema is documented in an XML DTD (eXtensible Markup Language
Document Type Definition) docutils.dtd__

__ http://docutils.sourceforge.net/docs/ref/docutils.dtd

> - The input parser, which converts a (text) file to the AST, of which
>   is the reStructuredText parser is the primary example. MyST does the
>   same for Markdown, and also “shares" reStructuredText’s
>   role/directive syntax extension system

Actually, the `parser` parses an input string presented to it by the
`reader` (it may come from file or other sources).

> - The output renderer, which converts the AST to the output format

In Docutils, this component is called a `writer`.

> What sphinx does is, in essence, extend the Docutils render process to
> better deal with multiple, inter-connected, documents (e.g.  a full
> website/book). For example, adding cross-document referencing and AST
> caching.

Spinx also provides a framework for several extensions, including 
at least two Markdown parsers (recommonmark and myst-parser).

These parsers should in principle also work with core Docutils. However,
I don't know of any implementation or documentation for this combination.

It would be a nice advancement, to have frontends similar to rst2...
that work with markdown input.

Another idea would be to add a ``:format:`` option to the "include"
directive that allows things like::

  .. include:: README.md
     :format: markdown
     
This could be an optional feature depending on an external markdown
parser that can be imported from Docutils. (Somewhat similar to
syntax-highlight with Pygments or some HTML-Math-Output options.)


Yet another idea is a Docutils-XML parser that would parse the native
Docutils XML format - allowing to store parsed documents as XML and
offers a gateway to the XML world (e.g. converting any input to Docutils
XML via XSLT).


Günter