docutils-develop — For developer discussions of the implementation.

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

Hi Engelbert,

At 2023-08-16T10:25:19+0200, engelbert gruber wrote:
> On Wed, 16 Aug 2023 at 05:38, G. Branden Robinson <
> g.b...@gm...> wrote:
> > For those whose systems don't have 1.23.0 installed yet, the
> > groff_man_style(7) document can be read in PDF; go to page 253.
> >
> > https://www.gnu.org/software/groff/manual/groff-man-pages.pdf
> 
> did put it on my list :-)

Cool.  Let me know what points, if any, need to be clarified.

> take him by his word  submit a minimal page pointing to the macros

I guess if someone installs the Linux man-pages package without
installing groff, and they get an error message, that a distributor's
problem to sort out.

> actually in my understanding man 7 man should be the man macros
> groff_man or man_roff or man _groff should container formatter
> requests

I don't think that's correct.  My understanding is that groff man pages
got prefixes 30+ years ago so that they could be simultaneously
installed with AT&T troff.  Part of that involved giving the GNU
reimplementation of AT&T troff commands a 'g' prefix ("gtroff", "gtbl",
"geqn", and so on).  But there were also man pages for things that
weren't commands, like font(5) in Research Unix, and the macro packages,
like man(7), ms(7), and mm(7).

So for sections 5 and 7, groff decided to just use its own name as a
prefix to avoid collisions.

The practice remains useful to distinguish implementations.  For
instance, on my Debian system there are also mandoc_man(7) and
mandoc_roff(7) pages.

So both man(7) and groff_man(7) would describe the "man" macro package.
To avoid repetition, as you suggest it's better if one just points to
the other.

The page documenting formatter requests, escape sequences, and
predefined register names (as well as, in groff 1.23.0, a lot of
specification and conceptual explanation), is groff(7).

The end of the groff(1) page attempts to present groff's ~59 man pages
in an organized way so that users can find material of interest.

Regards,
Branden

[Docutils-develop] [docutils:patches] #206 Improve SmartQuote performance

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

Thank you for the patch.

I wonder, why there is a considerable performance hit  despite the documentation saying that
>The compiled versions of the most recent patterns passed to re.compile() and the module-level matching functions are cached, so programs that use only a few regular expressions at a time needn’t worry about compiling regular expressions.

and Docutils uses far less than `re._MAXCACHE == 512` regular expressions.
Maybe "re.sub" is no *module-level matching function*? OTOH, the doc says:
>Pattern.sub(repl, string, count=0)
>     Identical to the sub() function, using the compiled pattern.


The 22% refer to the parse (or more precise parse+transform) time rather than the build time in a real-world use case (as the dummy builder is more efficient than a HTML builder, say). Still, 22% of the time to create a document tree is impressive.

Could you test the attached  simplified version of your patch. 
(If the unconditional pre-compilation is considered too wasteful in case "smartquotes" are switched off, I'd rather consider a conditional import of the "smartquotes" module.)

Another improvement may be achieved by simplifying the regexps themselves: 
The current version is taken from the "SmartyPants" module that also cares for HTML input and checks for character entities like  `–` or ` `.


Attachments:

- [pre-compile-regexes-simplified.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/2d7c8b7ca3/9c1b/attachment/pre-compile-regexes-simplified.patch) (7.4 kB; text/x-patch)


---

**[patches:#206] Improve SmartQuote performance**

**Status:** open
**Group:** None
**Created:** Wed Aug 16, 2023 04:37 PM UTC by Chris Sewell
**Last Updated:** Wed Aug 16, 2023 04:37 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Pre-compile-smartquote-regexes.patch](https://sourceforge.net/p/docutils/patches/206/attachment/0001-Pre-compile-smartquote-regexes.patch) (8.3 kB; application/octet-stream)
- [sphinx-build-after.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-after.svg) (199.1 kB; image/svg+xml)
- [sphinx-build-before.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-before.svg) (282.1 kB; image/svg+xml)


Performing a representative sphinx-build (10 x docutils/docs/ref/rst/restructuredtext.txt, dummy builder), and analysing with py-spy, you can see from the attached flamegraph that the smartquote transform accouts for over 22% of the build time!

This PR attempts to improve that situation (at least down to 18%) by caching regex compilation 


---

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] #206 Improve SmartQuote performance

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

---

**[patches:#206] Improve SmartQuote performance**

**Status:** open
**Group:** None
**Created:** Wed Aug 16, 2023 04:37 PM UTC by Chris Sewell
**Last Updated:** Wed Aug 16, 2023 04:37 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Pre-compile-smartquote-regexes.patch](https://sourceforge.net/p/docutils/patches/206/attachment/0001-Pre-compile-smartquote-regexes.patch) (8.3 kB; application/octet-stream)
- [sphinx-build-after.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-after.svg) (199.1 kB; image/svg+xml)
- [sphinx-build-before.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-before.svg) (282.1 kB; image/svg+xml)


Performing a representative sphinx-build (10 x docutils/docs/ref/rst/restructuredtext.txt, dummy builder), and analysing with py-spy, you can see from the attached flamegraph that the smartquote transform accouts for over 22% of the build time!

This PR attempts to improve that situation (at least down to 18%) by caching regex compilation 


---

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[engelbert g. <eng...@gm...>]

On Wed, 16 Aug 2023 at 05:38, G. Branden Robinson <
g.b...@gm...> wrote:

> Hi Engelbert,
>
> At 2023-08-14T10:41:58+0200, engelbert gruber wrote:
> > On man 7 man (AFAIR) is a list of safe statements .sp asf
>
> Yes.  The man(7) page from the Linux man-pages project does have a list
> of "safe" formatter requests.  Long story short, the current Linux
> man-pages maintainer would like to withdraw the page and has invited me
> to submit (the equivalent of) a merge request to do so.[1]  mandoc
> maintainer Ingo Schwarze and I take a pretty different approach to the
> problem; we agree that minimal use of formatter requests, and sticking
> to the existing sets of package macros (plus a few escape sequences) is
> the most reliable route to portable man page rendering.
>



>
> That "minimal" approach also means that people writing man(7) documents
> or tools to generate them have to master much less material.
>
>
>
> For those whose systems don't have 1.23.0 installed yet, the
> groff_man_style(7) document can be read in PDF; go to page 253.
>
> https://www.gnu.org/software/groff/manual/groff-man-pages.pdf


did put it on my list :-)


>
>
> [1] "I want to kill that page"
>

take him by his word  submit a minimal page pointing to the macros

actually in my understanding man 7 man should be the man macros
groff_man or man_roff or man _groff should container formatter requests

cheers


>
> https://lore.kernel.org/linux-man/fe3...@ke.../T/#m124e9719a24560c8ed5526e7464d4a4c311008a7
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

Hi Engelbert,

At 2023-08-14T10:41:58+0200, engelbert gruber wrote:
> On man 7 man (AFAIR) is a list of safe statements .sp asf

Yes.  The man(7) page from the Linux man-pages project does have a list
of "safe" formatter requests.  Long story short, the current Linux
man-pages maintainer would like to withdraw the page and has invited me
to submit (the equivalent of) a merge request to do so.[1]  mandoc
maintainer Ingo Schwarze and I take a pretty different approach to the
problem; we agree that minimal use of formatter requests, and sticking
to the existing sets of package macros (plus a few escape sequences) is
the most reliable route to portable man page rendering.

That "minimal" approach also means that people writing man(7) documents
or tools to generate them have to master much less material.

> which I tried to limit the writer output man 7 groff_man I learned
> only recent

In my opinion that man page became a more helpful resource with the
release of groff 1.22.4 in December 2018, and in groff 1.23.0 (released
5 July) there is a new groff_man_style(7) page that is written for
newcomers, and presumes as little knowledge of typesetting and *roff
programs as possible.  In full disclosure, much of it is my own work.

For those whose systems don't have 1.23.0 installed yet, the
groff_man_style(7) document can be read in PDF; go to page 253.

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

> Along the line of the discussion we had with the latex writer … target
> the structure or use only the type setting (line drawing)
> 
> Structure it was/is

If I'm understanding you correctly, I agree with the choice.  You want
to convert ReStructured Text into high-level structural markup as much
as the target language allows, and get involved with fiddly details of
typesetting as little as possible.

Regards,
Branden

[1] "I want to kill that page"

https://lore.kernel.org/linux-man/fe3...@ke.../T/#m124e9719a24560c8ed5526e7464d4a4c311008a7

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[engelbert g. <eng...@gm...>]

On man 7 man (AFAIR) is a list of safe statements .sp asf which I tried to
limit the writer output man 7 groff_man I learned only recent

Along the line of the discussion we had with the latex writer … target the
structure or use only the type setting (line drawing)

Structure it was/is

G. Branden Robinson <g.b...@gm...> schrieb am So. 13. Aug.
2023 um 12:11:

> At 2023-08-13T09:30:40-0000, Guenter Milde via Docutils-develop wrote:
> > Hi Branden,
> >
> > welcom to the Docutils developers list.
>
> Thank you!  Glad to be here.
>
> > On 2023-08-12, G. Branden Robinson wrote:
> > > 1.  mandoc(1)'s documentation takes a fairly partisan attitude
> > >     toward *roff macro languages; it endorses only mdoc(7),
> > >     deprecates man(7), and makes no attempt to support anything
> > >     else.
> >
> > If I got it right, "mandoc" tries to provide a "semantic markup" layer
> > for man pages.
>
> I don't believe that is correct.  First, there are a couple of things
> called "mandoc".  It is one way to spell a groff(1) (or troff(1), or
> nroff(1)) command-line option and argument combination, as in
>
> groff -mandoc foo.1 bar.2
>
> for example.  This loads a macro file called "andoc.tmac", which uses
> some *roff language features to relieve man(1) programs from having to
> read man page sources to determine which macro language, man(7) or
> mdoc(7), the pages use.  This feature dates back to 1991.
>
> https://git.savannah.gnu.org/cgit/groff.git/tree/ChangeLog.115#n3526
>
> Around 2008, Kristaps Dzonsons of OpenBSD started the "mdocml" project,
> an effort to replace the groff (and any other troff) formatter for the
> purpose of man page rendering.  In 2009, this project made the decision
> to name its formatter program "mandoc", and apparently later that year
> Ingo Schwarze decided to rename the entire project after the command.
>
> https://mandoc.bsd.lv/devhistory.html
>
> mandoc, in either meaning, is not a macro language specification or a
> semantic markup layer.
>
> mdoc(7), which in its present form originates in 4.3BSD-Reno (1990),[1]
> is an alternative to the man(7) macro language for *roff.  mdoc(7)'s
> emphasis is indeed on semantic markup.
>
> However, mdoc(7) is not purely semantic, and man(7) is not purely
> presentational.
>
> > Docutils aims to provide an alternative easy-to-read semantic markup
> > language for man page sources which works on a wide range of systems.
>
> Acknowledged.
>
> > Sticking to the subset supported by groff, mandoc, and Heirloom
> > Doctools seems to be a reasonable aproach then.
>
> Cool.  That baseline will avoid some headaches and ugliness.  I can help
> with translation to either macro package, but as "rst2man" has "man" in
> its name, and the man(7) and mdoc(7) lexicons cannot be mixed in a
> single document, is it fair to say that Docutils would like to improve
> its production of output in the man(7) language where feasible?
>
> An "rst2mdoc" is, of course, conceivable.
>
> Thank you for putting me in the picture.
>
> Regards,
> Branden
>
> [1] Ingo clarified the history recently for me.  The mdoc(7) in
>     4.3BSD-Reno is actually the third version of the macro language (not
>     counting a few extensions later added by the groff and mdocml/mandoc
>     projects).  The second version is known as "old mdoc" and while
>     groff, at least, still carries support for it, I don't know if any
>     pages in that form of the language survive anywhere.  The first
>     version of mdoc, is, apparently, completely lost.
>
> [2]
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/share/tmac/tmac.doc.old
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

At 2023-08-13T09:30:40-0000, Guenter Milde via Docutils-develop wrote:
> Hi Branden,
> 
> welcom to the Docutils developers list.

Thank you!  Glad to be here.

> On 2023-08-12, G. Branden Robinson wrote:
> > 1.  mandoc(1)'s documentation takes a fairly partisan attitude
> >     toward *roff macro languages; it endorses only mdoc(7),
> >     deprecates man(7), and makes no attempt to support anything
> >     else.
> 
> If I got it right, "mandoc" tries to provide a "semantic markup" layer
> for man pages.

I don't believe that is correct.  First, there are a couple of things
called "mandoc".  It is one way to spell a groff(1) (or troff(1), or
nroff(1)) command-line option and argument combination, as in

groff -mandoc foo.1 bar.2

for example.  This loads a macro file called "andoc.tmac", which uses
some *roff language features to relieve man(1) programs from having to
read man page sources to determine which macro language, man(7) or
mdoc(7), the pages use.  This feature dates back to 1991.

https://git.savannah.gnu.org/cgit/groff.git/tree/ChangeLog.115#n3526

Around 2008, Kristaps Dzonsons of OpenBSD started the "mdocml" project,
an effort to replace the groff (and any other troff) formatter for the
purpose of man page rendering.  In 2009, this project made the decision
to name its formatter program "mandoc", and apparently later that year
Ingo Schwarze decided to rename the entire project after the command.

https://mandoc.bsd.lv/devhistory.html

mandoc, in either meaning, is not a macro language specification or a
semantic markup layer.

mdoc(7), which in its present form originates in 4.3BSD-Reno (1990),[1]
is an alternative to the man(7) macro language for *roff.  mdoc(7)'s
emphasis is indeed on semantic markup.

However, mdoc(7) is not purely semantic, and man(7) is not purely
presentational.

> Docutils aims to provide an alternative easy-to-read semantic markup
> language for man page sources which works on a wide range of systems.

Acknowledged.

> Sticking to the subset supported by groff, mandoc, and Heirloom
> Doctools seems to be a reasonable aproach then.

Cool.  That baseline will avoid some headaches and ugliness.  I can help
with translation to either macro package, but as "rst2man" has "man" in
its name, and the man(7) and mdoc(7) lexicons cannot be mixed in a
single document, is it fair to say that Docutils would like to improve
its production of output in the man(7) language where feasible?

An "rst2mdoc" is, of course, conceivable.

Thank you for putting me in the picture.

Regards,
Branden

[1] Ingo clarified the history recently for me.  The mdoc(7) in
    4.3BSD-Reno is actually the third version of the macro language (not
    counting a few extensions later added by the groff and mdocml/mandoc
    projects).  The second version is known as "old mdoc" and while
    groff, at least, still carries support for it, I don't know if any
    pages in that form of the language survive anywhere.  The first
    version of mdoc, is, apparently, completely lost.

[2] https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/share/tmac/tmac.doc.old

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

Hi Branden,

welcom to the Docutils developers list.

On 2023-08-12, G. Branden Robinson wrote:

> I just subscribed to this list.  I work on groff and would like to help
> improve rst2man's output.

This is good news.

> 1.  mandoc(1)'s documentation takes a fairly partisan attitude toward
>     *roff macro languages; it endorses only mdoc(7), deprecates man(7),
>     and makes no attempt to support anything else.

If I got it right, "mandoc" tries to provide a "semantic markup" layer
for man pages.

Docutils aims to provide an alternative easy-to-read semantic markup
language for man page sources which works on a wide range of systems.

> 2.  Ingo Schwarze has been the mandoc(1) (formerly "mdocml" project)
>     maintainer for many years now.  He is also a groff contributor and
>     committer and we have worked productively together since 2017 to
>     better establish what it means to have portable man pages.

> 3.  There is no such thing as a "standard extension" to man(7), nor even
>     a standard "core" of man(7)--nor of mdoc(7), for that matter.  That
>     is because these languages have never been standardized.  *roff
>     itself has never been standardized, either.

> 4.  `UR` and `UE` _are_ GNU extensions to man(7), two of several.  They
>     have been supported by groff since 2009, and by mandoc(1) for nearly
>     10 years.[1]

> Unless one is targeting old proprietary/commercial Unix systems, there
> is little reason not to use the dialect of man(7) presented in the
> groff_man(7) page, complete with extensions--with the possible exception
> of the brand-new `MR` macro, a groff 1.23.0 arrival.  

Fine.

> My impression is that nearly all man page viewing that is observable is
> done via groff or mandoc(1).  Heirloom Doctools troff is probably in
> third place, but it too supports groff's man(7) extensions, since it
> incorporates (an old version of) groff's an-ext.tmac file.

Sticking to the subset supported by groff, mandoc, and Heirloom Doctools
seems to be a reasonable aproach then.

Thanks again

Günter

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

Hi everybody,

I just subscribed to this list.  I work on groff and would like to help
improve rst2man's output.

On 2023-08-10 12:32:39, Dmitry Shachnev wrote:
> On Thu, Aug 10, 2023 at 10:41:03AM -0000, Guenter Milde via
> Docutils-develop wrote:
> > On 2023-08-09, Dmitry Shachnev wrote:
> > > On Tue, Aug 08, 2023 at 07:58:28AM -0000, Guenter Milde via
> > > Docutils-develop wrote:
> >
> > >> > Another possibility would be using the `.UR` / `.UE` macros to
> > >> > produce hyperlinks. They are described in groff_man(7) man
> > >> > page.
> > ...
> > >> How would this be handled by other (t)roff converters?
> >
> > > What other implementations do we want to support?
> >
> > I remember discussions about the BSD versions but don't remember the
> > outcome.  Engelbert is our specialist for the man writer.
> 
> FreeBSD's and OpenBSD's man(7) mention the .UR / .UE macros:
> 
>      UR  Begin a uniform resource identifier block.  This is a
>          non-standard GNU extension.  It has the following syntax:
> 
>            .UR uri
>            link description to be shown
>            .UE

This page is elsewhere available as mandoc_man(7), which reveals its
origin.  There are some things to know about the material quoted above.

1.  mandoc(1)'s documentation takes a fairly partisan attitude toward
    *roff macro languages; it endorses only mdoc(7), deprecates man(7),
    and makes no attempt to support anything else.

2.  Ingo Schwarze has been the mandoc(1) (formerly "mdocml" project)
    maintainer for many years now.  He is also a groff contributor and
    committer and we have worked productively together since 2017 to
    better establish what it means to have portable man pages.

3.  There is no such thing as a "standard extension" to man(7), nor even
    a standard "core" of man(7)--nor of mdoc(7), for that matter.  That
    is because these languages have never been standardized.  *roff
    itself has never been standardized, either.

4.  `UR` and `UE` _are_ GNU extensions to man(7), two of several.  They
    have been supported by groff since 2009, and by mandoc(1) for nearly
    10 years.[1]

Unless one is targeting old proprietary/commercial Unix systems, there
is little reason not to use the dialect of man(7) presented in the
groff_man(7) page, complete with extensions--with the possible exception
of the brand-new `MR` macro, a groff 1.23.0 arrival.  On many of those
same proprietary/commercial Unix systems, mdoc(7) will not be available
at all; that macro package was developed by the UC Berkeley Computing
Science Research Group for release in 4.3BSD-Reno (1990), whereas
proprietary/commercial Unices were in the Unix System V line of descent.

groff and mandoc(1) are both of course available for any flavor of Unix,
but such proprietary/commercial Unices as still survive often exhibit
diffidence about incorporating them.  On the bright side, Solaris 11
replaced its proprietary troff with groff, HP-UX has been packaging
groff as an add-on for years (providing 1.23.0 packages within days of
upstream release), and Mike Fulton of IBM has been in touch with groff's
mailing list to help us address portability issues to AIX/z/OS.  (There
appear to be no serious problems, thanks to the presence of an extensive
POSIX-like layer, much as we can say for Cygwin and MSYS2 on Windows.)

The gr...@gn... mailing list is the Internet's water cooler for nearly
all public discussion of roff/nroff/troff/groff, leaving aside social
media outlets like Reddit and StackExchange which serve as Q&A forums.

My impression is that nearly all man page viewing that is observable is
done via groff or mandoc(1).  Heirloom Doctools troff is probably in
third place, but it too supports groff's man(7) extensions, since it
incorporates (an old version of) groff's an-ext.tmac file.

> Although, they also say "Use the mdoc(7) language, instead", and
> mdoc(7) does not mention these macros.

mdoc(7) uses a _completely different lexicon_ of macro names.  There is
literally no overlap between the two.  mdoc(7) names are spelled with an
initial capital letter and lowercase second letter; man(7) names are
spelled with two capital letters.  These are what you might call mere
conventions, but they have been rigidly held to.  The only exception
known to me is now-dead commercial Unix system, DEC Ultrix; it had `Ds`
and `De` macros for setting "displays", a concept man(7) and mdoc(7)
don't otherwise use.

mdoc(7)'s macro repertoire is many times the size of man(7)'s, and it
also has a unique approach among all *roff macro packages known to me
regarding macro argument handling.

In a footnote, I'll quote explanation of this in the groff_mdoc(7) page
in the groff 1.23.0 release.[2]

At any rate, a man page cannot mix man(7) and mdoc(7) macro names and
hope to render correctly.

> The same for .EX / .EE which we started using recently.

By one measure, `EX` and `EE` are of the same vintage as `UR` and `UE`;
they have been supported in groff releases for 14 years, and by
mandoc(1) for over 11 years.[3]  About a year ago, Ingo even conceded
their utility.[4]  :)

By another measure, `EX` and `EE` are 37 years old, since they appeared
in Ninth Edition Unix man(7).[5]

groff's man(7) extension macros are very permissively licensed.  No page
author that is concerned about their document remaining portable is
subject to any legal restriction on copying and using them.[6]

If there's anything I can shed light on, please ask.

Regards,
Branden

[1] https://cvsweb.bsd.lv/mandoc/man.c?sortby=date (revision 1.120)

[2] [UTF-8 follows]

    Most of mdoc’s general text and manual domain macros parse their
    argument lists for callable macro names.  This means that an
    argument in the list matching a general text or manual domain macro
    name (and defined to be callable) will be called with the remaining
    arguments when it is encountered.  In such cases, the argument,
    although the name of a macro, is not preceded by a dot.  Macro calls
    can thus be nested.  This approach to macro argument processing is a
    unique characteristic of the mdoc package, not a general feature of
    roff syntax.

    For example, the option macro, .Op, may call the flag and argument
    macros, .Fl and .Ar, to specify an optional flag with an argument.
          .Op Fl s Ar bytes      → [-s bytes]
    To prevent a word from being interpreted as a macro name, precede it
    with the dummy character.
          .Op \&Fl s \&Ar bytes  → [Fl s Ar bytes]

    In this document, macros whose argument lists are parsed for
    callable arguments are referred to as parsed, and those that may be
    called from an argument list are referred to as callable.  This
    usage is a technical faux pas, since all mdoc macros are in fact
    interpreted (unless prevented with ‘\&’), but as it is cumbersome to
    constantly refer to macros as “being able to call other macros”, we
    employ the term “parsed” instead.  Except where explicitly stated,
    all mdoc macros are parsed and callable.

    In the following, we term an mdoc macro that starts a line (with a
    leading dot) a command if a distinction from those appearing as
    arguments of other macros is necessary.

[3] https://cvsweb.bsd.lv/mandoc/man.c?sortby=date (revision 1.116)
[4] https://lists.gnu.org/archive/html/groff/2022-08/msg00081.html
[5] https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html
[6] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-ext.tmac?h=1.23.0

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[Dmitry S. <mi...@gm...>]

On Thu, Aug 10, 2023 at 10:41:03AM -0000, Guenter Milde via Docutils-develop wrote:
> On 2023-08-09, Dmitry Shachnev wrote:
> > On Tue, Aug 08, 2023 at 07:58:28AM -0000, Guenter Milde via Docutils-develop wrote:
> 
> >> > Another possibility would be using the `.UR` / `.UE` macros to produce
> >> > hyperlinks. They are described in groff_man(7) man page.
> ...
> >> How would this be handled by other (t)roff converters?
> 
> > What other implementations do we want to support?
> 
> I remember discussions about the BSD versions but don't remember the outcome.
> Engelbert is our specialist for the man writer.

FreeBSD's and OpenBSD's man(7) mention the .UR / .UE macros:

     UR	  Begin	a uniform resource identifier block.  This is a	non-standard
          GNU extension.  It has the following syntax:

                .UR uri
                link description to be shown
                .UE

Although, they also say "Use the mdoc(7) language, instead", and mdoc(7) does
not mention these macros.

The same for .EX / .EE which we started using recently.

--
Dmitry Shachnev

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

On 2023-08-09, Dmitry Shachnev wrote:
> On Tue, Aug 08, 2023 at 07:58:28AM -0000, Guenter Milde via Docutils-develop wrote:

>> > Another possibility would be using the `.UR` / `.UE` macros to produce
>> > hyperlinks. They are described in groff_man(7) man page.
...
>> How would this be handled by other (t)roff converters?

> What other implementations do we want to support?

I remember discussions about the BSD versions but don't remember the outcome.
Engelbert is our specialist for the man writer.

Günter

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

[Dmitry S. <mi...@gm...>]

Hi Günter!

On Tue, Aug 08, 2023 at 07:58:28AM -0000, Guenter Milde via Docutils-develop wrote:
> > Another possibility would be using the `.UR` / `.UE` macros to produce
> > hyperlinks. They are described in groff_man(7) man page.
> >
> > The macros themselves are supported by groff since 2007, but the next
> > groff version will enable them for terminal devices (using OSC 8 escape
> > sequence). See groff commit 9dadd72a3c9cd40c20e06e80e918a68badf83b0f.
> >
> > Debian's groff version 1.23.0-1 (and newer) already includes support
> > for them.
>
> How would this be handled by other (t)roff converters?

What other implementations do we want to support?

I thought we are already using some groff-specific macros, but I may be
wrong.

--
Dmitry Shachnev

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

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

if you send some pointers to places using the manpage-writer i could test too ... OTOH i check my linux systems packages


---

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

**Status:** open
**Group:** None
**Labels:** manpage 
**Created:** Sat Jul 29, 2023 05:05 PM UTC by Dmitry Shachnev
**Last Updated:** Sat Aug 05, 2023 04:41 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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

On 2023-08-05, Dmitry Shachnev via Docutils-develop wrote:

> > Currently, the manpage writer writes a reference like `ALT TEXT <URL>`
> > as just `ALT TEXT`, with alternate font. Would it be better to render
> > it as, for example, `ALT TEXT [URL]`, so the information is not lost?

...

> Another possibility would be using the `.UR` / `.UE` macros to produce
> hyperlinks. They are described in groff_man(7) man page.

> The macros themselves are supported by groff since 2007, but the next
> groff version will enable them for terminal devices (using OSC 8 escape
> sequence). See groff commit 9dadd72a3c9cd40c20e06e80e918a68badf83b0f.

> Debian's groff version 1.23.0-1 (and newer) already includes support
> for them.

How would this be handled by other (t)roff converters?

Günter

[Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

That is my current solution, seams to work on my ubuntu's man and mandoc viewing.


---

**[feature-requests:#72] rst2man: Show reference targets**

**Status:** open
**Group:** Default
**Created:** Wed Aug 26, 2020 03:47 PM UTC by Petr Viktorin
**Last Updated:** Sat Aug 05, 2023 04:24 PM UTC
**Owner:** engelbert gruber


Currently, the manpage writer writes a reference like `ALT TEXT <URL>` as just `ALT TEXT`, with alternate font.
Would it be better to render it as, for example, `ALT TEXT [URL]`, so the information is not lost?


---

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] Re: #72 rst2man: Show reference targets

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

Another possibility would be using the `.UR` / `.UE` macros to produce hyperlinks. They are described in groff_man(7) man page.

The macros themselves are supported by groff since 2007, but the next groff version will enable them for terminal devices (using OSC 8 escape sequence). See groff commit 9dadd72a3c9cd40c20e06e80e918a68badf83b0f.

Debian's groff version 1.23.0-1 (and newer) already includes support for them.


---

**[feature-requests:#72] rst2man: Show reference targets**

**Status:** open
**Group:** Default
**Created:** Wed Aug 26, 2020 03:47 PM UTC by Petr Viktorin
**Last Updated:** Fri Aug 04, 2023 10:10 AM UTC
**Owner:** engelbert gruber


Currently, the manpage writer writes a reference like `ALT TEXT <URL>` as just `ALT TEXT`, with alternate font.
Would it be better to render it as, for example, `ALT TEXT [URL]`, so the information is not lost?


---

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

On 2023-08-04, engelbert gruber via Docutils-develop wrote:

> **[feature-requests:#72] rst2man: Show reference targets**
> **Created:** Wed Aug 26, 2020 03:47 PM UTC by Petr Viktorin

> Currently, the manpage writer writes a reference like `ALT TEXT <URL>`
> as just `ALT TEXT`, with alternate font. Would it be better to render
> it as, for example, `ALT TEXT [URL]`, so the information is not lost?


> line of thought 

> * Reading a manpage  on screen in a terminal is like a printout 
> * printing links at the end, in or near section SEE ALSO might be far away

> plan

> * printing in place the one without label
> * printing at end of paragraph for labeled urls ?

The `target-notes`__ directive creates a footnote for each external
target in the text at the place where it occures in the source, and
corresponding footnote references after each reference.

However the distinction is not done by labeled vs. anonymous links but by
explicit vs. implicit hyperlink targets::
    
  Inlined targets like `du <ex1>`_ do not appear in the footnotes.

  External targets  like_ this are collected.
  Also `anonymous targets`__
  
  .. _like: ex2
  __ ex3
  
  .. target-notes::

__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#target-footnotes


Suggestion:

* Print links with `implicit hyperlink targets 
  <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
  #implicit-hyperlink-targets>`_ including the target in ``[]`` or
  ``<>``, whatever is more common in man pages).
 
* Add a paragraph recommending the "target-notes" directive for man
  pages with explicit links to the manpage writer documentation.
  
  The "target-notes" directive allows custom placement of the footnotes
  containing the link targets.
  
This gives document authors a choice for link placement.
(Currently, the "target-notes" directive can only be used once in a document,
subsequent uses repeat the complete list with new footnote numbers.)  

Günter     

[Docutils-develop] [docutils:feature-requests] Re: #72 rst2man: Show reference targets

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

line of thought 

* Reading a manpage  on screen in a terminal is like a printout 
* printing links at the end, in or near section SEE ALSO might be far away

plan

* printing in place the one without label
* printing at end of paragraph for labeled urls ?


---

**[feature-requests:#72] rst2man: Show reference targets**

**Status:** open
**Group:** Default
**Created:** Wed Aug 26, 2020 03:47 PM UTC by Petr Viktorin
**Last Updated:** Sat May 20, 2023 08:49 PM UTC
**Owner:** engelbert gruber


Currently, the manpage writer writes a reference like `ALT TEXT <URL>` as just `ALT TEXT`, with alternate font.
Would it be better to render it as, for example, `ALT TEXT [URL]`, so the information is not lost?


---

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] #458 Two issues regarding manpage writer and .TH

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

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



---

**[bugs:#458] Two issues regarding manpage writer and .TH**

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Mon Sep 05, 2022 11:13 AM UTC by Dmitry Shachnev
**Last Updated:** Thu Apr 20, 2023 07:47 PM UTC
**Owner:** nobody


Dear docutils developers,

I received two bug reports in Debian regarding the content of .TH macro in man pages:

First bug — https://bugs.debian.org/1016527 — asks that the value of `--date` argument be used for the third argument of `.TH`, instead of putting it on a separate line (Generated on: YYYY-MM-DD).

Second bug — https://bugs.debian.org/1018737 — asks that docutils not set fifth argument of `.TH` to empty string, but omit it completely and rely on the default value.

Please see those bugs for more detailed descriptions (and some discussion, in the first bug).


---

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...>]

patch applied , happy news considered :-)
cheers 


---

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

**Status:** open
**Group:** None
**Labels:** manpage 
**Created:** Sat Jul 29, 2023 05:05 PM UTC by Dmitry Shachnev
**Last Updated:** Sat Jul 29, 2023 10:46 PM 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:patches] #203 Catalan updates

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

some more points:

* in the docinfo, we use "authors:" and comma- or semicolon-separated author names instead of multiple instances of the "author" field,
* what is `codi-font`? (The "code" directive is semantic markup, not to be used just for a font change.)
* don't define shortcut roles (e.g. "i" for "index") -- authors can use the "role" directive to define their favourite shortcuts in the document



---

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

**Status:** open
**Group:** None
**Created:** Sun Jul 23, 2023 09:38 PM UTC by Antoni Bella Pérez
**Last Updated:** Tue Aug 01, 2023 08:27 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] Re: #203 Catalan updates

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

> Please use literal UTF-8 characters instead of \u.... 

I am aware that the ``\u...`` constructs are currently still present in ca.py as well as many other Docutils language modules.
However, a general review and update of the module seems the right time to switch to literal characters.


---

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

**Status:** open
**Group:** None
**Created:** Sun Jul 23, 2023 09:38 PM UTC by Antoni Bella Pérez
**Last Updated:** Mon Jul 31, 2023 07:25 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] #203 Catalan updates

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

Thank you for the update.
Two points:
* Please use literal UTF-8 characters instead of \u.... (This is a change of policy from 20 years ago when UTF8 was not widely supported by text editors. It makes the code easier read.)
*  Two files must be translated for each language: one in docutils/languages,  the other in docutils/parsers/rst/languages. → Could you revise both?



---

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

**Status:** open
**Group:** None
**Created:** Sun Jul 23, 2023 09:38 PM UTC by Antoni Bella Pérez
**Last Updated:** Sun Jul 23, 2023 09:38 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.

Re: [Docutils-develop] Add a new language [Valencian as a dialect of Catalan]

[Antoni B. P. <ant...@ya...>]

dilluns, 31 de juliol de 2023, a les 9:35:12 (CEST), Guenter Milde via 
Docutils-develop va escriure:
> Dear Toni, dear Docutils developers,
> 
> >> On Wed, 26 Jul 2023 Antoni Bella Pérez wrote:
> > 28 de juliol de 2023, engelbert gruber va escriure:
> On 2023-07-29, Antoni Bella Pérez wrote:
> >>>   I need help to decide what needs to be added to docutils so that
> >>> 
> >>> Valencian language be admitted as a language.
> >> 
> >> ca-va (ca_va for the module) ... looks good to me
> 
> I see a strong case for the `IETF language tag`_ "ca-valencia", with
> primary language subtag "ca" and the IETF-registered variant subtag
> "valencia". (I don't see how "ca-va" would fit in the `IETF language
> tag`_ syntax.)
> 
> .. _IETF language tag:
>     https://en.wikipedia.org/wiki/IETF_language_tag
> 
> >   'va' isn't any country, as a variant it should be 'ca-va' (without the
> > 
> > underscore), which is the translation of 'ca@va'.
> 
> We have to distinguish the tag used in the `language_code setting`_
> (which is also written to the HTML document) and the Python `language module
> name`_.
> 
> According to `BCP 47`_,
> 
>   A language tag is composed from a sequence of one or more "subtags",
>   [...]
>   distinguished and separated from other subtags in a tag by a hyphen
>   ("-", [Unicode] U+002D).
> 
>   ...
> 
>   There are different types of subtag, each of which is distinguished by
>   length, position in the tag, and content [...]
> 
>   ...
> 
>   [...] language tags and their subtags [...] are to be treated as case
>   insensitive
> 
> The `docutils.languages.LanguageImporter` selects a matching language
> module.
> 
> "Docutils Internationalization" describes how to get a matching Python
> `language module name`_:
> 
> * For case insensitivity, we use only lowercase in the module name.
> * Subtags are separated from primary tags by underscores instead of
>   hyphens to conform to Python naming rules.
> 
> 
> For Valencian, the module name would become ``ca_valencia.py``.
> 
> .. _language_code setting:
>    https://docutils.sourceforge.io/docs/user/config.html#language-code
> .. _language module name:
>   
> https://docutils.sourceforge.io/docs/howto/i18n.html#language-module-names
> .. _BCP 47:
>     https://www.rfc-editor.org/rfc/bcp/bcp47.txt
> 
> >   Can docutils support 'ca-va'?
> 
> Only, if "ca-valencia" is generally unacceptable and there is a
> convincing case and consensus for using "ca-va" instead.
> 
> With Docutils 0.20, the current LanguageImporter code, both "ca-valencia"
> and "ca-va" can be used and automatically selects the Catalan language
> module(s) ``ca.py``. The "html5" writer uses the "language-code" setting
> unchanged, e.g.::
> 
>   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ca-va" lang="ca-va">
> 
> >   Note you that if the country is added it would be 'ca-va_es' (it is only
> > 
> > presented in order to understand the subject) which is not desired by any
> > side.
> 
> Note, that with "ca-valencia", the canonical IETF tag including would
> become "ca-ES-valencia" as the subtag order is fixed and "variant" comes
> after "region".
> 
> Docutils would look for "ca_es_valencia", "ca_es.py", "ca_valencia.py",
> and "ca.py" language module(s) and use the first match.
> 
> >>> language be admitted as a language. As a note, I would like to state
> >>> 
> >>> that we reuse Catalan as much as possible:
> >>>   - The 'ca' translations in docutils too - no need to touch them
> 
> ...
> 
> >>>   With all this, how do you see it?
> 
> If there is no difference between Catalan and Valencian in the
> translations in "docutils/languages/ca.py" and
> "docutils/parsers/rst/languages/ca.py", using "ca-va" or "ca-valencia"
> should work out of the box since Docutils 0.10 (2012-12-16).
> 
> >>>   The reason is to be able to generate content with Sphinx.
> 
> I cannot tell about the Sphinx language features.
> 
> 
> Hope this helps,
> 
> Günter
> 

 Hi Günter and developers, thanks to all for your time

  Now, I prefer to use 'ca_valencia' in the docutils to follow the standard 
and, I will initiate the requirement within the Valencian community to make 
the change to two letters in the IETF.

  Can you enable it? 'Catalan (Valencian)' - 'ca_valencia'

  In Sphinx they have the requirement that the language be supported in the 
docutils, it won't be a problem.

  Remember: #203 Catalan updates https://sourceforge.net/p/docutils/patches/
203/ 

  Regards
  Toni
-- 
Dubta que les estrelles siguin foc.
Dubta que el Sol es mogui.
Dubta que la veritat sigui mentida.
Però no dubtis mai que t'estimo.
	- William Shakespeare

No se n'ha de posar massa
	- A grandmother on the TV show "Las recetas de Julie"

Re: [Docutils-develop] Add a new language [Valencian as a dialect of Catalan]

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

Dear Toni, dear Docutils developers,

>> On Wed, 26 Jul 2023 Antoni Bella Pérez wrote:
> 28 de juliol de 2023, engelbert gruber va escriure:
On 2023-07-29, Antoni Bella Pérez wrote:

>>>   I need help to decide what needs to be added to docutils so that
>>> Valencian language be admitted as a language.

>> ca-va (ca_va for the module) ... looks good to me

I see a strong case for the `IETF language tag`_ "ca-valencia", with
primary language subtag "ca" and the IETF-registered variant subtag
"valencia". (I don't see how "ca-va" would fit in the `IETF language
tag`_ syntax.)

.. _IETF language tag:
    https://en.wikipedia.org/wiki/IETF_language_tag

>   'va' isn't any country, as a variant it should be 'ca-va' (without the 
> underscore), which is the translation of 'ca@va'.

We have to distinguish the tag used in the `language_code setting`_
(which is also written to the HTML document) and the Python `language module
name`_.

According to `BCP 47`_, 

  A language tag is composed from a sequence of one or more "subtags",
  [...] 
  distinguished and separated from other subtags in a tag by a hyphen
  ("-", [Unicode] U+002D).
  
  ...
  
  There are different types of subtag, each of which is distinguished by
  length, position in the tag, and content [...]

  ...
  
  [...] language tags and their subtags [...] are to be treated as case
  insensitive

The `docutils.languages.LanguageImporter` selects a matching language
module.

"Docutils Internationalization" describes how to get a matching Python
`language module name`_:

* For case insensitivity, we use only lowercase in the module name.
* Subtags are separated from primary tags by underscores instead of
  hyphens to conform to Python naming rules.


For Valencian, the module name would become ``ca_valencia.py``.
     
.. _language_code setting:
   https://docutils.sourceforge.io/docs/user/config.html#language-code
.. _language module name:   
   https://docutils.sourceforge.io/docs/howto/i18n.html#language-module-names
.. _BCP 47: 
    https://www.rfc-editor.org/rfc/bcp/bcp47.txt


>   Can docutils support 'ca-va'?

Only, if "ca-valencia" is generally unacceptable and there is a
convincing case and consensus for using "ca-va" instead.

With Docutils 0.20, the current LanguageImporter code, both "ca-valencia"
and "ca-va" can be used and automatically selects the Catalan language
module(s) ``ca.py``. The "html5" writer uses the "language-code" setting
unchanged, e.g.::

  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ca-va" lang="ca-va">


>   Note you that if the country is added it would be 'ca-va_es' (it is only 
> presented in order to understand the subject) which is not desired by any 
> side.

Note, that with "ca-valencia", the canonical IETF tag including would
become "ca-ES-valencia" as the subtag order is fixed and "variant" comes
after "region".

Docutils would look for "ca_es_valencia", "ca_es.py", "ca_valencia.py",
and "ca.py" language module(s) and use the first match.

>>> language be admitted as a language. As a note, I would like to state
>>> that we reuse Catalan as much as possible:
>>>   - The 'ca' translations in docutils too - no need to touch them

...

>>>   With all this, how do you see it?

If there is no difference between Catalan and Valencian in the
translations in "docutils/languages/ca.py" and 
"docutils/parsers/rst/languages/ca.py", using "ca-va" or "ca-valencia"
should work out of the box since Docutils 0.10 (2012-12-16).

>>>   The reason is to be able to generate content with Sphinx.

I cannot tell about the Sphinx language features.


Hope this helps,

Günter