Questions on Documentation and NSS

[ricaljasan <ricaljasan at pacific dot net>]

Does documentation follow the 79-column style?  The style in
manual/nss.texi (and most other manual/*.texi files) appears to lean
towards 72 columns, although there are a handful of lines where it goes
over by a few characters. This isn't including @node, @item, etc., lines
which consistently go much longer on a single line, despite Texinfo
allowing '\' line breaks (tested, no errors, node references remained
correct).  I'll stick with 72 because of the respect-the-locals
philosophy, but that brings up a couple other questions: should I bother
bringing rogue 73+ character lines back to <73 when I come across them
or would changes like those be considered too superfluous?  Occasionally
I would add a character to a line and that would cause an entire
paragraph to shift, causing the diff to appear much more substantial
than it really was.  I left 73-column lines in those cases.  Aside from
preventing diff noise (a term I believe I heard on the list at some
point), I couldn't find any coding guidelines which stated documentation
source should be 72 columns instead of the glibc 79.

Next question: is it "the 'Name Service Switch'" or "Name Service
Switch"?  For instance, the second paragraph of the chapter states, "The
GNU C Library... calls this scheme `Name Service Switch'".  To me, "the
`Name Service Switch'" sounds more appropriate.  I do contrast that with
the acronym, NSS, however.  When I read the initials, I usually don't
prefix the phrase with "the" because I read it as the three letters,
"en-ess-ess", and it acts as its own entity for the most part.

I think the key difference to me is the use of "switch" as a noun in the
sense of: 7) a turning, shifting, or changing. (Dictionary.com)  I just
happened to be reading RFC 1034 the other day and when I finished it and
started skimming the references, I realized some of the historical
significance of the Domain Name Service - I saw a handful of earlier
name services which were obsoleted by it.  A few days later, it dawned
on me that the Name Service Switch was probably referring to the
"switch" that occurred as many of the early name services lived and
died, or the sheer number simply grew to require new methods of
management - exactly the situation described by the both the RFC and the
first paragraph of the NSS chapter in the manual.

To that end, I'm wondering if it would be appropriate to expand some of
the historical introduction (if I'm at all on the right track).  One of
the reasons I latched on to the NSS chapter is because I had no context
for what it was talking about, even after reading it.  And I need to know.

I just submitted a first patch for manual/nss.texi to libc-alpha and I'm
going to leave this chapter alone now while I move on to reading the
rest of the manual as I've wanted to do for a long time.  As I progress,
I'll continue to make edits, primarily to grammar, for general
improvement.  Now that I've gone through what felt like the crucible of
learning how to follow development and manage my own local branch in a
reasonably efficient manner, I feel like my workflow will be smooth
enough to prevent major hang-ups and move along at a decent pace.

One reason I'm moving on from the NSS chapter is that I couldn't stop
trying to completely restructure it.  This chapter completely fails at
meeting the GNU Coding Standards, where, in section 6.1 it is stated,
"Make sure your manual is clear to a reader who knows nothing about the
topic and reads it straight through."  Section names don't properly
reflect their content, information is scattered, and the
language/terminology is confusingly inconsistent.  After all the times
I've read and re-read this chapter now, I'm pretty sure it's not just me.

I could already make some proposals to restructure the content to make
it more reader-friendly, but I won't yet for a couple reasons.  First, I
don't know how open libc-alpha is to any restructuring of the manual yet
(I'm only talking about sections and their content within the chapter).
 Second, I can't say that I'm comfortable with an undertaking like that
until I've had more experience with the developers and exposure to the
library's manual and sources.

So this message is also something of an update so you know where that
one manual editor ran off too.  Again, thank you for your time and I
look forward to learning and contributing with you all.

Sincerely,
Rical Jasan