Re: Syntax issues in Policy Manual
On Fri, Jun 26, 2009 at 1:00 PM, Russ Allbery<rra@debian.org> wrote:
> Jeremiah Foster <jeremiah@jeremiahfoster.com> writes:
>
>> This line: "In all cases the part of the field contents on the same
>> line as the field name is empty." is not correct English syntax.
>
> There's arguably a missing comma, but I believe it's correct English
> syntax. The subject is the noun phrase:
>
> "the part of the field contents on the same line as the field name"
>
> The problem is that this is deeply nested syntax, more so than is easy
> to read. The simple subject is "part" modified by "of the field
> contents", with "on the same line" modifying "contents" and "as the
> field name" modifying "line". So if you diagram the sentence, there's a
> bunch of gunk hanging off the subject and getting between it and the
> verb, which is why you're finding it hard to read.
>
>> At the very least, you need to create a dependent clause thusly;
>>
>> "In all cases, the part of the field contents on the same line as the
>> field name, is empty."
>
> The second comma here *would* be a grammatical error. You cannot
> separate the noun from the verb with a comma.
>
> How about:
>
> In all cases, Files is a multiline field. The first line of the
> field value (the part on the same line as <tt>Files:</tt>) is always
> empty. The content of the field is expressed as continuation lines,
> one line per file. Each line must be indented by one space and
> contain a number of sub-fields, separated by spaces, as described
> below.
>
> The easiest way to make things easier to read is generally to rephrase
> into more, simpler sentences.
>
> We should probably also add an example.
>
>> Well you could have a wikified version and a non-wikified as you like,
>> but surely a wiki would be more open and reflect debian's openness.
>
> The whole point of Policy is that it only changes through a formal
> review process. It's exactly the opposite of a wiki. :)
I agree that Policy should be kept a closely reviewed thing. But maybe
we can have something like AnnoCPAN, where users are allowed to
provide /annotations/ inline with the actual policy. So people can add
things like "be careful here, this means ..." or something.
Then those annotations can be considered proposed changes for the
future, and the Policy folks can look through that to integrate things
(like clearer wording) into the actual, official Policy.
It is, I suppose, somewhere between a full wiki and the current
protectionist measures :-)
>
> --
> Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
>
>
> --
> To UNSUBSCRIBE, email to debian-policy-REQUEST@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
>
>
Reply to: