Re: Preferred Format of GNU C Library Manual Edits

[Siddhesh Poyarekar <siddhesh at redhat dot com>]

Firstly, thank you for your consideration for reviewers of your
patches :)

AFAIU, there are two distinct types of changes, one being grammatical
edits and other being changes to formatting of the output.  If you
separate the two and then ensure that your patches are not too large
(something as simple as one patch per file is also good enough), I
think you would have done enough to make it easy for your reviewers.

Siddhesh

On Sat, Jun 27, 2015 at 02:43:23PM -0700, ricaljasan wrote:
> Hi glibc,
> 
> I'm roughly halfway through the manual (working on grammatical edits),
> and now I need to know how I should start formatting/preparing my
> patches.  This is generally directed at whoever will be reviewing the
> patches, so as to make your part easier.
> 
> I'm at a point where the last few chapters have gone rather smoothly in
> terms of what I choose to edit, ignore, or makes notes of for future
> reference; i.e., I'm largely past the point of constantly asking myself,
> "[How] Should I edit this?"  Now that I have a reasonably consistent
> style and scope, and have learned enough git to be both useful and
> dangerous, it's time to return to those earlier chapters and
> rework/review them.  On top of cleaning early messes, this also provides
> the opportunity to set up my workflow for the remainder of the manual.
> 
> To give you an idea of how I'm structuring things, let me describe the
> perspective here in why-did-I-start-editing-the-manual land.  Foremost,
> I don't intend to read this thing cover-to-cover twice (not that
> continued work won't eventually cover that much ground though).  To make
> the most of this first pass, I see 2 primary groups of edits that if I
> were to ignore for now, but wanted to come back to later, would
> essentially result in reading the entire manual word-for-word over
> again.  One set is purely grammar related, and the other is variable
> formatting, which, assuming a variable's name should be formatted as
> code and its value in italics, is atrocious throughout.
> 
> Since the two groups are independent issues (unless you actually read
> variables like their formatting matters, in which case it does feel like
> a minor grammar issue), I've been editing them in parallel.  One branch
> for grammar, another for variable formatting.  Another reason for
> keeping them separate is I expect they'll be subject to entirely
> different opinions, and I would hate simple grammar fixes in a mixed
> patch set to be blocked because I couldn't tell the difference between
> the variable @code{size} and a string @var{size} bytes long.
> 
> Another class of edits worth mentioning is reference formatting.  These
> wouldn't be so bad to grep for and examine, but improperly formatted
> references are fundamentally a grammar issue because of how they render
> in the different output formats.  So far, I've included them in the
> grammar edits, but I could do something similar to variable formatting
> and cut them out into their own branch, if anybody thinks that would be
> useful or more appropriate.
> 
> Getting to the actual patch submission part of this, the way I plan on
> doing it is something like:
> 
> [Patch M/N] Grammatical edits to the GNU C Library Reference Manual.
> 
> where each M is a chapter.  Variable formatting and other manual-wide
> topics would follow similarly.
> 
> 
> Let me know if anything I've described should be changed in any way.
> 
> Thank you,
> Rical Jasan
>

Attachment: pgpJPthdn9tba.pgp
Description: PGP signature