Re: Question about reviewing others' documentation contributions

[Phil Bull <philbull gmail com>]

Hi Russell,

On Thu, 2010-08-19 at 07:58 +1000, Russell Dickenson wrote:
> I would like to take part in GNOME's documentation and in starting
> slowly, I thought a good idea would be to review the content of
> others' contributions. Since April has been very active recently I
> downloaded her files so that I could get a feel for the process and
> tools involved. My problem is that I can't open individual files
> because there's no index.page (?) file. As I understand (and to be
> honest I really *don't* yet understand) the index.page is key to
> Yelp's ability to present topic-based help, with the various topics
> linked as necessary.

Yes, that's right. Individual topics link *themselves* to the index
page. Without an index page, the links in those topics don't work, so
Yelp gives up trying to process the pages and gives an error.

The pages that April has been working on link themselves into "guide"
pages, which then link themselves into the index page. (The index page
is a special type of guide page, the "root" guide page.) It's a
hierarchy. Topics expect a certain structure to be in place, so if you
try to open a page on its own (without the structure being there), you
just get an error.

> Finally my question, then: if I want to review someone else's
> contributions, what's the best way of doing so? Do I need to do a "git
> pull..." of the matching git repo, manually download the contributed
> files into the same folder, then load Yelp?

All of the files that April has been working on fit into the document
structure here:

http://gitorious.org/desktop-help/desktop-help/trees/master

To get all of those documents, you can type the following:

git clone git://gitorious.org/desktop-help/desktop-help.git

Then, in the desktop-help folder that's created, replace an existing
file with one of April's modified versions and type the following in a
Terminal:

cd directory/where/desktop-help/was/put
yelp $PWD/

This will open the whole document up in Yelp, and you can navigate to
the topic that April modified.

Hope this helps,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull
Book - http://nostarch.com/ubuntu4.htm