[PATCH] sframe/doc: remove usage of xrefautomaticsectiontitle

[PATCH] sframe/doc: remove usage of xrefautomaticsectiontitle

[Indu Bhagat]

xrefautomaticsectiontitle appears to be available from texinfo 5.0 or
greater.  As such, it is not worthwhile to add requirement for a minimum
necessary makeinfo version.  So remove the usage of it.

ChangeLog:

	* libsframe/doc/sframe-spec.texi: Remove usage of
	  xrefautomaticsectiontitle.
---
 libsframe/doc/sframe-spec.texi | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
index 41f4ba17d83..49e5e9f0cf7 100644
--- a/libsframe/doc/sframe-spec.texi
+++ b/libsframe/doc/sframe-spec.texi
@@ -1,9 +1,6 @@
 \input texinfo       @c                    -*- Texinfo -*-
 @setfilename sframe-spec.info
 @settitle The SFrame Format
-@ifnottex
-@xrefautomaticsectiontitle on
-@end ifnottex
 
 @copying
 Copyright @copyright{} 2021-2022 Free Software Foundation, Inc.
-- 
2.37.2

Re: [PATCH] sframe/doc: remove usage of xrefautomaticsectiontitle

[Jan Beulich]

On 22.11.2022 23:10, Indu Bhagat wrote:
> xrefautomaticsectiontitle appears to be available from texinfo 5.0 or
> greater.  As such, it is not worthwhile to add requirement for a minimum
> necessary makeinfo version.  So remove the usage of it.

Thanks for making the adjustment, but is simply deleting the construct
the right thing to do? If this didn't serve any purpose, why was it
there? Yet if it did, is the result now less useful / usable?

Jan

Re: [PATCH] sframe/doc: remove usage of xrefautomaticsectiontitle

[Indu Bhagat]

On 11/23/22 01:07, Jan Beulich wrote:
> On 22.11.2022 23:10, Indu Bhagat wrote:
>> xrefautomaticsectiontitle appears to be available from texinfo 5.0 or
>> greater.  As such, it is not worthwhile to add requirement for a minimum
>> necessary makeinfo version.  So remove the usage of it.
> 
> Thanks for making the adjustment, but is simply deleting the construct
> the right thing to do? If this didn't serve any purpose, why was it
> there? 

The construct was being used in a sort of useless way; and I understand 
more of this only now.

xrefautomaticsectiontitle was guarded with @ifnottex, but IIUC, 
"@xrefautomaticsectiontitle on" has _no_effect_ on info documents (I see 
the generated .info has node names with makeinfo 6.8 and also 
https://lists.gnu.org/archive/html/help-texinfo/2020-01/msg00033.html). 
It seems (at least the newer) makeinfo uses node names for info document 
always (..and section names for HTML always).


> Yet if it did, is the result now less useful / usable?
> 

Usability is not affected.

As for usefulness, for sframe-spec.texi specifically, I think the node 
names are also equally informative, and IMO, there is little loss of 
quality of the manuals with using node names instead of section names at 
this time.

For example, there are usages like:

@node SFrame Frame Row Entries
@section SFrame FRE

and,

@node SFrame Function Descriptor Entries
@section SFrame FDE

which will need to remain for @menu items.

In any case, the needs of sframe-spec.texi are simple at this time: I 
have a patch that aligns the few other (unnecessary and confusing) cases 
of node-name != section-name in sframe-spec.texi, perhaps I should 
include it in a V2...

Thanks
Indu

[PATCH,V2] sframe/doc: remove usage of xrefautomaticsectiontitle

[Indu Bhagat]

[Changes in V2]
  - Keep node name and section title in sync when possible.
[End of changes in V2]

xrefautomaticsectiontitle appears to be available from texinfo 5.0 or
greater.  As such, it is not worthwhile to add requirement for a minimum
necessary makeinfo version.  So remove the usage of it.

Also align node name with section title where possible.

ChangeLog:

	* libsframe/doc/sframe-spec.texi: Remove usage of
	xrefautomaticsectiontitle.
---
 libsframe/doc/sframe-spec.texi | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
index 41f4ba17d83..0559d7c3882 100644
--- a/libsframe/doc/sframe-spec.texi
+++ b/libsframe/doc/sframe-spec.texi
@@ -1,9 +1,6 @@
 \input texinfo       @c                    -*- Texinfo -*-
 @setfilename sframe-spec.info
 @settitle The SFrame Format
-@ifnottex
-@xrefautomaticsectiontitle on
-@end ifnottex
 
 @copying
 Copyright @copyright{} 2021-2022 Free Software Foundation, Inc.
@@ -395,7 +392,7 @@ used for the function.
 
 @cindex The SFrame FDE info word
 @node The SFrame FDE info word
-@subsection The SFrame FDE info word, sfde_func_info
+@subsection The SFrame FDE info word
 
 The info word is a bitfield split into three parts.  From MSB to LSB:
 
@@ -562,7 +559,7 @@ Further FRE types may be added in future.
 
 @cindex The SFrame FRE info word
 @node The SFrame FRE info word
-@subsection The SFrame FRE info word, sfre_info
+@subsection The SFrame FRE info word
 
 The SFrame FRE info word is a bitfield split into four parts.  From MSB to LSB:
 
-- 
2.37.2

Re: [PATCH,V2] sframe/doc: remove usage of xrefautomaticsectiontitle

[Jan Beulich]

On 24.11.2022 01:28, Indu Bhagat via Binutils wrote:
> [Changes in V2]
>   - Keep node name and section title in sync when possible.
> [End of changes in V2]
> 
> xrefautomaticsectiontitle appears to be available from texinfo 5.0 or
> greater.  As such, it is not worthwhile to add requirement for a minimum
> necessary makeinfo version.  So remove the usage of it.
> 
> Also align node name with section title where possible.
> 
> ChangeLog:
> 
> 	* libsframe/doc/sframe-spec.texi: Remove usage of
> 	xrefautomaticsectiontitle.
> ---
>  libsframe/doc/sframe-spec.texi | 7 ++-----
>  1 file changed, 2 insertions(+), 5 deletions(-)

Okay.

Thanks, Jan