This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


On Sun, Jan 18, 2015 at 8:22 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> 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).

I guess what we need is an agreed upon reference saying NUL
is gone.  I *like* NUL. It's explicitly different than null or NULL.
Last time you said you wouldn't argue,
but now it's become an absolute requirement.
The rules for how to write NUL/null/NULL have changed,
and that's unfortunate.  And there was no discussion
going into this decision (I guess we're having it now, but still ...).

> And even back then,
> this was an abbreviation, not the full name.

It's a name, abbreviated or otherwise.
And a nice one to because it's clear and unambiguous.

>> > 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"?

I'm not sure I'd use formal phrasings such as "but not limited to",
but I would want to say that one must write, e.g., null-terminated
instead of NUL-terminated.
We have a bazillion coding convention rules,
for good reasons.
I think we can manage a few more for docs.

There are doc writing conventions already, btw,

http://www.gnu.org/prep/standards/standards.html#Documentation

and, heh, I'd forgotten that I'd already started a wiki
page for local rules/conventions.

https://sourceware.org/gdb/wiki/Internals%20GDB-Doc-Standards

So at least that part is done. :-)

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

Depends, I think.
If in the future one doesn't understand or even disagrees with the
replacement (how many disagree with our coding
convention of half-indented braces! 1/2 :-)) then having
such things written down will help advance the discussion,
in part because the discussion has already been had
and decided!

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

This isn't about asking anyone to step down.
This should also not be about trust.
If you can present a convincing argument
that draws on external references to support
your claim that NUL is "archaic" and shall not be used
in new documentation, I'll certainly re-evaluate
my opinion.
[I'll also hold an Irish-style wake for NUL.
Guinness for everyone! 1/2 :-)]

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

I still see NUL being referred to in the various places I look
as a valid name (abbreviation or otherwise).

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

The distinction is lost on me.
E.g., NUL-terminated names are strings of characters,
the last one of which has the valid name of NUL.

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

for reference sake,
This characterization bothers me.

> Nowadays,
> this is simply an obstacle to reading and understanding the text.  The
> purpose of my comments was to make the text more readable.

Alas the loss in readability is lost on me.
Is it really an obstacle to reading and understanding the text?
I'm not convinced.

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

If it serves to put in writing absolute rules that someone is likely
to get tripped up by or not understand then it will have served its purpose.

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

Called me?  I'm not sure how to interpret that.

I'm guessing no one else is interested in the discussion,
which is not unreasonable :-), so where we go is
I write "null-terminated" and get it written down so
that I can remember it.

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

Not rush to judgment would be a start.
"flatly refused" is pretty out there.
If our roles were reversed (the topic would have be different of course)
I would have said something like "I really think [...] is the
way to go because [...]. Please reconsider."
And even then I may not impose any kind of veto.

[E.g., in a different thread the pascal folks want to add
a patch that I think is unnecessary (though there's still
an outstanding question, and there may be a use-case
where the patch adds value) but I can live with it,
with perhaps a few mods and comments to the effect
that it's a pascal-specific choice. Depending on the
answer to the outstanding question, I'd be uncomfortable
with that choice becoming more general though.]

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

I don't understand.
I explicitly wrote that I was only talking about the cases other than
"supported on all platforms."  Of course we wouldn't like THAT 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.

IMO it's not an improvement.

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

"Suggest"?
Are you sure you meant to write that?
[I do try to review what I say before I hit Send,
but I don't always succeed and catch everything,
and I certainly allow anyone else to hit Send to soon as well.]

If I've made a suggestion to someone, and they
don't take it, then if it really was just a suggestion
I'd accept that.  If, OTOH, they still preferred their solution,
and while I may have used the word suggestion
the first time when in reality it was intended as a command,
then I would then say so.  The person I'm talking
to might take my future "suggestions" a little more
tepidly though, so clarity is important here.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]