Bug#64437: PROPOSED] Must/Should/May in policy

[Peter Samuelson <peter@cadcamlab.org>]

[Anthony Towns <aj@azure.humbug.org.au>]
> Voila. Here's the final diff with the changes discussed

Here's my proofreading, and a few opinions:

>  	  authors do not claim that not donating is immoral,
>  	  unethical, illegal or something similar; otherwise they must
> -	  go in contrib (or non-free, if even distribution is
> -	  restricted by such statements).</p>
> +	  go in or non-free.</p>
	  ^^^^^^^^^^^^^^^^^
I think you mean "go in non-free".

> +	    (see below), and should not do so unless they depend on a
> +	    particular version of that package..</p>
	                                     ^^^^
s/.././

>  	    Note, that this applies only to directories <em>below</em>
>  	    <tt>/usr/local</tt>, not <em>in</em>
> -	    <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
> -	    itself may only contain the sub-directories listed in
> +	    <tt>/usr/local</tt>. Packages must not create sub-directories 
> +	    in the directory <tt>/usr/local</tt> itself, except those listed in

IMHO, s/sub-directories/directories/ for consistency.

> @@ -1165,7 +1184,7 @@
>      
>  	  <p>
>  	    The <tt>/usr/local</tt> directory itself and all the
> -	    subdirectories created by the package should have
> +	    subdirectories created by the package should (by default) have

In this context, "subdirectories" does make sense.

> @@ -1437,7 +1458,7 @@
>  	  <heading>Managing the links</heading>
>  	    
>  	  <p>
> -	    A program is provided, <prgn>update-rc.d</prgn>, to handle
> +	    The program <prgn>update-rc.d</prgn> is provided to make
>  	    the it easier for package maintainers to arrange for the
	    ^^^
Remove "the".

>  		<example>
>  		  Setting &lt;parameter&gt; to `&lt;value&gt;'.
>  		</example></p>

Shouldn't that be
		  Setting <var>parameter</var> to <var>value</var>.
?

> -	  If a program should depend on environment variables for its
> -	  configuration, the program has to be changed to fall back to
> +	  If a program usulaly depends on environment variables for its
	               ^^^^^^^
	               usually

>  	    only use POSIX features. If a script requires non-POSIX
>  	    features from the shell interpreter, the appropriate shell
> -	    has to be specified in the first line of the script (e.g.,
> -	    `<tt>#!/bin/bash</tt>') and the package has to depend on
> +	    should be specified in the first line of the script (e.g.,
> +	    `<tt>#!/bin/bash</tt>') and the package must depend on

I think "must be specified" is appropriate here, but I don't feel
strongly about it.

>  	  <example>
>  	    &lt;arch&gt;-&lt;os&gt;
>  	  </example>
>  	  where `&lt;arch&gt;' is one of the following: i386, alpha, arm, m68k,
>  	  powerpc, sparc and `&lt;os&gt;' is one of: linux, gnu.  Use

Again, <var>arch</var>-<var>os</var> rather than &lt; and &gt; .

> @@ -2947,7 +2968,7 @@
>  		<example>
>  		  /usr/lib/cgi-bin/&lt;cgi-bin-name&gt;
>  		</example>
> -		and can be referred to as
> +		and should be referred to as
>  		<example>
>  		  http://localhost/cgi-bin/&lt;cgi-bin-name&gt;
>  		</example></p></item>

And again.

> -		the Web Document Root.  Instead use the
> +		the Web Document Root.  Instead they should use the
>  		/usr/share/doc/&lt;package&gt; directory for documents and

And again.  Oh well, maybe this should be a separate patch.

> +	  programs (like IMAP daemons) must lock the mailbox in a
> +	  NFS-safe way. This means that <tt>fcntl()</tt> locking must

s/a NFS-safe/an NFS-safe/

>  	<p>
> -	  No package should ever install files into the directories
> +	  Package must not install files into the directories
	  ^^^^^^^
"Packages", or "A package".


Peter