docutils-develop — For developer discussions of the implementation.

Re: [Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

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

Since I have not seen any developer feedback,
here is some user feedback.

- citations without content: I've never seen it
- footnotes without content or without "label": I've never seen it
- figures without caption/legend: no "legend" is reasonably common, but no
caption is extremely rare and is a need met by `image` (I believe)

Cheers, Alan Isaac



On Mon, Jun 17, 2024 at 12:45 PM Guenter Milde via Docutils-develop <
doc...@li...> wrote:

> Dear Docutils Developers,
>
> I still hope to get some feedback on what to do with the discrepancies of
>
> * user documentation
> * Docutils Generic Document Type Description (docutils.dtd), and
> * "rst" parser behaviour.
>
>
> Footnotes and Citations
>   may be specified **without content** in rST without the parser
> complaining.
>
>   According to documentation and docutils.dtd content is required.
>
>   → Is there any use-case for empty footnotes or citations?
>
> Footnote label
>   is optional according to docutils.dtd
>
>   According to user documentation, a label is required.
>   The "rst" parser requires a label, too.
>
>   → Is there any use-case for a footnote without label?
>
>
> Figures
>   require a caption or legend according to docutils.dtd.
>
>   The "rst" parser and the documentation allow figures without caption or
>   legend.
>
>   → OK to Allow figures without caption/legend in the Docutils Generic DTD?
>
>
> See also https://sourceforge.net/p/docutils/bugs/489/
>
>
> Günter
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

[Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

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

Dear Docutils Developers,

I still hope to get some feedback on what to do with the discrepancies of

* user documentation
* Docutils Generic Document Type Description (docutils.dtd), and
* "rst" parser behaviour.


Footnotes and Citations
  may be specified **without content** in rST without the parser complaining.
  
  According to documentation and docutils.dtd content is required.
  
  → Is there any use-case for empty footnotes or citations?
  
Footnote label
  is optional according to docutils.dtd
  
  According to user documentation, a label is required. 
  The "rst" parser requires a label, too.

  → Is there any use-case for a footnote without label?


Figures
  require a caption or legend according to docutils.dtd.

  The "rst" parser and the documentation allow figures without caption or
  legend.

  → OK to Allow figures without caption/legend in the Docutils Generic DTD?


See also https://sourceforge.net/p/docutils/bugs/489/


Günter

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Tue Jun 11, 2024 12:13 PM UTC
**Owner:** nobody


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #60 Allow definition_list_item to have multiple terms

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

Commit [r9747] changes the DTD, documentation, and `nodes.definition_list_item.content_model` to allow multiple terms for one definition.



---

**[feature-requests:#60] Allow definition_list_item to have multiple terms**

**Status:** open-fixed
**Group:** Default
**Created:** Thu Jan 03, 2019 09:10 AM UTC by Takeshi KOMIYA
**Last Updated:** Tue Dec 12, 2023 06:20 PM UTC
**Owner:** nobody
**Attachments:**

- [support_multiple_terms_on_definition_list_item.patch](https://sourceforge.net/p/docutils/feature-requests/60/attachment/support_multiple_terms_on_definition_list_item.patch) (3.7 kB; application/octet-stream)


In HTML  spec, definition list accepts multiple terms in a item.  This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #95 Multiterm definition items

[Günter M. <mi...@us...>]

See also [feature-requests:#60] for allowing multi-term definitions in the doctree  and writer support.


---

**[patches:#95] Multiterm definition items**

**Status:** open
**Group:** 
**Created:** Tue Jul 31, 2012 08:38 AM UTC by Kirill Smelkov
**Last Updated:** Wed Nov 21, 2018 09:00 PM UTC
**Owner:** nobody


Following discussion on docutils-users about multi-term definition list items \[1,2\],
I'am also posting my patches here, just to make sure they don't get lost.


Thanks,
Kirill

\[1\] https://sourceforge.net/mailarchive/forum.php?thread\_name=F406FAD0-FC0D-425E-B9DB-EC6D959E8371%40tibsnjoan.co.uk&forum\_name=docutils-users
\[2\] http://permalink.gmane.org/gmane.text.docutils.user/6765


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #94 Should docutils whine about nesting simple body elements?

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Group**:  --> Default
- **Comment**:

In Docutils 0.22 (since [r9732]), you can validate a  Document Tree element (`nodes.Element` instance) and its children by calling its `validate()` method. 
There is also a "transform" that checks a complete document after parsing and reports validation problems as WARNING system messages. It can be activated with the [validate](https://docutils.sourceforge.io/docs/user/config.html#validate) configuration setting.

The new "xml" parser validates the parsing result by default, so if you save the source
~~~
<paragraph classes="availability">
    <inline classes="xref std std-ref">Availability:</inline>
    Unix, not WASI.
    <paragraph>Content of the "availability" directive.</paragraph>
</paragraph>
~~~
to a file foo.xml, say, and run
    
    docutils --parser=xml --writer=pseudoxml foo.xml

the result is
~~~
<document source="/tmp/foo.xml">
    <paragraph classes="availability">
        
        <inline classes="xref std std-ref">
            Availability:
        
        Unix, not WASI.
        <paragraph>
            Content of the "availability" directive.
        
    <section classes="system-messages">
        <title>
            Docutils System Messages
        <system_message level="2" line="4" source="/tmp/foo.xml" type="WARNING">
            <paragraph>
                Element <paragraph classes="availability"> invalid:
                  Child element <paragraph> not allowed at this position.
~~~
The original example would also complain about the unknown node `<pending_xref>` as this is an extension by Sphinx.



---

**[feature-requests:#94] Should docutils whine about nesting simple body elements?**

**Status:** open-fixed
**Group:** Default
**Created:** Thu Feb 09, 2023 09:55 AM UTC by Julien Palard
**Last Updated:** Thu May 11, 2023 08:00 AM UTC
**Owner:** nobody


Context:

[This](https://github.com/python/cpython/blob/45fa12aec8f508c224a1521cfe3ae597f1026264/Doc/tools/extensions/pyspecific.py#L149) call to `nested_parse` adds a `Paragraph` node to a `Paragraph` node,  this look forbidden by [the doc](https://docutils.sourceforge.io/docs/ref/doctree.html#body-elements), and it also look to misbehave sphinx-side, when translating the document, where we completly loose the nested paragraph once translated.

It renders properly though when **not** translated.

The linked `nested_parse` returns:

```xml
<paragraph classes="availability">
    <pending_xref refdoc="index" refdomain="std" refexplicit="True" reftarget="availability" reftype="ref" refwarn="True">
        <inline classes="xref std std-ref">
            Availability
    : 
    Unix, not Emscripten, not WASI.
    <paragraph>
        Hello world I'm the content of the "availability" directive.
```

If it's really something that should not be done, maybe some kind of warning at build time could help debugging those issues?



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #203 Catalan updates

[Günter M. <mi...@us...>]

- **status**: open-accepted --> closed-accepted



---

**[patches:#203] Catalan updates**

**Status:** closed-accepted
**Group:** None
**Created:** Sun Jul 23, 2023 09:38 PM UTC by Antoni Bella Pérez
**Last Updated:** Tue May 21, 2024 09:26 AM UTC
**Owner:** nobody
**Attachments:**

- [docutils-catalan_update.patch](https://sourceforge.net/p/docutils/patches/203/attachment/docutils-catalan_update.patch) (4.4 kB; text/x-patch)


* Has been ordered to following the source better (in English)
* All right from original translator


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #203 Catalan updates

[Günter M. <mi...@us...>]

Docutils 0.22 officially supports "Catalan (Valencian)". 
Thanks to all who helped with translations, verifications, and the patch to pypa/trove-classifiers!


---

**[patches:#203] Catalan updates**

**Status:** open-accepted
**Group:** None
**Created:** Sun Jul 23, 2023 09:38 PM UTC by Antoni Bella Pérez
**Last Updated:** Wed Apr 10, 2024 01:59 PM UTC
**Owner:** nobody
**Attachments:**

- [docutils-catalan_update.patch](https://sourceforge.net/p/docutils/patches/203/attachment/docutils-catalan_update.patch) (4.4 kB; text/x-patch)


* Has been ordered to following the source better (in English)
* All right from original translator


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #204 Add Georgian translation

[Günter M. <mi...@us...>]

- **status**: open-accepted --> closed-accepted
- **Comment**:

Georgian is  officially supported in Docutils 0.22. Thank you for the translations.



---

**[patches:#204] Add Georgian translation**

**Status:** closed-accepted
**Group:** None
**Created:** Mon Jul 24, 2023 03:54 AM UTC by Temuri Doghonadze
**Last Updated:** Wed Apr 10, 2024 01:59 PM UTC
**Owner:** nobody
**Attachments:**

- [ka.patch](https://sourceforge.net/p/docutils/patches/204/attachment/ka.patch) (7.3 kB; application/octet-stream)


Initial upload of Georgian translation.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #481 manpage: please stop converting text to full capitals

[engelbert g. <gr...@us...>]

- **status**: open --> open-fixed



---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 11:17 AM UTC
**Owner:** engelbert gruber


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #205 [manpage] Change macros for literal block to avoid warnings from groff 1.23

[engelbert g. <gr...@us...>]

- **status**: open --> closed-fixed
- **Comment**:

already applied in prior version 



---

**[patches:#205] [manpage] Change macros for literal block to avoid warnings from groff 1.23**

**Status:** closed-fixed
**Group:** None
**Labels:** manpage 
**Created:** Sat Jul 29, 2023 05:05 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Aug 09, 2023 10:25 AM UTC
**Owner:** nobody
**Attachments:**

- [manpage_literal_block.patch](https://sourceforge.net/p/docutils/patches/205/attachment/manpage_literal_block.patch) (627 Bytes; text/x-patch)


Docutils manpage writer currently uses `.ft C`, but this causes warnings from groff ≥ 1.23.0.

Please see the downstream bug https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1041809 for a discussion about this issue with many references.

The attached patch, based on the original patch from G. Branden Robinson, fixes the warnings and makes the manpage writer use `.EX` and `.EE` instead, which are documented [here](https://manpages.debian.org/unstable/groff/groff_man.7.en.html#Document_structure_macros):

> Begin and end example. After .EX, filling is disabled and a constant-width (monospaced) font is selected. Calling .EE enables filling and restores the previous font.

So this should be equivalent to the previous code (`.nf`/`.fi` was for the filling, `.ft C`/`.ft P` was for the font).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #105 manpage: would like more informative document comments

[engelbert g. <gr...@us...>]

- **status**: open --> open-fixed
- **Group**:  --> Default



---

**[feature-requests:#105] manpage: would like more informative document comments**

**Status:** open-fixed
**Group:** Default
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Sun Apr 07, 2024 05:09 PM UTC
**Owner:** engelbert gruber


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #107 use .MR for references to man-pages

[G. B. R. <br...@us...>]

Just a quick note.  You will not need to generate the arguments to the `MR` macro with a leading `\%` escape sequence.  The _groff_man_style_ man page has them here for complicated reasons; the short version is that the _tbl_, _eqn_, and _refer_ programs can be installed with a prefix determined by the builder of _groff_ at compilation time, because _groff_  supports being installed simultaneously with another (usually AT&T or AT&T-descended)  _troff_.   The prefix can be expanded in contexts where hyphenation is _not_ disabled, so a hyphenation control escape sequence is always prepended, even if the prefix is empty.  This is harmless.  I just wanted to point it out so that you don't think you've have to generate these escape sequences in the output you produce.


---

**[feature-requests:#107] use .MR for references to man-pages**

**Status:** open
**Group:** Default
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:43 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:44 PM UTC
**Owner:** engelbert gruber


the manpage of groff_man_style 

> See also
>        tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  man(1)  de‐
>        scribes  the man page librarian on your system.

is written using the .MR macro

~~~
  .SH "See also"
  .
  .MR \%tbl 1 ,
  .MR \%eqn 1 ,
  and
  .MR \%refer 1
  are preprocessors used with man pages.
  .
  .MR man 1
  describes the man page librarian on your system.
~~~

But then the rST input would loo like

~~~
See also
--------

tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  
man(1)  describes  the man page librarian on your system.
~~~

meaning we need to find the already formatted manpage references , which could be anywhere
in the text (except code . in code man(1) would be calling function man)


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #488 prepare URIs

[engelbert g. <gr...@us...>]

---

**[bugs:#488] prepare URIs **

**Status:** open
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:55 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:55 PM UTC
**Owner:** engelbert gruber


groff_man_style on hyperlinks

    The arguments to .MR, .MT, and .UR should be prepared for typesetting
    
1. Use special character escape sequences to encode Unicode  basic  Latin  characters  where  necessary, particularly the hyphen-minus.
2. URIs can be lengthy; ... the  application  of  non-printing break point escape sequences \: after each slash (or series thereof), and before each  dot  (or  series  thereof)  is recommended 
3. Consider  adding  break points  before  or after at signs in email addresses, and question marks, ampersands, and number signs in HTTP(S) URIs.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #107 use .MR for references to man-pages

[engelbert g. <gr...@us...>]

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -21,7 +21,7 @@
 
 But then the rST input would loo like
 
- ~~~
+~~~
 See also
 --------
 

~~~~




---

**[feature-requests:#107] use .MR for references to man-pages**

**Status:** open
**Group:** Default
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:43 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:43 PM UTC
**Owner:** engelbert gruber


the manpage of groff_man_style 

> See also
>        tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  man(1)  de‐
>        scribes  the man page librarian on your system.

is written using the .MR macro

~~~
  .SH "See also"
  .
  .MR \%tbl 1 ,
  .MR \%eqn 1 ,
  and
  .MR \%refer 1
  are preprocessors used with man pages.
  .
  .MR man 1
  describes the man page librarian on your system.
~~~

But then the rST input would loo like

~~~
See also
--------

tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  
man(1)  describes  the man page librarian on your system.
~~~

meaning we need to find the already formatted manpage references , which could be anywhere
in the text (except code . in code man(1) would be calling function man)


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #107 use .MR for references to man-pages

[engelbert g. <gr...@us...>]

---

**[feature-requests:#107] use .MR for references to man-pages**

**Status:** open
**Group:** Default
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:43 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:43 PM UTC
**Owner:** engelbert gruber


the manpage of groff_man_style 

> See also
>        tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  man(1)  de‐
>        scribes  the man page librarian on your system.

is written using the .MR macro

~~~
  .SH "See also"
  .
  .MR \%tbl 1 ,
  .MR \%eqn 1 ,
  and
  .MR \%refer 1
  are preprocessors used with man pages.
  .
  .MR man 1
  describes the man page librarian on your system.
~~~

But then the rST input would loo like

 ~~~
See also
--------

tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.  
man(1)  describes  the man page librarian on your system.
~~~

meaning we need to find the already formatted manpage references , which could be anywhere
in the text (except code . in code man(1) would be calling function man)


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #106 use .UR/.UE .MT/.ME macros for references

[engelbert g. <gr...@us...>]

---

**[feature-requests:#106] use .UR/.UE .MT/.ME macros for references**

**Status:** open
**Group:** Default
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:35 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:35 PM UTC
**Owner:** engelbert gruber


emit the macros for references do not expand in the writer.

maybe configurable expansion. 


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #486 0.21.1: sdist is missing tox.ini

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r9657].
Thank you for the report.



---

**[bugs:#486] 0.21.1: sdist is missing tox.ini**

**Status:** open-fixed
**Created:** Mon Apr 22, 2024 08:01 AM UTC by Marcel Telka
**Last Updated:** Tue Apr 23, 2024 07:44 PM UTC
**Owner:** nobody


The sdist package for version 0.21.1 is missing tox.ini.  Please add the missing tox.ini to sdist to make downstream testing easier.  Thank you.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Karl O. P. <ko...@ka...>]

On Sat, 27 Apr 2024 11:04:09 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> On 2024-04-26, Karl O. Pinc wrote on Fri, 26 Apr 2024
> > Guenter Milde via <doc...@li...> wrote:  
> >> On 2024-04-24, G. Branden Robinson wrote:  
> >> > At 2024-04-24T19:06:23-0000, Guenter Milde wrote:  

> >> If there are no objections, I would sacrifice the FORM FEED
> >> in favour of a simple commit test for trailing whitespace.

> ><snip>
> >    If some unrelated text might look to Emacs as a local variables
> > list, you can countermand that by inserting a form-feed character
> > (a page delimiter, see Pages) after that text.  Emacs only looks for
> > file-local variables in the last page of a file, after the last page
> > delimiter.  
> 
> > So my guess is that the line feed is a "guard" that allows RST
> > files to end in something that looks to emacs like a local variable
> > list, but is intended to be document text.  This does sound like
> > it could be useful in special edge cases.  

> How about this change then:
> 
> diff --git a/docutils/docs/ref/doctree.txt
> b/docutils/docs/ref/doctree.txt index 6798300a3..ca66796b4 100644
> --- a/docutils/docs/ref/doctree.txt
> +++ b/docutils/docs/ref/doctree.txt
> @@ -5147,8 +5147,8 @@ models of the following elements:
> `\<abbreviation>`_, .. _table of compatible image formats:
> rst/directives.html#image-formats 
>  
> -
> -..
> +.. Emacs settings
> +
>     Local Variables:
>     mode: indented-text
>     indent-tabs-mode: nil

Makes sense to me.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

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

On 2024-04-26, Karl O. Pinc wrote on Fri, 26 Apr 2024
> Guenter Milde via <doc...@li...> wrote:
>> On 2024-04-24, G. Branden Robinson wrote:
>> > At 2024-04-24T19:06:23-0000, Guenter Milde wrote:

>> >> So my question is:

>> >> * Do we want to keep the emacs variables block?

...

>> If there are no objections, I would sacrifice the FORM FEED
>> in favour of a simple commit test for trailing whitespace.

> I am no expert; note the emacs docs say:

...

><snip>
>    If some unrelated text might look to Emacs as a local variables list,
> you can countermand that by inserting a form-feed character (a page
> delimiter, see Pages) after that text.  Emacs only looks for
> file-local variables in the last page of a file, after the last page
> delimiter.

> So my guess is that the line feed is a "guard" that allows RST
> files to end in something that looks to emacs like a local variable
> list, but is intended to be document text.  This does sound like
> it could be useful in special edge cases.

Sounds reasonable. 

How about this change then:

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 6798300a3..ca66796b4 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -5147,8 +5147,8 @@ models of the following elements: `\<abbreviation>`_,
 .. _table of compatible image formats: rst/directives.html#image-formats
 
 
-
-..
+.. Emacs settings
+
    Local Variables:
    mode: indented-text
    indent-tabs-mode: nil


Regards,

Günter

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Karl O. P. <ko...@ka...>]

On Fri, 26 Apr 2024 10:56:53 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> Dear Branden,
> 
> On 2024-04-24, G. Branden Robinson wrote:
> > At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop
> > wrote:  
> >> So my question is:  
> 
> >> * Do we want to keep the emacs variables block?
> >>   Is anyone using emacs?  
> 
> > I tend to use Vim, but occasionally use emacs.  
> 
> >> * If yes, do we need the FORM FEED character
> >>   (it shows as ^L in my text editor).  
> 
> > As far as I know, this is not necessary.  As I recollect, GNU Emacs
> > scans backward through the last 3,000 bytes of the file attempting
> > to match the "Local variables:" pattern; the lack of a form feed
> > character before that text does not frustrate the search.  
> 


> AFAIK, the ^L (FORM FEED) is intended to hide the local variables away
> (maybe as a marker for some emacs-special functionality or simply by
> pushing the following lines out of view).

> If there are no objections, I would sacrifice the FORM FEED 
> in favour of a simple commit test for trailing whitespace.

I am no expert; note the emacs docs say:

The start of
the local variables list should be no more than 3000 characters from the
end of the file, and must be on the last page if the file is divided
into pages.
<snip>
   If some unrelated text might look to Emacs as a local variables list,
you can countermand that by inserting a form-feed character (a page
delimiter, see Pages) after that text.  Emacs only looks for
file-local variables in the last page of a file, after the last page
delimiter.

So my guess is that the line feed is a "guard" that allows RST
files to end in something that looks to emacs like a local variable
list, but is intended to be document text.  This does sound like
it could be useful in special edge cases.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

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

Dear Branden,

On 2024-04-24, G. Branden Robinson wrote:
> At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop wrote:
>> So my question is:

>> * Do we want to keep the emacs variables block?
>>   Is anyone using emacs?

> I tend to use Vim, but occasionally use emacs.

>> * If yes, do we need the FORM FEED character
>>   (it shows as ^L in my text editor).

> As far as I know, this is not necessary.  As I recollect, GNU Emacs
> scans backward through the last 3,000 bytes of the file attempting to
> match the "Local variables:" pattern; the lack of a form feed character
> before that text does not frustrate the search.

thanks for checking this out.

AFAIK, the ^L (FORM FEED) is intended to hide the local variables away
(maybe as a marker for some emacs-special functionality or simply by pushing
the following lines out of view).

The FORM FEED is converted to a SPACE prior to parsing as rST by Docutils.
The local variables are invisible in the output because they are in a
comment block.

The Policies mention the comment block but not the FORM FEED 
(rsp. only indirectly via the source serving as example).


If there are no objections, I would sacrifice the FORM FEED 
in favour of a simple commit test for trailing whitespace.


Günter

[Docutils-develop] [docutils:bugs] #487 Ambiguous license in test/test_utils/test_math/test__init__.py

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

Thank you for the report. 
This was an  oversight after creating the test script from a template.
In the repository, the GPL is removed for better consistency with the rest of Docutils.
For Docutils 0.21, …,  0.21.2,  both licenses are applicable.

Fixed in [r9656]



---

**[bugs:#487] Ambiguous license in test/test_utils/test_math/test__init__.py**

**Status:** open-fixed
**Created:** Wed Apr 24, 2024 08:57 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Apr 24, 2024 08:57 PM UTC
**Owner:** nobody


Dear Günter,

The header of [this file](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/test_utils/test_math/test__init__.py) says:

```python
#!/usr/bin/env python3
# :Copyright: © 2024 Günter Milde.

#             Released without warranty under the terms of the
#             GNU General Public License (v. 2 or later)

# :License: Released under the terms of the `2-Clause BSD license`_, in short:
#
#    Copying and distribution of this file, with or without modification,
#    are permitted in any medium without royalty provided the copyright
#    notice and this notice are preserved.
#    This file is offered as-is, without any warranty.
#
# .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
```

So it mentions both GPL and BSD license.

Do both licenses really apply, and if not, can the extra one be removed?




---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #487 Ambiguous license in test/test_utils/test_math/test__init__.py

[Dmitry S. <man...@us...>]

---

**[bugs:#487] Ambiguous license in test/test_utils/test_math/test__init__.py**

**Status:** open
**Created:** Wed Apr 24, 2024 08:57 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Apr 24, 2024 08:57 PM UTC
**Owner:** nobody


Dear Günter,

The header of [this file](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/test_utils/test_math/test__init__.py) says:

```python
#!/usr/bin/env python3
# :Copyright: © 2024 Günter Milde.

#             Released without warranty under the terms of the
#             GNU General Public License (v. 2 or later)

# :License: Released under the terms of the `2-Clause BSD license`_, in short:
#
#    Copying and distribution of this file, with or without modification,
#    are permitted in any medium without royalty provided the copyright
#    notice and this notice are preserved.
#    This file is offered as-is, without any warranty.
#
# .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
```

So it mentions both GPL and BSD license.

Do both licenses really apply, and if not, can the extra one be removed?




---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[G. B. R. <g.b...@gm...>]

At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop wrote:
> So my question is:
> 
> * Do we want to keep the emacs variables block?
>   Is anyone using emacs?

I tend to use Vim, but occasionally use emacs.

> * If yes, do we need the FORM FEED character
>   (it shows as ^L in my text editor).

As far as I know, this is not necessary.  As I recollect, GNU Emacs
scans backward through the last 3,000 bytes of the file attempting to
match the "Local variables:" pattern; the lack of a form feed character
before that text does not frustrate the search.

Try out the attached file.

Regards,
Branden