Preferred Format of GNU C Library Manual Edits

[ricaljasan <ricaljasan at pacific dot net>]

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: signature.asc
Description: OpenPGP digital signature