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

Message ID 643ebaf3-211f-c240-f5d7-88e47b1631d8@codesourcery.com
State New
Headers show
Series
  • [PR,gdb/25716] Modify Docs to avoid HTML filename collision on Windows
Related show

Commit Message

Carroll, Paul June 19, 2020, 4:41 p.m.
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(-)

-- 
2.21.0

Comments

Andrew Burgess July 7, 2020, 3:45 p.m. | #1
* 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

> 

>
Carroll, Paul July 7, 2020, 7:51 p.m. | #2
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.
---
 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}.
Andrew Burgess July 8, 2020, 10:42 a.m. | #3
* 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

>
Eli Zaretskii July 8, 2020, 6:13 p.m. | #4
> 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.

Patch

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}.