[website] 02/06: Consistently start new sentences on a new line.

Bas Couwenberg sebastic at xs4all.nl
Sun Feb 16 00:14:38 UTC 2014


This is an automated email from the git hooks/post-receive script.

sebastic-guest pushed a commit to branch master
in repository website.

commit e1973928a4fff77b27d1fcdf69e181f354f468ee
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date:   Sun Feb 16 01:09:18 2014 +0100

    Consistently start new sentences on a new line.
---
 policy.xml | 275 ++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 152 insertions(+), 123 deletions(-)

diff --git a/policy.xml b/policy.xml
index d7981eb..9a6c072 100644
--- a/policy.xml
+++ b/policy.xml
@@ -59,8 +59,8 @@
     </para>
     <para>
       Thanks to efforts of the Debian GIS team, we currently have many
-      exciting GIS packages in Debian's main archives. Other programs
-      are well along their way to being included in the archive.
+      exciting GIS packages in Debian's main archives.
+      Other programs are well along their way to being included in the archive.
     </para>
     <para>
       The Debian source packages maintained by the Debian GIS team are also
@@ -108,17 +108,20 @@
     </para>
     <para>
       When working on these, you will find immediate targets for improvements
-      of the original English versions, too. For these, though, you need access
-      to Debian GIS's source code repository. Very welcome are tutorials that
-      guide Debian users towards the use of packages to their immediate benefit.
-      You may also consider to write respective articles for Magazines, be they
-      online or in print.
+      of the original English versions, too.
+      For these, though, you need access to Debian GIS's source code repository.
+      Very welcome are tutorials that guide Debian users towards the use of
+      packages to their immediate benefit.
+      You may also consider to write respective articles for Magazines,
+      be they online or in print.
     </para>
     <para>
       This policy is a work in progress, and attempts to document best
-      practices which evolve and change over time. Different people tend to do
-      things in different ways. If your way diverges, you may want to document
-      it here so that others can benefit. Please send any comments or ideas to
+      practices which evolve and change over time.
+      Different people tend to do things in different ways.
+      If your way diverges, you may want to document it here
+      so that others can benefit.
+      Please send any comments or ideas to
       <ulink url="mailto:debian-gis at lists.debian.org">debian-gis at lists.debian.org</ulink>.
     </para>
     <sect2 id="membership">
@@ -184,15 +187,16 @@
   <sect1 id="repositories">
     <title>Repositories</title>
     <para>
-      We use Git and Subversion (SVN) repositories, hosted by Debian. You can
-      have a look at each repository through Alioth's web interfaces:
+      We use Git and Subversion (SVN) repositories, hosted by Debian.
+      You can have a look at each repository through Alioths web interfaces:
       <ulink url="http://anonscm.debian.org/gitweb/">gitweb</ulink> and
       <ulink url="http://anonscm.debian.org/viewvc/pkg-grass/">ViewVC</ulink>.
     </para>
     <para>
       The Git repository is the primary location for our source packages these
-      days. However, the Subversion repository is still used for some packages
-      that have not migrated to Git yet.
+      days.
+      However, the Subversion repository is still used for some packages that
+      have not migrated to Git yet.
     </para>
     <warning id="umask">
       <para>
@@ -258,10 +262,10 @@
       <title>SSH tips</title>
       <para id="ssh-config">
         You can avoid specifying your Alioth user name by setting it in
-        <filename>~/.ssh/config</filename> as follows. Note that in that case,
-        with <command>debcheckout</command> you can replace the
-        <option>--user</option> option by the <option>-a</option> option, for
-        a shorter typing.
+        <filename>~/.ssh/config</filename> as follows.
+        Note that in that case, with <command>debcheckout</command> you can
+        replace the <option>--user</option> option by the
+        <option>-a</option> option, for less typing.
 <programlisting>
 Host *.debian.org
 	User your-user-name
@@ -269,8 +273,9 @@ Host *.debian.org
       </para>
       <para id="ssh-add">
         You can avoid typing your SSH password again and again using the
-        <command>ssh-add</command> command. On remote connections the SSH agent
-        needs to be enabled with the command <command>eval</command>
+        <command>ssh-add</command> command.
+        On remote connections the SSH agent needs to be enabled with the
+        command <command>eval</command>
         <option>$(</option><command>ssh-agent</command><option>)</option>.
       </para>
       <para id="wiki-alioth">
@@ -362,9 +367,10 @@ pkg-grass/
           <command>git-buildpackage</command> can be set to a directory layout
           similar to the one we use with <command>svn-buildpackage</command>
           by using the <literal>export-dir</literal> and
-          <literal>tarball-dir</literal> options. However those settings should
-          only be in a system-wide or user-wide <filename>gbp.conf</filename>
-          file and not the one committed in the Git repository.
+          <literal>tarball-dir</literal> options.
+          However those settings should only be in a system-wide or user-wide
+          <filename>gbp.conf</filename> file and not the one committed in the
+          Git repository.
         </para>
       </sect3>
       <sect3 id="other-git-branches">
@@ -524,20 +530,21 @@ pkg-grass/
         For packages where we set the <literal>mergeWithUpstream</literal>
         property, which excludes the upstream sources, there is no easy way to
         prepare a Git repository from our Subversion repository that would look
-        like the package was always managed in Git. Nevertheless, the following
-        recipe will generate a Git repository that contains all the history of
-        the debian directory, plus a collection of selected upstream source
-        releases.
+        like the package was always managed in Git.
+        Nevertheless, the following recipe will generate a Git repository that
+        contains all the history of the debian directory, plus a collection of
+        selected upstream source releases.
       </para>
       <itemizedlist>
         <listitem>
           <para>
             Start the conversion as explained in the
             <ulink url="http://wiki.debian.org/Alioth/Git#ConvertaSVNAliothrepositorytoGit">Alioth/Git</ulink>
-            page of the Debian wiki. To be consistent with a later usage of
-            <command>git-buildpackage</command>, it is preferable to prefix the
-            tag names <quote>debian</quote>. During this conversion, you can
-            take advantage of the file
+            page of the Debian wiki.
+            To be consistent with a later usage of
+            <command>git-buildpackage</command>,
+            it is preferable to prefix the tag names <quote>debian</quote>.
+            During this conversion, you can take advantage of the file
             <filename>/trunk/community/infrastructure/comitters</filename>
             in the Subversion repository, and expand it if necessary.
           </para>
@@ -577,12 +584,12 @@ pkg-grass/
         It is also possible to prepare a Git repository containing some of the
         package's history using the command
         <command>git-import-dscs --debsnap</command> from the helper toolkit
-        <command>git-buildpackage</command>. This will download all the versions
-        of a package available in
+        <command>git-buildpackage</command>.
+        This will download all the versions of a package available in
         <ulink url="http://snapshot.debian.org">snapshot.debian.org</ulink>
-        and create tags for each of them. Note that as this paragraph is
-        written, the tool is not aware that <literal>backports</literal>
-        should be a different branch.
+        and create tags for each of them.
+        Note that as this paragraph is written, the tool is not aware that
+        <literal>backports</literal> should be a different branch.
       </para>
     </sect2>
   </sect1>
@@ -592,9 +599,11 @@ pkg-grass/
       <title>Newcomer guidelines for building proper Debian packages</title>
       <para>
         Some newcomers tend to go the create DEBIAN dir, move files around and
-        `dpkg-deb -b` way to create Debian packages. Short answer: Forget about
-        this. The only way to the official Debian mirror leads via proper
-        source packages. The right way to build Debian packages is described in
+        `dpkg-deb -b` way to create Debian packages.
+        Short answer: Forget about this.
+        The only way to the official Debian mirror leads via proper source
+        packages.
+        The right way to build Debian packages is described in the
         <ulink url="http://www.debian.org/doc/manuals/maint-guide/">Debian New Maintainers' Guide</ulink>.
       </para>
       <para>
@@ -682,9 +691,8 @@ pkg-grass/
               <command>pristine-tar</command>
               (<ulink url="http://packages.qa.debian.org/p/pristine-tar.html">PTS</ulink>,
               <ulink url="http://manpages.debian.net/cgi-bin/man.cgi?query=pristine-tar">man</ulink>)
-              is used to allow byte-identical
-              recreation of the original tarball from the
-              <literal>upstream</literal> branch.
+              is used to allow byte-identical recreation of the original
+              tarball from the <literal>upstream</literal> branch.
             </para>
             <para>
               Use <command>git-buildpackage</command>'s
@@ -908,13 +916,15 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder
             <command>git-import-orig</command> makes it easy to update of the
             <literal>upstream</literal> branch using upstream releases
             distributed as a compressed archive, and to merge these changes in
-            the <literal>master</literal> branch. Its option
-            <command>--pristine-tar</command> is useful for stabilizing the MD5 sum
-            of the "<filename>orig.tar.gz</filename>" produced when building a
-            source package from the repository alone (not doing so results in
-            archive rejection of package updates). With recent versions of
-            <command>git-buildpackage</command>, it is often unnecessary to rename
-            the freshly downloaded original upstream archive.
+            the <literal>master</literal> branch.
+            Its option <command>--pristine-tar</command>
+            is useful for stabilizing the MD5 sum of the
+            "<filename>orig.tar.gz</filename>" produced when building a source
+            package from the repository alone (not doing so results in archive
+            rejection of package updates).
+            With recent versions of <command>git-buildpackage</command>,
+            it is often unnecessary to rename the freshly downloaded original
+            upstream archive.
           </para>
           <para>
             If you do not use <command>git-buildpackage</command>, please use
@@ -1054,7 +1064,8 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder
             </para>
             <para>
               This will create an empty, bare, shared Git repository and setup some
-              hooks. Each package is kept in its own Git repository.
+              hooks.
+              Each package is kept in its own Git repository.
             </para>
             <para>
               See the <link linkend="ssh-config">SSH tips</link> section for how to configure the default <command>ssh</command> username for <literal>git.debian.org</literal>.
@@ -1154,8 +1165,8 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder
           <para>
             That is, either include the changelog entry with each commit using
             <command>dch</command>,
-            or finish your work by updating the changelog, e.g. using
-            <command>gbp-dch</command>.
+            or finish your work by updating the changelog,
+            e.g. using <command>gbp-dch</command>.
           </para>
         </sect4>
       </sect3>
@@ -1285,33 +1296,40 @@ alias <command>svn-bt</command>='svn-buildpackage --svn-tag'
         <para id="svn-mergewithupstream">
           <command>svn-inject <replaceable>-o</replaceable></command> sets up the
           <literal>mergeWithUpstream</literal> property for the SVN directories
-          where packages are stored. In case <command>svn-inject</command>
-          was not used, you can do it by hand with the command
-          <command>svn propset</command>
-          <replaceable>mergeWithUpstream</replaceable>
-          <replaceable>1</replaceable> <replaceable>debian</replaceable>.
+          where packages are stored.
+          In case <command>svn-inject</command> was not used,
+          you can do it by hand with the command:
+<programlisting>
+<command>svn propset</command> <literal>mergeWithUpstream</literal> <literal>1</literal> <literal>debian</literal>
+</programlisting>
         </para>
         <para id="download-upstream-source">
-          To download the upstream sources (if there is a
-          <filename>debian/watch</filename> file):
-          <command>echo "origDir=.." >> .svn/deb-layout && uscan --force-download</command>.
-          Alternatively, you can try
-          <command>debian/rules get-orig-source</command>.
+          To download the upstream sources
+          (if there is a <filename>debian/watch</filename> file):
+<programlisting>
+<command>echo</command> <literal>"origDir=.."</literal> >> <filename>.svn/deb-layout</filename> && <command>uscan</command> <option>--force-download</option>
+</programlisting>
+          Alternatively, you can try:
+<programlisting>
+<command>make</command> <option>-f</option> <filename>debian/rules</filename> <literal>get-orig-source</literal>
+</programlisting>
         </para>
         <para id="svn-write-access">
           If you're a Debian Developer or a member of the pkg-grass group on
           Alioth, you can commit your changes: <command>svn commit</command>
-          (also <command>svn ci</command>). Otherwise, you can ask to be added
-          to the group (see the <link linkend="membership">Membership</link>
-          section), or send the result of <command>svn diff</command> to the
+          (or <command>svn ci</command>).
+          Otherwise, you can ask to be added to the group
+          (see the <link linkend="membership">Membership</link> section),
+          or send the result of <command>svn diff</command> to the
           <ulink url="mailto:debian-gis at lists.debian.org">mailing list</ulink>
-          (<command>gzip -9</command> it, if it's too large).
+          (<command>gzip</command> <option>-9</option> it, if it's too large).
         </para>
         <para id="svn-tag-release">
           It may happen that a package version has been uploaded to Debian
           repositories, and you forgot to tag the last build with
-          <command>svn-buildpackage --svn-tag</command>. You can tag this
-          package also retroactively. A first step, creating the tags directory,
+          <command>svn-buildpackage --svn-tag</command>.
+          You can tag this package also retroactively.
+          A first step, creating the tags directory,
           can be achieved in two ways: either create it locally as sibling of
           <filename class="directory">trunk/</filename> with
           <command>svn mkdir</command>
@@ -1386,11 +1404,13 @@ lintian ../build-area/*changes
       </para>
       <para>
         Please keep in mind issues like the possibility to upgrade to the next
-        Ubuntu stable release. Packages that are backports can be made
+        Ubuntu stable release.
+        Packages that are backports can be made
         <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version">inferior in version by using a tilde</ulink>.
         If the package contains additional development, a version number without
         the tilde will make it higher, but not as high as the next Debian
-        revision. For example:
+        revision.
+        For example:
 <programlisting>
   2.12.0-1~natty1 (backport in PPA)
 < 2.12.0-1        (from Debian in Ubuntu)
@@ -1434,12 +1454,12 @@ lintian ../build-area/*changes
       <title>R packages</title>
       <para>
         <ulink url="http://packages.qa.debian.org/r-base-core">GNU R</ulink>
-        sometimes introduces backward incompatibilities, so the current practice
-        is to make packages depend on versions equal or higher to the one 
-        against which they were built. When using <code>r-base-dev</code>,
-        this can be achieved by adding the substitution variable
-        <code>${R:Depends}</code> in the <literal>Depends</literal> field of
-        the binary package.
+        sometimes introduces backward incompatibilities,
+        so the current practice is to make packages depend on versions equal or
+        higher to the one against which they were built.
+        When using <code>r-base-dev</code>, this can be achieved by adding the
+        substitution variable <code>${R:Depends}</code> in the
+        <literal>Depends</literal> field of the binary package.
       </para>
     </sect2>
   </sect1>
@@ -1457,10 +1477,13 @@ lintian ../build-area/*changes
     </para>
     <para>
       The tasks files are not hosted in the Debian GIS repositories, but in the
-      Debian Blends repository. Interested members of the Debian GIS project on
-      the Alioth forge can request write access to the Blends repository.
-      You can easily check out its sources with the command
-      <command>debcheckout -a debian-gis</command>.
+      Debian Blends repository.
+      Interested members of the Debian GIS project on the Alioth forge can
+      request write access to the Blends repository.
+      You can easily check out its sources with the command:
+<programlisting>
+<command>debcheckout</command> <option>-a</option> <literal>debian-gis</literal>
+</programlisting>
     </para>
     <para>
       The syntax of the tasks files is very similar to Debian control files,
@@ -1540,8 +1563,9 @@ Uploaders: <replaceable>John Doe <johndoe at example.com></replaceable>,
             <title>Standards-Version</title>
             <para>
               Please always use the latest unless there are concerns for
-              backporting. If no changes are needed, please indicate this
-              fact in the changelog, and increment the value of the field.
+              backporting.
+              If no changes are needed, please indicate this fact in the
+              changelog, and increment the value of the field.
 <programlisting>
 Standards-Version: 3.9.5
 </programlisting>
@@ -1706,10 +1730,11 @@ pristine-tar = True
       <para>
         This file is recommended by the Policy
         (<ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource">§ 4.14</ulink>)
-        from version 3.8.0 for documenting source package handling. Please
-        follow the recommendation. For instance, this file is needed when we
-        use a patch system, when the upstream sources are in another format
-        than gzipped tar archive, when we repack the sources,…
+        from version 3.8.0 for documenting source package handling.
+        Please follow the recommendation.
+        For instance, this file is needed when we use a patch system,
+        when the upstream sources are in another format than gzipped
+        tar archive, when we repack the sources,…
       </para>
     </sect2>
     <sect2 id="debian-readme-test">
@@ -1717,17 +1742,19 @@ pristine-tar = True
       <para>
         This file was
         (<ulink url="http://lists.debian.org/debian-devel-announce/2011/01/msg00006.html">recommended by the Security team</ulink>)
-        for describing to others than the regular maintainer how the package's
+        for describing to others than the regular maintainer how the package
         functionality can properly be tested.
       </para>
     </sect2>
     <sect2 id="debian-source-format">
       <title><filename>debian/source/format</filename></title>
       <para>
-        This file should contain <quote><literal>3.0 (quilt)</literal></quote> in
-        order to use this source format.  Other formats should be avoided unless
-        they bring a specific advantage.
+        This file should contain <quote><literal>3.0 (quilt)</literal></quote>.
+        Other formats should be avoided unless they bring a specific advantage.
       </para>
+<programlisting>
+3.0 (quilt)
+</programlisting>
     </sect2>
     <sect2 id="debian-source-option">
       <title><filename>debian/source/option</filename></title>
@@ -1790,12 +1817,14 @@ pristine-tar = True
           <filename class="directory">/git/pkg-grass</filename> directory on
           Alioth and created with the
           <link linkend="git-repository-on-alioth"><command>setup-repository</command></link>
-          script available there. There, they must give write access to the
-          <literal>pkg-grass</literal> Alioth group and all the Debian
-          Developers, with appropriate Unix permissions (including SGID bit on
-          directories) and ACLs. See
-          <filename class="directory">/git/pkg-grass</filename> itself as an
-          example. <command>setup-repository</command> does this automatically.
+          script available there.
+          On Alioth write access must be given to the
+          <literal>pkg-grass</literal> group and all the Debian Developers,
+          with appropriate Unix permissions (including SGID bit on directories)
+          and ACLs.
+          See <filename class="directory">/git/pkg-grass</filename> itself as
+          an example.
+          <command>setup-repository</command> does this automatically.
         </para>
         <para>
           Git repositories managed with a helper tool should announce it. For
@@ -1841,18 +1870,18 @@ pristine-tar = True
       <para>
         Once you injected a new package please make sure that it is mentioned
         in the appropriate <link linkend="tasks">tasks</link> file in the
-        source of the <package>debian-gis</package> Blend package. Some team
-        members watch the changes in the Debian GIS packaging pool but it helps
-        if the maintainer of a new package verifies that everything is in the
-        right place.
+        source of the <package>debian-gis</package> Blend package.
+        Some team members watch the changes in the Debian GIS packaging pool
+        but it helps if the maintainer of a new package verifies that everything
+        is in the right place.
       </para>
     </sect2>
     <sect2 id="building-and-tagging">
       <title>Building and tagging the packages</title>
       <para>
-        We prefer that uploaded packages are built in a chroot, to provide
-        similar build environment to the whole team. After upload, please
-        <link linkend="vcs-tags">tag</link> the
+        We prefer that uploaded packages are built in a chroot,
+        to provide similar build environment to the whole team.
+        After upload, please <link linkend="vcs-tags">tag</link> the
         <link linkend="git-tag-release">Git</link> or
         <link linkend="svn-tag-release">Subversion</link> repository.
       </para>
@@ -1862,25 +1891,27 @@ pristine-tar = True
       <para>
         Often happens that the upstream code doesn't fit well into the Debian
         distribution: be this wrong paths, missing features, anything that
-        implies editing the source files. When you directly edit upstream's
-        source files, your changes will be put into a .diff.gz file if you use
-        the <literal>1.0</literal> source format and in a monolithic patch if
-        you use the <literal>3.0 (quilt)</literal> format. To better organize
-        the patches and group the by function, please use a patch handling
-        system which keeps patches under the
-        <filename class="directory">debian/patches</filename> directory.
+        implies editing the source files.
+        When you directly edit upstreams source files, your changes will be put
+        into a .diff.gz file if you use the <literal>1.0</literal> source format
+        and in a monolithic patch if you use the <literal>3.0 (quilt)</literal>
+        format.
+        To better organize the patches and group the by function, please use a
+        patch handling system which keeps patches under the
+        <filename class="directory">debian/patches/</filename> directory.
       </para>
       <para>
         The <literal>3.0 (quilt)</literal> dpkg source format provides its own
-        patch system. Apart from this, the most popular is
-        <command>quilt</command>. <literal>simple-patchsys</literal>,
-        from the <package>CDBS</package> package, is deprecated since version
-        <literal>0.4.85</literal>. <command>dpatch</command> has been popular
-        as well, but is not compatible with the <literal>3.0 (quilt)</literal>
+        patch system.
+        Apart from this, the most popular is <command>quilt</command>.
+        <literal>simple-patchsys</literal>, from the <package>CDBS</package>
+        package, is deprecated since version <literal>0.4.85</literal>.
+        <command>dpatch</command> has been popular as well,
+        but is not compatible with the <literal>3.0 (quilt)</literal>
         source format and is
         <ulink url="http://lists.debian.org/878vqt6was.fsf@luthien.mhp">planned to be removed 2017</ulink>.
-        Please don't use any other patch system in Debian GIS, unless
-        absolutely necessary.
+        Please don't use any other patch system in Debian GIS,
+        unless absolutely necessary.
       </para>
       <sect3 id="quilt">
         <title>Using <command>quilt</command></title>
@@ -1918,23 +1949,21 @@ QUILT_PATCHES="debian/patches"
           </para>
           <para>
             Now start editing files, with:
-          </para>
 <programlisting>
 <command>quilt edit</command> <replaceable><file></replaceable>
 </programlisting>
+          </para>
           <para>
             And repeat the process for each file the patch is involved with.
             At the end, run:
-          </para>
 <programlisting>
 <command>quilt refresh</command>
 </programlisting>
-          <para>
             This will compare the noted state of the edited files with the
             current state, and will produce a patch in
-            <filename>debian/patches</filename>. Remember: the patch is
-            currently applied (you can check this with
-            <command>quilt applied</command>).
+            <filename>debian/patches</filename>.
+            Remember: the patch is currently applied
+            (you can check this with <command>quilt applied</command>).
           </para>
         </sect4>
         <sect4 id="quilt-apply">

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/website.git



More information about the Pkg-grass-devel mailing list