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

Re: Syntax issues in Policy Manual

On Jun 26, 2009, at 16:15, Lesley Binks wrote:

2009/6/26 Jeremiah Foster <jeremiah@jeremiahfoster.com>:

       On this page:
http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Files one
can see the following sentence under "5.6.21 Files"

"In all cases the part of the field contents on the same line
as the field name is empty."

This syntax is rather garbled. I'd like to propose a fix for that
entire paragraph;

"The 'Files:' field contains information for files included with the package. The rest of the 'Files:' line must be empty. Immediately following the 'Files:' line is a list containing one file per line with each line being indented with a single space and fields separated by spaces."

It might be nice to have a wiki for the Manual then one can make
changes to the text without having to have a committer bit.

       Warm regards,

Hi Jeremiah

I'm sorry to say I disagree on both counts :(

Quite alright. :)

I find the paragraph
"This field contains a list of files with information about each one.
The exact information and syntax varies with the context.  In all
cases the part of the field contents on the same line as the field
name is empty. The remainder of the field is one line per file, each
line being indented by one space and containing a number of sub-fields
separated by spaces. "
to be quite clear.

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. 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."

You also should use a pronoun make it clear. But furthermore, it is a very confusing sentence and ought to be re-worded. As is the paragraph, as is that page and the manual in general. As someone who works often with new debian packagers with the debian-perl group, I find they do not read the manual because they find it hard to understand. Frankly, the English is stilted throughout.

Having read the existing  paragrpah I understand that the field name
"Files:" is on a line of it's own ( in differentiation to the syntax
of Control Files as described in section 5.1 of the same document).
The field values then appear on separate lines indented by one space
and containing contextually varying space separated sub-fields i.e.
values relevant to the datum on this specific line which vary
depending on context.

I feel your suggestion lacks something important about the nature of
the data -namely that the 'Files:' field is a control field and the
list of files (and each file's sub values ) is its value.

I think that is obvious by the context, which is discussing the list fields in a .changes file.

Furthermore, while the list of field values has contextually varying
sub-values, they all follow a particular format which is adequately

I think all that is succinctly conveyed in the original text.

At best I would simply add a comma after "In all cases, ...".  The
sentence is grammatically correct - the subject is "the part of the
field contents on the same line as the field name" and it is empty.
Semantically I had to use the existing paragraph and refer to section
5.1 to understand your aim here.

Again, that is not a grammatically correct sentence. To make it correct you'd need to specify

"In all cases, the part of the field contents which is on the same line as the field name, is empty."

But still, with the help of that pronoun to show what you are referring to, you see the fact that you are referring to "contents" of something which is "empty." Odd, at best - confusing at worst.

I am not convinced by your arguments and still feel alternative wording of that entire paragraph is required.

I am also cautious about wiki'ising this manual.  I'd rather we go
through a more cautious process of agreeing the wording and ensuring
the detail is clear to all readers globally.

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.

While English is my native tongue I am sure it is difficult where it
is a second language and if we change one part in English then what
about translations?

I would be tempted to do a tidy up by consistently calling the field
values either field values or field contents at least in the whole of
section 5.

I understand how difficult it is to write technical documentation accurately, and I think debian documentation is good. I most certainly do not want to impugn anyone's hard work, I think everyone involved with that document has done a great job. But I think it needs to undergo a transformation to be used more broadly. Keeping it in the form that it is now is only going to prevent that change.

Warm regards,


Reply to: