[PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[Carroll, Paul]

This is an issue involving the documentation for GDB.
In our case, we use texi2html to convert the gdb.texinfo file into multiple HTML files.
When this is done, we end up with some HTML files that have different contents, but the same name (ignoring case).
That is, we get two files, frame-apply.html and Frame-Apply.html.
The first HTML file is an anchor that points to another HTML file.
The second HTML file is an actual piece of text in the documentation - a section.
This is not an issue for Linux, but can be a problem for Windows system, where filenames are case insensitive.

This patch fix this problem, which results in the 'frame-apply.html' file not being generated.
This patch removes an @anchor(frame apply) and modifies the 2 @xref's that refer to it,
so as to avoid the creation of multiple files that are only different by case.

2020-06-19  Paul Carroll  <pcarroll@codesourcery.com>
     PR gdb/25716
     * gdb/doc/gdb.texinfo (Frame Apply): Remove anchor for 'frame 
apply' and adjust xrefs to it.

---
  gdb/doc/gdb.texinfo | 5 ++---
  1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 59e3e75d18..5301e98fee 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3600,7 +3600,7 @@ is, using:
  @end smallexample

  The @code{tfaas} command accepts the same options as the @code{frame
-apply} command.  @xref{frame apply}.
+apply} command.  @xref{Frame Apply, frame apply}.

  @kindex thread name
  @cindex name a thread
@@ -8358,7 +8358,6 @@ tfaas i lo -q -t lock_something_t

  @node Frame Apply
  @section Applying a Command to Several Frames.
-@anchor{frame apply}
  @kindex frame apply
  @cindex apply command to several frames
  @table @code
@@ -8490,7 +8489,7 @@ is, using:
  @end smallexample

  The @code{faas} command accepts the same options as the @code{frame
-apply} command.  @xref{frame apply}.
+apply} command.  @xref{Frame Apply, frame apply}.

  Note that the command @code{tfaas @var{command}} applies @var{command}
  on all frames of all threads.  See @xref{Threads,,Threads}.
-- 
2.21.0

Re: [PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[Andrew Burgess]

* Carroll, Paul <pcarroll@codesourcery.com> [2020-06-19 09:41:49 -0700]:

> This is an issue involving the documentation for GDB.
> In our case, we use texi2html to convert the gdb.texinfo file into multiple HTML files.
> When this is done, we end up with some HTML files that have different contents, but the same name (ignoring case).
> That is, we get two files, frame-apply.html and Frame-Apply.html.
> The first HTML file is an anchor that points to another HTML file.
> The second HTML file is an actual piece of text in the documentation - a section.
> This is not an issue for Linux, but can be a problem for Windows system, where filenames are case insensitive.
> 
> This patch fix this problem, which results in the 'frame-apply.html' file not being generated.
> This patch removes an @anchor(frame apply) and modifies the 2 @xref's that refer to it,
> so as to avoid the creation of multiple files that are only different by case.
> 
> 2020-06-19  Paul Carroll  <pcarroll@codesourcery.com>
>     PR gdb/25716
>     * gdb/doc/gdb.texinfo (Frame Apply): Remove anchor for 'frame apply' and

Lots of whitespace in this patch was replaced with '_' for some
reason, which means this patch didn't apply cleanly.  Not sure where
this has occurred, but I don't see this with other patches, so I'd
like to say this is something at your end.

> adjust xrefs to it.
> 
> ---
>  gdb/doc/gdb.texinfo | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 59e3e75d18..5301e98fee 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -3600,7 +3600,7 @@ is, using:
>  @end smallexample
> 
>  The @code{tfaas} command accepts the same options as the @code{frame
> -apply} command.  @xref{frame apply}.
> +apply} command.  @xref{Frame Apply, frame apply}.

I wonder if we should use '@xref{Frame Apply, , frame apply}.' here?

Currently in html we get: 'See frame apply.'
And in a pdf we get: 'See [frame apply], page 112.'

After this commit the html stays the same, but the pdf changes to:
'See Section 8.5 [Frame Apply], page 112.'.  The new 'Section xxx'
doesn't bother me, but 'Frame Apply' is not the name of the section,
nor is it the name of the command.

With my proposed change then the html version stays the same, and the
pdf version becomes: 'See Section 8.5 [frame apply], page 112.', we
now name the actual command.

What do you think?

Thanks,
Andrew

> 
>  @kindex thread name
>  @cindex name a thread
> @@ -8358,7 +8358,6 @@ tfaas i lo -q -t lock_something_t
> 
>  @node Frame Apply
>  @section Applying a Command to Several Frames.
> -@anchor{frame apply}
>  @kindex frame apply
>  @cindex apply command to several frames
>  @table @code
> @@ -8490,7 +8489,7 @@ is, using:
>  @end smallexample
> 
>  The @code{faas} command accepts the same options as the @code{frame
> -apply} command.  @xref{frame apply}.
> +apply} command.  @xref{Frame Apply, frame apply}.
> 
>  Note that the command @code{tfaas @var{command}} applies @var{command}
>  on all frames of all threads.  See @xref{Threads,,Threads}.
> -- 
> 2.21.0
> 
> 

Re: [PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[Carroll, Paul]

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


On 7/7/2020 8:45 AM, Andrew Burgess wrote:
> Lots of whitespace in this patch was replaced with '_' for some
> reason, which means this patch didn't apply cleanly.  Not sure where
> this has occurred, but I don't see this with other patches, so I'd
> like to say this is something at your end.

Somehow an extra space was added for lines that started with a space.  
No idea how it got there.  Copy-paste error.

>> adjust xrefs to it.
>>
>> ---
>>   gdb/doc/gdb.texinfo | 5 ++---
>>   1 file changed, 2 insertions(+), 3 deletions(-)
>>
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index 59e3e75d18..5301e98fee 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -3600,7 +3600,7 @@ is, using:
>>   @end smallexample
>>
>>   The @code{tfaas} command accepts the same options as the @code{frame
>> -apply} command.  @xref{frame apply}.
>> +apply} command.  @xref{Frame Apply, frame apply}.
> I wonder if we should use '@xref{Frame Apply, , frame apply}.' here?
>
> Currently in html we get: 'See frame apply.'
> And in a pdf we get: 'See [frame apply], page 112.'
>
> After this commit the html stays the same, but the pdf changes to:
> 'See Section 8.5 [Frame Apply], page 112.'.  The new 'Section xxx'
> doesn't bother me, but 'Frame Apply' is not the name of the section,
> nor is it the name of the command.
>
> With my proposed change then the html version stays the same, and the
> pdf version becomes: 'See Section 8.5 [frame apply], page 112.', we
> now name the actual command.
>
> What do you think?
>
> Thanks,
> Andrew

Looks good to me.  there are 2 xrefs that would need the same change.  
 From what I generated, the PDFs show the difference while the HTML 
files are identical.  So, yes, it matches what you indicated.

I'm attaching my patch with your change.


[-- Attachment #2: 0001-fix-for-pr-25716.patch --]
[-- Type: text/plain, Size: 1069 bytes --]

---
 gdb/doc/gdb.texinfo | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 59e3e75d18..5301e98fee 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3600,7 +3600,7 @@ is, using:
 @end smallexample
 
 The @code{tfaas} command accepts the same options as the @code{frame
-apply} command.  @xref{frame apply}.
+apply} command.  @xref{Frame Apply,,frame apply}.
 
 @kindex thread name
 @cindex name a thread
@@ -8358,7 +8358,6 @@ tfaas i lo -q -t lock_something_t
 
 @node Frame Apply
 @section Applying a Command to Several Frames.
-@anchor{frame apply}
 @kindex frame apply
 @cindex apply command to several frames
 @table @code
@@ -8490,7 +8489,7 @@ is, using:
 @end smallexample
 
 The @code{faas} command accepts the same options as the @code{frame
-apply} command.  @xref{frame apply}.
+apply} command.  @xref{Frame Apply,,frame apply}.
 
 Note that the command @code{tfaas @var{command}} applies @var{command}
 on all frames of all threads.  See @xref{Threads,,Threads}.
-- 
2.21.0

Re: [PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[Andrew Burgess]

* Carroll, Paul <pcarroll@codesourcery.com> [2020-07-07 12:51:17 -0700]:

> 
> On 7/7/2020 8:45 AM, Andrew Burgess wrote:
> > Lots of whitespace in this patch was replaced with '_' for some
> > reason, which means this patch didn't apply cleanly.  Not sure where
> > this has occurred, but I don't see this with other patches, so I'd
> > like to say this is something at your end.
> 
> Somehow an extra space was added for lines that started with a space.  No
> idea how it got there.  Copy-paste error.
> 
> > > adjust xrefs to it.
> > > 
> > > ---
> > >   gdb/doc/gdb.texinfo | 5 ++---
> > >   1 file changed, 2 insertions(+), 3 deletions(-)
> > > 
> > > diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> > > index 59e3e75d18..5301e98fee 100644
> > > --- a/gdb/doc/gdb.texinfo
> > > +++ b/gdb/doc/gdb.texinfo
> > > @@ -3600,7 +3600,7 @@ is, using:
> > >   @end smallexample
> > > 
> > >   The @code{tfaas} command accepts the same options as the @code{frame
> > > -apply} command.  @xref{frame apply}.
> > > +apply} command.  @xref{Frame Apply, frame apply}.
> > I wonder if we should use '@xref{Frame Apply, , frame apply}.' here?
> > 
> > Currently in html we get: 'See frame apply.'
> > And in a pdf we get: 'See [frame apply], page 112.'
> > 
> > After this commit the html stays the same, but the pdf changes to:
> > 'See Section 8.5 [Frame Apply], page 112.'.  The new 'Section xxx'
> > doesn't bother me, but 'Frame Apply' is not the name of the section,
> > nor is it the name of the command.
> > 
> > With my proposed change then the html version stays the same, and the
> > pdf version becomes: 'See Section 8.5 [frame apply], page 112.', we
> > now name the actual command.
> > 
> > What do you think?
> > 
> > Thanks,
> > Andrew
> 
> Looks good to me.  there are 2 xrefs that would need the same change.  From
> what I generated, the PDFs show the difference while the HTML files are
> identical.  So, yes, it matches what you indicated.
> 
> I'm attaching my patch with your change.
>

Normally Eli reviews documentation changes, but given there's not
really any content change here I feel I can approve this.

Thanks,
Andrew




> ---
>  gdb/doc/gdb.texinfo | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 59e3e75d18..5301e98fee 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -3600,7 +3600,7 @@ is, using:
>  @end smallexample
>  
>  The @code{tfaas} command accepts the same options as the @code{frame
> -apply} command.  @xref{frame apply}.
> +apply} command.  @xref{Frame Apply,,frame apply}.
>  
>  @kindex thread name
>  @cindex name a thread
> @@ -8358,7 +8358,6 @@ tfaas i lo -q -t lock_something_t
>  
>  @node Frame Apply
>  @section Applying a Command to Several Frames.
> -@anchor{frame apply}
>  @kindex frame apply
>  @cindex apply command to several frames
>  @table @code
> @@ -8490,7 +8489,7 @@ is, using:
>  @end smallexample
>  
>  The @code{faas} command accepts the same options as the @code{frame
> -apply} command.  @xref{frame apply}.
> +apply} command.  @xref{Frame Apply,,frame apply}.
>  
>  Note that the command @code{tfaas @var{command}} applies @var{command}
>  on all frames of all threads.  See @xref{Threads,,Threads}.
> -- 
> 2.21.0
> 

Re: [PATCH][PR gdb/25716] Modify Docs to avoid HTML filename collision on Windows

[Eli Zaretskii]

> Date: Tue, 7 Jul 2020 16:45:51 +0100
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org
> 
> >  The @code{tfaas} command accepts the same options as the @code{frame
> > -apply} command.  @xref{frame apply}.
> > +apply} command.  @xref{Frame Apply, frame apply}.
> 
> I wonder if we should use '@xref{Frame Apply, , frame apply}.' here?

We could, but that'd be for a different reason.

> With my proposed change then the html version stays the same, and the
> pdf version becomes: 'See Section 8.5 [frame apply], page 112.', we
> now name the actual command.
> 
> What do you think?

I don't mind to use your suggestion, as it fixes both Paul's problem
and the one you mentioned.

Thanks.