docutils-users — General discussions, questions, help requests.

[Docutils-users] --link-stylesheet path not relative to working directory

[Alan G. I. <ala...@gm...>]

If I try to link to the stylesheet instead of embedding it
(in rst2html5) I get a path that is not relative to the
working directory. Instead it backs up to the root and
works it's way down. (But that's terrible, since the
target computer naturally has a different folder
structure.)

1. Is this expected?

2. Possibly relevant (?): I invoke a particular Python
by using it's full path.

Thanks, Alan Isaac

[Docutils-users] purpose of brackets class?

[Alan G. I. <ala...@gm...>]

Low priority inquiry: in the HTML writer,
why does an ``aside`` for a footnote have a ``brackets`` class?
Wdt it make more sense to add this to the span.label and the
use CSS to provide the actual brackets?

Thanks,
Alan Isaac

[Docutils-users] reference role?

[Alan G. I. <ala...@gm...>]

Would it make sense to add ``reference`` to the standard roles?

Motivating example: I would like to produce a ``figure-ref`` role
to link to figures with a ``name`` class; I imagine
that this would subclass reference but would be styled differently.
For example, for an HTML writer, as ``target-counter()`` becomes available,
it would make use of the counter.

Related aside: the ``rst2latex`` writer needs to move the figure label
to *after* the caption, otherwise ``--reference-label=ref``
does not work correctly (i.e., does not produce the figure number).

Alan Isaac

Re: [Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

The release notes at
https://docutils.sourceforge.io/HISTORY.html#release-0-17-2021-04-03
explain  the use of text level tags by making reference to
inline elements. This misled to me to think that this applied to
the list of inline elements at
https://docutils.sourceforge.io/docs/ref/doctree.html#inline-elements
Instead, follow the examples at
https://docutils.sourceforge.io/test/functional/input/data/html5-text-level-tags.txt

This post is for other users.
Thanks to Günter for helping me understand.

fyi, Alan Isaac

Re: [Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

This sounds great.  Here is how I understand this:
if I update from Subversion and install the latest revision (8786)
that I should be able to use my custom `dfn(emphasis)` role and see a `dfn`
element if I use the rst2html5.py script (which, iiuc, uses the
rst2html5_polyglot writer).

However, I still see an `em` element with a `dfn` class.
Have I misunderstood? I'm looking at
https://docutils.sourceforge.io/HISTORY.html#release-0-17-2021-04-03

Thanks, Alan Isaac



On 7/3/2021 5:30 AM, Guenter Milde via Docutils-users wrote:
> This goal is already easy to achieve since version:
> 
>    - Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
>      <i>, <b>, <u>, <mark>, and <bdi> if a matching class value
>      is found in `inline` and `literal` elements.
>      Use <ins> and <del> if a matching class value
>      is found in `inline`, `literal`, or `container` elements.
>      Use <small> for generated code line numbers.
> 
>    -- HISTORY.txt

Re: [Docutils-users] dfn role? (enhancement)

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

On 2021-07-02, Alan G. Isaac wrote:
> Might docutils consider adding the `dfn` role? (It is already in Sphinx.)
> For an HTML writer, this would become a `dfn` element.

> Goal: add this semantic content to HTML output.

This goal is already easy to achieve since version:

  - Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
    <i>, <b>, <u>, <mark>, and <bdi> if a matching class value
    is found in `inline` and `literal` elements.
    Use <ins> and <del> if a matching class value
    is found in `inline`, `literal`, or `container` elements.
    Use <small> for generated code line numbers.

  -- HISTORY.txt

For an example see the output of

  docutils/test/functional/input/data/html5-text-level-tags.txt
  
in test/functional/expected/standalone_rst2html5.html


I don't think it makes much sense to provide these output-format specific
roles as default roles. I did consider an rST include-file in
"docutils/parsers/rst/include/":

  Standard data files intended for inclusion in reStructuredText
  documents are distributed with the Docutils source code, located in
  the "docutils" package in the ``docutils/parsers/rst/include``
  directory.  To access these files, use the special syntax for standard
  "include" data files, angle brackets around the file name::
  
      .. include:: <isonum.txt>

  -- directives.txt


Günter

[Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

Might docutils consider adding the `dfn` role? (It is already in Sphinx.)
For an HTML writer, this would become a `dfn` element.

Goal: add this semantic content to HTML output.

Thanks for considering,
Alan Isaac

Re: [Docutils-users] closing a header block

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

Dear Sidney,

On 2021-05-27, Sidney Cadot wrote:

>> This is not only impossible (with standard rST syntax), it is also an
>> invalid Doctils document tree.
>> https://docutils.sourceforge.io/docs/ref/docutils.dtd
>> https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy

> Ok, that settles it. The restriction seems strange and somewhat arbitrary
> to my programmer's eye, but it is there alright.

With more input and searching in the Docutils sources, I have to correct
myself on both accounts. Details below.

> > >> Second, if not: is there a fundamental reason why the second
> > >> parse-tree would be incompatible with the document model of RsT?
> > >> (If that's the case, why?)

While your second example would be an invalid Docutils document, there
is no need to have a valid document tree before the parsing and
transformations are completed.

In other words, a transient document tree state like

    <document source="/tmp/simple.rst">
        <section ids="first-section" names="first\ section">
            <title>First section</title>
            <paragraph>First lorem ipsum</paragraph>
        </section>
     ← place next element here!

is not invalid per se. it depends on what would be the next element:

* if the next element is <section level="1"> or <section level="2">, fine.
  
* if the next element is *not* a <section> or a <section> with incompatible
  level (outside 1, ..., level_of_the_closed_section + 1), the final
  document tree is invalid.

> > >> Third, if it is possible in principle, but not yet in practice, is
> > >> there a way to implement this without touching the parser; say, by
> > >> adding a docutils Directive?

This should be possible -- directives can do "anything" that is possible in
Python:

As a new section can close the preceding section, there must be a way to
do this programatically. The solution is described in the docstring for
docutils.parser.rst.states.check_subsection():
   
     Check for a valid subsection header.  Return 1 (true) or None (false).

     When a new section is reached that isn't a subsection of the current
     section, back up the line count (use ``previous_line(-x)``), then
     ``raise EOFError``.  The current StateMachine will finish, then the
     calling StateMachine can re-examine the title.  This will work its way
     back up the calling chain until the correct section level isreached.

     @@@ Alternative: Evaluate the title, store the title info & level, and
     back up the chain until that level is reached.  Store in memo? Or
     return in results?

     :Exception: `EOFError` when a sibling or supersection encountered.

It should be possible to "close" a section by a directive raising
`EOFError` and the following rST examples would generate valid documents::


   A section
   ---------
   
   .. close-section::
   
   Another section
   ---------------
   
as well as ::   

   A section
   ---------

   .. close-section::
   
   .. directive-that-generates-a-section-with-compatible-level::
   
OTOH, such a directive will certainly not become part of the Docutils,
because input like ::

   A section
   ---------
   
   Section content

   .. close-section::

   Anything other than the preceding examples.
   
would generate an invalid document.


Therfore, my suggestion would be to incorporate the closing into the 
"directive-that-generates-a-section-with-compatible-level", e.g. so that you
may write, e.g, ::

   A section
   ---------
   
   A subsection
   ~~~~~~~~~~~~

   Subsection content.
   
   .. directive-that-generates-a-section-with-compatible-level::
   
      :section-level: 1

   
Caveats:
  * This is not part of the API but an implementation detail that may
    change in future.
  * I did not test.
  * I don't know about side-effects.



> A similar request was filed to the issue tracker.
>> https://sourceforge.net/p/docutils/feature-requests/74
>> It turned out to be about an intermediate structure (adding sections by a
>> directive). In this case, the resulting doctree would be valid but telling
>> the section-adding-directive where to add these sections seems a better
>> solution than changing rST syntax or adding a section-closing directive in
>> Docutils.


> Yes, that seems very much related to what I was thinking about.

> As it turns out handling this stuff fully at the sphinx level has its own
> set of challenges. Especially the toctree stuff and how it interacts with
> the section headers seems quite badly designed I am sorry to say, to the
> point that the general recommendation seems to be: don't use them in the
> same document -- which is annoying (and hard to defend from a usability
> perspective). I had hoped that some alternative solution with help from the
> docutils level could be useful; but I guess this will need to be fully
> fixed at the sphinx level after all.

I am not familiar with the toctree and Sphinx extensions, so I cannot
recommend here besides the general adwise to balance the gain in usability
with added complexity.

I hope this helps a bit,

Günter

Re: [Docutils-users] Converting a pygments CSS stylesheet to latex

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

On 2021-06-16, Jorge Scandaliaris wrote:

> Hi,
> I am writing some documents in ReStructuredText which include source code
> and I want the end result to be in PDF, so I used rst2latex to generate the
> .tex files. I wanted to experiment with different stylesheets so I tried to
> convert pygments CSS stylesheets to LaTeX using the pygments_css2sty.py
> script.

Is this script provided by Pygments or from the Docutils sandbox?
https://docutils.sourceforge.io/sandbox/stylesheets/pygments_css2sty.py

> I post here because my initial attempt failed with an error message from
> the script. After troubleshooting a bit, I found that the first part of the
> CSS generated by pygmentize seemed different to the rest. I tried removing
> that part and the script worked fine. I guess the output from pygmentize
> might have changed recently.

There were several changes to Pygments since the last update of the
Docutils sandbox script 2013-03-27, indeed.

> What I did was:
> pygmentize -f html -S colorful >pygments-colorful.css
> and the part I had to remove from the top was something like:

> pre { line-height: 125%; }
> td.linenos .normal { color: inherit; background-color: transparent;
> padding-left: 5px; padding-right: 5px; }
> span.linenos { color: inherit; background-color: transparent; padding-left:
> 5px; padding-right: 5px; }
> td.linenos .special { color: #000000; background-color: #ffffc0;
> padding-left: 5px; padding-right: 5px; }
> span.linenos.special { color: #000000; background-color: #ffffc0;
> padding-left: 5px; padding-right: 5px; }

On my Debian/stable system, with Pygments version 2.3.1, the output of
`pygmentize -f html -S colorful` does not contain these lines this further
indicates that there was a "recent" addition.

> Maybe the script has to be adapted to filter out this portion, or to
> generate the correct output from it? I am quite ignorant in CSS and html,
> so I can't really tell what's doing.

Volunteers/patches welcome.


Thank you for reporting,
Günter

[Docutils-users] Converting a pygments CSS stylesheet to latex

[Jorge S. <jsc...@gm...>]

Hi,
I am writing some documents in ReStructuredText which include source code
and I want the end result to be in PDF, so I used rst2latex to generate the
.tex files. I wanted to experiment with different stylesheets so I tried to
convert pygments CSS stylesheets to LaTeX using the pygments_css2sty.py
script.
I post here because my initial attempt failed with an error message from
the script. After troubleshooting a bit, I found that the first part of the
CSS generated by pygmentize seemed different to the rest. I tried removing
that part and the script worked fine. I guess the output from pygmentize
might have changed recently.
What I did was:
pygmentize -f html -S colorful >pygments-colorful.css
and the part I had to remove from the top was something like:

pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent;
padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left:
5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0;
padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0;
padding-left: 5px; padding-right: 5px; }

Maybe the script has to be adapted to filter out this portion, or to
generate the correct output from it? I am quite ignorant in CSS and html,
so I can't really tell what's doing.
Regards,

Jorge Scandaliaris

Re: [Docutils-users] epigraph reacts to comments in rst2html5

[Alan G. I. <ala...@gm...>]

> On 2021-06-01, Alan G. Isaac wrote:
>> Adding a comment within an epigraph directive produces
>> an extra (empty) blockquote element in the output.  E.g.,

> 


On 6/3/2021 9:48 AM, Guenter Milde via Docutils-users wrote:
> I am not surprised:
>    The attribution only closes the block-quote, not the
>    directive


Got it. Thanks.
Alan Isaac

Re: [Docutils-users] epigraph reacts to comments in rst2html5

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

On 2021-06-01, Alan G. Isaac wrote:
> Adding a comment within an epigraph directive produces
> an extra (empty) blockquote element in the output.  E.g.,

> .. epigraph::

>     An epigraph.

>     -- A.U. Thor

>     .. a comment

I am not surprised:

* The “epigraph” directive produces an “epigraph”-class block quote.

  -- docutils/docs/ref/rst/directives.html#epigraph

* Multiple block quotes may occur consecutively if terminated with
  attributions.

  -- docutils/docs/ref/rst/directives.html#epigraph

* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive.
  
* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive::
  
   .. epigraph::
  
       An epigraph.
  
       -- S. Ource
  
       Another epigraph

* Comments may replace text blocks in syntax constructs::

     This is a paragraph
     
        .. this is a comment in a block-quote

  See the pseudo-xml output of this example.

* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive.
  
I agree that other outcomes may be equally feasible but I cannot see a clear
winner in any other handling of the given input example.

If you really want a block quote after the attribution without the
"epigraph" class, the two input alternatives give the same result
(except for the different place of the empty comment)::


.. epigraph::

  a block quote
  
  -- by someone
  
..

  the next block-quote: no epigraph

.. class:: epigraph

..
  
  a block quote
  
  -- by someone
  
  the next block-quote: no longer epigraph


Günter

[Docutils-users] epigraph reacts to comments in rst2html5

[Alan G. I. <ai...@am...>]

Adding a comment within an epigraph directive produces
an extra (empty) blockquote element in the output.  E.g.,

.. epigraph::

    An epigraph.

    -- A.U. Thor

    .. a comment

fwiw, Alan Isaac

Re: [Docutils-users] rst2html5 title demotion?

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

Dear Alan,

On 2021-05-25, Alan G. Isaac wrote:
> On 5/25/2021 9:25 AM, Guenter Milde via Docutils-users wrote:

> ... here is an example of what broke.
> I have documents (call them chapters), where the
> top level section header is the chapter title.
> Each of these has a single top-level header.
> These format perfectly, individually.

> Sometimes I combine these into a single document.
> Under the new defaults, since there are multiple
> top-level sections, the combined document does not
> maintain the desired formatting.

I can reproduce. In the output of the combined file, section headings
look different from the output of the chapter files. However, this is
consistent for "html4", "html5", "latex", and "odf" and reflects the missing
document title in the combined document.

Setting the "initial-header-level" to 1 is a possible workaround in this
use-case.  However, it leads to bad formatting (with the browser default
styling for headings) when the combined document has a title::

  Collection of recent unpublished work
  *************************************

  .. include:: text1.txt
  .. include:: text2.txt


> I understand the point you made about the double use of
> the h1 element in previous writers. However, I
> always understood (misunderstood?) this as an
> effort to provide access to a document-level title
> while still providing access to *all* of the header
> elements within a document. This seemed useful, since
> some documents have many levels. 

"Saving" elements for use with lower-level headings may have been
sensible with HTML4.1 but is no longer necessary with HTML5 and
<section> elements: here we have the possibility of infinite nesting and
can also use the ARIA "role" element to set a heading level.


> Nevertheless, I typically turned it off with the `--no-doc-title`
> option.

This results in documents without title also for the stand-alone chapters.
A missing document title may be OK for home-use but is generally not
recommended for published work. How would you cite the combined document?

This is, IMV, also the reason behind the obsolete search engine optimization
(SEO) rule "HTML documents must have exactly one <h1> element":   
One <h1> can be extracted as document title, more than one <h1> is
ambiguous (just as multiple top-level headings in rST source).

HTML5's outline algorithm allows to determine a document title also when
several <h1> elements are used, but this depends on document structure and
is not guaranteed to work for any document (see below).

> Finally, to your core concern: sectioning.

> My preferred solution would allow multiple h1 elements
> *outside* of section elements, thus conforming to the idea that
> header depth should conform to section depth.

> Note that the standard has the concept of implicit sections,
> but `body` is also considered an explicit section.
> (That's my non-expert understanding.)
> The explicit body section can contain multiple h1 elements.

I share this understanding -- this would not violate the standard. However,
it would not align header rank to section depth: the <h1> elements start
implicit sub-sections (level 2). There is no heading in level 1 (i.e. no
document title).
 

> I see that there is some debate about whether a document *should*
> contain multiple h1 elements, but there does not seem to be any debate
> that a document *should not* skip levels. Demotion of the top
> level header to h2 therefore seems to me to be clearly forbidden
> while multiple h1 elements does not.

IMV, both are instances of a titleless document, valid but not ideal. 
Cf. the statement cited in
https://www.impactplus.com/blog/multiple-h1-headlines-okay: 

    it makes no difference to Google whether you use no H1 tags or 100.
    
See also the usage notes in
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements 


* Both cases are valid HTML documents (in HTML4 as well as in HTML5).
  
  If sections without heading work best for a special use case, fine.

* It is recommended not to skip levels and to have a heading in each section
  level.
  
  - With explicit sections, you cannot skip section levels but you can have
    sections without heading.

  - With implicit sections, you cannot have a section without heading but
    you can skip levels.
    (In HTML5, the <body> element is considered an explicit section
    and thus can be without heading).
    
  To handle the "hole" at level 1, you can either skip <h1> elements and
  keep heading rank and outline level in sync, or you can use <h1> for
  outline level 2 (top sections) and <h:math:`(n-1)`> for outline level
  math:`n`.  The "initial-header-level" setting allows to configure which
  "coping strategy" is used. The best fix is to provide a document title in
  the source.  

As Docutils is already generating explicit sections when converting the rST
source to a document tree, I prefer to follow the tip
in https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections

  Authors are also encouraged to explicitly wrap sections in elements of
  sectioning content, instead of relying on the implicit sections generated
  by having multiple headings in one element of sectioning content.

and keep the current default behaviour.

Viele Grüße,
Günter

Re: [Docutils-users] MathJax3 question

[Lilian C. <lib...@gm...>]

Yup pretty smart guy

Enviado desde mi Tablet Samsung.
Get Outlook para Android<https://aka.ms/AAb9ysg>

________________________________
From: Guenter Milde via Docutils-users <doc...@li...>
Sent: Monday, May 31, 2021 1:43:43 PM
To: doc...@li... <doc...@li...>
Subject: Re: [Docutils-users] MathJax3 question

On 2021-05-29, Alan G. Isaac wrote:
> I'm starting to try out MathJax3 with the rst2html5 option
>      --math-output="MathJax https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
> as suggested here:
>      https://docutils.sourceforge.io/docs/user/config.html#math-output

> However, the resulting HTML file does not include the polyfill recommended here:
>      https://www.mathjax.org/#gettingstarted

> Looking at http://docs.mathjax.org/en/latest/output/browser.html leads me to believe
> that MathJax3 is currently using ES5 and that the polyfill is only needed for
> outdated browsers. And in fact, I am seeing ZERO problems.
> So I suppose that leaving out the polyfill is a browser-support decision.

> I am NOT worried about old browsers.
> I would just like to confirm my understanding.

The idea is to keep things simple in our interface and documentation while
giving helpful links so that the interested user can easily find the full
documentation (in this case about MathJaX).

Since the latest improvements in MathML output, there may be even less need to
introduce additional dependencies and JavaScript.

Günter



_______________________________________________
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] MathJax3 question

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

On 2021-05-29, Alan G. Isaac wrote:
> I'm starting to try out MathJax3 with the rst2html5 option
>      --math-output="MathJax https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
> as suggested here:
>      https://docutils.sourceforge.io/docs/user/config.html#math-output

> However, the resulting HTML file does not include the polyfill recommended here:
>      https://www.mathjax.org/#gettingstarted

> Looking at http://docs.mathjax.org/en/latest/output/browser.html leads me to believe
> that MathJax3 is currently using ES5 and that the polyfill is only needed for
> outdated browsers. And in fact, I am seeing ZERO problems.
> So I suppose that leaving out the polyfill is a browser-support decision.

> I am NOT worried about old browsers.
> I would just like to confirm my understanding.

The idea is to keep things simple in our interface and documentation while
giving helpful links so that the interested user can easily find the full
documentation (in this case about MathJaX).

Since the latest improvements in MathML output, there may be even less need to
introduce additional dependencies and JavaScript.

Günter

Re: [Docutils-users] rst2html5 containers

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

On 2021-05-29, Alan G. Isaac wrote:
> Unlike other directives, container directives still add
> a `docutils` class (in rst2html5). Is this intentional?

Yes, this was kept following a bug report because "container" is a very
generic term that is also used in other CSS frameworks and can lead to
wrong formatting.

Günter

Re: [Docutils-users] footnotes for rst2html5

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

On 2021-05-30, Alan G. Isaac wrote:
> The rst2html5 writer follows the old treatment of writing HTML footnotes,
> but iiuc modern usage favors the use of an `aside` element (with ongoing
> discussion of adding `note` and `noteref` elements).

> Could the rst2html writer possibly move to the use of `aside`?

> Background discussions:

> - https://www.davidmacd.com/blog/html51-footnotes.html
> - http://kb.daisy.org/publishing/docs/html/notes.html

There is already a "future changes" entry in the RELEASE-NOTES (required
as advance-warning because this is a change to the API with a chance to
break existing applications (Sphinx uses "html5" as default HTML writer
and there are many custom stylesheets out "in the wild).

However, the jury is still out, whether footnotes are an "aside"¹ or more
closely related to the main text. IMV, ``role="note"``² is a better fit.

Günter

¹ The aside element represents a section of a page that consists of
  content that is tangentially related to the content of the parenting
  sectioning content, and which could be considered separate from that
  content. https://www.w3.org/TR/html52/sections.html#the-aside-element

² (note (role): A section whose content is parenthetic or ancillary to
  the main content of the resource.
  https://www.w3.org/TR/wai-aria-1.1/#note

[Docutils-users] footnotes for rst2html5

[Alan G. I. <ala...@gm...>]

The rst2html5 writer follows the old treatment of writing HTML footnotes,
but iiuc modern usage favors the use of an `aside` element (with ongoing
discussion of adding `note` and `noteref` elements).

Could the rst2html writer possibly move to the use of `aside`?

Background discussions:

- https://www.davidmacd.com/blog/html51-footnotes.html
- http://kb.daisy.org/publishing/docs/html/notes.html

Cheers,
Alan Isaac

[Docutils-users] rst2html5 containers

[Alan G. I. <ai...@am...>]

Unlike other directives, container directives still add
a `docutils` class (in rst2html5). Is this intentional?

Cheers, Alan Isaac

[Docutils-users] MathJax3 question

[Alan G. I. <ala...@gm...>]

I'm starting to try out MathJax3 with the rst2html5 option
     --math-output="MathJax https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
as suggested here:
     https://docutils.sourceforge.io/docs/user/config.html#math-output

However, the resulting HTML file does not include the polyfill recommended here:
     https://www.mathjax.org/#gettingstarted

Looking at http://docs.mathjax.org/en/latest/output/browser.html leads me to believe
that MathJax3 is currently using ES5 and that the polyfill is only needed for
outdated browsers. And in fact, I am seeing ZERO problems.
So I suppose that leaving out the polyfill is a browser-support decision.

I am NOT worried about old browsers.
I would just like to confirm my understanding.

Thank you, Alan Isaac

Re: [Docutils-users] closing a header block

[Sidney C. <si...@ji...>]

Hi Guenter,

This is not only impossible (with standard rST syntax), it is also an
> invalid Doctils document tree.
> https://docutils.sourceforge.io/docs/ref/docutils.dtd
> https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy


Ok, that settles it. The restriction seems strange and somewhat arbitrary
to my programmer's eye, but it is there alright.

A similar request was filed to the issue tracker.
> https://sourceforge.net/p/docutils/feature-requests/74
> It turned out to be about an intermediate structure (adding sections by a
> directive). In this case, the resulting doctree would be valid but telling
> the section-adding-directive where to add these sections seems a better
> solution than changing rST syntax or adding a section-closing directive in
> Docutils.
>

Yes, that seems very much related to what I was thinking about.

As it turns out handling this stuff fully at the sphinx level has its own
set of challenges. Especially the toctree stuff and how it interacts with
the section headers seems quite badly designed I am sorry to say, to the
point that the general recommendation seems to be: don't use them in the
same document -- which is annoying (and hard to defend from a usability
perspective). I had hoped that some alternative solution with help from the
docutils level could be useful; but I guess this will need to be fully
fixed at the sphinx level after all.

Thanks,
  Sidney

Re: [Docutils-users] closing a header block

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

On 2021-05-26, Sidney Cadot wrote:

> I am using docutils through Sphinx, and I am running into an issue there,
> which I think should best be solved in the RsT parsing stage.

...

> ... if I want to "pop" a heading level to the next higher (or any
> higher) level without introducing a new header, I am stuck.

...

> So I want my parse tree to be (again in pseudo-xml):

> *<section level="1">*
> *    <p>First lorem ipsum etc. etc.</p>*
> *    <section level="2">*
> *        <p>Second lorem ipsum etc. etc.</p>*
> *    </section>*
> *    <p>Alea iacta est!</p>*
> *</section>*

> I have a few questions....

> First, is this already somehow possible? Is there some syntax that directs
> the parser to produce the second parse tree?

This is not only impossible (with standard rST syntax), it is also an
invalid Doctils document tree.
https://docutils.sourceforge.io/docs/ref/docutils.dtd
https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy

> Second, if not: is there a fundamental reason why the second parse-tree
> would be incompatible with the document model of RsT? (If that's the case,
> why?)

See the link below.

> Third, if it is possible in principle, but not yet in practice, is there a
> way to implement this without touching the parser; say, by adding a
> docutils Directive? E.g. something that would work like this?

A similar request was filed to the issue tracker. 
https://sourceforge.net/p/docutils/feature-requests/74
It turned out to be about an intermediate structure (adding sections by a
directive). In this case, the resulting doctree would be valid but telling
the section-adding-directive where to add these sections seems a better
solution than changing rST syntax or adding a section-closing directive in
Docutils.

Günter

Re: [Docutils-users] closing a header block

[Sidney C. <si...@ji...>]

Hi David,

> Why do this? What is the purpose?
> What would this "popped" section mean? What does it represent?

It is a continuation of a previous section that was interrupted by a
subsection.

This is not something that is usually encountered in rendered text (if at
all).

The reason it would be useful is that it allows tree transform operations
to have a better understanding of the structure of a document, and to adopt
their behavior on the "level" they reside at. The specific use-case for me
is the toctree directive in sphinx. It is not strange to have it as the
last directive on an RsT page:

Main heading
==========

Bla bla

Subheading
=========

Bla bla

Subsubheading
===========

Bla bla bla

.. toctree::


In this example, the toctree directive is processed at to lowest-level
subtree level in the parse tree:

<sec main><sec sub><sec subsub>TOCTREE</sec></sec></sec>

Whereas I would want to be able to achieve this:

<sec main><sec sub><sec subsub></sec></sec>TOCTREE</sec>

SoI want the toctree directive to be executed at a level of my choosing,
rather than at the level induced by its incidental place after an unknown
number of sub-heading levels.

There is a quite a bit of discussion about this on the sphinx side; the
current recommended practice is to either have subheadings in a page; or a
toctree; but not both. Which, frankly, is silly.

People are trying to solve this by patching up the 'toctree' semantics.
However, I feel the core of the problem is that the toctree directive
(especially at the end of the page) defaults to the last-active heading
level; I cannot currently have it there and associate it to a higher (most
often: the topmost) indentation level.

> How would this be represented on the screen or page? How would the reader
*know* that the section level had been "popped"?

That's a presentation matter. It is conceivable to make a presentation
where the body texts at different levels have a different color, or
different indentation. In that case, having this ability would matter. But
that is pretty far fetched of course. It is not something that happens
(often, if at all) in typesetting.

Presentation isn't my main concern though. Having the ability for tree
transforms and directives to correctly known the sub-heading nesting
structure of a document seems useful enough, and that is hard to do now,
especially at the end of a document where the nesting level is just
whatever is active at the time.

> If you absolutely insist, if you must "pop" the section level, here's an
ugly workaround:

The workaround does not do what I ask though; it introduces a new section;
it doesn't continue the previously open section.
Also, It introduces another heading (even if its text is empty) which I
don't want. I may be able to patch around that in HTML with CSS; but not in
other back-ends.

Now I may not be able to convince you that what I try to do is useful; but
I am still interested to find out if it is *possible*, eg with a custom
directive, and how I would go about that. Any pointers by you or anyone
else would be appreciated.

Best, Sidney






On Thu, May 27, 2021 at 3:53 AM David Goodger <go...@py...> wrote:

> I suspect that you may need a sidebar or topic in place of your section
> level 2:
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic
> Or maybe a rubric:
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric
>
> IMHO, a "popped" section is meaningless and you don't need it.
>
> Some questions come to mind:
>
> Why do this? What is the purpose?
>
> What would this "popped" section mean? What does it represent?
>
> How would this be represented on the screen or page? How would the reader
> *know* that the section level had been "popped"?
>
> Have you ever seen this in the real world? Please show us an example or
> three.
>
> If you absolutely insist, if you must "pop" the section level, here's an
> ugly workaround:
>
> Level 1
> =======
>
> Level 2
> ----------
>
> \
> ====
>
>
> That last title is a backslash followed by a space. It produces a level-1
> section with no title. You could make it explicit with a title of "title
> omitted", apply a class to it, add some CSS, and have it disappear
> completely.
> Use at your own risk.
>
> David Goodger
> <https://david.goodger.org>
>
>
> On Wed, May 26, 2021 at 3:55 PM Sidney Cadot <si...@ji...> wrote:
>
>> Hello all,
>>
>> I am using docutils through Sphinx, and I am running into an issue there,
>> which I think should best be solved in the RsT parsing stage. Ideally, this
>> could be addressed by a directive, or perhaps there is some other way that
>> any of you can point me to. Anyway here's the issue:
>>
>> When parsing RsT, nested sections are created by the RsT. It will add (or
>> change) hierarchical levels when it encounters heading lines. And a
>> hierarchical level is valid up to the next header line.
>>
>> (If my superficial understanding of the RsT source is correct, this is
>> mostly handled in the docutils.parsers.rst.RSTState.check_subsection()
>> method.)
>>
>> Okay. While this model is easy to understand and use, it does leave some
>> types of reasonable document structures out of reach. In particular, if I
>> want to "pop" a heading level to the next higher (or any higher) level
>> without introducing a new header, I am stuck.
>>
>> As an example, suppose I have this text:
>>
>>
>>
>>
>> *section level 1===========*
>>
>>
>> *First lorem ipsum etc etc.*
>>
>>
>>
>>
>>
>> *Section level 2--------------------Second lorem ipsum etc etc.*
>>
>> *Alea iacta est!*
>> Now in the current parser, the "Alea iacta est" paragraph will sit at
>> section level #2. In pseudo-XML, the parse tree will be:
>>
>>
>> *<section level="1">*
>>
>> *    <p>First lorem ipsum etc. etc.</p>*
>> *    <section level="2">*
>>
>> *        <p>Second lorem ipsum etc. etc.</p>*
>>
>> *        <p>Alea iacta est!</p>*
>>
>> *    </section>*
>> *</section>*
>>
>> What I want to do however is end the "section level 2" before "Alea iacta
>> est", and resume parsing section level 1.
>>
>> So I want my parse tree to be (again in pseudo-xml):
>>
>>
>> *<section level="1">*
>>
>> *    <p>First lorem ipsum etc. etc.</p>*
>> *    <section level="2">*
>>
>> *        <p>Second lorem ipsum etc. etc.</p>*
>>
>> *    </section>*
>>
>> *    <p>Alea iacta est!</p>*
>>
>> *</section>*
>> I have a few questions....
>>
>> First, is this already somehow possible? Is there some syntax that
>> directs the parser to produce the second parse tree?
>>
>> Second, if not: is there a fundamental reason why the second parse-tree
>> would be incompatible with the document model of RsT? (If that's the case,
>> why?)
>>
>> Third, if it is possible in principle, but not yet in practice, is there
>> a way to implement this without touching the parser; say, by adding a
>> docutils Directive? E.g. something that would work like this?
>>
>>
>>
>>
>> *section level 1===========*
>>
>>
>> *First lorem ipsum etc etc.*
>>
>>
>>
>>
>>
>> *Section level 2--------------------Second lorem ipsum etc etc.*
>>
>> *.. pop-heading-level*
>>
>> *    :levels: 1*
>>
>>
>> *Alea iacta est!*
>>
>> Any insight into this will be much appreciated.
>>
>> Kind regards, Sidney
>>
>> _______________________________________________
>> 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] closing a header block

[David G. <go...@py...>]

I suspect that you may need a sidebar or topic in place of your section
level 2: https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic
Or maybe a rubric:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric

IMHO, a "popped" section is meaningless and you don't need it.

Some questions come to mind:

Why do this? What is the purpose?

What would this "popped" section mean? What does it represent?

How would this be represented on the screen or page? How would the reader
*know* that the section level had been "popped"?

Have you ever seen this in the real world? Please show us an example or
three.

If you absolutely insist, if you must "pop" the section level, here's an
ugly workaround:

Level 1
=======

Level 2
----------

\
====


That last title is a backslash followed by a space. It produces a level-1
section with no title. You could make it explicit with a title of "title
omitted", apply a class to it, add some CSS, and have it disappear
completely.
Use at your own risk.

David Goodger
<https://david.goodger.org>


On Wed, May 26, 2021 at 3:55 PM Sidney Cadot <si...@ji...> wrote:

> Hello all,
>
> I am using docutils through Sphinx, and I am running into an issue there,
> which I think should best be solved in the RsT parsing stage. Ideally, this
> could be addressed by a directive, or perhaps there is some other way that
> any of you can point me to. Anyway here's the issue:
>
> When parsing RsT, nested sections are created by the RsT. It will add (or
> change) hierarchical levels when it encounters heading lines. And a
> hierarchical level is valid up to the next header line.
>
> (If my superficial understanding of the RsT source is correct, this is
> mostly handled in the docutils.parsers.rst.RSTState.check_subsection()
> method.)
>
> Okay. While this model is easy to understand and use, it does leave some
> types of reasonable document structures out of reach. In particular, if I
> want to "pop" a heading level to the next higher (or any higher) level
> without introducing a new header, I am stuck.
>
> As an example, suppose I have this text:
>
>
>
>
> *section level 1===========*
>
>
> *First lorem ipsum etc etc.*
>
>
>
>
>
> *Section level 2--------------------Second lorem ipsum etc etc.*
>
> *Alea iacta est!*
> Now in the current parser, the "Alea iacta est" paragraph will sit at
> section level #2. In pseudo-XML, the parse tree will be:
>
>
> *<section level="1">*
>
> *    <p>First lorem ipsum etc. etc.</p>*
> *    <section level="2">*
>
> *        <p>Second lorem ipsum etc. etc.</p>*
>
> *        <p>Alea iacta est!</p>*
>
> *    </section>*
> *</section>*
>
> What I want to do however is end the "section level 2" before "Alea iacta
> est", and resume parsing section level 1.
>
> So I want my parse tree to be (again in pseudo-xml):
>
>
> *<section level="1">*
>
> *    <p>First lorem ipsum etc. etc.</p>*
> *    <section level="2">*
>
> *        <p>Second lorem ipsum etc. etc.</p>*
>
> *    </section>*
>
> *    <p>Alea iacta est!</p>*
>
> *</section>*
> I have a few questions....
>
> First, is this already somehow possible? Is there some syntax that directs
> the parser to produce the second parse tree?
>
> Second, if not: is there a fundamental reason why the second parse-tree
> would be incompatible with the document model of RsT? (If that's the case,
> why?)
>
> Third, if it is possible in principle, but not yet in practice, is there a
> way to implement this without touching the parser; say, by adding a
> docutils Directive? E.g. something that would work like this?
>
>
>
>
> *section level 1===========*
>
>
> *First lorem ipsum etc etc.*
>
>
>
>
>
> *Section level 2--------------------Second lorem ipsum etc etc.*
>
> *.. pop-heading-level*
>
> *    :levels: 1*
>
>
> *Alea iacta est!*
>
> Any insight into this will be much appreciated.
>
> Kind regards, Sidney
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>