Re: Syntax issues in Policy Manual
On Jun 26, 2009, at 16:15, Lesley Binks wrote:
2009/6/26 Jeremiah Foster <jeremiah@jeremiahfoster.com>:
Hello,
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,
Jeremiah
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
described.
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,
Jeremiah
Reply to: