Bug#422552: Minor typos and wording suggestions
Michael Tautschnig writes ("Bug#422552: Minor typos and wording suggestions"):
> While reading the Debian policy I found some minor things I'd like to see
> improved. I'm refering to the PDF dated 2006-10-02, so page numbers might be
> slightly inaccurate, please bear with me.
I'm sorry to have to say this but I your list seems to be largely
wording changes intended to make the language more idiomatic, but I
think that your command of idiomatic English is not sufficiently
strong to reliably make these kind of wording improvements.
The following changes seem correct to me:
> - Page 8, 2.5 Priorities, Paragraph on "required": s/Removing an
> required/Removing a required/
>
> - Page 40, 6.2, heading: Maintainer scripts Idempotency -
> idempotency should be lowercase here.
The following are matters of opinion about which I disagree:
> - Page 39, 6.1, fourth paragraph: ... (this is usually true when
> writing shell scripts, in fact). - This is the Debian policy, I
> think this is not the point for giving general advice (or even
> opinions of the authors, even though I do agree here). Rather, the
> reader should be referred to 10.4, Scripts, where this is
> discussed appropriately.
Experience has shown that a very large proportion of sh programmers
fail to use set -e appropriately. I think this rider is important
here because otherwise the text could be read to suggest that this was
something which applies particularly to dpkg maintainer scripts.
Since this is such a common failing it's worth using the space here
for this imprecation.
> - Page 40, 6.1, first paragraph of page 40: ... These considerations
> really apply to all shell scripts. - Again, this is the Debian
> policy, not the point for general advice, refer to 10.4.
This is less of a common problem nowadays but even so it is worth
making it clear that these comments are't something specifically to do
with dpkg or Debian.
> - Page 41, 6.6, 1, 2: ... If this does not work, the error unwind:
> -- so - what, there seems to be some part of the sentence missing.
I think this can be read as `dpkg will attempt .... the error
unwind'. In any case the meaning is clear and additional verbiage
will hurt rather than help the clarity of the text.
The following changes seem simply wrong to me:
> - Page 39, 6.1, third paragraph, first line: ... exit status from
> these scripts. ... should read ... exit status of these
> scripts. ...
>
> - Page 40, 6.3: ... redirected into a pipe for ... ; this should be
> ... redirected to a pipe for ...
>
> - Page 40, 64: ... system looks for the exit status ... ; this
> should be ... system looks at the exit status ...
>
> - Page 9, 2.5 Priorities, Paragraph on "extra": This is not too nice
> read, I'd suggest the following wording: extra For one, this
> contains all packages that conflict with others of priority
> required, important, standard or optional. Furthermore it is used
> for packages that are only likely to be useful if you already know
> what they are or packages that have specialized requirements.
>
> - Page 39, 6.1, second paragraph: ... and must not be not
> world-writable; either this is a major error as it means that the
> files _must be_ world-writable, or it should be reworded to must
> be world-writable. Then it would deserve some explanation because
> usually one would never want world-writable scripts.
Ian.
Reply to: