On Fri, Sep 14, 2012 at 07:45:06PM +0100, Julian Foad wrote: > I was recently thinking how much nicer it would be if we could ship 'man' > pages that contain useful descriptions rather than just saying (currently) > 'please see the built-in help or the book'. It's not a terrible problem as > it is, but for a mature project I would like to see more. > > I've often thought it would be nice to generate the help text and the man > pages and the reference section of The Book all from the same source. So I > had a go. > > I'm certainly not advocating that we commit the attached patch in its current > state, and maybe we won't ever want to do this, or maybe we will. I am just > putting the idea out for anyone else to play around with, and see where it > goes. > > I found it fun. > > > - Julian
Hey Julian, I've pondered this very idea a while back but never got any further than revising the output of 'svn help merge' (this was before we released 1.7). I fully support this idea. Ideally, the output of 'svn help' and the book's reference pages for commands would match up, and would also be installed as man pages on UNIX-like system (which aren't that useful on non-UNIX systems). Another idea I've had was to make 'svn help' more like a walk-through tutorial. I.e. just plain 'svn help' would hint at a starting point such as 'svn help tutorial', which would briefly explain what Subversion is and what it does, and then ask the reader to proceed with other 'svn help' pages to get a guided tour through the various commands. The user would proceed with reading e.g. 'svn help checkout' and would then be guided through the help pages in some pre-defined order (e.g. 'svn help info' -> 'svn help status' -> 'svn help update' -> 'svn commit', etc). Each help page would close with a hint at the next page to read if the user is following the tutorial: "If you are following the svn tutorial, please read 'svn help foo' next." It might be hard to write help pages that work well as both a tutorial and a reference, but I believe it's worth trying.
