This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] microMIPS support


On Thu, 26 Apr 2012, Eli Zaretskii wrote:

> > > Index entries should all start with lower-case letters, otherwise the
> > > index sorting is unpredictable (in non-US locales).
> > 
> >  OK, but is that a problem?  If a foreign locale uses a different sorting 
> > order, then it's exactly what the user of that locale expects, isn't it?  
> 
> Not if the Info files are then put into a release tarball and
> distributed worldwide.

 So may I suggest fixing the release process to use the intended locale 
instead (C or en_US, or whatever)?  Force it in a `make' rule or whatever.  
I think you'll get worse troubles than just an incorrect index order when 
an incorrect locale is selected.  It's the tools that should be fixed, not 
the text of the manual modified to work around any limitations.

> >  As far as I know writing MIPS in small letters when referred to the name 
> > of the architecture (as opposed to a keyword, such in GAS's `.set mips0' 
> > directive) is incorrect.
> 
> You could have "MIPS" not as the first word in the index entry, if you
> must have it in caps.

 I'll see what I can do about it then, if that satisfies you.  However I 
still have troubles to accept this requirement.  So if the first word had 
to be a city or person's name, you'd demand it to start with a small 
letter too?  I just don't buy it, sorry, there's something wrong with the 
process if you must make such requirements.

> >  As the platform maintainer I can offer you to review the whole manual and 
> > adjust all the instances of "MIPS" (plus any variants and any related 
> > acronyms I'll spot) as a separate change.  I think it will be more 
> > productive and not really a lot of effort.
> 
> I will do that when I have time, thanks.

 I offered you mine instead, but I won't insist.

> >  So in the end it looks to me "MIPS", etc. should actually use no special 
> > formatting (except possibly where used as keywords), so while I can still 
> > go through the manual, I'll only adjust items like ISA or ASE.
> 
> I think @acronym{MIPS} looks nicer, but I won't insist on that.

 I have regenerated both paragraphs added with the tag applied and 
actually I agree -- and contrary to documentation it works just fine for 
microMIPS.  So I decided to follow your suggestion even though @acronym is 
a misnomer here ("MIPS" and all the derivatives are really the same class 
of names as "Intel", or "Linux", or "NetBSD" are -- it's just that their
capitalisation is weird).  You've convinced me.

> > > I didn't ask you to revamp the entire section.  Even if the rest of
> > > the section will never be fixed, it still makes sense to not increase
> > > the amount of node-less subsections.
> >
> >  It makes no sense to me not to revamp the entire section
> 
> I won't object if you do revamp it, if you feel like it.  But I will
> approve the patch even if you don't, because I think it's unfair to
> ask you to fix what you didn't break.

 I appreciate that, but likewise it's my right to offer you doing it.

> > > > Nesting too deep can be frustrating too, and here you'd have to have
> > > > two intermediate pages with node lists only for just a couple lines'
> > > > worth of nodes.
> > > 
> > > I can go with removing the subsection altogether, if you don't feel
> > > strongly with keeping it.
> > > 
> > > But if we keep the subsection, I'd like to have a node there.
> > 
> >  It doesn't make sense to me to make this whole section flat, the matters 
> > described are distinct enough
> 
> I'm confused: you just said above that too deep nesting is not good,
> now you are saying that NOT nesting will be too shallow?  Shouldn't
> there be some middle ground between these two extremes?

 I am opposed to nesting nodes, not subsections (including, in particular, 
numbering the latters allow) -- which appear tangential to each other -- 
the formers are used for structuring by the Info format and the latters by 
PDF (for bookmarks, that clearly correspond to Info's nodes, but do not 
interfere with how the document itself is paginated).  And to breaking 
structure with partial changes -- that's no different to how I treat 
changes to code.

> > I just can't seem convinced we need all these nodes here.
> 
> Can I ask you to trust my experience on this one?  Having nodes makes
> navigation inside Info easier.

 I've used Info documentation for some 15 years now and I am not getting 
lost on pages like one concerned.  However I do recognise your experience 
may be different.  So I have reworked the section as below.  Do you really 
like the outcome, like an empty "ARM" subsection with a lone reference to 
its "Breakpoint Kinds" subsubsection?  I find it an unnecessary hassle to 
go through when reading the manual.

 Note that I had to use node names different to sub- and subsubsection 
titles to avoid duplicate names that are not supported for nodes.

 I still think your original suggestion to have such a reference in the 
MIPS subsection for one of its subsubsections, but not the other would be 
rather odd.

 So here goes the section rework (I have merged the node additions with 
index reference updates; I have applied your request to avoid capitalised 
proper names at the beginning for the ARM reference as well) followed by 
a diff to my microMIPS changes.  I hope you can accept these changes.

  Maciej

2012-04-26  Maciej W. Rozycki  <macro@codesourcery.com>

	gdb/doc/
	* gdb.texinfo (Architecture-Specific Protocol Details): Add nodes
	and index entries throughout.

gdb-doc-remote-arch.diff
Index: gdb-fsf-trunk-quilt/gdb/doc/gdb.texinfo
===================================================================
--- gdb-fsf-trunk-quilt.orig/gdb/doc/gdb.texinfo	2012-04-27 00:08:04.055561374 +0100
+++ gdb-fsf-trunk-quilt/gdb/doc/gdb.texinfo	2012-04-27 00:36:17.025444873 +0100
@@ -36475,9 +36475,21 @@ This section describes how the remote pr
 target architectures.  Also see @ref{Standard Target Features}, for
 details of XML target descriptions for each architecture.
 
+@menu
+* ARM Architecture-Specific Protocol Details::
+* MIPS Architecture-Specific Protocol Details::
+@end menu
+
+@node ARM Architecture-Specific Protocol Details
 @subsection ARM
 
+@menu
+* ARM Breakpoint Kinds::
+@end menu
+
+@node ARM Breakpoint Kinds
 @subsubsection Breakpoint Kinds
+@cindex breakpoint kinds, @acronym{ARM}
 
 These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
 
@@ -36494,9 +36506,16 @@ These breakpoint kinds are defined for t
 
 @end table
 
+@node MIPS Architecture-Specific Protocol Details
 @subsection MIPS
 
+@menu
+* MIPS Register Packet Format::
+@end menu
+
+@node MIPS Register Packet Format
 @subsubsection Register Packet Format
+@cindex register packet format, @acronym{MIPS}
 
 The following @code{g}/@code{G} packets have previously been defined.
 In the below, some thirty-two bit registers are transferred as

gdb-micromips-doc-fix.diff
Index: gdb-fsf-trunk-quilt/gdb/doc/gdb.texinfo
===================================================================
--- gdb-fsf-trunk-quilt.orig/gdb/doc/gdb.texinfo	2012-04-27 00:33:17.515562192 +0100
+++ gdb-fsf-trunk-quilt/gdb/doc/gdb.texinfo	2012-04-27 00:23:50.675579198 +0100
@@ -20265,8 +20265,9 @@ Show the MIPS ABI used by @value{GDBN} t
 
 @item set mips compression @var{arg}
 @kindex set mips compression
-@cindex MIPS code compression
-Tell @value{GDBN} which MIPS compressed ISA encoding is used by the
+@cindex code compression, @acronym{MIPS}
+Tell @value{GDBN} which @acronym{MIPS} compressed
+@acronym{ISA, Instruction Set Architecture} encoding is used by the
 inferior.  @value{GDBN} uses this for code disassembly and other
 internal interpretation purposes.  This setting is only referred to
 when no executable has been associated with the debugging session or
@@ -20275,22 +20276,24 @@ Otherwise this setting is automatically 
 provided by the executable.
 
 Possible values of @var{arg} are @samp{mips16} and @samp{micromips}.
-The default compressed ISA encoding is @samp{mips16}, as executables
-containing MIPS16 code frequently are not identified as such.
+The default compressed @acronym{ISA} encoding is @samp{mips16}, as
+executables containing @acronym{MIPS16} code frequently are not
+identified as such.
 
 This setting is ``sticky''; that is, it retains its value across
 debugging sessions until reset either explicitly with this command or
 implicitly from an executable.
 
 The compiler and/or assembler typically add symbol table annotations to
-identify functions compiled for the MIPS16 or microMIPS ISAs.  If these
-function-scope annotations are present, @value{GDBN} uses them in
-preference to the global compressed ISA encoding setting.
+identify functions compiled for the @acronym{MIPS16} or
+@acronym{microMIPS} @acronym{ISA}s.  If these function-scope annotations
+are present, @value{GDBN} uses them in preference to the global
+compressed @acronym{ISA} encoding setting.
 
 @item show mips compression
 @kindex show mips compression
-Show the MIPS compressed ISA encoding used by @value{GDBN} to debug the
-inferior.
+Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by
+@value{GDBN} to debug the inferior.
 
 @item set mipsfpu
 @itemx show mipsfpu
@@ -36540,6 +36543,7 @@ These breakpoint kinds are defined for t
 
 @menu
 * MIPS Register Packet Format::
+* MIPS Breakpoint Kinds::
 @end menu
 
 @node MIPS Register Packet Format
@@ -36569,23 +36573,25 @@ as @code{MIPS32}.
 
 @end table
 
+@node MIPS Breakpoint Kinds
 @subsubsection Breakpoint Kinds
+@cindex breakpoint kinds, @acronym{MIPS}
 
 These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
 
 @table @r
 
 @item 2
-16-bit MIPS16 mode breakpoint.
+16-bit @acronym{MIPS16} mode breakpoint.
 
 @item 3
-16-bit microMIPS mode breakpoint.
+16-bit @acronym{microMIPS} mode breakpoint.
 
 @item 4
-32-bit standard MIPS mode breakpoint.
+32-bit standard @acronym{MIPS} mode breakpoint.
 
 @item 5
-32-bit microMIPS mode breakpoint.
+32-bit @acronym{microMIPS} mode breakpoint.
 
 @end table
 
Index: gdb-fsf-trunk-quilt/gdb/mips-tdep.c
===================================================================
--- gdb-fsf-trunk-quilt.orig/gdb/mips-tdep.c	2012-04-27 00:33:17.515562192 +0100
+++ gdb-fsf-trunk-quilt/gdb/mips-tdep.c	2012-04-27 00:11:50.385601288 +0100
@@ -8769,8 +8769,8 @@ This option can be set to one of:\n\
      and carried over to subsequent sessions.  */
   add_setshow_enum_cmd ("compression", class_obscure, mips_compression_strings,
 			&mips_compression_string, _("\
-Set the compressed ISA encoding used."), _("\
-Show the compressed ISA encoding used."), _("\
+Set the compressed ISA encoding used by MIPS code."), _("\
+Show the compressed ISA encoding used by MIPS code."), _("\
 Select the compressed ISA encoding used in functions that have no symbol\n\
 information available.  The encoding can be set to either of:\n\
   mips16\n\


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]