Re: Syntax issues in Policy Manual
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 :(
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.
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.
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.
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.
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.
Regards
Lesley
Reply to: