diff mbox series

sframe/doc: remove usage of xrefautomaticsectiontitle

Message ID 20221122221028.2924195-1-indu.bhagat@oracle.com
State Accepted
Headers
Series sframe/doc: remove usage of xrefautomaticsectiontitle |

Checks

Context Check Description
snail/binutils-gdb-check success Github commit url

Commit Message

Indu Bhagat Nov. 22, 2022, 10:10 p.m. UTC 
  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(-)

Comments

Jan Beulich Nov. 23, 2022, 9:07 a.m. UTC | #1 
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
Indu Bhagat Nov. 23, 2022, 10:51 p.m. UTC | #2 
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
diff mbox series

Patch

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.