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.
Received on 2012-09-14 22:04:47 CEST