Patch for Ubuntu Desktop Guide (Re: Words to avoid?)

[Matthew Paul Thomas]

On Jul 8, 2006, at 6:47 AM, Matthew Paul Thomas wrote:
> ...
> And so that I'm not just bikeshedding as usual, here's a diff to  
> improve the Ubuntu Desktop Guide.
> ...

Matthew E asked me to write to the list about the markup changes I'd  
made. That's probably the least interesting aspect of the diff, :-) but  
here goes ...

> ...
> -			<para>You can find out more about the philosophy of free software  
> <ulink url="&gnu-philosophy;">here</ulink>.
> -			</para>
> +
> +			<itemizedlist>
> +				<listitem><ulink url="&gnu-philosophy;">More about the philosophy  
> of Free Software</ulink></listitem>
> +			</itemizedlist>

When a link was included to a related Web site, I put it in an  
<itemizedlist> like this. "Here" as link text is not easily scannable.

> ...
>  			<title>Show hidden files and folders in <application>
>  						<phrase>Nautilus</phrase></application></title>
> -			<procedure>
> -				<step>
>  					<para>In <application>Nautilus</application>, use the <keycombo>
>  							<keycap>Ctrl</keycap>
>  							<keycap>H</keycap>
> @@ -156,14 +146,13 @@
>  							<guimenuitem>Show Hidden Files</guimenuitem>
>  						</menuchoice>.
>  					</para>
> -				</step>
> +					<para>To permanently show all hidden files and folders:</para>
> +			<procedure>
>  				<step>
> -					<para>To permanently show all hidden files and folders, choose
> ...

In several cases, such as this one, there were <step>s in a <procedure>  
that aren't actually part of the procedure, so some of them became  
<para>s. (In this example, you should do either one thing *or* the  
other, depending on what you want to achieve.)

> ...
> -							<para>Install the rar package from the  
> <emphasis>Multiverse</emphasis> repository (see <xref  
> linkend="add-applications"/>).</para>
> +							<para>Install the rar package from the  
> <quote>Multiverse</quote> repository (see <xref  
> linkend="add-applications"/>).</para>

For names of repositories, I changed <emphasis> to <quote> throughout.  
I'm not certain that <quote> is the best element to use here, but I am  
certain that it's more appropriate than <emphasis>. And the  
presentation of <quote> (curly quotes) seems apt given the oddness of  
the repository names.

> ...
> +					<step>
> +						Choose
>  					<menuchoice>
>  						<guimenu>File</guimenu>
> -						<guimenuitem>Import Photos...</guimenuitem>
> -					</menuchoice>. See <xref linkend="gthumb"/> for more on  
> <application>gThumb</application>.
> -				</para>
> +						<guimenuitem>Import Photos</guimenuitem>
> +					</menuchoice>.

It seems awkward to include any ellipsis from a menu item when  
describing that item in help. Including the ellipsis doesn't help with  
recognition, and it looks bad if (as in this case) the menu item is at  
the end of a sentence: three bold dots immediately followed by one  
non-bold one. Ugh.

> ...
> -                            <para>Select the  
> <guibutton>General</guibutton> tab.
> -                                Enter the name of the computer in the
> +                            <para>Click <guilabel>General</guilabel>,  
> and enter the name of the computer in the
>                                      <guilabel>Hostname</guilabel>  
> field.</para>

In several places <guibutton> was used when referring to tabs, not  
buttons; I changed it to <guilabel>.

> ...
> -               		 <para>IRC chat: <phrase>&ubuntu-irc;</phrase> -  
> chat in realtime with the irc community. You will need an  
> <application>irc client</application> to connect. Ubuntu comes with a  
> messenger client, open &gaim;.</para>
> +               		 <para>IRC chat: <phrase>&ubuntu-irc;</phrase> -  
> chat in realtime with the irc community. You will need an IRC client  
> to connect, such as Gaim: &gaim;.</para>

There is no such application as "irc client", so <application> was  
inappropriate.

> ...
> -					<para>Some websites require the <application>Java</application>  
> plugin for Mozilla Firefox. There are two ways of enabling support for  
> this plugin. Most users will find that the easiest way is to install  
> the <application>j2re1.4-mozilla-plugin</application> package from the  
> <emphasis>Multiverse</emphasis> repository.</para>
> -					<para>Alternatively, for a more complete  
> <application>Java</application> installation, see <xref  
> linkend="java"/>.</para>
> +					<para>Some websites require the Java plugin for Mozilla Firefox.  
> The easiest way to view Java applets is to install the  
> <application>j2re1.4-mozilla-plugin</application> package from the  
> <quote>Multiverse</quote> repository.</para>
> +					<para>For a more complete Java installation, see <xref  
> linkend="java"/>.</para>

Same here: Java isn't an application.

> ...
>  				<sect3 id="diveintopython" status="complete">
> -					<title>Dive Into Python</title>
> -						<para><application>Dive Into Python</application> is a book on  
> learning how to program in the preferred Ubuntu language, Python.  
> Aimed at programmers with some previous experience, it comes installed  
> with every Ubuntu installation.</para>
> -						<para>You can read <application>Dive Into Python</application>  
> <ulink  
> url="file:///usr/share/doc/diveintopython/html/toc/index.html">here</ 
> ulink>.</para>
> +					<title><citetitle>Dive Into Python</citetitle></title>
> +					<para><citetitle>Dive Into Python</citetitle> is a book for  
> learning how to program in Python, aimed at programmers with some  
> previous experience.</para>

Dive Into Python sure isn't an application, but I was expecting  
<citetitle> to give me italics, and it gave me quotes instead. Any  
suggestions?

That's all
-- 
Matthew Paul Thomas
http://mpt.net.nz/