Documentation Bug 630652 created to install Guide update for Other Assets

[Thomas Bullock]

Geert and Yawar,

Thanks to both for your thoughtful replies and instructions.  All your comments are relevant for me.  To make my patch I had to check out the most recent revision and then insert my changes and then test to see if I had messed up anything.  It would have saved me a lot of trouble had I known what you both have provided in your two most recent sets of instructions.  

That is not a complaint, because my experience made me able to appreciate and understand better what you provided in your messages.  I still have questions about parts, so I will send those on when I have worked thru what each of you have said.  In the meantime, know that all that you have provided will be integrated into my write up for documentation for new developers.  I was at the point where I was intending to investigate how to insert my stuff into the wiki.  That will be delayed until after I have updated my draft version of the notes for the wiki.

Thanks again.  You have provided great stuff!!

Tom 

> -----Original Message-----
> From: Geert Janssens [mailto:janssens-geert at telenet.be]
> Sent: Thursday, September 30, 2010 1:52 AM
> To: gnucash-devel at gnucash.org
> Cc: Yawar Amin; Thomas Bullock
> Subject: Re: Documentation Bug 630652 created to install Guide update
> for Other Assets
> 
> 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