You can subscribe to this list here.
2002 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
(3) |
Sep
(15) |
Oct
(21) |
Nov
(18) |
Dec
(59) |
---|---|---|---|---|---|---|---|---|---|---|---|---|
2003 |
Jan
(43) |
Feb
(35) |
Mar
(78) |
Apr
(65) |
May
(163) |
Jun
(169) |
Jul
(137) |
Aug
(77) |
Sep
(47) |
Oct
(27) |
Nov
(43) |
Dec
(68) |
2004 |
Jan
(61) |
Feb
(39) |
Mar
(11) |
Apr
(42) |
May
(86) |
Jun
(82) |
Jul
(24) |
Aug
(26) |
Sep
(37) |
Oct
(62) |
Nov
(131) |
Dec
(43) |
2005 |
Jan
(31) |
Feb
(56) |
Mar
(65) |
Apr
(165) |
May
(106) |
Jun
(97) |
Jul
(65) |
Aug
(150) |
Sep
(78) |
Oct
(115) |
Nov
(41) |
Dec
(26) |
2006 |
Jan
(50) |
Feb
(39) |
Mar
(56) |
Apr
(67) |
May
(89) |
Jun
(68) |
Jul
(116) |
Aug
(65) |
Sep
(58) |
Oct
(103) |
Nov
(28) |
Dec
(52) |
2007 |
Jan
(92) |
Feb
(60) |
Mar
(124) |
Apr
(96) |
May
(69) |
Jun
(79) |
Jul
(25) |
Aug
(22) |
Sep
(7) |
Oct
(17) |
Nov
(27) |
Dec
(32) |
2008 |
Jan
(57) |
Feb
(87) |
Mar
(51) |
Apr
(43) |
May
(56) |
Jun
(62) |
Jul
(25) |
Aug
(82) |
Sep
(58) |
Oct
(42) |
Nov
(38) |
Dec
(86) |
2009 |
Jan
(50) |
Feb
(33) |
Mar
(84) |
Apr
(90) |
May
(109) |
Jun
(37) |
Jul
(22) |
Aug
(51) |
Sep
(93) |
Oct
(86) |
Nov
(31) |
Dec
(62) |
2010 |
Jan
(33) |
Feb
(57) |
Mar
(62) |
Apr
(43) |
May
(30) |
Jun
(49) |
Jul
(20) |
Aug
(40) |
Sep
(152) |
Oct
(38) |
Nov
(15) |
Dec
(32) |
2011 |
Jan
(29) |
Feb
(25) |
Mar
(65) |
Apr
(45) |
May
(27) |
Jun
(11) |
Jul
(14) |
Aug
(8) |
Sep
(13) |
Oct
(117) |
Nov
(60) |
Dec
(19) |
2012 |
Jan
(23) |
Feb
(32) |
Mar
(24) |
Apr
(41) |
May
(56) |
Jun
(24) |
Jul
(15) |
Aug
(11) |
Sep
(26) |
Oct
(21) |
Nov
(12) |
Dec
(31) |
2013 |
Jan
(32) |
Feb
(24) |
Mar
(39) |
Apr
(44) |
May
(44) |
Jun
(8) |
Jul
(9) |
Aug
(12) |
Sep
(34) |
Oct
(19) |
Nov
(5) |
Dec
(9) |
2014 |
Jan
(22) |
Feb
(12) |
Mar
(7) |
Apr
(2) |
May
(13) |
Jun
(17) |
Jul
(8) |
Aug
(10) |
Sep
(7) |
Oct
(4) |
Nov
|
Dec
(39) |
2015 |
Jan
(13) |
Feb
(12) |
Mar
(12) |
Apr
(40) |
May
(5) |
Jun
(22) |
Jul
(3) |
Aug
(42) |
Sep
(5) |
Oct
(10) |
Nov
|
Dec
(10) |
2016 |
Jan
(9) |
Feb
(43) |
Mar
(5) |
Apr
(14) |
May
(17) |
Jun
(5) |
Jul
(5) |
Aug
(22) |
Sep
(5) |
Oct
|
Nov
(4) |
Dec
(18) |
2017 |
Jan
(28) |
Feb
(29) |
Mar
(9) |
Apr
(23) |
May
(48) |
Jun
(5) |
Jul
(32) |
Aug
(9) |
Sep
(13) |
Oct
(13) |
Nov
(6) |
Dec
(4) |
2018 |
Jan
(6) |
Feb
(5) |
Mar
(1) |
Apr
(2) |
May
(5) |
Jun
(17) |
Jul
(12) |
Aug
(15) |
Sep
|
Oct
(2) |
Nov
|
Dec
|
2019 |
Jan
|
Feb
(6) |
Mar
(3) |
Apr
(5) |
May
(10) |
Jun
(6) |
Jul
(6) |
Aug
|
Sep
(11) |
Oct
(18) |
Nov
(10) |
Dec
(7) |
2020 |
Jan
(3) |
Feb
(14) |
Mar
(2) |
Apr
(1) |
May
(5) |
Jun
|
Jul
(1) |
Aug
(11) |
Sep
(8) |
Oct
|
Nov
(1) |
Dec
(14) |
2021 |
Jan
(7) |
Feb
(2) |
Mar
(1) |
Apr
(8) |
May
(23) |
Jun
(7) |
Jul
(10) |
Aug
(1) |
Sep
|
Oct
(7) |
Nov
(10) |
Dec
(2) |
2022 |
Jan
|
Feb
(21) |
Mar
|
Apr
(3) |
May
(7) |
Jun
(4) |
Jul
(1) |
Aug
|
Sep
(3) |
Oct
|
Nov
|
Dec
|
2023 |
Jan
(18) |
Feb
|
Mar
(1) |
Apr
|
May
(9) |
Jun
|
Jul
|
Aug
(5) |
Sep
|
Oct
|
Nov
|
Dec
|
2024 |
Jan
|
Feb
(2) |
Mar
(3) |
Apr
(5) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
From: Alan G. I. <ala...@gm...> - 2021-05-29 14:51:35
|
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 |
From: Sidney C. <si...@ji...> - 2021-05-27 12:12:56
|
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 |
From: Guenter M. <mi...@us...> - 2021-05-27 11:26:08
|
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 |
From: Sidney C. <si...@ji...> - 2021-05-27 08:30:40
|
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. >> > |
From: David G. <go...@py...> - 2021-05-27 01:53:50
|
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. > |
From: Sidney C. <si...@ji...> - 2021-05-26 19:55:42
|
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 |
From: Alan G. I. <ala...@gm...> - 2021-05-25 18:25:39
|
> Alan wrote: >> I already pointed out that it means that combining two >> documents (e.g., with an `include`) that have compatible >> header notation and individually format perfect produces >> a broken combined document. On 5/25/2021 9:25 AM, Guenter Milde via Docutils-users wrote: > Producing broken documents is bad, so I would like to improve the situation. > Could you provide a minimal working (rsp. breaking) example and specify what > you would expect and what is broken, please? I may have miscommunicated here. By using the `--initial-header-level` option, I was able to fix things for my use. Nevertheless, 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 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. Nevertheless, I typically turned it off with the `--no-doc-title` option. 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 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. Again, I simply share my non-expert opinion and experience. As I said, I have a solution that is working for me. And again, thank you for all your work on this! Alan |
From: Guenter M. <mi...@us...> - 2021-05-25 13:25:55
|
Dear Alan, On 2021-05-24, Alan G. Isaac wrote: > I am not going to drag out this discussion, but I must make one > last appeal to revert the default behavior. I am actually glad you don't give up easily, as this makes me think again about the document structure and design and hopefully helps to improve implementation and documentation. There are, however, still open questions regarding the core of your problem with the current behaviour and I currently come to different conclusions, so please bear with me. > Changing the meaning of a section header because it occurs > a second time seems to me to be fundamentally broken behavior. > So I must ask: how much consultation did you do on this? > E.g., Did David agree that this is good behavior? Changing the meaning of a section header when it occures just one time is actually the standard behaviour of rST laid down by David in the reStructuredText Markup Specification. https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document This means that with the default settings, the input :: Document Title -------------- This is the content. generates a document without sections (here rendered as Docutils XML) :: <document ids="document-title" names="document\ title" source="/tmp/titles.rst" title="Document Title"> <title>Document Title</title> <paragraph>This is the content.</paragraph> </document> OTOH, changing the the input to :: 1st Section Title ----------------- Content of section 1 2nd Section Title ----------------- Content of section 2 leads to a document with two sections but no document title :: <document source="/tmp/titles.rst"> <section ids="st-section-title" names="1st\ section\ title"> <title> 1st Section Title <paragraph> Content of section 1 <section ids="nd-section-title" names="2nd\ section\ title"> <title> 2nd Section Title <paragraph> Content of section 2 Of course, this also holds, if the 2nd section is from a different file and included after the 1st section. "html4css1" has a special feature: it uses a <h1> tag for both, document title and 1st-level section titles. https://docutils.sourceforge.io/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why > I already pointed out that it means that combining two > documents (e.g., with an `include`) that have compatible > header notation and individually format perfect produces > a broken combined document. Producing broken documents is bad, so I would like to improve the situation. Could you provide a minimal working (rsp. breaking) example and specify what you would expect and what is broken, please? > Also, this decision seems out of step with the current > understanding of HTML document structure. The changing of the default `initial_header_level`__ setting for HTML5 was triggered by a rendering problem observed in Firefox, Chromium and Opera after the mapping of Docutils "section" nodes from <div class="section"> to <section>. I consulted the `MDN Web Docs`__ as well as the `HTML Specifications`__ before settling on this change. __ https://docutils.sourceforge.io/docs/user/config.html#initial-header-level __ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements __ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#specifications The most current `"living standard"`__ says: Sections may contain headings of any rank, but authors are strongly encouraged to either use only h1 elements, or to use elements of the appropriate rank for the section's nesting level. __ https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections The "html5" writer does the latter, using: <body> h1 <section> h2 <section> h3 ... ... also, if the document heading is missing because the top-level section is nevertheless nested inside the <body> of the document. In my understanding, this provides a good match of Docutils document structure to HTML5. However, I agree that HTML document structure (especially the understanding of a section's "nesting level") is a complex issue, , and I may have missed something. > For example, consider: > https://www.impactplus.com/blog/multiple-h1-headlines-okay This post starts quoting Webmaster Trends Analyst John Mueller [...] it makes no difference to Google whether you use no H1 tags or 100. which endorses both, the "html4css1" way of re-using <h1> for document title and section title as well as "html5"s way of skipping <h1> if there is no document title. The section about screen readers states Whether you decide it's better to use no H1s or several, consider if it will have an impact on someone who uses a screen reader for accessibility. and the summary says Although multiple top-level headings won't hurt your Google rankings, it may be preferable to stick to maintaining only one H1 per page until more information is available on the topic. > https://webdesign.tutsplus.com/articles/the-truth-about-multiple-h1-tags-in-the-html5-era--webdesign-16824 This article is interesting to read (although a bit dated). It states that "it is perfectly fine to use as many <h1> tags as your document calls for; that is one per sectioning root or content section." but also admits "It is permissible by the HTML5 spec to use lower level headings than <h1> to label a section". The "New <h1> Usage Rules" seem to contradict with the "living standard"'s recommendation and handling in current browsers. They can be reconciled using the caveat given at the end: "But if you do decide to use a tag other than <h1> for a section label, just ensure you follow the same rules as listed above, replacing <h1> in each rule with your chosen tag." The example problem given there is a page containing several independent "articles". Docutils currently does not offer a way to distinguish independent "articles" from interrelated "sections" inside one rST document. > Thus I again urge reverting this change. Just reverting to ``initial_header_level == 1`` would require another solution to the rendering problems in current browsers. Alternatives include "not using <section> elements" and "styling every heading level in the mandatory CSS style-sheet" which I am open to discuss. Thank you for the feedback, Günter |
From: Alan G. I. <ala...@gm...> - 2021-05-24 16:18:42
|
On 5/24/2021 4:28 AM, Guenter Milde via Docutils-users wrote: > I changed the default value for the "html5" writer to bring it in line > with HTML5 behaviour after making it write <section> instead of <div > class="section">. Of course you should use CSS, but I believe it is a bad > idea to force everyone to define the visual features for every <Hn> level > in order to override current browser default just to keep using <H1> for > both, title and first-level section heading when the "web consensus" > moved to using <H1> for the title and <H1+n> for section headings -- > independent of my personal preference in this question. I am not going to drag out this discussion, but I must make one last appeal to revert the default behavior. Changing the meaning of a section header because it occurs a second time seems to me to be fundamentally broken behavior. So I must ask: how much consultation did you do on this? E.g., Did David agree that this is good behavior? I already pointed out that it means that combining two documents (e.g., with an `include`) that have compatible header notation and individually format perfect produces a broken combined document. That's exactly how I discovered this change. This alone should cause immense hesitation. Also, this decision seems out of step with the current understanding of HTML document structure. For example, consider: https://www.impactplus.com/blog/multiple-h1-headlines-okay https://webdesign.tutsplus.com/articles/the-truth-about-multiple-h1-tags-in-the-html5-era--webdesign-16824 Thus I again urge reverting this change. However, this is my last comment on this matter. Thanks for all your work! Alan Isaac |
From: Guenter M. <mi...@us...> - 2021-05-24 08:28:48
|
On 2021-05-23, Alan G. Isaac wrote: > But of course you already did provide this option. Actually, this was not me: the initial-header-level__ option is there "for ages". __ https://docutils.sourceforge.io/docs/user/config.html#initial-header-level > I still claim this is a bad default (who on earth is using docutils > without CSS), but my problem is already addressed. I changed the default value for the "html5" writer to bring it in line with HTML5 behaviour after making it write <section> instead of <div class="section">. Of course you should use CSS, but I believe it is a bad idea to force everyone to define the visual features for every <Hn> level in order to override current browser default just to keep using <H1> for both, title and first-level section heading when the "web consensus" moved to using <H1> for the title and <H1+n> for section headings -- independent of my personal preference in this question. >> If I have a document with a single >> top level header, it becomes a h1 element. Yes, by default, a lone top-level section title is promoted to `document title`__ (<H1 class="title">). You can, however, use the doctitle_xform__ setting if it should be a section heading instead. Then you will get a <H1> with html4css1 and <H2> with html5. __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title __ https://docutils.sourceforge.io/docs/user/config.html#doctitle-xform >> If I later include in it a document with a top level header, >> they both become h2 elements. I have many documents like this. This very much depends: * If both documents use the same adornment style for their respective top-level headings, none will be promoted to document title. * If the master document uses an adornment style that is never reused in the rest of the document and its children, this will become the document title (<H1 class="title">) unless doctitle_xform == False. It may be a good idea to check your documents for current and intended behaviour and eventuall correct either the doctitle_xform setting or the style of the initial heading in master documents. Günter |
From: Alan G. I. <ala...@gm...> - 2021-05-23 18:40:31
|
But of course you already did provide this option. I still claim this is a bad default (who on earth is using docutils without CSS), but my problem is already addressed. Thanks! Alan On 5/23/2021 8:04 AM, Alan G. Isaac wrote: > Please, please revert this change. > A bad default display decision by browser makers > does not imply that docutils users should not > have access to h1 elements. > > If you cannot revert this, please provide an option > to control it. > > Note that the current behavior the situation is close > to impossible. If I have a document with a single > top level header, it becomes a h1 element. > If I later include in it a document with a top level header, > they both become h2 elements. I have many documents like this. > > Alan Isaac |
From: Guenter M. <mi...@us...> - 2021-05-22 21:56:12
|
On 2021-05-22, Alan G. Isaac wrote: > If I run the example at > https://rst2html5.readthedocs.io/en/latest/README.html#example > I do not see the documented output. Please be aware, that the "rst2html5" documented here is a 3rd-party project, not Docutils' html5 writer! (cf. https://rst2html5.readthedocs.io/en/latest/authors.html) > Instead, I see the h1 elements demoted to h2, which is unwanted > Removing the second title produces the expected output. > I'm using an up to date docutils (revision 8757). This is an intended and documented change: - Change the `initial_header_level`_ setting's default to "2", as browsers use the `same style for <h1> and <h2> when nested in a section`__. .. _initial_header_level: docs/user/config.html#initial-header-level __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article --- RELEASE-NOTES.txt Günter |
From: Alan G. I. <ala...@gm...> - 2021-05-22 12:32:51
|
If I run the example at https://rst2html5.readthedocs.io/en/latest/README.html#example I do not see the documented output. Instead, I see the h1 elements demoted to h2, which is unwanted Removing the second title produces the expected output. I'm using an up to date docutils (revision 8757). Thank you, Alan Isaac |
From: Guenter M. <mi...@us...> - 2021-05-05 09:28:26
|
On 2021-05-04, Mariusz Wasiluk wrote: > Thank you for the answer. Yes, I saw the release notes however I don't > understand how this behavior is in line with what is stated in > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism > "The backslash is removed from the output" suggests that there will be no > character in the output, even NULL. I agree that the documentation needs clarification. Escape characters are removed from output documents by the Docutils "writers". Your example uses a representation of the internal document tree (doctree). > Currently, my example produces invalid XML (I get parsing error from lxml). This should not happen and is probably a bug in the asdom() method for Text nodes. > So I wonder if my use case is invalid? Currently, the XML produced by .asdom().toxml() is not tested. While not invalid, you may consider it experimental/unsupported. Contributions improving test coverage are welcome. > Shall I remove \x00 from the XML output before further processing? Depending on your needs, you could either restore or remove escaping not "used up" by Docutils. Docutils provides the nodes.unescape() function for this purpose (which allows either restoring or removal and also caters for the special meaning of escaped whitespace). When you don't want the escapes, you may also consider using the "xml" writer instead of publish_doctree(). Fixing ...asdom() would also need to consider whether escapes should be restored or removed. Günter > wt., 4 maj 2021 o 19:53 Guenter Milde via Docutils-users < > doc...@li...> napisał(a): >> On 2021-05-04, Mariusz Wasiluk wrote: >> > Hello, >> > I have following snippet: >> > from docutils.core import publish_doctree >> > dom = publish_doctree(r'Foo\\bar').asdom() >> > print(repr(dom.toxml())) >> > with docutils>=0.16, I get: >> > u'<?xml version="1.0" ?><document >> > source="<string>"><paragraph>Foo\x00\\bar</paragraph></document>' >> > with previous versions I get: >> > u'<?xml version="1.0" ?><document >> > source="<string>"><paragraph>Foo\\bar</paragraph></document>' >> > Why with the newest docutils versions I'm getting \x00 in the output? >> This is an intended change: >> Until 0.16, backslashs were removed prior to storing a Text string in the >> document tree. Since 0.16 they are stored as NULL. >> See the HISTORY.txt entry for 0.16: >> - Keep `backslash escapes`__ in the document tree. Backslash characters >> in >> text are be represented by NULL characters in the ``text`` attribute of >> Doctree nodes and removed in the writing stage by the node's >> ``astext()`` method. >> __ >> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism >> This change was implemented in order to allow escaping "active characters" >> also in transforms. The RELEASE_NOTES list one example: >> [...] This allows, e.g., escaping of author-separators in >> `bibliographic fields`__. >> __ >> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism >> __ docs/ref/rst/restructuredtext.html#bibliographic-fields >> Another usage is escaping of characters that would otherwise be >> transformed by >> the smartquotes__ transform. >> __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes >> 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. > [-- Skipped Type: text/html --] > [-- Type: text/plain, Encoding: 7bit --] > [-- Type: text/plain, Encoding: 7bit --] |
From: Mariusz W. <go...@gm...> - 2021-05-04 18:23:50
|
Thank you for the answer. Yes, I saw the release notes however I don't understand how this behavior is in line with what is stated in https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism "The backslash is removed from the output" suggests that there will be no character in the output, even NULL. Currently, my example produces invalid XML (I get parsing error from lxml). So I wonder if my use case is invalid? Shall I remove \x00 from the XML output before further processing? wt., 4 maj 2021 o 19:53 Guenter Milde via Docutils-users < doc...@li...> napisał(a): > On 2021-05-04, Mariusz Wasiluk wrote: > > > Hello, > > > I have following snippet: > > > from docutils.core import publish_doctree > > dom = publish_doctree(r'Foo\\bar').asdom() > > print(repr(dom.toxml())) > > > with docutils>=0.16, I get: > > u'<?xml version="1.0" ?><document > > source="<string>"><paragraph>Foo\x00\\bar</paragraph></document>' > > > with previous versions I get: > > u'<?xml version="1.0" ?><document > > source="<string>"><paragraph>Foo\\bar</paragraph></document>' > > > Why with the newest docutils versions I'm getting \x00 in the output? > > This is an intended change: > > Until 0.16, backslashs were removed prior to storing a Text string in the > document tree. Since 0.16 they are stored as NULL. > > See the HISTORY.txt entry for 0.16: > > - Keep `backslash escapes`__ in the document tree. Backslash characters > in > text are be represented by NULL characters in the ``text`` attribute of > Doctree nodes and removed in the writing stage by the node's > ``astext()`` method. > > __ > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism > > This change was implemented in order to allow escaping "active characters" > also in transforms. The RELEASE_NOTES list one example: > > [...] This allows, e.g., escaping of author-separators in > `bibliographic fields`__. > > __ > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism > __ docs/ref/rst/restructuredtext.html#bibliographic-fields > > Another usage is escaping of characters that would otherwise be > transformed by > the smartquotes__ transform. > > __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes > > > 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. > |
From: Guenter M. <mi...@us...> - 2021-05-04 17:52:56
|
On 2021-05-04, Mariusz Wasiluk wrote: > Hello, > I have following snippet: > from docutils.core import publish_doctree > dom = publish_doctree(r'Foo\\bar').asdom() > print(repr(dom.toxml())) > with docutils>=0.16, I get: > u'<?xml version="1.0" ?><document > source="<string>"><paragraph>Foo\x00\\bar</paragraph></document>' > with previous versions I get: > u'<?xml version="1.0" ?><document > source="<string>"><paragraph>Foo\\bar</paragraph></document>' > Why with the newest docutils versions I'm getting \x00 in the output? This is an intended change: Until 0.16, backslashs were removed prior to storing a Text string in the document tree. Since 0.16 they are stored as NULL. See the HISTORY.txt entry for 0.16: - Keep `backslash escapes`__ in the document tree. Backslash characters in text are be represented by NULL characters in the ``text`` attribute of Doctree nodes and removed in the writing stage by the node's ``astext()`` method. __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism This change was implemented in order to allow escaping "active characters" also in transforms. The RELEASE_NOTES list one example: [...] This allows, e.g., escaping of author-separators in `bibliographic fields`__. __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism __ docs/ref/rst/restructuredtext.html#bibliographic-fields Another usage is escaping of characters that would otherwise be transformed by the smartquotes__ transform. __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes Günter |
From: Mariusz W. <go...@gm...> - 2021-05-04 15:28:03
|
Hello, I have following snipped: from docutils.core import publish_doctree dom = publish_doctree(r'Foo\\bar').asdom() print(repr(dom.toxml())) with docutils>=0.16, I get: u'<?xml version="1.0" ?><document source="<string>"><paragraph>Foo\x00\\bar</paragraph></document>' with previous versions I get: u'<?xml version="1.0" ?><document source="<string>"><paragraph>Foo\\bar</paragraph></document>' Why with the newest docutils versions I'm getting \x00 in the output? |
From: Guenter M. <mi...@us...> - 2021-04-18 10:44:26
|
On 2021-04-17, seb...@ch... wrote: > Le 16/04/2021 à 18:19, Alan G. Isaac a écrit : >> With rst2beamer, I'm getting table widths that are far too narrow. This is a known problem: reST-documents line length is assumed to be 80 characters. The tablewidth is set relative to this value. If someone produces documents with line length of 132 this will lead to suboptimal results. -- https://docutils.sourceforge.io/docs/user/latex.html#tables You may use the :width: or :widths: options of the `table directive`__ to manually set the table column widths. With the table-style_ option, you can also set document-wide defaults. With ``--table-style: colwidths-auto``, LaTeX determines table column width by their content. Warning colwidths-auto is only suited for tables with simple cell content. LaTeX puts the content of auto-sized columns on one line (merging paragraphs) and may fail with complex content. __ https://docutils.sourceforge.io/docs/ref/rst/directives.html#table __ https://docutils.sourceforge.io/docs/user/config.html#table-style-latex-writers >> It looks like this is coming from the latex writer (specifically, >> get_colspecs). It appears to produce only about half of >> the \textwidth as the table width. >> Unfortunately I am in the middle of a project and cannot explore >> this further at the moment, but my workaround has been to set >> the width on the table to far above 100%. Perhaps this report >> while inadequate will be of some use. May be there is more at stake here, especially as beamer may have different default. You may consider to ask back once you have the time to generate minimal examples ... Günter |
From: engelbert g. <eng...@gm...> - 2021-04-17 14:27:51
|
release 0.17.1 is on pypi fixes two things * in python3.6 in an ascii environment reading the docutils.sty file fails, due to unicode characters in the file. * provide defaults (fallbacks) for settings (tab_width) if docutils is used by third party frontends. all the best e |
From: <seb...@ch...> - 2021-04-17 13:41:46
|
Le 16/04/2021 à 18:19, Alan G. Isaac a écrit : > With rst2beamer, I'm getting table widths that are far too narrow. > It looks like this is coming from the latex writer (specifically, > get_colspecs). It appears to produce only about half of > the \textwidth as the table width. > > Unfortunately I am in the middle of a project and cannot explore > this further at the moment, but my workaround has been to set > the width on the table to far above 100%. Perhaps this report > while inadequate will be of some use. > Hi Isaac, The column width is evaluated with the number of letters in each column : This means that the two following tables will be rendered with different width : > > ====== ======= > |Col1| |Col2| > ------ ------- > v1 v2 > ====== ======= > > .. |Col1| replace:: First column with title > .. |Col2| replace:: 2nd column with title > > ======================= ===================== > First column with title 2nd column with title > ----------------------- --------------------- > v1 v2 > ======================= ===================== Sébastien |
From: Alan G. I. <ala...@gm...> - 2021-04-16 16:19:34
|
With rst2beamer, I'm getting table widths that are far too narrow. It looks like this is coming from the latex writer (specifically, get_colspecs). It appears to produce only about half of the \textwidth as the table width. Unfortunately I am in the middle of a project and cannot explore this further at the moment, but my workaround has been to set the width on the table to far above 100%. Perhaps this report while inadequate will be of some use. Best, Alan Isaac |
From: Guenter M. <mi...@us...> - 2021-04-07 22:13:11
|
On 2021-04-07, Guenter Milde via Docutils-users wrote: > On 2021-04-07, Mula, Wojciech (Nokia - PL/Wroclaw) wrote: >> Hi, I don't have an SF account, so adding a comment here. >> To reproduce the issue it's sufficient to set LANG=C (or unset LANG at >> all). It works with Python 3.6 from Redhat 8. I think the correct >> solution is to open the .sty file in __init__.py with explicitly set >> encoding to UTF-8. >> Günter asked why not using UTF-8? In our case we didn't even know that >> our CI setup does have locale set. > Thank you for the additional info. ... Update: you may try with the newest repository version. Günter |
From: Guenter M. <mi...@us...> - 2021-04-07 19:11:41
|
On 2021-04-07, Mula, Wojciech (Nokia - PL/Wroclaw) wrote: > Hi, I don't have an SF account, so adding a comment here. > To reproduce the issue it's sufficient to set LANG=C (or unset LANG at > all). It works with Python 3.6 from Redhat 8. I think the correct > solution is to open the .sty file in __init__.py with explicitly set > encoding to UTF-8. > Günter asked why not using UTF-8? In our case we didn't even know that > our CI setup does have locale set. Thank you for the additional info. Next question: how come that building HTML with Sphinx wants to load a LaTeX style file?? Can you provide a full log (to the list or as pm)? Günter |
From: Mula, W. (N. - PL/Wroclaw) <woj...@no...> - 2021-04-07 08:52:27
|
Hi, I don't have an SF account, so adding a comment here. To reproduce the issue it's sufficient to set LANG=C (or unset LANG at all). It works with Python 3.6 from Redhat 8. I think the correct solution is to open the .sty file in __init__.py with explicitly set encoding to UTF-8. Günter asked why not using UTF-8? In our case we didn't even know that our CI setup does have locale set. best regards Wojciech |
From: engelbert g. <eng...@gm...> - 2021-04-03 12:20:14
|
Release Notes * Installing with ``setup.py`` now requires setuptools_. Alternatively, install with pip_. * The generic command line front end tool docutils-cli.py_ allows the free selection of reader, parser, and writer components. * New, experimental wrapper to integrate the `recommonmark`__ Markdown parser for use with Docutils. __ https://pypi.org/project/recommonmark/ * HTML5 writer: - Use the new semantic tags <main>, <section>, <header>, <footer>, <aside>, <figure>, and <figcaption>. See ``minimal.css`` and ``plain.css`` for styling rule examples. Change the `initial_header_level`_ setting's default to "2", as browsers use the `same style for <h1> and <h2> when nested in a section`__. - 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. - New optional style ``responsive.css``, adapts to different screen sizes. - New option embed_images_. .. _initial_header_level: docs/user/config.html#initial-header-level __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article .. _embed_images: docs/user/config.html#embed-images * docutils/writers/html5_polyglot/ - ``minimal.css``: Move non-essential styling to ``plain.css``. Code line numbers as pseudo-elements which are skipped when copying text. - ``plain.css``: Support numbered figures. * LaTeX writer: - New configuration setting `legacy_class_functions`_. - The special value "auto" for the `graphicx_option`_ setting is no longer supported (it never worked for xetex/luatex). - `Styling commands`__ using the legacy ``\docutilsrole`` prefix are now ignored. Use ``\DUrole``. __ docs/user/latex.html#classes - Most helper commands and element definitions are now defined in the LaTeX package `docutils.sty`_ and only inserted in the document preamble if the stylesheet__ setting does not lists "docutils". __ docs/user/config.html#stylesheet-latex-writers - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``. - Fixes (thanks to) from John Thorvald Wodder II: alignment of nested tables, support memoir document class, * pseudoxml-writer got a ``--detailled`` option for pretty printing text nodes. * odf/odt-writer improved metadata handling. * manpage-writer fixes #380 commandline option in spinx, #126 title with spaces, #168 empty citation, #394 newline after rubric. * Miscellaneous: - Fixes in Arabic mappings and Korean translations. - directives: Prevent infinte inclusion loops. - roles: Apply patch #174 `Lowercase new role names on registration` by John Thorvald Wodder II. cheers engelbert |