bug#52126: Problematic characters in info node names

bug#52126: Problematic characters in info node names

[Stefan Kangas]

admin/release-process says:

** Manuals
Check for node names using problematic characters:
  find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
Sadly makeinfo does not warn about such characters.

Running that gives me some matches:

doc/misc/modus-themes.texi:@node Advanced customization (do-it-yourself)
doc/misc/modus-themes.texi:@node Per-theme customization settings (DIY)
doc/misc/modus-themes.texi:@node Case-by-case face specs using the
themes' palette (DIY)
doc/misc/modus-themes.texi:@node Face specs at scale using the themes'
palette (DIY)
doc/misc/modus-themes.texi:@node Remap face with local value (DIY)
doc/misc/modus-themes.texi:@node Cycle through arbitrary colors (DIY)
doc/misc/modus-themes.texi:@node Override colors (DIY)
doc/misc/modus-themes.texi:@node Override color saturation (DIY)
doc/misc/modus-themes.texi:@node Font configurations for Org and others (DIY)
doc/misc/modus-themes.texi:@node Configure bold and italic faces (DIY)
doc/misc/modus-themes.texi:@node Custom Org user faces (DIY)
doc/misc/modus-themes.texi:@node Update Org block delimiter fontification (DIY)
doc/misc/modus-themes.texi:@node Measure color contrast (DIY)
doc/misc/modus-themes.texi:@node Load theme depending on time of day (DIY)
doc/misc/modus-themes.texi:@node Backdrop for pdf-tools (DIY)
doc/misc/modus-themes.texi:@node Decrease mode line height (DIY)
doc/misc/modus-themes.texi:@node A theme-agnostic hook for theme loading (DIY)
doc/misc/modus-themes.texi:@node Note on EWW and Elfeed fonts (SHR fonts)
doc/misc/modus-themes.texi:@node Frequently Asked Questions (FAQ)
doc/misc/org.texi:@node Hooks (2)

However, there are no instructions for what to do about these cases.

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 26 Nov 2021 16:24:15 +0100
> 
> admin/release-process says:
> 
> ** Manuals
> Check for node names using problematic characters:
>   find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
> Sadly makeinfo does not warn about such characters.
> 
> Running that gives me some matches:

Please report to the respective developers, but other than that, we
don't care too much.  It isn't a grave problem, and in practice slmost
never causes any trouble.

> However, there are no instructions for what to do about these cases.

There cannot be any instructions, since the manual authors should
rewrite the relevant parts not to use those characters, if possible.

Thanks.

bug#52126: Problematic characters in info node names

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> ** Manuals
> Check for node names using problematic characters:
>   find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
> Sadly makeinfo does not warn about such characters.
>
> Running that gives me some matches:
>
> doc/misc/modus-themes.texi:@node Advanced customization (do-it-yourself)
> doc/misc/modus-themes.texi:@node Per-theme customization settings (DIY)

(etc)

I think this has to be fixed in the Modus manual, so I've added
Protesilaos to the CCs.  (The issue is that parentheses aren't valid in
texinfo node names, apparently.)

> doc/misc/org.texi:@node Hooks (2)

And in the Org manual, so I've added Kyle to the CCs, too.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#52126: Problematic characters in info node names

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> ** Manuals
>> Check for node names using problematic characters:
>>   find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
>> Sadly makeinfo does not warn about such characters.

Did something change here since the above note in admin/release-process
was written in 2013 (commit 16bcc96df4)?

I read in (info "(texinfo) Node Line Requirements") that:

   * Unfortunately, you cannot reliably use periods, commas, or colons
     within a node name; these can confuse the Info reader.  Also, a
     node name may not start with a left parenthesis preceding a right
     parenthesis, as in '(not)allowed', since this syntax is used to
     specify an external manual.  (Perhaps these limitations will be
     removed some day.)

     'makeinfo' warns about such problematic usage in node names, menu
     items, and cross-references.  If you don't want to see the
     warnings, you can set the customization variable
     'INFO_SPECIAL_CHARS_WARNING' to '0' (*note Other Customization
     Variables::).

(Though I can't see any warnings produced when running "make info" in a
fresh tree.)

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 29 Nov 2021 09:44:17 -0800
> Cc: 52126@debbugs.gnu.org, Protesilaos Stavrou <info@protesilaos.com>,
>  Kyle Meyer <kyle@kyleam.com>, Glenn Morris <rgm@gnu.org>
> 
> I read in (info "(texinfo) Node Line Requirements") that:
> 
>    * Unfortunately, you cannot reliably use periods, commas, or colons
>      within a node name; these can confuse the Info reader.  Also, a
>      node name may not start with a left parenthesis preceding a right
>      parenthesis, as in '(not)allowed', since this syntax is used to
>      specify an external manual.  (Perhaps these limitations will be
>      removed some day.)

This is mainly because of the stand-alone Info reader.  The Emacs Info
mode copes with these characters in node names much better.

So yes, it is desirable to avoid them, but it isn't a catastrophe if
they are there.

bug#52126: Problematic characters in info node names

[Protesilaos Stavrou]

On 2021-11-29, 19:52 +0200, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Mon, 29 Nov 2021 09:44:17 -0800
>> Cc: 52126@debbugs.gnu.org, Protesilaos Stavrou <info@protesilaos.com>,
>>  Kyle Meyer <kyle@kyleam.com>, Glenn Morris <rgm@gnu.org>
>> 
>> I read in (info "(texinfo) Node Line Requirements") that:
>> 
>>    * Unfortunately, you cannot reliably use periods, commas, or colons
>>      within a node name; these can confuse the Info reader.  Also, a
>>      node name may not start with a left parenthesis preceding a right
>>      parenthesis, as in '(not)allowed', since this syntax is used to
>>      specify an external manual.  (Perhaps these limitations will be
>>      removed some day.)
>
> This is mainly because of the stand-alone Info reader.  The Emacs Info
> mode copes with these characters in node names much better.
>
> So yes, it is desirable to avoid them, but it isn't a catastrophe if
> they are there.

Thanks!

I just removed the problematic characters from my repo.  Though this
change will be brought into emacs.git as part of my next tagged release
(in a few weeks).

Two questions then:

1. Do you want me to change this now on the trunk?
2. This affects the emacs-28 branch.  Should I patch that as well?

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: larsi@gnus.org, Stefan Kangas <stefan@marxist.se>,
>  52126@debbugs.gnu.org, kyle@kyleam.com, rgm@gnu.org
> Date: Mon, 29 Nov 2021 20:04:37 +0200
> 
> 1. Do you want me to change this now on the trunk?

Yes.

> 2. This affects the emacs-28 branch.  Should I patch that as well?

It's up to you.  It isn't important either way.

bug#52126: Problematic characters in info node names

[Glenn Morris]

Stefan Kangas wrote:

> Did something change here since the above note in admin/release-process
> was written in 2013 (commit 16bcc96df4)?

Yes. It's easy to find old versions of the Texinfo manual, eg
http://www.nongnu.org/texi2latex/texinfo/Node-Line-Requirements.html

Newer Texinfo is less strict, but Emacs configure still claims to
support 4.13.

> (Though I can't see any warnings produced when running "make info" in a
> fresh tree.)

It never did warn about such things; it made no sense to me.

https://lists.gnu.org/r/bug-texinfo/2013-08/msg00008.html

bug#52126: Problematic characters in info node names

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I read in (info "(texinfo) Node Line Requirements") that:
>>
>>    * Unfortunately, you cannot reliably use periods, commas, or colons
>>      within a node name; these can confuse the Info reader.  Also, a
>>      node name may not start with a left parenthesis preceding a right
>>      parenthesis, as in '(not)allowed', since this syntax is used to
>>      specify an external manual.  (Perhaps these limitations will be
>>      removed some day.)
>
> This is mainly because of the stand-alone Info reader.  The Emacs Info
> mode copes with these characters in node names much better.
>
> So yes, it is desirable to avoid them, but it isn't a catastrophe if
> they are there.

I guess what I'm asking myself if its useful to keep this advice in
admin/release-process.

Personally, I have no strong opinion either way, but I note that
makeinfo seems to now claim to warn about any problematic cases.

bug#52126: Problematic characters in info node names

[Protesilaos Stavrou]

[-- Attachment #1: Type: text/plain, Size: 666 bytes --]

On 2021-11-29, 20:07 +0200, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Protesilaos Stavrou <info@protesilaos.com>
>> Cc: larsi@gnus.org, Stefan Kangas <stefan@marxist.se>,
>>  52126@debbugs.gnu.org, kyle@kyleam.com, rgm@gnu.org
>> Date: Mon, 29 Nov 2021 20:04:37 +0200
>> 
>> 1. Do you want me to change this now on the trunk?
>
> Yes.
>
>> 2. This affects the emacs-28 branch.  Should I patch that as well?
>
> It's up to you.  It isn't important either way.

Both patches are attached.  Each file name contains the Emacs version it
belongs to.

I can push directly from here if you think everything is in order.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Remove-problematic-characters-from-modus-themes-emacs28.patch --]
[-- Type: text/x-patch, Size: 11115 bytes --]

From ecf3bf66ba8c9f2805196ece2607d7f1c9cae3d5 Mon Sep 17 00:00:00 2001
Message-Id: <ecf3bf66ba8c9f2805196ece2607d7f1c9cae3d5.1638213252.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Mon, 29 Nov 2021 21:13:55 +0200
Subject: [PATCH] Remove problematic characters from modus-themes.org (bug#52126)

* doc/misc/modus-themes.org
(Enable and load, Font configurations for Org and others)
(Note on highlight-parentheses.el, Note on god-mode.el): Update links to
headings so that they no longer include the removed portions of text.

(Option for color-coding success state, Option for line highlighting)
(Option for line numbers, Option for parenthesis matching)
(Advanced customization, Per-theme customization settings)
(Case-by-case face specs using the themes' palette)
(Face specs at scale using the themes' palette)
(Remap face with local value, Cycle through arbitrary colors)
(Override colors, Override color saturation)
(Font configurations for Org and others, Configure bold and italic faces)
(Custom Org user faces, Update Org block delimiter fontification)
(Measure color contrast, Load theme depending on time of day)
(Backdrop for pdf-tools)
(A theme-agnostic hook for theme loading, Note on EWW and Elfeed fonts)
(Frequently Asked Questions): Remove parentheses from headings as they
can cause problems in the .texi version of the file.
---
 doc/misc/modus-themes.org | 66 +++++++++++++++++++--------------------
 1 file changed, 33 insertions(+), 33 deletions(-)

diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org
index 675144d517..9674a12e69 100644
--- a/doc/misc/modus-themes.org
+++ b/doc/misc/modus-themes.org
@@ -279,9 +279,9 @@ * Enable and load
 
 2. The functions will run the ~modus-themes-after-load-theme-hook~ as
    their final step.  This can be employed for bespoke configurations
-   ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]).  Experienced users may not
-   wish to rely on such a hook and the functions that run it: they may
-   prefer a custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
+   ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]).  Experienced users may not wish to rely
+   on such a hook and the functions that run it: they may prefer a
+   custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
 
 ** Sample configuration for use-package
 :properties:
@@ -483,7 +483,7 @@ ** Option for inhibiting theme reload
 
 Enable this behaviour by setting this variable to ~nil~.
 
-** Option for color-coding success state (deuteranopia)
+** Option for color-coding success state
 :properties:
 :alt_title: Success' color-code
 :description: Toggle blue color for success or done states
@@ -1056,7 +1056,7 @@ ** Option for language checkers
 style, is controlled by the built-in variables ~underline-minimum-offset~,
 ~x-underline-at-descent-line~, ~x-use-underline-position-properties~.
 
-** Option for line highlighting (hl-line-mode)
+** Option for line highlighting
 :properties:
 :alt_title: Line highlighting
 :description: Choose style of current line (hl-line-mode)
@@ -1108,7 +1108,7 @@ ** Option for line highlighting (hl-line-mode)
 This style affects several packages that enable ~hl-line-mode~, such as
 =elfeed=, =notmuch=, and =mu4e=.
 
-** Option for line numbers (display-line-numbers-mode)
+** Option for line numbers
 :properties:
 :alt_title: Line numbers
 :description: Toggle subtle style for line numbers
@@ -1137,7 +1137,7 @@ ** Option for line numbers (display-line-numbers-mode)
 the rest of the buffer.  Foreground values for all relevant faces are
 updated to accommodate this aesthetic.
 
-** Option for parenthesis matching (show-paren-mode)
+** Option for parenthesis matching
 :properties:
 :alt_title: Matching parentheses
 :description: Choose between various styles for matching delimiters/parentheses
@@ -1723,7 +1723,7 @@ ** Option for variable-pitch font in headings
 
 [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]].
 
-* Advanced customization (do-it-yourself)
+* Advanced customization
 :properties:
 :custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
 :end:
@@ -1738,7 +1738,7 @@ * Advanced customization (do-it-yourself)
 incompatibilities between versioned releases of the themes.  As such,
 they are labelled as "do-it-yourself" or "DIY".
 
-** Per-theme customization settings (DIY)
+** Per-theme customization settings
 :properties:
 :custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193
 :end:
@@ -1773,7 +1773,7 @@ ** Per-theme customization settings (DIY)
 For a more elaborate design, it is better to inspect the source code of
 ~modus-themes-toggle~ and relevant functions.
 
-** Case-by-case face specs using the themes' palette (DIY)
+** Case-by-case face specs using the themes' palette
 :properties:
 :custom_id: h:1487c631-f4fe-490d-8d58-d72ffa3bd474
 :end:
@@ -1877,7 +1877,7 @@ ** Case-by-case face specs using the themes' palette (DIY)
 (set-face-attribute 'cursor nil :background (modus-themes-color-alts 'blue 'red))
 #+end_src
 
-** Face specs at scale using the themes' palette (DIY)
+** Face specs at scale using the themes' palette
 :properties:
 :custom_id: h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae
 :end:
@@ -1992,7 +1992,7 @@ ** Face specs at scale using the themes' palette (DIY)
    ...))
 #+end_src
 
-** Remap face with local value (DIY)
+** Remap face with local value
 :properties:
 :custom_id: h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f
 :end:
@@ -2054,7 +2054,7 @@ ** Remap face with local value (DIY)
 functions that also accept an arbitrary face.  We shall leave the
 experimentation up to you.
 
-** Cycle through arbitrary colors (DIY)
+** Cycle through arbitrary colors
 :properties:
 :custom_id: h:77dc4a30-b96a-4849-85a8-fee3c2995305
 :end:
@@ -2218,7 +2218,7 @@ ** Cycle through arbitrary colors (DIY)
  ...)
 #+end_src
 
-** Override colors (DIY)
+** Override colors
 :properties:
 :custom_id: h:307d95dd-8dbd-4ece-a543-10ae86f155a6
 :end:
@@ -2334,7 +2334,7 @@ ** Override colors (DIY)
 ratio between two color values, so it can help in overriding the palette
 (or a subset thereof) without making the end result inaccessible.
 
-** Override color saturation (DIY)
+** Override color saturation
 :properties:
 :custom_id: h:4589acdc-2505-41fc-9f5e-699cfc45ab00
 :end:
@@ -2454,7 +2454,7 @@ ** Override color saturation (DIY)
     ('modus-vivendi (modus-themes-load-vivendi))))
 #+end_src
 
-** Font configurations for Org and others (DIY)
+** Font configurations for Org and others
 :properties:
 :custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929
 :end:
@@ -2511,9 +2511,9 @@ ** Font configurations for Org and others (DIY)
 something like the ~text-scale-adjust~ command which only operates on the
 base font size (i.e. the ~default~ face's absolute height).
 
-[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts (SHR fonts)]].
+[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts]].
 
-** Configure bold and italic faces (DIY)
+** Configure bold and italic faces
 :properties:
 :custom_id: h:2793a224-2109-4f61-a106-721c57c01375
 :end:
@@ -2605,7 +2605,7 @@ ** Configure bold and italic faces (DIY)
 (add-hook 'modus-themes-after-load-theme-hook #'my-modes-themes-bold-italic-faces)
 #+end_src
 
-** Custom Org user faces (DIY)
+** Custom Org user faces
 :properties:
 :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad
 :end:
@@ -2693,7 +2693,7 @@ ** Custom Org user faces (DIY)
 
 [[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]].
 
-** Update Org block delimiter fontification (DIY)
+** Update Org block delimiter fontification
 :properties:
 :custom_id: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50
 :end:
@@ -2735,7 +2735,7 @@ ** Update Org block delimiter fontification (DIY)
     (font-lock-flush)))
 #+end_src
 
-** Measure color contrast (DIY)
+** Measure color contrast
 :properties:
 :custom_id: h:02e25930-e71a-493d-828a-8907fc80f874
 :end:
@@ -2808,7 +2808,7 @@ ** Measure color contrast (DIY)
 Such knowledge may prove valuable while attempting to override some of
 the themes' colors: [[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]].
 
-** Load theme depending on time of day (DIY)
+** Load theme depending on time of day
 :properties:
 :custom_id: h:1d1ef4b4-8600-4a09-993c-6de3af0ddd26
 :end:
@@ -2835,7 +2835,7 @@ ** Load theme depending on time of day (DIY)
   (circadian-setup))
 #+end_src
 
-** Backdrop for pdf-tools (DIY)
+** Backdrop for pdf-tools
 :properties:
 :custom_id: h:ff69dfe1-29c0-447a-915c-b5ff7c5509cd
 :end:
@@ -2897,7 +2897,7 @@ ** Backdrop for pdf-tools (DIY)
 they automatically switch to their dark mode when ~modus-themes-toggle~ is
 called from inside a buffer whose major-mode is ~pdf-view-mode~.
 
-** A theme-agnostic hook for theme loading (DIY)
+** A theme-agnostic hook for theme loading
 :properties:
 :custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776
 :end:
@@ -3509,7 +3509,7 @@ ** Note on highlight-parentheses.el
 "Do-It-Yourself" (DIY) sections, which provide insight into the more
 advanced customization options of the themes.
 
-[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]].
+[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]].
 
 In the following example, we are assuming that the user wants to (i)
 re-use color variables provided by the themes, (ii) be able to retain
@@ -3775,12 +3775,12 @@ ** Note on god-mode.el
 :custom_id: h:4da1d515-3e05-47ef-9e45-8251fc7e986a
 :end:
 
-The ~god-mode~ library does not provide faces that could be configured by
-the Modus themes.  Users who would like to get some visual feedback on
-the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream to
-set up their own configurations, such as by changing the ~mode-line~ face
-([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]).  This is an adaptation of the
-approach followed in the upstream README:
+The ~god-mode~ library does not provide faces that could be configured
+by the Modus themes.  Users who would like to get some visual feedback
+on the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream
+to set up their own configurations, such as by changing the ~mode-line~
+face ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]).  This is an adaptation of the approach
+followed in the upstream README:
 
 #+begin_src emacs-lisp
 (defun my-god-mode-update-mode-line ()
@@ -3874,7 +3874,7 @@ ** Note on SHR colors
 
 Consult {{{kbd(C-h v shr-use-colors)}}}.
 
-** Note on EWW and Elfeed fonts (SHR fonts)
+** Note on EWW and Elfeed fonts
 :properties:
 :custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c
 :end:
@@ -3988,7 +3988,7 @@ ** Note on pdf-tools link hints
             "-draw"       "text %X,%Y '%c'"))))
 #+end_src
 
-* Frequently Asked Questions (FAQ)
+* Frequently Asked Questions
 :properties:
 :custom_id: h:b3384767-30d3-4484-ba7f-081729f03a47
 :end:
-- 
2.34.0


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0001-Remove-problematic-characters-from-modus-themes-emacs29.patch --]
[-- Type: text/x-patch, Size: 11450 bytes --]

From 030a5c570487e2809a1ae902f43d1fecf381030c Mon Sep 17 00:00:00 2001
Message-Id: <030a5c570487e2809a1ae902f43d1fecf381030c.1638213514.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Mon, 29 Nov 2021 21:06:52 +0200
Subject: [PATCH] Remove problematic characters from modus-themes.org (bug#52126)

* doc/misc/modus-themes.org
(Enable and load, Font configurations for Org and others)
(Note on highlight-parentheses.el, Note on god-mode.el): Update links to
headings so that they no longer include the removed portions of text.

(Option for color-coding success state, Option for line highlighting)
(Option for line numbers, Option for parenthesis matching)
(Advanced customization, Per-theme customization settings)
(Case-by-case face specs using the themes' palette)
(Face specs at scale using the themes' palette)
(Remap face with local value, Cycle through arbitrary colors)
(Override colors, Override color saturation)
(Font configurations for Org and others, Configure bold and italic faces)
(Custom Org user faces, Update Org block delimiter fontification)
(Measure color contrast, Load theme depending on time of day)
(Backdrop for pdf-tools, Decrease mode line height)
(A theme-agnostic hook for theme loading, Note on EWW and Elfeed fonts)
(Frequently Asked Questions): Remove parentheses from headings as they
can cause problems in the .texi version of the file.
---
 doc/misc/modus-themes.org | 68 +++++++++++++++++++--------------------
 1 file changed, 34 insertions(+), 34 deletions(-)

diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org
index f3c2e37b7d..f67a179567 100644
--- a/doc/misc/modus-themes.org
+++ b/doc/misc/modus-themes.org
@@ -279,9 +279,9 @@ * Enable and load
 
 2. The functions will run the ~modus-themes-after-load-theme-hook~ as
    their final step.  This can be employed for bespoke configurations
-   ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]).  Experienced users may not
-   wish to rely on such a hook and the functions that run it: they may
-   prefer a custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
+   ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]).  Experienced users may not wish to rely
+   on such a hook and the functions that run it: they may prefer a
+   custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
 
 ** Sample configuration with and without use-package
 :properties:
@@ -515,7 +515,7 @@ ** Option for inhibiting theme reload
 Regardless of this option, the active theme must be reloaded for changes
 to user options to take effect ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]).
 
-** Option for color-coding success state (deuteranopia)
+** Option for color-coding success state
 :properties:
 :alt_title: Success' color-code
 :description: Toggle blue color for success or done states
@@ -1151,7 +1151,7 @@ ** Option for language checkers
 ~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~,
 respectively.
 
-** Option for line highlighting (hl-line-mode)
+** Option for line highlighting
 :properties:
 :alt_title: Line highlighting
 :description: Choose style of current line (hl-line-mode)
@@ -1205,7 +1205,7 @@ ** Option for line highlighting (hl-line-mode)
 This style affects several packages that enable ~hl-line-mode~, such as
 =elfeed=, =notmuch=, and =mu4e=.
 
-** Option for line numbers (display-line-numbers-mode)
+** Option for line numbers
 :properties:
 :alt_title: Line numbers
 :description: Toggle subtle style for line numbers
@@ -1260,7 +1260,7 @@ ** Option for intense markup in Org and others
 With a non-nil value (~t~), these constructs will use a more prominent
 background and foreground color combination instead.
 
-** Option for parenthesis matching (show-paren-mode)
+** Option for parenthesis matching
 :properties:
 :alt_title: Matching parentheses
 :description: Choose between various styles for matching delimiters/parentheses
@@ -1913,7 +1913,7 @@ ** Option for variable-pitch font in headings
 
 [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]].
 
-* Advanced customization (do-it-yourself)
+* Advanced customization
 :properties:
 :custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
 :end:
@@ -1928,7 +1928,7 @@ * Advanced customization (do-it-yourself)
 incompatibilities between versioned releases of the themes.  As such,
 they are labelled as "do-it-yourself" or "DIY".
 
-** Per-theme customization settings (DIY)
+** Per-theme customization settings
 :properties:
 :custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193
 :end:
@@ -1963,7 +1963,7 @@ ** Per-theme customization settings (DIY)
 For a more elaborate design, it is better to inspect the source code of
 ~modus-themes-toggle~ and relevant functions.
 
-** Case-by-case face specs using the themes' palette (DIY)
+** Case-by-case face specs using the themes' palette
 :properties:
 :custom_id: h:1487c631-f4fe-490d-8d58-d72ffa3bd474
 :end:
@@ -2067,7 +2067,7 @@ ** Case-by-case face specs using the themes' palette (DIY)
 (set-face-attribute 'cursor nil :background (modus-themes-color-alts 'blue 'red))
 #+end_src
 
-** Face specs at scale using the themes' palette (DIY)
+** Face specs at scale using the themes' palette
 :properties:
 :custom_id: h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae
 :end:
@@ -2182,7 +2182,7 @@ ** Face specs at scale using the themes' palette (DIY)
    ...))
 #+end_src
 
-** Remap face with local value (DIY)
+** Remap face with local value
 :properties:
 :custom_id: h:7a93cb6f-4eca-4d56-a85c-9dcd813d6b0f
 :end:
@@ -2244,7 +2244,7 @@ ** Remap face with local value (DIY)
 functions that also accept an arbitrary face.  We shall leave the
 experimentation up to you.
 
-** Cycle through arbitrary colors (DIY)
+** Cycle through arbitrary colors
 :properties:
 :custom_id: h:77dc4a30-b96a-4849-85a8-fee3c2995305
 :end:
@@ -2408,7 +2408,7 @@ ** Cycle through arbitrary colors (DIY)
  ...)
 #+end_src
 
-** Override colors (DIY)
+** Override colors
 :properties:
 :custom_id: h:307d95dd-8dbd-4ece-a543-10ae86f155a6
 :end:
@@ -2524,7 +2524,7 @@ ** Override colors (DIY)
 ratio between two color values, so it can help in overriding the palette
 (or a subset thereof) without making the end result inaccessible.
 
-** Override color saturation (DIY)
+** Override color saturation
 :properties:
 :custom_id: h:4589acdc-2505-41fc-9f5e-699cfc45ab00
 :end:
@@ -2644,7 +2644,7 @@ ** Override color saturation (DIY)
     ('modus-vivendi (modus-themes-load-vivendi))))
 #+end_src
 
-** Font configurations for Org and others (DIY)
+** Font configurations for Org and others
 :properties:
 :custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929
 :end:
@@ -2708,9 +2708,9 @@ ** Font configurations for Org and others (DIY)
 which only operates on the base font size (i.e. the ~default~ face's
 absolute height).
 
-[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts (SHR fonts)]].
+[[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts]].
 
-** Configure bold and italic faces (DIY)
+** Configure bold and italic faces
 :properties:
 :custom_id: h:2793a224-2109-4f61-a106-721c57c01375
 :end:
@@ -2805,7 +2805,7 @@ ** Configure bold and italic faces (DIY)
 
 [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]].
 
-** Custom Org user faces (DIY)
+** Custom Org user faces
 :properties:
 :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad
 :end:
@@ -2893,7 +2893,7 @@ ** Custom Org user faces (DIY)
 
 [[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]].
 
-** Update Org block delimiter fontification (DIY)
+** Update Org block delimiter fontification
 :properties:
 :custom_id: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50
 :end:
@@ -2935,7 +2935,7 @@ ** Update Org block delimiter fontification (DIY)
     (font-lock-flush)))
 #+end_src
 
-** Measure color contrast (DIY)
+** Measure color contrast
 :properties:
 :custom_id: h:02e25930-e71a-493d-828a-8907fc80f874
 :end:
@@ -3008,7 +3008,7 @@ ** Measure color contrast (DIY)
 Such knowledge may prove valuable while attempting to override some of
 the themes' colors: [[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]].
 
-** Load theme depending on time of day (DIY)
+** Load theme depending on time of day
 :properties:
 :custom_id: h:1d1ef4b4-8600-4a09-993c-6de3af0ddd26
 :end:
@@ -3035,7 +3035,7 @@ ** Load theme depending on time of day (DIY)
   (circadian-setup))
 #+end_src
 
-** Backdrop for pdf-tools (DIY)
+** Backdrop for pdf-tools
 :properties:
 :custom_id: h:ff69dfe1-29c0-447a-915c-b5ff7c5509cd
 :end:
@@ -3097,7 +3097,7 @@ ** Backdrop for pdf-tools (DIY)
 they automatically switch to their dark mode when ~modus-themes-toggle~ is
 called from inside a buffer whose major-mode is ~pdf-view-mode~.
 
-** Decrease mode line height (DIY)
+** Decrease mode line height
 :properties:
 :custom_id: h:03be4438-dae1-4961-9596-60a307c070b5
 :end:
@@ -3192,7 +3192,7 @@ ** Decrease mode line height (DIY)
 (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)
 #+end_src
 
-** A theme-agnostic hook for theme loading (DIY)
+** A theme-agnostic hook for theme loading
 :properties:
 :custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776
 :end:
@@ -3806,7 +3806,7 @@ ** Note on highlight-parentheses.el
 "Do-It-Yourself" (DIY) sections, which provide insight into the more
 advanced customization options of the themes.
 
-[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]].
+[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]].
 
 In the following example, we are assuming that the user wants to (i)
 re-use color variables provided by the themes, (ii) be able to retain
@@ -4072,12 +4072,12 @@ ** Note on god-mode.el
 :custom_id: h:4da1d515-3e05-47ef-9e45-8251fc7e986a
 :end:
 
-The ~god-mode~ library does not provide faces that could be configured by
-the Modus themes.  Users who would like to get some visual feedback on
-the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream to
-set up their own configurations, such as by changing the ~mode-line~ face
-([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]).  This is an adaptation of the
-approach followed in the upstream README:
+The ~god-mode~ library does not provide faces that could be configured
+by the Modus themes.  Users who would like to get some visual feedback
+on the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream
+to set up their own configurations, such as by changing the ~mode-line~
+face ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]).  This is an adaptation of the approach
+followed in the upstream README:
 
 #+begin_src emacs-lisp
 (defun my-god-mode-update-mode-line ()
@@ -4171,7 +4171,7 @@ ** Note on SHR colors
 
 Consult {{{kbd(C-h v shr-use-colors)}}}.
 
-** Note on EWW and Elfeed fonts (SHR fonts)
+** Note on EWW and Elfeed fonts
 :properties:
 :custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c
 :end:
@@ -4285,7 +4285,7 @@ ** Note on pdf-tools link hints
             "-draw"       "text %X,%Y '%c'"))))
 #+end_src
 
-* Frequently Asked Questions (FAQ)
+* Frequently Asked Questions
 :properties:
 :custom_id: h:b3384767-30d3-4484-ba7f-081729f03a47
 :end:
-- 
2.34.0

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: larsi@gnus.org, stefan@marxist.se, 52126@debbugs.gnu.org,
>  kyle@kyleam.com, rgm@gnu.org
> Date: Mon, 29 Nov 2021 21:32:44 +0200
> 
> >> 2. This affects the emacs-28 branch.  Should I patch that as well?
> >
> > It's up to you.  It isn't important either way.
> 
> Both patches are attached.  Each file name contains the Emacs version it
> belongs to.
> 
> I can push directly from here if you think everything is in order.

Feel free to push to any of the two branches.

Thanks.

bug#52126: Problematic characters in info node names

[Protesilaos Stavrou]

On 2021-11-29, 21:46 +0200, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Protesilaos Stavrou <info@protesilaos.com>
>> Cc: larsi@gnus.org, stefan@marxist.se, 52126@debbugs.gnu.org,
>>  kyle@kyleam.com, rgm@gnu.org
>> Date: Mon, 29 Nov 2021 21:32:44 +0200
>> 
>> >> 2. This affects the emacs-28 branch.  Should I patch that as well?
>> >
>> > It's up to you.  It isn't important either way.
>> 
>> Both patches are attached.  Each file name contains the Emacs version it
>> belongs to.
>> 
>> I can push directly from here if you think everything is in order.
>
> Feel free to push to any of the two branches.
>
> Thanks.

Done for both.  Thank you!

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: larsi@gnus.org, stefan@marxist.se, 52126@debbugs.gnu.org,
>  kyle@kyleam.com, rgm@gnu.org
> Date: Mon, 29 Nov 2021 22:07:58 +0200
> 
> On 2021-11-29, 21:46 +0200, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >> Both patches are attached.  Each file name contains the Emacs version it
> >> belongs to.
> >> 
> >> I can push directly from here if you think everything is in order.
> >
> > Feel free to push to any of the two branches.
> >
> > Thanks.
> 
> Done for both.  Thank you!

You should have only pushed to one of the branches, not to both.
Because they are the same changes, right?

bug#52126: Problematic characters in info node names

[Protesilaos Stavrou]

On 2021-11-29, 22:32 +0200, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Protesilaos Stavrou <info@protesilaos.com>
>> Cc: larsi@gnus.org, stefan@marxist.se, 52126@debbugs.gnu.org,
>>  kyle@kyleam.com, rgm@gnu.org
>> Date: Mon, 29 Nov 2021 22:07:58 +0200
>> 
>> On 2021-11-29, 21:46 +0200, Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>> >> Both patches are attached.  Each file name contains the Emacs version it
>> >> belongs to.
>> >> 
>> >> I can push directly from here if you think everything is in order.
>> >
>> > Feel free to push to any of the two branches.
>> >
>> > Thanks.
>> 
>> Done for both.  Thank you!
>
> You should have only pushed to one of the branches, not to both.
> Because they are the same changes, right?

There is a slight difference between them.  The one for the master
branch has an extra diff hunk which removes a single "(DIY)" from a
heading.  This is because emacs-28 has version 1.6.0 of the themes while
master has 1.7.0.

Commit 030a5c5704 on master:

   doc/misc/modus-themes.org | 68 +++++++++++++++++++++++------------------------

Commit ecf3bf66ba on emacs-28:

   doc/misc/modus-themes.org | 66 +++++++++++++++++++++++------------------------

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: larsi@gnus.org, stefan@marxist.se, 52126@debbugs.gnu.org,
>  kyle@kyleam.com, rgm@gnu.org
> Date: Mon, 29 Nov 2021 22:56:29 +0200
> 
> >> Done for both.  Thank you!
> >
> > You should have only pushed to one of the branches, not to both.
> > Because they are the same changes, right?
> 
> There is a slight difference between them.  The one for the master
> branch has an extra diff hunk which removes a single "(DIY)" from a
> heading.  This is because emacs-28 has version 1.6.0 of the themes while
> master has 1.7.0.

The common part should only be committed to one branch.
Alternatively, the commit to emacs-28 should be marked with the "do
not merge to master" note.  See CONTRIBUTE for more about this.

bug#52126: Problematic characters in info node names

[Kyle Meyer]

Glenn Morris writes:

> Stefan Kangas wrote:
>
>> Did something change here since the above note in admin/release-process
>> was written in 2013 (commit 16bcc96df4)?
>
> Yes. It's easy to find old versions of the Texinfo manual, eg
> http://www.nongnu.org/texi2latex/texinfo/Node-Line-Requirements.html
>
> Newer Texinfo is less strict, but Emacs configure still claims to
> support 4.13.

I wonder whether 4.13 actually has a problem with the cases flagged in
this issue, where the parentheses are not at the start of the text.
Texinfo's ab404029d0 (parens only disallowed when looks like an external
manual ref, 2011-09-18) made the following text change:

   @cindex Characters, invalid in node name
   @cindex Invalid characters in node names
   @cindex Node names, invalid characters in
  -Unfortunately, you cannot use periods, commas, colons or parentheses
  -within a node name; these confuse the Texinfo processors.  Perhaps
  -this limitation will be removed some day, too.
  +Unfortunately, you cannot use periods, commas, or colons within a node
  +name; these confuse the Texinfo processors.  Also, a node name may not
  +start with a left parenthesis and contain a right parenthesis, as in
  +@code{(not)allowed}; this specifies an external manual in Info.
  +Perhaps these limitations will be removed some day, too.

That looks to be a pure documentation update to more accurately describe
the restrictions.  The commit message links to a thread [*] that seems
to confirm that.  There Patrice Dumas says

  What is not allowed, in reality, and leads to an error message is parentheses
  beginning at the beginning of the node name as you said:
  
   @node (man)bad
  
   c.texi:6: Syntax for an external node used for `(man)bad'

[*] https://lists.gnu.org/archive/html/bug-texinfo/2011-09/msg00024.html

bug#52126: Problematic characters in info node names

[Kyle Meyer]

Lars Ingebrigtsen writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> ** Manuals
>> Check for node names using problematic characters:
>>   find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
>> Sadly makeinfo does not warn about such characters.
>>
>> Running that gives me some matches:
[...]
>> doc/misc/org.texi:@node Hooks (2)
>
> And in the Org manual, so I've added Kyle to the CCs, too.

Hmm, that "(2)" is being added by ox-texinfo.el's to make the node
unique.  As I mentioned in another message
(<87tufue02l.fsf@kyleam.com>), I think these parentheses are probably
okay, even for older versions of Texinfo.

On the other hand, I have no objections to sidestepping the issue with
something like this:

diff --git a/doc/misc/org.org b/doc/misc/org.org
index 85117714ee9..adf24da1c3f 100644
--- a/doc/misc/org.org
+++ b/doc/misc/org.org
@@ -15571,7 +15571,7 @@ ** Advanced Export Configuration
 :DESCRIPTION: Fine-tuning the export output.
 :END:
 
-*** Hooks
+*** Export hooks
 :PROPERTIES:
 :UNNUMBERED: notoc
 :END:
@@ -18203,7 +18203,7 @@ *** Functions
   #+kindex: C-c C-v f
   Choose a file to tangle.  Bound to {{{kbd(C-c C-v f)}}}.
 
-*** Hooks
+*** Tangle hooks
 :PROPERTIES:
 :UNNUMBERED: notoc
 :END:

bug#52126: Problematic characters in info node names

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> The common part should only be committed to one branch.
> Alternatively, the commit to emacs-28 should be marked with the "do
> not merge to master" note.  See CONTRIBUTE for more about this.

Yup.

Otherwise, I get to resolve merge conflicts over my morning coffee.  :-)

    There are unresolved conflicts in .../emacs/doc/misc/modus-themes.org
    Conflicts in:
    doc/misc/modus-themes.org

    Resolve the conflicts manually
    automerge: merge error

It's not the end of the world, but it saves time if we can avoid it.

bug#52126: Problematic characters in info node names

[Protesilaos Stavrou]

On 2021-11-29, 22:39 -0800, Stefan Kangas <stefan@marxist.se> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> The common part should only be committed to one branch.
>> Alternatively, the commit to emacs-28 should be marked with the "do
>> not merge to master" note.  See CONTRIBUTE for more about this.
>
> Yup.
>
> Otherwise, I get to resolve merge conflicts over my morning coffee.  :-)
>
>     There are unresolved conflicts in .../emacs/doc/misc/modus-themes.org
>     Conflicts in:
>     doc/misc/modus-themes.org
>
>     Resolve the conflicts manually
>     automerge: merge error
>
> It's not the end of the world, but it saves time if we can avoid it.

I understand, re-read CONTRIBUTE, and apologise for the inconvenience.

Should I then revert the commit in master and apply to it the 1
difference I mentioned before?  Just asking so that we do not commit
multiple times.

I noticed in 0854453ec2343cbfac3ac8e233cdc7bd2c8554a9 a pattern for how
reverted commits should be written.  I can follow that.

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#52126: Problematic characters in info node names

[Stefan Kangas]

Protesilaos Stavrou <info@protesilaos.com> writes:

> I understand, re-read CONTRIBUTE, and apologise for the inconvenience.

No need to apologize.  It happens!

> Should I then revert the commit in master and apply to it the 1
> difference I mentioned before?  Just asking so that we do not commit
> multiple times.

It's better to just leave it alone for now, as it's already been merged
to master.

bug#52126: Problematic characters in info node names

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: larsi@gnus.org, 52126@debbugs.gnu.org, kyle@kyleam.com, rgm@gnu.org
> Date: Tue, 30 Nov 2021 09:16:02 +0200
> 
> I noticed in 0854453ec2343cbfac3ac8e233cdc7bd2c8554a9 a pattern for how
> reverted commits should be written.  I can follow that.

You don't have to: the pattern is produced by Git itself, and if you
want to add or change something, invoke "git revert -e".

bug#52126: Problematic characters in info node names

[Stefan Kangas]

Kyle Meyer <kyle@kyleam.com> writes:

> Hmm, that "(2)" is being added by ox-texinfo.el's to make the node
> unique.  As I mentioned in another message
> (<87tufue02l.fsf@kyleam.com>), I think these parentheses are probably
> okay, even for older versions of Texinfo.
>
> On the other hand, I have no objections to sidestepping the issue with
> something like this:

Thanks, that looks like a reasonable fix.  None of this seems urgent to
me, so I'd suggest you consider pushing that fix to the Org-mode
repository and we will eventually get it merged into Emacs in the normal
way.

With that, I'm closing this bug as it seems the issues here are resolved.

Thanks.

bug#52126: Problematic characters in info node names

[Kyle Meyer]

Stefan Kangas writes:

> Thanks, that looks like a reasonable fix.  None of this seems urgent to
> me, so I'd suggest you consider pushing that fix to the Org-mode
> repository and we will eventually get it merged into Emacs in the normal
> way.

Pushed to the Org repo (0acd2fed2).