None of the edits I made were in criticism. In an academic context a proof reader would mark almost all the same sentences for revision.
August 10, 2022 9:06 AM, "Maxime Devos" <[email protected]> wrote: > On 10-08-2022 08:10, [email protected] wrote: > >> August 5, 2022 1:59 PM, "Maxime Devos" <[email protected]> wrote: >> Technical grammatical correction: the software that Guix "has" is that in >> the monorepo, >> 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 "freed" >> source code rather than the unmodified upstream source (see: 28.4.1 Software >> Freedom). >> --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 >> readers. > > "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 >> builds), >> 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. >> >> [1] https://en.wikipedia.org/wiki/Redundancy_(linguistics) > > 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 copyleft.org > 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 >> suggest: >> --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 unnecessary >> 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 project". >> >> 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 "working". >>> 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 >>> patches. >> >> 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 >> explicit. > > 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 >>> name. >>> >>> "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 >> embedded. >> 3rd case: predication is determined by the past. We can know whether x was >> *ever* embedded. >> >> Why? > > 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. > > Greetings, > Maxime.
