[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: Re: Manual Pages

From: Kenneth Wood <kenneth.wood_at_e2open.com>
Date: 2007-02-13 22:22:05 CET

>-----Original Message-----
>From: Jeff Smith [mailto:jsmith@robotronics.com]
>Sent: Tuesday, February 13, 2007 2:27 PM
>To: users@subversion.tigris.org
>Subject: Re: Manual Pages
>
>
>[original question from "Nadav Har'El"
>http://svn.haxx.se/users/archive-2007-01/0922.shtml ]
>On Wednesday 24 January 2007 09:01, Mark Moore wrote:
>> I just wanted to add my voice to the benefits of man pages when
>> working in a command line environment.
>>
>> As Nadav speculates in his post, there *are* existing tools
>to extract
>> man pages from HTML.  And, the XML that almost certainly is
>the source
>> behind the online svnbook is designed to be rendered in multiple
>> formats (e.g. HTML & PDF).
>
>I'm not good at leaving old threads alone, but...
>
>I don't think the reason was explained well enough, why we don't need
>to install man pages. I don't see that anyone mentioned the
>documentation that is _more_ convenient than man pages:
>
>svn --help
>
>Does that not provide just as much as should the man pages? If not, it
>needs to. Sometimes man page installation is more confusing or memory
>consuming, but if I'm using `svn add` then I'd rather be able to just
>say `svn --help add`, and that's just what I do.
>

Man pages memory consuming? I hope not, they should just be files
on disk that are found and displayed when you use the "man" command.

I believe, traditionaly, "<command> -h" gave a summary, while "man <command>"
gave lots more info, specifically more exposition and detailed examples.

svn help add doesn't show the following tidbit, for example, that's on the web:

===========================================================================
To add a file to your working copy:

$ svn add foo.c
A foo.c

When adding a directory, the default behavior of svn add is to recurse:

$ svn add testdir
A testdir
A testdir/a
A testdir/b
A testdir/c
A testdir/d

You can add a directory without adding its contents:

$ svn add --non-recursive otherdir
A otherdir
==============================================================================

Well, "svn help add" didn't tell me that the default behavior is to recurse,
although it was implied. Good thing I looked on the web. :^)

Kidding aside, that's the kind of exposition that the man page would provide,
as well as the examples.

And, compare the output of "svn help add"
with all the exposition in the book, and you'll see there is a lot unsaid
by "svn help add"

Compare:

 perl -h

Usage: perl [switches] [--] [programfile] [arguments]
  -0[octal] specify record separator (\0, if no argument)
  -a autosplit mode with -n or -p (splits $_ into @F)
  -C enable native wide character system interfaces
  -c check syntax only (runs BEGIN and CHECK blocks)
  -d[:debugger] run program under debugger
  -D[number/list] set debugging flags (argument is a bit mask or alphabets)
  -e 'command' one line of program (several -e's allowed, omit programfile)
  -F/pattern/ split() pattern for -a switch (//'s are optional)
  -i[extension] edit <> files in place (makes backup if extension supplied)
  -Idirectory specify @INC/#include directory (several -I's allowed)
  -l[octal] enable line ending processing, specifies line terminator
  -[mM][-]module execute `use/no module...' before executing program
  -n assume 'while (<>) { ... }' loop around program
  -p assume loop like -n but print line also, like sed
  -P run program through C preprocessor before compilation
  -s enable rudimentary parsing for switches after programfile
  -S look for programfile using PATH environment variable
  -T enable tainting checks
  -u dump core after parsing program
  -U allow unsafe operations
  -v print version, subversion (includes VERY IMPORTANT perl info)
  -V[:variable] print configuration summary (or a single Config.pm variable)
  -w enable many useful warnings (RECOMMENDED)
  -W enable all warnings
  -X disable all warnings
  -x[directory] strip off text before #!perl line and perhaps cd to directory

with "man perl" - which I won't paste here, as that would be overkill...

>---------------------------------------------------------------------
>To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
>For additional commands, e-mail: users-help@subversion.tigris.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Tue Feb 13 22:23:41 2007

This is an archived mail posted to the Subversion Users mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.