Inconsistency between @page and @subpage parsing (Origin: bugzilla #651081)

[doxygen]

status NEW severity normal in component general for ---
Reported in version 1.7.4 on platform Other
Assigned to: Dimitri van Heesch

On 2011-05-25 17:31:49 +0000, Simon A Watts wrote:

I recently encountered a case where @subpage links were not formed correctly
in PDF/Latex, but were correct in HTML.  I was not able to track down the
reason why - as a test case worked okay, but the real project did not.

Anyway, I did notice that there was an inconsistency in the parsing rules in
'commentscan.l', between @page and @subpage - both directives should be
followed by the respective page label (the label for this page for @page,
and the target page for @subpage).  So I'd expect the labels in both cases
to be parsed using the same token rules.

However, the label for @page is defined as a 'FILE' token, whereas for
@subpage the label is define as the 'LABELID' token.

'FILE' token is defined on line 815:

0813: FILESCHAR [a-z_A-Z0-9\x80-\xFF\\:\\\/\-\+]
0814: FILEECHAR [a-z_A-Z0-9\x80-\xFF\-\+]
0815: FILE
({FILESCHAR}*{FILEECHAR}+("."{FILESCHAR}*{FILEECHAR}+)*)|("\""[^\n\"]*"\"")

'LABELID' token is defined on line 817.

0817: LABELID   [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*

The label following @page is parsed on line 1314:

1314: <PageDocArg1>{FILE} { // first argument; page name
1315: 	current->name = stripQuotes(yytext);
1316: 	BEGIN( PageDocArg2 ); 
1317: }

The label following @subpage is parsed on line 1518:

1518: <SubpageLabel>{LABELID} { // first argument
1519: 	addOutput(yytext);
1520:       // we add subpage labels as a kind of "inheritance" relation to
prevent
1521: 	// needing to add another list to the Entry class.
1522: 	current->extends->append(new BaseInfo(yytext,Public,Normal));
1523: 	BEGIN(SubpageTitle);
1524: }

I think that both cases should be using 'LABELID' - for consistency at
least.

[albert-github]

It looks to me that both \page and \subpage should use the LABELID.
@doxygen what do you think?

[albert-github]

An intriguing problem so I made a small test case

• page commands with non label names line pg++, should be filtered out by the subpage command
  Interestingly this works but because the subpage command is placed back in the processing stream and the + signs are caught in the "// catch-all for anything else"
• markdown file with the name bb++.md so the name would be used as the label
  This works as the + of the filename is "mangled" to _09, the resulting, internal, label is md_bb_09_09

So it looks like not LABELID can be used but FILE at both places.

• tested als0 a page name starting with a number and this also works when changing
• changing from LABELID to FILE also sees to it that some extra related pages are not shown as related pages (they were and are still present as subpages).

Example: example.tar.gz

I've just pushed a proposed patch, pull request #10296

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.10.0.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).