[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: v2: A proposal of a consistent set of clear rules and guidelines inv

From: Maxime Devos
Subject: Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches.
Date: Wed, 10 Aug 2022 11:06:34 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.12.0

On 10-08-2022 08:10, wrote:
August 5, 2022 1:59 PM, "Maxime Devos" <> wrote:
Technical grammatical correction: the software that Guix "has" is that in the 
but it "distributes" many packages. Thus:
--8<---------------cut here---------------start------------->8---
* In principle, Guix only distributes free software; when the upstream source 
contains some
non-free software, it should be removed such that ‘guix build --source’ returns the 
source code rather than the unmodified upstream source (see: 28.4.1 Software 
--8<---------------cut here---------------end--------------->8---
I consider the difference between referring to external source code by 
including a
(snippet-sanitised) copy or downloading it from an URL + snippet-sanitising to 
be immaterial,
except for space and I/O savings, so I consider "has" to include "distributes".

While "distributes" is more specific, I really meant "has" here -- 
gnu/packages/patches/... and
gnu/packages/*.scm must be free too, even if it is was not a distributed 
package (more concretely,
see the bits about patches failing to remove non-freeness).

This is simply a grammatical error. "Has" is third person singular. While its 
common to speak
in such a way, it's not proper English, and including minor slang should be 
avoided in technical
writing. Otherwise inconsistency of presentation is guaranteed, causing serious 
overhead for

"Has" is third person singular, and "Guix" is singular and not "I" or "you", so "has" seems appropriate here to me.

I think that matching the singular/plural of the verb and the subject is common, standard and proper English and not slang.

Going by previous replies, you seem to know English well, so I think there's some miscommunication here.

(Even better would be to replace the rather generic ‘to have’ by something more specific, but I'll have to think a bit about what would be more specific yet not overly specific.)

* The source of the package needs to correspond to what is actually built 
(i.e., act as the
corresponding source), to fulfill our ethical and legal obligations.
The [i.e.] addendum above is redundant, its better worded as:
--8<---------------cut here---------------start------------->8---
* The source of a package must correspond to what is actually built (i.e., 
there must be
an explicit relation between source code and the result of its build for all 
to fulfill our ethical and legal obligations.
--8<---------------cut here---------------end--------------->8---
You write that the addendum is redundant, but then change the addendum by 
replacing a word in the
addendum by a possible definition. I'm not following how that reduces 
redundancy, and it also
appears to be contrary to the lack of verbosity that Andreas would like.
Redundancy in language is information expressed more than once. Including 
redundant clauses
is bad grammar[1]

You wrote:
The source of the package needs to correspond to what is actually built (i.e., 
act as the
corresponding source)
You simply said the same thing twice. It is by definition, a redundant clause.

then change the addendum by replacing a word in the
addendum by a possible definition.
Elaboration doesnt necessarily add redunancy, it is useful for clarifying 
statements. I was
trying to infer your intention in adding the clause, to offer an example of how 
it could be
more clearly stated.


The purpose of 'i.e.' constructs is to state the same thing differently, to clarify matters (by elaboration or by redundancy). I don't see how redundancy is bad, though it can easily be overdone.

I think that explicitly mentioning the term 'corresponding source' instead of only the more implicit 'source of X corresponds to Y', because the former 'corresponding source' has a very specific meaning (*) in free software, whereas the latter construct is more ambiguous.

Compare with your definition 'there must be an explicit relation ...’, which loses a lot of nuance.

(*) E.g., the GPL has a long and detailed definition: ‘The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, [lots and lots of text]’.

I can look into inserting a footnote linking to the GPL or or such, to make clear "corresponding source" is a term on its own and not just some description, for people that don't already know about "corresponding source".

To make things more concrete and to resolve conflicts between the principles, a 
few cases have been
worked out:
To a newcomer (the target audience), the above may lead to confusion as to what 
wasn't already
concrete in the above descriptions, or what principles above come into 
conflict. There is a mild,
latent assumption that they are familiar with the Guix workflow, which should 
be avoided. Thus I
--8<---------------cut here---------------start------------->8---
For the purpose of clarifying preferred practices and reducing friction in the 
review process
introduced by subjective variation, a few guidelines have been worked out:
--8<---------------cut here---------------end--------------->8---
I don't see how a fancy wording amounting to essentially the same thing would 
reduce confusion or
avoid latent assumptions.
We have to consider how the audience will be experiencing the documentation. 
Are they reading it
like a novel, tuned in to each step of the process, or are they briefly 
approaching a paragraph
at a time, trying to quickly gather information for how to accomplish what they 
need so that they
can return to their work?

While we should seek to reduce verbosity, which means reducing the inclusion of 
information, we should also be optimizing each paragraph to be self-contained 
snapshots, lacking
ambiguity. I addressed this in my Guix Days talk, and most people seemed to 
agree with that point.

To make things more concrete and to resolve conflicts between the principles a 
few cases have been
worked out:
No "principals" had yet been explicitly addressed.
Assuming that principals = principles, those principles have already been mentioned above -- see the bullet list in 20.4.5. But yes, the conflicts have not yet been addressed and aren't anywhere.
If I stumble onto this sentence in isolation, I
will have have to ask: "What conflicts and principles?". By being explicit, we 
optimize towards a
"snapshot" that can be better understood in isolation.

The term "subjective variation" may be obtuse. I chose it in order to concisely say 
"... and
reducing friction in the review process introduced by several autonomous 
individuals with
distinct programming practices and backgrounds working together on a collective 

I think it does the work, but others may disagree.

I do not see how your wording is more explicit than mine.

While I did not mention what the conflicts were, neither are you mentioning (in the text itself) what the "subjective variations" would be.

I don't think you have to ask "What conflicts", as the more frequent cases have been worked out below, resolving the potential conflicts. There might be some conflicts remaining, but it's hard to write about conflicts of which I don't know that they exist, and if they are known to exist, I think it would be better to resolve the conflicts (with a few new worked-out cases) and that way remove them from existence.

I'll have a try at rewording things in the next version to avoid implicitness and ambiguity, though I do not expect success.

Additionally, I don't see why this sentence has to be understood in isolation but not the first two sentences ‘Snippets, phases and patches at times serve overlapping purposes. To decide between the three, there are a few guiding principles:’.

The purpose of the hypothetical patch or phase is to remove the non-freeness. 
As such, if the
non-freeness wasn't removed, the patch or phase did not work, for the local meaning of 
This is machine-independent (so no "it might work on their machine"), unless 
there is some kind of
non-determinism, but I haven't ever noticed that happening for non-freeness 
removal code.

For a patch, the problem is that a patch removing a non-free file automatically 
contains the
non-free file (^), and we do not want anything non-free to appear in Guix even 
if only in its
Is better as:
--8<---------------cut here---------------start------------->8---
For patches, the issue is that a patch that removes a non-free file 
automatically contains the
non-free file (^), and we do not want any non-free software to be distributed 
with Guix, even
if it only appears within the context of a patch.
Concerning phases, the problem is that they do not influence the result of 
‘guix build --source’.
--8<---------------cut here---------------end--------------->8---
Why the change:

* singular->plural (for: patch) -- is this to reduce the wordcount (avoid an 
'a'), or for
consistency, or ...?
* passive->active (for: removing -> that removes) -- it becomes more wordy, so 
seems harder to
follow for me
"Removing" is here a gerund, which shouldn't be applied to objects. This is a 
grammatical error.
The sentences as a whole were adjusted to accommodate the correction.

I don't know how this form of a verb would be classified in English. I don't see why "removing" shouldn't be applied to objects and I don't see how it is a grammatical error; that construct parses fine for me. It's a bogus construct in my native language but it seems to work well in English.

* appear->be distributed -- more wordy, also things parts of Guix itself (and 
hence not
distributed, except for "guix build guix" and "guix pull") should be free so I 
don't think being
more specific makes things more precise.
I'm not attached to using distributed over "appears", it just seems more 
I'll try looking for a more explicit word that is not too specific.

* "only in its patches" -> "if it only appears within the context of a patch" 
-- more wordy, and
more indirection
* "For a phases" -> "Concerning phases" -- slightly less direct
We're here discussing a general indefinite case, and thus the plural form is 
more proper.

Is "general indefinite case" grammatical terminology or a description? For the former: I'm not finding any relevant search results.

I am not following how you go from "a general indefinite case" to "thus the plural it is more proper". A plural seems to be more common in these situations and doesn't seem to cause trouble here so I think I'll switch to a plural in the next version, but I don't see how it is more proper.

more efficient use of time. Secondly, if the fix of a technical issue embeds a 
store file name,
then it has to be a phase. Otherwise, if the store file name were to be 
embedded in the source,
Right, I already introduces a store file name, and that "otherwise" refers to 
the same store file

"the store file name" is singular, so ^W^W -- nevermind, that's a subjunctive? 
I would go for the
simpler "if the store file name were embedded in the source", dropping the 'to 
be' indirection.
That sounds good to me.

Question: do you know how to decide between "if X were to be embedded"/"if X were 
embedded" and "if
X was embedded"?
1st case: evokes future anterior; predication is contingent & retroactive. 
Should be used in
indeterminate circumstances.
2nd case: predication is determined by the present. We can know at present 
whether x is currently
3rd case: predication is determined by the past. We can know whether x was 
*ever* embedded.


I was wondering if the 2nd case is considered correct grammar (even if maybe not appropriate in this particular case) or just a personal quirk. Also, when learning English grammar, it was more based on 'feel' than explicit rules and consequently it was hard to decide between (2) and (3).

I don't know about (1), but (3) indeed doesn't seem appropriate here.

I'll change it to (2) in the next version.


Attachment: OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]