Re: Tomboy Peer Review

[Shaun McCance <shaunm gnome org>]

On Wed, 2010-05-19 at 08:44 -0500, Paul Cutler wrote:
> Hi,
> 
> I've finished the Tomboy docs and I have some outstanding questions to
> get them to 100% completion.  I believe Shaun had done a brief review
> prior to 2.30 but there were a couple missing pages.
> 
> If you check out the Tomboy git repo, there is a docs branch.  It also
> has a TODO file with some of these questions and future work.
> 
> Validation issues (I can't figure these two out, all other pages
> validate):
> 
> sync-setup.page:  
> 
> sync-setup.page:46: element title: Relax-NG validity error : Did not
> expect element title there
> sync-setup.page:46: element title: Relax-NG validity error : Element
> page has extra content: title

There's an extra title element between section elements.

> whatsnew.page:
> 
> whatsnew.page:8: element revision: Relax-NG validity error : Expecting
> an element , got nothing
> whatsnew.page:8: element revision: Relax-NG validity error : Invalid
> attribute date for element revision

2010-3-07 should be 2010-03-07. The One True Date Format always
zero-pads.

> introduction.page: The Tomboy screenshot isn't showing up.  I'm not sure
> why, comparing the code to projectmallard.org it looks correct.

It works for me. How are you calling Yelp?

> sync-setup.page: How do I enable the PackageKit functionality Shaun
> mentioned in the past so a user can click a link to install sshfs or
> wdfs?

Right now, like this:

<link href="install:sshfs">Install sshfs</link>

But this might change before 3.0. In particular, I think I'd
like to put the install: URI on the xref, leaving href open
for a fallback URI, like so:

<link xref="install:sshfs"
href="http://sshfs.example.com/download";>Install sshfs</link>

And keep in mind that install links are 3.0-only.

> The Common Problems and Advanced Actions are stubs - I've asked for help
> on the mailing list for content for those.
> 
> Lastly, how do I manage the "See Also" links?  I have a number of
> duplicates.

Bug in gnome-doc-utils. If A has <link type="seealso" xref="B"/>
and B has <link type="seealso" xref="A"/>, you'll see those links
twice. In 2.30 and earlier, it picks up both and doesn't detect
the duplicate. So just be careful to only declare your links in
one direction. This is fixed in 3.0.

> A peer review for content would also be appreciated.  I'm sure I've made
> a few mistakes and some of the language / grammar can be improved in
> places.

Thanks Paul. I'll try to look it over more thoroughly later
today.

--
Shaun