Re: [PATCH, rs6000] Improve indentation of prototype documentation

[Segher Boessenkool <segher at kernel dot crashing dot org>]

On Mon, Jun 04, 2018 at 02:37:20PM -0500, Kelvin Nilsen wrote:
> 
> This patch removes extraneous line breaks to condense the number of lines require in the "PowerPC AltiVec Built-in Functions" section of the gcc.pdf manual by about 7 pages.  Besides improving the appearance of this documentation, there are two additional benefits:

What does line wrap now look like, both in the pdf and in the "plain" info
doc?  (And in html?)

> 1. Subsequent patches that move prototype definitions in order to alphabetize definitions or in order to group definitions requiring the same target options together are easier to understand if each prototype description is represented on a single line.
> 
> 2. Enclosing the group of 8 vec_xl prototypes and 8 vec_xst prototypes between @smallexample and @end smallexample allows these prototypes to be automatically parsed by a tool that validates consistency between implementation and documentation of built-in functions.

Yes, excellent :-)

> Segher: if you prefer, I can break this into multiple smaller patches.  What would be the ideal size of each patch?

No, this is fine: it is doing just one thing (well, also the smallexample
thing), and the patch is readable enough.

What you shouldn't do is patches that interleave many things, or that do
multiple (big) things that can just as well be separate patches, or that
move things as well as modify them (in that case, do a patch that just
moves things, and one that does the modifications).

> Is this ok for trunk?

Yes.  Thank you!


Segher


> 2018-06-04  Kelvin Nilsen  <kelvin@gcc.gnu.org>
> 
> 	* doc/extend.texi (PowerPC AltiVec Built-in Functions): Adjust
> 	indentation and line wrap for many prototypes.  Add missing
> 	@smallexample directives around block of prototypes for vec_xl and
> 	vec_xst.