Merge lp:~nhandler/ubuntu-docs/ppa into lp:ubuntu-docs/karmic

[Nathan Handler]

[Dougie Richardson (dougierichardson)]

Thanks Nathan this is a very good addition to the Documentation.

review: Approve

[lp:~nhandler/ubuntu-docs/ppa]

301. By Adam Sommer on 2009-05-11

Patch by Nathan Handler to remove information about dhcdbd that is no longer needed. Fixes LP: #373867.

302. By Adam Sommer on 2009-05-11

Patch by Joel Goguen adding note about restarting after joining a domain. Fixes LP: #352934.

303. By Matthew East on 2009-05-12

Merging from nhandler's ppa branch

[Matthew East (mdke)]

I've merged this but have two small comments:

The first is that the document didn't validate due to the use of
<emphasis> inside a <command> tag. Please always check the validity of
the docbook before committing using the scripts/validate.sh script.

The second is that I don't think PPA warrants its own top level
section - logically this seems to be part of the "Adding a software
repository" section, and should probably be a sub-section of that.
Nathan, do you agree?

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

[Nathan Handler (nhandler)]

On Tue, May 12, 2009 at 7:00 AM, Matthew East <email address hidden> wrote:
> The first is that the document didn't validate due to the use of
> <emphasis> inside a <command> tag. Please always check the validity of
> the docbook before committing using the scripts/validate.sh script.

This error has to do with there not being anything in the style guide
about how to denote parts of a command/line of text that a user needs
to modify. Dougie Richardson suggested using <emphasis> to make these
parts stand out, so that is what I used. If the validate script is
going to complain, would it be better to simply ignore it? Or should
we use something like <>'s around the text instead?

> The second is that I don't think PPA warrants its own top level
> section - logically this seems to be part of the "Adding a software
> repository" section, and should probably be a sub-section of that.
> Nathan, do you agree?

I originally made the adding a PPA section separate from everything
else due to the fact that we were not sure what we wanted to do with
it. I figured having it separate would make it easiest to merge it
into other sections later. I think having it as a sub-section of
"Adding a software repository" would make the most sense.

Nathan

[Matthew East (mdke)]

On Tue, May 12, 2009 at 12:16 PM, Nathan Handler <email address hidden> wrote:
> On Tue, May 12, 2009 at 7:00 AM, Matthew East <email address hidden> wrote:
>> The first is that the document didn't validate due to the use of
>> <emphasis> inside a <command> tag. Please always check the validity of
>> the docbook before committing using the scripts/validate.sh script.
>
> This error has to do with there not being anything in the style guide
> about how to denote parts of a command/line of text that a user needs
> to modify. Dougie Richardson suggested using <emphasis> to make these
> parts stand out, so that is what I used. If the validate script is
> going to complain, would it be better to simply ignore it? Or should
> we use something like <>'s around the text instead?

Understood. There's an open thread about this issue on the mailing
list about how to handle this, so let's see how that is resolved. For
the time being I removed the offending <emphasis> tag.

>> The second is that I don't think PPA warrants its own top level
>> section - logically this seems to be part of the "Adding a software
>> repository" section, and should probably be a sub-section of that.
>> Nathan, do you agree?
>
> I originally made the adding a PPA section separate from everything
> else due to the fact that we were not sure what we wanted to do with
> it. I figured having it separate would make it easiest to merge it
> into other sections later. I think having it as a sub-section of
> "Adding a software repository" would make the most sense.

Ok, let's do it that way, thanks for the input.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

=== modified file 'add-applications/C/add-applications.xml'
--- add-applications/C/add-applications.xml	2009-03-18 17:40:51 +0000
+++ add-applications/C/add-applications.xml	2009-05-09 21:44:58 +0000
@@ -221,8 +221,8 @@
     <caution>
     <para>
     Only add software repositories from sources that you trust. Third-party 
-    software repositories are not checked for security by Ubuntu members, so 
-    could contain software which is harmful to your computer.
+    software repositories are not checked for security by Ubuntu members, and 
+    may contain software which is harmful to your computer.
     </para>
     </caution>
     <procedure>
@@ -237,7 +237,7 @@
         <para>Enter the APT line for the extra repository. This should be 
         available from the website of the repository, and should look similar 
         to the following:</para>
-        <screen>deb http://ftp.debian.org etch main</screen>
+        <programlisting>deb http://archive.ubuntu.com/ubuntu/ &distro-short-codename; main</programlisting>
     </step>
     <step>
         <para>Click <guibutton>Add Source</guibutton> and then click 
@@ -265,6 +265,57 @@
     <guilabel>Authentication</guilabel> tab, click <guibutton>Import Key 
     File</guibutton> and select the GPG key to be imported.
     </para>
+    <para>
+    You can also add the GPG key using the terminal by entering the following command:
+    </para>
+    <screen><command>sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com <emphasis>key-fingerprint</emphasis></command></screen>
+</sect1>
+
+<sect1 id="adding-ppa" status="review">
+     <title>Adding a Personal Package Archive (PPA)</title>
+     <para>
+     <ulink url="https://launchpad.net/">Launchpad</ulink> provides all users
+     with their own Personal Package Archive (PPA) that can be used to build
+     and store Ubuntu packages. In the same way that you can
+     add a normal software repository, you can also add a PPA to the
+     package manager's list of available repositories. PPAs work like normal
+     Ubuntu archives. You can install software in the usual way -- for example,
+     through apt-get or synaptic -- and whenever there's an update Ubuntu will
+     prompt you to install it.
+     </para>
+     <caution>
+     <para>
+     You download and install PPA packages at your own risk. Ubuntu, Launchpad
+     and Canonical do not endorse these packages. You must be certain that you
+     trust the PPA owner before you install their software. 
+     </para>
+     </caution>
+     <para>
+     You should begin by familiarizing yourself with <xref linkend="adding-repos"/> before beginning.
+     </para>
+     <para>
+     The APT line for the PPA can be found on the PPA overview page on Launchpad,
+     and should look similar to the following:
+     </para>
+     <programlisting>deb http://ppa.launchpad.net/<emphasis>user</emphasis>/ppa/<emphasis>ppa-name</emphasis> &distro-short-codename; main</programlisting>
+     <para>
+     As a security measure, all PPAs use a unique GPG key to digitally sign the
+     packages that they provide. This makes it easy to check that the packages
+     have not been tampered with since Launchpad built them and to be sure that
+     you are downloading from the PPA that want. In order for your package
+     manager to be able to check this, you need the public key that corresponds
+     to the signatures. The key should be available for download on the PPA
+     overview page on Launchpad. Until you add the PPA's key to your system, you
+     will see warnings that you are downloading from an untrusted source.
+     </para>
+     <para>
+     The key used to sign a PPA is listed on the PPA overview page. Instructions
+     on how to add the key can be found in <xref linkend="adding-repos"/>.
+     </para>
+     <para>
+     Additional information about adding a PPA repository can be found on
+     <ulink url="https://help.launchpad.net/Packaging/PPA">Launchpad</ulink>.
+     </para>
 </sect1>
 
 <sect1 id="offline" status="draft">