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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
