Re: Minor tweaks to the MIPS documentation

[Richard Sandiford <rdsandiford at googlemail dot com>]

"Maciej W. Rozycki" <macro@codesourcery.com> writes:
> On Sat, 22 Jun 2013, Richard Sandiford wrote:
>
>> Several small and unexciting changes:
>> 
>> - Consistently use "MIPS" rather than "@sc{mips}".  "@sc{mips}" looks strange
>>   in the PDF output and "MIPS" was already the prevalent form.  Also,
>>   "@sc{mips}" doesn't really look right alongside "microMIPS".
>
>  Thanks, I think you missed a couple that are not strictly "MIPS" though, 
> a patch follows.  And I think @sc{isa} might fall into the same category 
> (but I haven't touched these).  I also changed one "MIPS3" to "MIPS III" 
> for consistency with "MIPS V" used elsewhere, and replaced some other @sc 
> commands with @samp for consistency with the corresponding part of 
> as.texinfo.  Also I think we should standardise on "MIPS16" rather than 
> "MIPS 16" used in some places, the latter has never been proper usage.
>
>  Overall perhaps using @acronym{MIPS}, @acronym{microMIPS}, @acronym{ISA}, 
> etc. like the GDB manual does for these names would be a good idea?

The documentation says:

  Use the `@acronym' command for abbreviations written in all capital
  letters, such as `NASA'.

so it wouldn't be suitable for "microMIPS".  And in practice the "micro"
ends up smaller than the surrounding text, which just looks silly.

Besides, MIPS's own documentation doesn't bother.  The "MIPS32" in
"MIPS32 Architecture" is the same height as the "A", which IMO looks
better than making "MIPS32" smaller.  I also think there'd be zero
chance of applying this consistently.  Especially when it appears
alongside other capitalised terms like "PC", "CPU", "FPU", "ASE".
There'd be no obvious stopping point.

I only kept "@sc{gnu}" because I wasn't sure whether that was an
FSF preference.

> @@ -91,8 +91,8 @@ R4000 processor, and @samp{-mips4} to th
>  R10000 processors.  @samp{-mips5}, @samp{-mips32}, @samp{-mips32r2},
>  @samp{-mips64}, and @samp{-mips64r2}
>  correspond to generic
> -@sc{MIPS V}, @sc{MIPS32}, @sc{MIPS32 Release 2}, @sc{MIPS64},
> -and @sc{MIPS64 Release 2}
> +@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, @samp{MIPS64},
> +and @samp{MIPS64 Release 2}
>  ISA processors, respectively.  You can also switch
>  instruction sets during the assembly; see @ref{MIPS ISA, Directives to
>  override the ISA level}.

As Eli says, using @samp here is wrong.  Please just remove the @sc instead.

OK with that change, thanks.

Richard