Re: [PATCH] Add support for embedding scripts in .debug_gdb_scripts.

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 17 Jan 2015 20:15:46 -0800
> From: Doug Evans <xdje42@gmail.com>
> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> 
> > I wasn't talking only about that.  I was talking in general about the
> > argument "we do this elsewhere 'like this', so let's continue doing
> > that 'like this'".  For example, the "NUL" thingie.
> 
> NUL has been the name of the zero byte in ASCII since the early 60s.

Not any longer: its Unicode name is "NULL" (upper-case, because
Unicode uses upper-case for all character names).  And even back then,
this was an abbreviation, not the full name.

> > Maybe we should, but I'd like first to agree that an argument of this
> > kind doesn't have too much weight.  It's okay to look at past
> > practices when the choice is purely stylistic.  But when there are
> > clear advantages to deviating from past practices, those past
> > practices shouldn't hold us back, otherwise we will stagnate.  Agreed?
> 
> Only to the extent that such reasoning must be re-evaluated
> every time it is applied.

I agree with "re-evaluated".  I don't agree with "rejected" as the
default modus operandi.

> Plus, I don't understand the point about more formal conventions
> not having too much weight.  People should be able to write code
> with some expectation that what they've written is correct.
> The same should be true with NEWS/doc.
> And one way we do that is with documented rules and conventions.

I don't think it's reasonable, or even practical, to codify each and
every case like that.  Did you really mean that we write down
something like "use 'null byte' for the byte whose value is zero,
including, but not limited to, when talking about C-style string
terminator"?  There would be any number of such "rules"; following
them will probably be a much higher PITA than occasionally having to
replace words after a review.

I normally don't argue about style, except when I think there's more
than just style at stake.  Eventually, people should trust the
validity of my views on these matters, or ask me to step down.

> > In this case, "NUL" is simply incorrect English: there's no such word
> > or acronym.  The only legitimate use of "NUL" I know of is in
> > reference to the DOS/Windows null device.
> 
> Au contraire.
> NUL has been the common name of the zero byte since long before
> gdb was born.
> Ref: above link on ASCII, for example

See above.

In any case, you weren't talking about "NUL" the name, you said things
like "NUL-terminated names" and "non-NUL prefix byte".  This isn't
about "NUL" the character's archaic name, this is about a byte whose
value is zero, a.k.a. "null".  And our audience is 21st century
readers, not vintage 1960s flock of assembly-language programmers, for
whom NUL and STX were acronyms they saw all day every day.  Nowadays,
this is simply an obstacle to reading and understanding the text.  The
purpose of my comments was to make the text more readable.

> Let's add a new section to the conventions wiki for NEWS/docs.
> One of those entries will be:
> 
> All NEWS entries for new features shall specify the platform(s) on which
> the feature is available, if it is not a generally available feature.
> [or words to that effect]
> And let's enforce all these rules the way we do
> coding conventions (which I don't have a problem with).
> 
> Ok?

I'm fine with that, if no one objects.  But you cannot possibly codify
all such minor issues, they are too many.  And it isn't needed, from
my POV.

> > I can also live with you asking me in response to please change all
> > the other instances to use the same style.  But what I would prefer
> > not to live with is flat refusal to make a requested change in your
> > patch because "we do that elsewhere".
> 
> If I believe the request is invalid (e.g., NUL), then
> I've got to push back.

You did, and I called you.  If it weren't important, I would've
accepted.  I didn't.  Where do we go from here?

> Also, until the patch is checked in, it's premature
> to assess whether anything was flatly refused.

You didn't agree and didn't propose any compromise, so how else to
understand your reaction?

> If the community agrees to requiring new non-general features
> in NEWS to always specify the platform they're for, then I'm happy
> to go with the flow.

IMO, which changes need to mention the platforms is a judgment call.
So no such generally enforced rule is necessary.  But if we want to
state that always, I don't object, although in many cases it will be
redundant, and will probably say something like "supported on all
platforms".  I suspect we won't like the result.

> >> These things seem to be of a "shall be this way" flavor,
> >> and I wasn't expecting that.
> >
> > Isn't that normal during patch review process?
> 
> Not when one of the choices is perfectly valid (e.g., NUL).

So is the text I proposed instead.  This isn't about validity, this is
about making the text more easily read and understood.

Judging human-readable text includes suggesting better wording, even
if the original one is valid.  When I suggest a different wording or
spelling, I don't necessarily mean to say the original was incorrect
or invalid, just that there's a better one.  Don't we want our manual
to be as best as possible?