Re: [PATCH] microMIPS support

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 26 Apr 2012 19:00:55 +0100
> From: "Maciej W. Rozycki" <macro@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> > 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.

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

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

> so I'd rather stick to @acronym

Fine with me, I suggested to use either one.

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

> > > As it stands I'd prefer to keep the formatting consistent through the 
> > > manual.
> > 
> > There's no reason to consistently do the wrong thing.  Every 1000-mile
> > journey begins with the first step.
> 
>  I think the right thing is to fix it all in one go first and only then 
> enforce the new rule.  I think holding a useful functional change just 
> because it keeps using the established practice in documentation is 
> counter-productive.

Actually, _you_ are holding it, by continuously rejecting my requests
for changes.  The changes I asked for are not so extensive, so I
really don't understand why we are still arguing.

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

> > > 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 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 think index references would better be added separately too -- these 
> > > would be "ARM Breakpoint Kinds," "MIPS Register Packet Format" and "MIPS 
> > > Breakpoint Kinds," respectively.
> > 
> > Sorry, I don't follow.  Please elaborate.
> 
>  These are the three subsubsections in the section concerned 
> (Architecture-Specific Protocol Details).  With my change in place two 
> will be titled "Breakpoint Kinds" so I prepended their containing 
> subsection names (ARM and MIPS) to the respective index entries.  
> Likewise I can see no sense in having a generic index entry such as 
> "Register Packet Format" for a reference to a platform-specific piece of 
> text, so I have prepended the subsection (platform) name there too.

That's fine, thanks.

> > Then how about "executables" or "executable code" instead of
> > "binaries"?
> 
>  OK, that sounds like a plan to me -- how about:
> 
> "Set the compressed ISA encoding used by MIPS code."
> 
> then?

OK.

Thanks.