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

Re: Syntax issues in Policy Manual



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.  :)

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>


Reply to: