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

[Matthew East]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Thanks for this. I'm only replying to some of these - most of the
changes you've made are bugfixes about incorrect use of tags or
erroneous language, but there are some we should think about.

* Matthew Paul Thomas:
>> ...
>> -            <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.

Very nice. I'd like to see this in the styleguide definitely.

> 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.

So, we need to be consistent about this throughout all our guides, so we
should talk about that.

>> ...
>> +                    <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.

Yes, that seems fair to me. Again, that would be nice to have in the
styleguide.


Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEsNY7tSaF0w5rBv8RAgBsAJ9CAA4Jbw2KnQAFiyJvTuInEmgZLgCeLhjx
EKAYiiwNqwSn4crfW0MmEMM=
=8iaY
-----END PGP SIGNATURE-----