Preferred Format of GNU C Library Manual Edits

Preferred Format of GNU C Library Manual Edits

[ricaljasan]

[-- Attachment #1: Type: text/plain, Size: 2920 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Preferred Format of GNU C Library Manual Edits

[Siddhesh Poyarekar]

[-- Attachment #1: Type: text/plain, Size: 3541 bytes --]

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 #2: Type: application/pgp-signature, Size: 473 bytes --]

Re: Preferred Format of GNU C Library Manual Edits

[ricaljasan]

[-- Attachment #1: Type: text/plain, Size: 889 bytes --]

On 07/07/2015 12:24 AM, Siddhesh Poyarekar wrote:
> 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.

Thank you for the feedback.  That should be exactly how things work out,
as each chapter is typically a single file.  There may be supplementary
files which have a few additional edits, but many of the included files
are code examples and I have example vetting set aside as a separate
project.

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

Rical


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]