Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[Ben Finney]

Howdy David,

Thank you for caring about the documentation and source, I am very
glad of the review of my proposed changes.

On 24-May-2016, David Kalnischkies wrote:
> RFC2440 refers to a "key-value pair" as "Armor Header" (in that
> casing). A collection of those is called "Armor Headers" – compare
> §6.2 (especially the two paragraphs above the "Armor Header Key"
> list).

Thank you. I have removed those changes and left that standard
terminology in place.

> > rfc822-style
> 
> If I have seen it right, we talk about our own method-interface
> here, which for self-containment is probably better described as
> deb822 style as we have that around as a manpage while rfc822 deals
> with all sorts of things not applying to us.

The deb822-style describes formats like the package control fields.

I confusingly wrote “RFC 822” when referring to APT's HTTP-style
protocols. It just doesn't apply.

> > rfc2616
> 
> Is superseded by now (7230-7237), so it shouldn't be referred to anymore
> the HTTP protocol anymore.

I have updated the commit messages to reflect the current HTTP
standards for those cases.

Please let me know whether you require further changes in

to accept the merge.

-- 
 \ “I have an answering machine in my car. It says, ‘I'm home now. |
  `\  But leave a message and I'll call when I'm out.’” —Steven Wright |
_o__)  |
Ben Finney 


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[David Kalnischkies]

On Sun, May 22, 2016 at 01:32:20PM +1000, Ben Finney wrote:
> On 21-May-2016, David Kalnischkies wrote:
> > As an example, your changes in the context of gpgv are incorrect as
> > the official term in rfc2440 for the "key-value pairs" is "Armor
> > Header" not field as you suggest and even if that is grossly
> > inconsistent I don't think its a good idea to change this.
> 
> The documentation refers to the “armor header” as the collection of
> name-value pairs that head the armor. I have now followed this
> terminology.

No. RFC2440 refers to a "key-value pair" as "Armor Header" (in that
casing). A collection of those is called "Armor Headers" – compare §6.2
(especially the two paragraphs above the "Armor Header Key" list).


> > In the context of http(-like) the more correct term might be "header
> > fields" which you use sometimes (then you replaced a 'line'), but
> > not always. In comments just "fields" might be correct much like the
> > RFC uses it in long paragraphs where its clear what is meant, but in
> > error messages we should perhaps be using the full term.
> 
> I have tried to make minimal changes to the text of messages. For many
> context there is no other kind of field, so “field” suffices in most
> places.

In messages displayed to users any change is a "big" change (see
translations below), so being verbose isn't a problem – especially as we
can't make any assumptions about the context such error messages will be
print in and the user reading them.


> > (btw: the registry for "Message Header Field Names" is called
> > "Message Headers", so using "headers" isn't as inconsistent as you
> > make it sound)
> 
> If that name is used, it's another inconsistency :-)

https://www.iana.org/assignments/message-headers/message-headers.xhtml

See RFC7231: "Hypertext Transfer Protocol (HTTP/1.1): Semantics and
Content" §8.3 among others, so… good luck changing that I presume.


> > Changing the tests/integration/status-* files is interesting in so
> > far as you are modifying the descriptions of actual packages (which
> > might or might not be changed in the meantime).
> 
> Do those packages actually exist? I didn't realise.

Usually they do… The status-* and Packages-* files tend to be (reduced)
real-world examples. There are exceptions in which they are completely
constructed, but those are quite obvious if you see them…

The package in question is 'insserv' btw, which still has this
description and I would assume they have field knowledge, so I would
pass such a change up to them first.

(And yes, in theory changes to those files can modify the tests – in
practice in these two instances they wont as these tests do not deal
with Descriptions)


> > In the documentation you do typo/style fixes (FDs, URIs, HTTP, …)
> > which should be fixed in the translations (doc/po) as well to avoid
> > needless fuzzies.
> 
> I am not sure how to do this (I am not familiar with proper use of
> gettext). I only changed terms in the area where I was already
> changing “header” and “field” terminology.
> 
> Which files should I modify for translation? Some are auto-generated,
> I think.

Yes, *.pot files are traditionally auto-generated from the sources.  It
is needed if you want to start a new translation.  It is also used to
update existing translations (*.po) automatically by marking all
strings which were changed as "fuzzy" so a translator has to review them
before they are used again which is unneeded busywork if all what is
done in the message is a fixed typo. I tend to do it manually, but there
are also tools to help you: man 1p msguntypot.

You are lucky, most of your changes are to files which aren't translated
– looks for me like its just one and in that commit you modified the pot
file, too. Given that this is just changing a Translator comment, its
a prime candidate for msguntypot.


> doc/Doxyfile.in

The file is semi-autogenerated as in: While it contains our
configuration for doxygen, it is updated by "doxygen -u" (manually)
which is reverting your changes to the comments, so you will have to
talk to doxygen upstream as this isn't our doing (and effects ever
doxygen user).


> rfc822-style

If I have seen it right, we talk about our own method-interface here,
which for self-containment is probably better described as deb822 style
as we have that around as a manpage while rfc822 deals with all sorts of
things not applying to us.


> rfc2616

Is superseded by now (7230-7237), so it shouldn't be referred to anymore
the HTTP protocol anymore.


Best regards

David Kalnischkies


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[Ben Finney]

On 21-May-2016, David Kalnischkies wrote:

> Could you please split especially the first one up more?

I have now updated the branch with more granular changes
.

> As an example, your changes in the context of gpgv are incorrect as
> the official term in rfc2440 for the "key-value pairs" is "Armor
> Header" not field as you suggest and even if that is grossly
> inconsistent I don't think its a good idea to change this.

The documentation refers to the “armor header” as the collection of
name-value pairs that head the armor. I have now followed this
terminology.

> In the context of http(-like) the more correct term might be "header
> fields" which you use sometimes (then you replaced a 'line'), but
> not always. In comments just "fields" might be correct much like the
> RFC uses it in long paragraphs where its clear what is meant, but in
> error messages we should perhaps be using the full term.

I have tried to make minimal changes to the text of messages. For many
context there is no other kind of field, so “field” suffices in most
places.

> (btw: the registry for "Message Header Field Names" is called
> "Message Headers", so using "headers" isn't as inconsistent as you
> make it sound)

If that name is used, it's another inconsistency :-)

> Changing the tests/integration/status-* files is interesting in so
> far as you are modifying the descriptions of actual packages (which
> might or might not be changed in the meantime).

Do those packages actually exist? I didn't realise.

Will the corrected text alter the outcome of the test case?

> Changing to "LSB fields" is in sofar interesting as even the
> "official doc" [0] isn't clear on which term is preferred.

Yes. I have made note of this in the separate revision now committed.

> In the documentation you do typo/style fixes (FDs, URIs, HTTP, …)
> which should be fixed in the translations (doc/po) as well to avoid
> needless fuzzies.

I am not sure how to do this (I am not familiar with proper use of
gettext). I only changed terms in the area where I was already
changing “header” and “field” terminology.

Which files should I modify for translation? Some are auto-generated,
I think.

> Some of the http->HTTP changes are wrong as these parts are talking
> about the method named 'http', not the protocol 'HTTP'.

Right, I have taken more care and distinguished ‘http’ as a method
name now.


Please (someone) review the latest update when you have time, and let
me know what should be done to get the changes in.

-- 
 \ “The aim of science is not to open the door to infinite wisdom, |
  `\but to set some limit on infinite error.” —Bertolt Brecht, |
_o__)_Leben des Galilei_, 1938 |
Ben Finney 


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[Ben Finney]

On 21-May-2016, David Kalnischkies wrote:

> (incomplete quick look)

Thank you for looking and giving a prompt response.

> Could you please split especially the first one up more?

Yes, I'll do that.

-- 
 \ “Pinky, are you pondering what I'm pondering?” “I think so, |
  `\ Brain, but me and Pippi Longstocking — I mean, what would the |
_o__)  children look like?” —_Pinky and The Brain_ |
Ben Finney 


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[David Kalnischkies]

Hi,

(incomplete quick look)

On Sat, May 21, 2016 at 04:41:19PM +1000, Ben Finney wrote:
> On 21-May-2016, Ben Finney wrote:
> > I will prepare a change set to correct the documentation, code
> > comments, and messages emitted by APT.
> 
> These changes are in the Git branch at
> .

Could you please split especially the first one up more?

As an example, your changes in the context of gpgv are incorrect as the
official term in rfc2440 for the "key-value pairs" is "Armor Header" not
field as you suggest and even if that is grossly inconsistent I don't
think its a good idea to change this.

In the context of http(-like) the more correct term might be "header
fields" which you use sometimes (then you replaced a 'line'), but not
always. In comments just "fields" might be correct much like the RFC
uses it in long paragraphs where its clear what is meant, but in error
messages we should perhaps be using the full term.

(btw: the registry for "Message Header Field Names" is called "Message
Headers", so using "headers" isn't as inconsistent as you make it sound)

Changing the tests/integration/status-* files is interesting in so far
as you are modifying the descriptions of actual packages (which might or
might not be changed in the meantime). Changing to "LSB fields" is in
sofar interesting as even the "official doc" [0] isn't clear on which
term is preferred. I guess they are to be treated as http-like. Either
way, I don't see much point in changing testdata, but with the rest…

In the documentation you do typo/style fixes (FDs, URIs, HTTP, …) which
should be fixed in the translations (doc/po) as well to avoid needless
fuzzies.

Some of the http->HTTP changes are wrong as these parts are talking
about the method named 'http', not the protocol 'HTTP'.


> For consistency, the function names and other API should be changed
> (so that, for example, the collection of header fields is not named
> ‘headers’, or that an individual field is not named ‘header’).

Well, as usual, we can't easily change public API so I would like to
avoid that for the moment… we could look into it after stretch.

If it is non-public like in methods/ you could run wild…


Best regards

David Kalnischkies

[0] https://wiki.debian.org/LSBInitScripts/


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[Ben Finney]

Control: tags -1 + patch

On 21-May-2016, Ben Finney wrote:
> I will prepare a change set to correct the documentation, code
> comments, and messages emitted by APT.

These changes are in the Git branch at
.

For consistency, the function names and other API should be changed
(so that, for example, the collection of header fields is not named
‘headers’, or that an individual field is not named ‘header’).

If desired, I can come up with a change set to bring those names into
line also.

-- 
 \ “I went to the museum where they had all the heads and arms |
  `\  from the statues that are in all the other museums.” —Steven |
_o__)   Wright |
Ben Finney 


signature.asc
Description: PGP signature

Bug#824908: apt: inconsistent “header” terminology throughout documentation, comments, messages

[Ben Finney]

Package: apt
Version: 1.2.12
Severity: minor

The code base for APT uses the term “header” in several distinct ways.


The following usages correctly refer to the singular content at the
head of some data stream:

* The singular header of a binary file, such as an AR archive.

* The singular header of an HTTP request or response.


Other usages are confused and should be corrected:

* The head of a section in a document. This is correctly termed a
  “section head” or “heading”.

* The name-value pair of a field, such as in a Packages file. This is
  correctly termed a “field”.

* The name-value pair of a field in a header, such as a field in an
  HTTP request. This is correctly termed a “header field”.


I will prepare a change set to correct the documentation, code
comments, and messages emitted by APT.

Translation files are present in the VCS, but I will leave those
untouched because I think they are generated automatically.

-- 
 \   “A free society is one where it is safe to be unpopular.” |
  `\—Adlai Ewing Stevenson |
_o__)  |
Ben Finney 


signature.asc
Description: PGP signature