bugtexinfo - GNU documentation system - Bugs: bug #11700, rfe: diagnose references which...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

bug #11700: rfe: diagnose references which produce wrong title in pronted output

Submitted by:  James Youngman <jay>
Submitted on:  Sat 22 Jan 2005 04:00:21 PM UTC  
 
Category: NoneRelease: 4.7
Priority: 5 - NormalSeverity: 3 - Normal
Item Group: NonePrivacy: Public
Open/Closed: ClosedAssigned to: Patrice Dumas <pertusus>
Status: Fixed

Wed 02 Nov 2011 08:59:43 PM UTC, comment #4:

In the Parser (for HTML), @xrefautomaticsectiontitle is now implemented.

Patrice Dumas <pertusus>
Project MemberIn charge of this item.
Thu 10 Feb 2011 07:20:29 PM UTC, comment #3:

Maybe instead of warning when the third argument is different from the node name, it would be better to use the section name as third argument automatically when there is no third (nor second in makeinfo) argument. If I recall well this is done like that in texi2html (at least with some options, I haven't checked exactly). Could TeX also do something along?

I don't like warning about typos part of the language. Doing an external document checker would be right, however (and would certainly be quite easily done with the Parser). So I think that @warnings xrefthirdwrong is a bad idea.

If doing something automatic in texi2dvi is not possible, @warnings xrefthirdmissing
could be interesting (but maybe use a full command, like
@warnxrefthirdmissing
to be more consistent with the other commands?)

Patrice Dumas <pertusus>
Project MemberIn charge of this item.
Thu 10 Feb 2011 05:49:47 PM UTC, comment #2:

(James, if you have any comments or corrections, please say, of course.)

Patrice,

After thinking about this a little, I think there are two separate things that could be done:

1) warn about any existing third argument of an xref that doesn't match the corresponding first-argument node name. I.e., for manuals that don't always use the three-argument form but when they do, the names should match. (I believe the Texinfo manual itself falls into this category.) Example:
@xref{mynode,, My Nodr} @c typo in third arg
...
@node mynode
@section My Node

2) warn about xrefs lacking a third argument where the first-argument node has a nontrivially-different corresponding section name. Example, continuing the above:
@xref{mynode}

(As I understand it, that's what James is trying to achieve with his manuals.)

In the Texinfo manual, I don't always use the full section name in third args, because the full section name can get very long, so as to be descriptive in the main text. Example:
@section @code{@@anchor}: Defining Arbitrary Cross Reference Targets
I would use just @xref{anchor,,@code{@@anchor}} for this, since all that extra text would just get in the way (IMHO).

If an xref is to an anchor rather than a node, or a node outside the current manual, I think there are no warnings to give.

I expect that few manuals manage to follow either of these rules perfectly, and third-arg xrefs can in theory be entirely independent of section names, as shown in the examples in the Texinfo manual. (Whether it's ever actually useful for them to be so completely independent, I'm not so sure.)

So, I think maybe these should be enabled via a new command:
@warnings xrefthirdwrong,xrefthirdmissing

wdyt?

Thanks,
Karl

Karl Berry <karl>
Project Administrator
Sun 23 Jan 2005 06:02:41 PM UTC, comment #1:

I agree this would be a nice enhancement. Thanks for the suggestion.

(I thought texinfo-mode in Emacs had support for something like this, but I don't see anything now. Hmm.)

Karl Berry <karl>
Project Administrator
Sat 22 Jan 2005 04:00:21 PM UTC, original submission:

Suppose all my @node commands are followed by a section/chapter heading. Mostly, the node name and the heading will be the same. Some of them will not. If I use @ref{nodename} rather than using the three-argument form of cross-reference I will get in the DVI file a reference to a section entitled [nodename].

To ensure that the manual is high-quality, the references should tie up, and checking for this manually is very time-consuming. I wish the computer was able to help me do it - one way for this to happen is for makeinfo to detect these mistakes and issue a warning message.

I'm suggesting the use of makeinfo for this to avoid spurious warnings about constructs like this:

@node comb, delta, cdc, Invoking CSSC Programs
@section @code{comb}

James Youngman <jay>

 

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by pertusus (Posted a comment)
  • -unavailable- added by karl (Posted a comment)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 3 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Wed 02 Nov 2011 08:59:43 PM UTCpertususOpen/ClosedOpen=>Closed
      StatusNone=>Fixed
    Thu 10 Feb 2011 05:49:47 PM UTCkarlAssigned toNone=>pertusus

    Back to the top


    Powered by Savane 3.1-cleanup1