[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: |
blake |
Subject: |
Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches. |
Date: |
Wed, 10 Aug 2022 10:33:32 +0000 |
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" <maximedevos@telenet.be> wrote:
> On 10-08-2022 08:10, blake@reproduciblemedia.com wrote:
>
>> August 5, 2022 1:59 PM, "Maxime Devos" <maximedevos@telenet.be> 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.
- v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., Maxime Devos, 2022/08/05
- Message not available
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., blake, 2022/08/05
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., Maxime Devos, 2022/08/09
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., blake, 2022/08/10
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., Maxime Devos, 2022/08/10
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches.,
blake <=
- Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches., Maxime Devos, 2022/08/10
[PATCH] doc: Update contribution guidelines on patches, etc., Liliana Marie Prikler, 2022/08/06
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Maxime Devos, 2022/08/09
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Liliana Marie Prikler, 2022/08/09
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Maxime Devos, 2022/08/09
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Liliana Marie Prikler, 2022/08/09
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Maxime Devos, 2022/08/09
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Liliana Marie Prikler, 2022/08/10
- Re: [PATCH] doc: Update contribution guidelines on patches, etc., Maxime Devos, 2022/08/09
[PATCH v2] doc: Update contribution guidelines on patches, etc., Liliana Marie Prikler, 2022/08/10