Documentation Bug 630652 created to install Guide update for Other Assets

[Yawar Amin]

Hi Tom,

On 2010-09-29, at 15:58, Thomas Bullock wrote:

>> […]
> 
> [<Tom:>] Yawar,  thanks for all  the attention you have paid to this patch of mine.  I just now got caught up with your previous emails connected with my patch and also trac changesets 19618 and 19619.  I now have these questions/comments:
> 
> 1.  Where do I learn how to use Trac?  Its output is excellent when showing clearing the differences between two items.

Trac is a basically a convenient, no-installation-required Web-based viewer for what’s going on in the repository. It has a kind of news feed called the Timeline [1], and a nice way of looking at each change that goes into the software or docs. That’s the diff viewer you’ve seen previously.

I would guess the developers are more dependent on repository-management software they have installed on their own computers, rather than Trac. See [2] and [3].

> 2.  I suppose in learning how to use Trac I will learn how to integrate several modules into one output file.  If not, how do I do that?

A single patch can actually contain all three kinds of changes: adding a new file, modifying an existing file, and deleting an existing file. Just make any and all changes you want, cd to the top-level directory of the gnucash-docs project, and run a ‘diff -ur >changes.patch’ from there. That will look through all subdirectories for changes and integrate everything into a single patch. For details on the diff command, run ‘man diff’ and skim through the options there. (You can ignore most of them. Press Space to scroll down by a page, and ‘q’ to exit the manual viewer.)

> 3.  What happens in XML or HTML when trailing spaces are not removed?  It clearly is important or you would not have spent the effort.

Oh dear. I’m afraid I’m something of a pedant about whitespace :-) As I mentioned in the change message, it’s cosmetic. Sometimes spurious whitespace clutters up a repository’s history, so some people don’t like it. From the perspective of XML/HTML, multiple trailing spaces are simply combined into a single space in the output file. So e.g.,

	He said, <quote>I don’t     believe you.</quote>

would be turned into

	He said, “I don’t believe you.”

> 4.  How does trac detect the presence of spaces in one module and not the other?  If you removed the unwanted spaces, how did you disclose them in order to remove them?

Trac actually just displays all its information from the GnuCash version control (change control) repository, managed by Subversion.[2] It knows how to display changes in a nice, friendly way.

> 5.  thanks for calling to my attention these XML proper treatments: &rsquo;, &dash;, and <quote>...</quote>

Ah, another cosmetic obsession of mine :-) &rsquo;, &lsquo;, and friends are just a few of the pre-defined entities we can use in our XML/HTML.[4]

> 6.  I found two errors that I had not caught previously: one is a spelling error; the other is a sequence of tenses error.  Since you have promoted my modules, when would be the proper time to correct those by making another patch.  I assume it would be after you get done promoting my changes to 2.2 as well as the trunk.  Is that correct?  If so, when will that likely be?  If not correct, what is your recommendation?

By any chance: discesses and damaage? Check out [5]: I’ve fixed those. If my changes in [6] and [7] look OK to you, I can go ahead and commit them to the repository. In any case, send a patch to the list, and I’ll integrate all your further changes. It doesn’t matter that you and I work in parallel and maybe change some of the same things–the software can handle that, that’s the beauty of it :-)

As for the 2.2 branch, my plan is to finalise this series of patches on trunk into a ‘correct’ state, then backport (duplicate with any necessary changes) each of the patches onto 2.2, in one fell swoop.

> Thanks again for your very careful review of my patch.  

Glad to help. Some people collect stamps, I collect patches … :-)

> Other Issue:  Still working on my description of what is needed in the sequence of steps for newcomers participating in the documentation effort.  Per John Ralls advice, I will put that in the wiki and let others know when that happens.

It’s definitely a lot to learn. XML … DocBook … diffing … reading diffs and understanding changes … the Wiki is a nice way to lower the barriers to entry though. What I hope for is a kind of relay race where the non-technical people can provide valuable content, then the more technical-minded people can run with it–massage it and mold it to fit inside the system.

Regards,

Yawar

[1] http://svn.gnucash.org/trac/timeline
[2] http://wiki.gnucash.org/wiki/Subversion
[3] http://wiki.gnucash.org/wiki/Git
[4] http://www.netlingo.com/tips/html-code-cheat-sheet.php
[5] http://lists.gnucash.org/pipermail/gnucash-devel/2010-September/029687.html
[6] http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20100928/888e9e95/attachment.obj
[7] http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20100928/888e9e95/attachment-0001.obj

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20100929/1adcd36c/attachment.bin>