Not that I imply that I have that much understanding of Subversion yet
to be worthy of votes, but I wanted to let you know, that there is not
only agreeing here.
On Fri 2003-03-14 at 07:31:57 -0800, Ben Collins-Sussman wrote:
> Paul Lussier <pll@lanminds.com> writes:
>
> > So, should I look at updating the static man pages now, or would it
> > be better to wait until Rafael has time to add the necessary code to
> > the C sources to automagically generate man pages at build time?
>
> To be honest, I hate seeing all this duplication of documentation:
+1, of course :-)
>
> * all our binaries are already self-documenting ('svn help foo')
>
> * the man pages potentially contain the same information
>
> * chapter 8 of the book has the same information, plus some
> discussion.
>
> If it were up to me, I'd make our man pages *really* short: they
> would simply tell people to run 'svn help', and contain links to the
> website and/or book.
+0.5 if that is meant to be temporary due lack of resources
-0.5 if that is meant to be a permanent measure.
man pages are *the* standard in the UNIX world. There are other tools
than man (including GUIs) which understand the man page format and are
able to process them. I cannot do that (reasonably easy) with svn help
output.
Also, I always got the feeling that the command line help is kept
overly tense in order to fit better on the screen. A real reference
docu (in man pages) wouldn't have that restriction.
For example, let's look at svn help:
usage: svn <subcommand> [options] [args]
Type "svn help <subcommand>" for help on a specific subcommand.
Most subcommands take file and/or directory arguments, recursing
on the directories. If no arguments are supplied to such a
command, it will recurse on the current directory (inclusive) by
default.
Available subcommands:
add
cat
[... 23 commands removed ...]
switch (sw)
update (up)
Subversion is a tool for revision control.
For additional information, see http://subversion.tigris.org
If I am not sure how the command I need is named, I have up to 27
sub-pages to look though, without any easy way to search them (I
realize that I probably can trim that down to 5 probable candidates,
but I hope you see my point).
I understand that svn help is the best way to get a cross-platform
compatible help. But IMHO it should be considered that: a band-aid,
not a holy grail. ;-)
If currently there are no resources to keep appropriate docu
up-to-date, that's okay. But please keep the goal of providing
reference docu in a format reasonably close to the preferred one of
each platform. Of course, ideally the different formats would be
produced automatically from some common source.
Benjamin.
- application/pgp-signature attachment: stored
Received on Fri Mar 14 19:49:22 2003