Documentation Bug 630652 created to install Guide update for Other Assets

[Geert Janssens]

On Thursday 30 September 2010, Yawar Amin wrote:
<snip>
> > 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.)

The idea is right, but the example you give might be confusing. The diff 
command requires file or directory names to compare so the example as given 
will result in an error.

Since the target of discussion here is changes to the gnucash documentation, 
I'll presume we are making changes in a local subversion working copy of the 
gnucash-docs module.

To make a patch I let subversion do most of the work for me. Since we're 
working in a local working copy, subversion already keeps track of changes we 
make. It's just a matter of letting subversion output those changes in a nice 
patch format. The svn diff command is suitable for that. However, for the 
patch to be useful this command should be executed within a larger context.

1. cd to the top-level directory of the gnucash-docs project

2. A patch should always be made against the most recent revision of the 
gnucash-docs project in subversion.
In order to make sure your working copy is based on the most recent revision, 
run svn update (or abbreviated, svn up).
This will pull in all changes and patches that have been committed to the 
gnucash-docs module since you checked out your own working copy from 
subversion. If those changes don't conflict with your local changes, they will 
be merged automatically into your local working copy. If there are conflicting 
changes, you will have to figure out which changes to keep and which ones to 
dismiss. Recently svn has some primitive tools to help you with this. Upon 
conflicts it will ask you what to do. See [1] for more information on conflict 
resolution.

As a side-note, [2] is a very good introduction to subversion and how to 
perform basic things.

As another side-note: to avoid merge conflicts as much as possible, it's wise 
to run svn up regularly, so repository changes are pulled in frequently and in 
smaller chunks.

3. Once the conflicts are resolved, run svn status (or abbreviated, svn stat)
This will list all files that are different between your local working copy 
and the project in subversion. This can be files that have been deleted, new 
files or modified files. Again, see [2] to understand the output of this 
command.

4. To create a patch, you have to make sure that subversion will consider your 
changes for commit. In practice only files that have status "A" (Added), "M" 
(Modified) or "D" (Deleted) will be taken into account. If you see files in 
the list that you know have changes you want to include, but that are not in 
this state, you should deal with this first.
- Newly created files (the ones in state "?") you wish to include in the patch 
should first be added via svn add
- Files you removed with a plain rm command (the ones in state "!") should be 
properly removed via svn rm

5. Now to create your patch, simply run
svn diff > changes.patch
Note that the svn diff command doesn't require you to give file names. It will 
go through your working copy and write a proper patch, containing all new 
files, deleted files and file modifications.
If you wish to be more selective, you can also specify exactly which files you 
wish to add to the patch like so:
svn diff <list-of-files-and-or-directories> > changes.patch
For example
svn diff guide/C/ch_capgain.xml AUTHORS > changes.patch
will only include changes to the files guide/C/ch_capgain.xml and the AUTHORS 
file into the patch.
Likewise the command
svn diff guide > changes.patch
will only include any changes in any file below the guide directory.


I realize it's much to cope with at once, buy hopefully this explanation will 
help you understand better how to create a patch.

> > 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.”
> 
As Yawar says, xml and html don't really care about trailing whitespace. It's 
mostly a coding habit to remove them. There are even text editors that do this 
automatically sometimes. If such a "cleaned up" file is committed to 
subversion together with actual code/documentation changes, you may have a 
harder time reading the differences later on, for example when you are looking 
at a track difference page. The whitespace changes distract from the actual 
changes. That's what Yawar meant with "clutters up the repository". So being 
strict in trailing whitespace is not a matter of proper syntax, but rather a 
matter of making it easier for humans to read changes made.

For that reason also, pure whitespace fixes should be done in separate patches 
from actual changes.

<snip>

> > 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 :-)
> 
True, but I'll repeat here that frequent calls of svn up will ease your work.
If you wait too long, you risk conflicts when Yawar and Tom are working on the 
same file. Especially if Yawar has just committed a patch sent in by Tom, Tom 
should run svn update so his local working copy knows that the patch is now in 
subversion and only new changes should be added to a future patch.

> 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.
> 
That would be useful indeed. As a technical person I'd need the input from 
non-technical persons to find the blind spots in our documentation. I'm just 
too experienced at this point to see which parts are not clear.
That's why Tom's input in the wiki would be invaluable. It would be written 
from the perspective of someone who doesn't know the processes we use. As a 
more technical user, I would afterwards only correct errors and perhaps add 
context where that would be useful.

Geert

[1] http://svnbook.red-
bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve
[2] http://svnbook.red-bean.com/en/1.5/svn.tour.html