Re: beginning manpage alterations

[Karl Fogel <kf...@newton.ch.collab.net>]

David Waite <ma...@akuma.org> writes:
> Attached is a new manpage for the 'svn' application. The commands and
> command-line arguments are documented, but there is still quite a bit
> of cleanup, additional documenting of commands, datespec, command-line
> arguments accepted by each command, svn-understood properties and
> environment variables.
> 
> However, since I'm going to take a break from working on the manpage
> for right now, I figure I would send it back upstream to make sure it
> isn't lost

Ah, thanks.  Okay: is anyone else interested in maintaining the man
page?  If so, can you take a look at this update, make sure it's not
missing anything major, and follow up here?

I'd like to get this checked in; but even more, I'd like to know that
it's not going to go stale again :-)...

-K

> .\" You can view this file with:
> .\" nroff -man [filename]
> .\"
> .TH svn 1 "27 Jul 2002" "svn 0.14.0" "Subversion Command Line Tool"
> .SH NAME
> svn \- Subversion command line tool
> .SH SYNOPSIS
> 
> .B svn
> .I command
> [
> .I options
> ] [
> .I args
> ]
> 
> .SH NOTE
> This manpage covers all the features of the 
> .B svn
> command line tool.
> 
> .SH OVERVIEW
> .B Subversion
> is a version control system, which allows you to keep old versions of files 
> (usually source code), keep a log of who, when, and why changes occurred, 
> etc., like 
> .BR "cvs(1)" ", " "rcs(1)" ", or " "sccs(1)" "." 
> .B Subversion 
> keeps a single copy of the master sources.  This copy is called the source 
> ``repository''; it contains all the information to permit extracting previous 
> software releases at any time.  More about 
> .B Subversion
> as a general version control system is documented elsewhere.
> 
> .SH OPTIONS
> The options available to different subversion commands. Note that only some
> of these options are valid with each command.
> .TP
> .BR -h " or " --help " or " -?
> show help on a subcommand
> .TP
> .BR -v " or " --version
> print client version info
> .TP
> .BR -q " or " --quiet
> print as little as possible
> .TP
> .BR -v " or " --verbose
> print extra information
> .TP
> .BR -V " or " --very-verbose
> print maxmimum information
> .TP
> \fB-D\fP or \fB--date\fP \fIDATESPEC\fP
> specify a date corresponding to 
> .I DATESPEC 
> (instead of a revision.)
> .TP
> \fB-r\fP or \fB--revision\fP \fIREVSPEC\fP
> specify revision or range of revisions corresponding to 
> .IR REVSPEC .
> .TP
> .BR -R " or " --recursive
> descend recursively
> .TP
> .BR -N " or " --nonrecursive
> operate on single directory only
> .TP
> .B --force
> force operation to run
> .TP
> \fB-m\fP or \fB--message\fP \fImessage\fP
> specify commit message 
> .I message
> .TP
> \fB-F\fP or \fB--file\fP \fIfile\fP
> read data from file 
> .I file
> .TP
> .BI --xml-file " file
> read/write xml to specified file 
> .I file
> .TP
> .BI --message-encoding " encoding
> take log message in charset encoding 
> .I encoding
> .TP
> .BI --targets " file
> pass contents of file 
> .I file
> as additional args
> .TP
> .BI --username " name
> specify a username
> .TP
> .BI --password " password
> specify a password
> .TP
> \fB-x\fP or \fB--extensions\fP \fIarguments\fP
> pass
> .I arguments
> as bundled options to underlying diff util
> .TP
> .B --xml
> output in XML
> .TP
> .B --strict
> use strict semantics
> .SH COMMANDS
> svn has many options. Remember to run "
> .B "svn help"
> to display a list of all commands, and to request a help text for a particular
> command, run
> .B "svn help command" 
> .
> .TP
> \fBadd\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
> Put files and directories under revision control, scheduling them for addition
> to repository.  They will be added in next commit.
> 
> .B example:
> svn add foo.c bar.h baz/ bat/*.m
> .P
> .
> 
> .TP
> \fBcheckout|co\fP [ \fIoptions\fP ] \fIrepository\fP [ \fIdestination\fP ]
> Check out a working copy from a repository, into a subdirectory named either
> based on the last portion of the repository path, or the optional
> .I destination
> 
> A necessary preliminary for most Subversion work: creates your private copy of
> the source for \fIrepository\fP (the repository must be identified with a valid
> URL string). You can work with this copy without interfering with others'
> work.  At least one subdirectory level is always created.
> .P
> .
> 
> .TP
> \fBcleanup\fP [ \fItarget\|.\|.\|.\fP ]
> Recursively clean up the working copy, removing locks, resuming unfinished
> operations, etc.
> .TP
> \fBcommit|ci\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
> Use this command when you wish to ``post'' your changes to other
> developers, by incorporating them into the source repository.
> .TP
> \fBcopy|cp\fP [ \fIoptions\fP ] \fIsource destination\fP
> .RI Where " source " and " destination
> can be directories or files, referenced locally by path and within a
> repository by URL. `copy' is used where you want to make a copy of
> .I source
> so that
> .I destination
> will share ancestry of
> .IR source .
> Unless it is a directory, 
> .I destination
> must not exist (like traditional UNIX
> .BR cp(1) , 
> .I source
> will be placed inside of a directory of 
> .IR destination .)
> 
> .TP
> \fBdelete|del|remove|rm\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP )
> Mark the given files/directories for deletion upon commit. When you
> commit, the entries will be removed from the head revision in the
> repository, and deleted from your working copy.
> 
> If given a URL, the specified file is deleted with an immediate commit
> 
> \fBexample:\fP svn delete foo.c bar.h
> 
> .TP
> \fBdiff\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP[@\fIrev\fP] \fIURL\fP[@\fIrev\fP] )
> Display file changes as contextual diffs. The target can be a
> directory, in which it operates recursively. The target can be an URL,
> although this is only useful if two revisions are also given.
> 
> \fBexample:\fP svn diff README
> 
> Compares the working copy version of the file with current repository
> version.
> 
> \fBexample:\fP svn diff -rHEAD README
> 
> Compares the working copy with most recent repository version.
> 
> \fBexample:\fP svn diff -r123:456 README
> 
> Compares revisions 123 and 456 of the file in the repository.
> 
> \fBexample:\fP
>   svn diff -r123:456 http://rep.com/repo/README
> 
> Compare revisions 123 and 456 of the file in the repository without
> the need for a working copy.
> 
> .TP
> \fBexport\fP [ \fIoptions\fP ] ( \fIURL\fP [ \fIdestination\fP ]| \fIpath1\fP \fIpath2\fP )
> exports a clean working version into a directory. If a URL is specified,
> the latest version (or specified revision) is checked out either into
> .I destination
> or into a directory named after the last path component of the URL if
> .I destination
> was not specified.
> 
> If two local paths were specified,
> .I path2
> gets a clean copy of the contents of
> .IR path1 ,
> preserving local changes but not copying files not under source control.
> .TP
> .BI help|h|? " [command]
> Without a given command argument, this prints generic help, including a
> list of acceptable commands . If a specific command is entered, a short
> description on how to use that command is presented.
> 
> .TP
> \fBimport\fP [ \fIoptions\fP ] \fIURL\fP [ \fIpath\fP ] [ \fINew-Repository-Entry\fP ]
> Import a file or tree into the repository.
> 
> .TP
> \fBinfo\fP [ \fItarget\|.\|.\|.\fP ]
> Print info about a versioned resource.
> 
> .TP
> \fBlog\fP [ \fIoptions\fP ] [ \fIURL\fP ] [ \fItarget\|.\|.\|.\fP ]
> Show log messages (and affected entities) for commits in which any of the
> entities in question changed.  If none were specified, then recursive
> inclusion is the default.  The set of messages can be further restricted
> by a date or revision range specification (using -D or -r). A URL can also
> be specific to retrieve logs from a remote repository. If the URL is
> passed alone, then only that entry will be searched. If paths are also
> supplied with the URL, then only those paths are searched, based at the
> given URL.
> 
> \fBexample:\fP svn log
> 
> Recursively retrieve logs for all revision under "."
> 
> \fBexample:\fP svn log README
> 
> Retrieve logs for only those revisions where README was affected.
> 
> \fBexample:\fP svn log http://rep.com/repo/README
> 
> Retrieve logs for the file without the need for a local checkout of the
> repository.
> 
> \fBexample:\fP svn log README LICENSE
> 
> Retrive logs for all revisions where both files were affected.
> 
> \fBexample:\fP svn log http://rep.com/repo README LICENSE
> 
> Retrieve logs for both files in the remote repository without the need for
> a local checkout of the repository.
> 
> .TP
> \fBmerge\fI [ \fIoptions\fP ] \fIarguments\|.\|.\|.\fP [ \fItarget dir\fP ]
> 
> apply the differences between two paths to a working copy path. If 
> .I target dir
> is not specified, it is assumed to be ``.'', the current working directory.
> .TP
> .BI mkdir " [directory...]
> Create the directory(ies), if they do not already exist. The directories can
> be specified as a local directory name, or as a URL.
> 
> .TP
> .BI "move|mv " "[options] source destination"
> Rename
> .IR "source " "to or into" " destination" ". Both " "source " "and"
> .I destination
> can be specified either as a file path in the local repository or as a URL.
> 
> .TP
> .BI "propdel|pdel" "[options] propname [target\|.\|.\|.]"
> Remove property 
> .I propname
> on files and directories.
> .TP
> .BI "propedit|pedit|pe" "[options] propname [targets]"
> Edit property 
> .IR propname " with 
> .B $EDITOR 
> on files and directories.
> .TP
> .BI "propget|pget|pg " "[options] propname [targets]"
> Get the value of 
> .I propname
> on files and directories.
> .TP
> .BI "proplist|plist|pl" " [options] [target\|.\|.\|.]"
> List all properties for given files and directories.
> .TP
> .BI "propset|pset|ps ""[options] propname [value] [targets\|.\|.\|.]"
> Set property 
> .I propname
> to 
> .I value
> on files and directories.
> .TP
> .BI "revert" " [options] [file\|.\|.\|.]"
> Restore a pristine working copy version of file, undoing all local changes.
> .TP
> .BI "status|stat|st " "[options] [target\|.\|.\|.]"
> Print the status of working copy files and directories.
> 
> .TP
> .BI "update|up " "[options] [file\|.\|.\|.]"
> Execute this command from \fIwithin\fP your private source directory when you
> wish to update your copies of source files from changes that other developers
> have made to the source in the repository. Without a given argument, this
> command will update everything, recursively.
> 
> \fBexample:\fP svn update foo.c bar.h baz/ bat/*.m 
> .SH WWW
> http://subversion.tigris.org
> .SH HISTORY
> .P
> .IR 2002-07-25 :
> Updated to 0.14.0 (Alpha) release. (David Waite)
> .SH "SEE ALSO"
> .BR svnadmin (1)
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org

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

Re: beginning manpage alterations

[Karl Fogel <kf...@newton.ch.collab.net>]

David Waite <ma...@akuma.org> writes:
> I'd love to devise a system where the manpage was generated from
> contents of the handbook, but I cannot think of any such system which
> doesn't require something like docbook-xml :-)

Switching the Handbook to docbook-xml is a possibility, actually, but
I'll leave that call to Ben and others who edit the Handbook most
frequently.  There's been some talk about it here; do you know
docbook-xml and would you be able to help do that?

Keeping the two documents in sync is certainly a bear, yes.

-Karl

> Karl Fogel wrote:
> 
> >David Waite <ma...@akuma.org> writes:
> >
> >>Attached is a new manpage for the 'svn' application. The commands and
> >>command-line arguments are documented, but there is still quite a bit
> >>of cleanup, additional documenting of commands, datespec, command-line
> >>arguments accepted by each command, svn-understood properties and
> >>environment variables.
> >>
> >>However, since I'm going to take a break from working on the manpage
> >>for right now, I figure I would send it back upstream to make sure it
> >>isn't lost
> >>
> >
> >Ah, thanks.  Okay: is anyone else interested in maintaining the man
> >page?  If so, can you take a look at this update, make sure it's not
> >missing anything major, and follow up here?
> >
> >I'd like to get this checked in; but even more, I'd like to know that
> >it's not going to go stale again :-)...
> >
> >-K
> >
> >
> >>.\" You can view this file with:
> >>.\" nroff -man [filename]
> >>.\"
> >>.TH svn 1 "27 Jul 2002" "svn 0.14.0" "Subversion Command Line Tool"
> >>.SH NAME
> >>svn \- Subversion command line tool
> >>.SH SYNOPSIS
> >>
> >>.B svn
> >>.I command
> >>[
> >>.I options
> >>] [
> >>.I args
> >>]
> >>
> >>.SH NOTE
> >> This manpage covers all the features of the .B svn
> >>command line tool.
> >>
> >>.SH OVERVIEW
> >>.B Subversion
> >> is a version control system, which allows you to keep old versions
> >> of files (usually source code), keep a log of who, when, and why
> >> changes occurred, etc., like .BR "cvs(1)" ", " "rcs(1)" ", or "
> >> "sccs(1)" "." .B Subversion keeps a single copy of the master
> >> sources.  This copy is called the source ``repository''; it
> >> contains all the information to permit extracting previous software
> >> releases at any time.  More about .B Subversion
> >>as a general version control system is documented elsewhere.
> >>
> >>.SH OPTIONS
> >>The options available to different subversion commands. Note that only some
> >>of these options are valid with each command.
> >>.TP
> >>.BR -h " or " --help " or " -?
> >>show help on a subcommand
> >>.TP
> >>.BR -v " or " --version
> >>print client version info
> >>.TP
> >>.BR -q " or " --quiet
> >>print as little as possible
> >>.TP
> >>.BR -v " or " --verbose
> >>print extra information
> >>.TP
> >>.BR -V " or " --very-verbose
> >>print maxmimum information
> >>.TP
> >>\fB-D\fP or \fB--date\fP \fIDATESPEC\fP
> >> specify a date corresponding to .I DATESPEC (instead of a revision.)
> >>.TP
> >>\fB-r\fP or \fB--revision\fP \fIREVSPEC\fP
> >> specify revision or range of revisions corresponding to .IR REVSPEC
> >> .
> >>.TP
> >>.BR -R " or " --recursive
> >>descend recursively
> >>.TP
> >>.BR -N " or " --nonrecursive
> >>operate on single directory only
> >>.TP
> >>.B --force
> >>force operation to run
> >>.TP
> >>\fB-m\fP or \fB--message\fP \fImessage\fP
> >> specify commit message .I message
> >>.TP
> >>\fB-F\fP or \fB--file\fP \fIfile\fP
> >> read data from file .I file
> >>.TP
> >>.BI --xml-file " file
> >> read/write xml to specified file .I file
> >>.TP
> >>.BI --message-encoding " encoding
> >> take log message in charset encoding .I encoding
> >>.TP
> >>.BI --targets " file
> >> pass contents of file .I file
> >>as additional args
> >>.TP
> >>.BI --username " name
> >>specify a username
> >>.TP
> >>.BI --password " password
> >>specify a password
> >>.TP
> >>\fB-x\fP or \fB--extensions\fP \fIarguments\fP
> >>pass
> >>.I arguments
> >>as bundled options to underlying diff util
> >>.TP
> >>.B --xml
> >>output in XML
> >>.TP
> >>.B --strict
> >>use strict semantics
> >>.SH COMMANDS
> >>svn has many options. Remember to run "
> >>.B "svn help"
> >>to display a list of all commands, and to request a help text for a particular
> >>command, run
> >> .B "svn help command" .
> >>.TP
> >>\fBadd\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
> >>Put files and directories under revision control, scheduling them for addition
> >>to repository.  They will be added in next commit.
> >>
> >>.B example:
> >>svn add foo.c bar.h baz/ bat/*.m
> >>.P
> >>.
> >>
> >>.TP
> >>\fBcheckout|co\fP [ \fIoptions\fP ] \fIrepository\fP [ \fIdestination\fP ]
> >>Check out a working copy from a repository, into a subdirectory named either
> >>based on the last portion of the repository path, or the optional
> >>.I destination
> >>
> >>A necessary preliminary for most Subversion work: creates your private copy of
> >>the source for \fIrepository\fP (the repository must be identified with a valid
> >>URL string). You can work with this copy without interfering with others'
> >>work.  At least one subdirectory level is always created.
> >>.P
> >>.
> >>
> >>.TP
> >>\fBcleanup\fP [ \fItarget\|.\|.\|.\fP ]
> >>Recursively clean up the working copy, removing locks, resuming unfinished
> >>operations, etc.
> >>.TP
> >>\fBcommit|ci\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
> >>Use this command when you wish to ``post'' your changes to other
> >>developers, by incorporating them into the source repository.
> >>.TP
> >>\fBcopy|cp\fP [ \fIoptions\fP ] \fIsource destination\fP
> >>.RI Where " source " and " destination
> >>can be directories or files, referenced locally by path and within a
> >>repository by URL. `copy' is used where you want to make a copy of
> >>.I source
> >>so that
> >>.I destination
> >>will share ancestry of
> >>.IR source .
> >> Unless it is a directory, .I destination
> >>must not exist (like traditional UNIX
> >> .BR cp(1) , .I source
> >> will be placed inside of a directory of .IR destination .)
> >>
> >>.TP
> >>\fBdelete|del|remove|rm\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP )
> >>Mark the given files/directories for deletion upon commit. When you
> >>commit, the entries will be removed from the head revision in the
> >>repository, and deleted from your working copy.
> >>
> >>If given a URL, the specified file is deleted with an immediate commit
> >>
> >>\fBexample:\fP svn delete foo.c bar.h
> >>
> >>.TP
> >>\fBdiff\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP[@\fIrev\fP] \fIURL\fP[@\fIrev\fP] )
> >>Display file changes as contextual diffs. The target can be a
> >>directory, in which it operates recursively. The target can be an URL,
> >>although this is only useful if two revisions are also given.
> >>
> >>\fBexample:\fP svn diff README
> >>
> >>Compares the working copy version of the file with current repository
> >>version.
> >>
> >>\fBexample:\fP svn diff -rHEAD README
> >>
> >>Compares the working copy with most recent repository version.
> >>
> >>\fBexample:\fP svn diff -r123:456 README
> >>
> >>Compares revisions 123 and 456 of the file in the repository.
> >>
> >>\fBexample:\fP
> >>  svn diff -r123:456 http://rep.com/repo/README
> >>
> >>Compare revisions 123 and 456 of the file in the repository without
> >>the need for a working copy.
> >>
> >>.TP
> >>\fBexport\fP [ \fIoptions\fP ] ( \fIURL\fP [ \fIdestination\fP ]| \fIpath1\fP \fIpath2\fP )
> >>exports a clean working version into a directory. If a URL is specified,
> >>the latest version (or specified revision) is checked out either into
> >>.I destination
> >>or into a directory named after the last path component of the URL if
> >>.I destination
> >>was not specified.
> >>
> >>If two local paths were specified,
> >>.I path2
> >>gets a clean copy of the contents of
> >>.IR path1 ,
> >>preserving local changes but not copying files not under source control.
> >>.TP
> >>.BI help|h|? " [command]
> >>Without a given command argument, this prints generic help, including a
> >>list of acceptable commands . If a specific command is entered, a short
> >>description on how to use that command is presented.
> >>
> >>.TP
> >>\fBimport\fP [ \fIoptions\fP ] \fIURL\fP [ \fIpath\fP ] [ \fINew-Repository-Entry\fP ]
> >>Import a file or tree into the repository.
> >>
> >>.TP
> >>\fBinfo\fP [ \fItarget\|.\|.\|.\fP ]
> >>Print info about a versioned resource.
> >>
> >>.TP
> >>\fBlog\fP [ \fIoptions\fP ] [ \fIURL\fP ] [ \fItarget\|.\|.\|.\fP ]
> >>Show log messages (and affected entities) for commits in which any of the
> >>entities in question changed.  If none were specified, then recursive
> >>inclusion is the default.  The set of messages can be further restricted
> >>by a date or revision range specification (using -D or -r). A URL can also
> >>be specific to retrieve logs from a remote repository. If the URL is
> >>passed alone, then only that entry will be searched. If paths are also
> >>supplied with the URL, then only those paths are searched, based at the
> >>given URL.
> >>
> >>\fBexample:\fP svn log
> >>
> >>Recursively retrieve logs for all revision under "."
> >>
> >>\fBexample:\fP svn log README
> >>
> >>Retrieve logs for only those revisions where README was affected.
> >>
> >>\fBexample:\fP svn log http://rep.com/repo/README
> >>
> >>Retrieve logs for the file without the need for a local checkout of the
> >>repository.
> >>
> >>\fBexample:\fP svn log README LICENSE
> >>
> >>Retrive logs for all revisions where both files were affected.
> >>
> >>\fBexample:\fP svn log http://rep.com/repo README LICENSE
> >>
> >>Retrieve logs for both files in the remote repository without the need for
> >>a local checkout of the repository.
> >>
> >>.TP
> >>\fBmerge\fI [ \fIoptions\fP ] \fIarguments\|.\|.\|.\fP [ \fItarget dir\fP ]
> >>
> >> apply the differences between two paths to a working copy path. If
> >> .I target dir
> >>is not specified, it is assumed to be ``.'', the current working directory.
> >>.TP
> >>.BI mkdir " [directory...]
> >>Create the directory(ies), if they do not already exist. The directories can
> >>be specified as a local directory name, or as a URL.
> >>
> >>.TP
> >>.BI "move|mv " "[options] source destination"
> >>Rename
> >>.IR "source " "to or into" " destination" ". Both " "source " "and"
> >>.I destination
> >>can be specified either as a file path in the local repository or as a URL.
> >>
> >>.TP
> >>.BI "propdel|pdel" "[options] propname [target\|.\|.\|.]"
> >> Remove property .I propname
> >>on files and directories.
> >>.TP
> >>.BI "propedit|pedit|pe" "[options] propname [targets]"
> >> Edit property .IR propname " with .B $EDITOR on files and
> >> directories.
> >>.TP
> >>.BI "propget|pget|pg " "[options] propname [targets]"
> >> Get the value of .I propname
> >>on files and directories.
> >>.TP
> >>.BI "proplist|plist|pl" " [options] [target\|.\|.\|.]"
> >>List all properties for given files and directories.
> >>.TP
> >>.BI "propset|pset|ps ""[options] propname [value] [targets\|.\|.\|.]"
> >> Set property .I propname
> >> to .I value
> >>on files and directories.
> >>.TP
> >>.BI "revert" " [options] [file\|.\|.\|.]"
> >>Restore a pristine working copy version of file, undoing all local changes.
> >>.TP
> >>.BI "status|stat|st " "[options] [target\|.\|.\|.]"
> >>Print the status of working copy files and directories.
> >>
> >>.TP
> >>.BI "update|up " "[options] [file\|.\|.\|.]"
> >>Execute this command from \fIwithin\fP your private source directory when you
> >>wish to update your copies of source files from changes that other developers
> >>have made to the source in the repository. Without a given argument, this
> >>command will update everything, recursively.
> >>
> >> \fBexample:\fP svn update foo.c bar.h baz/ bat/*.m .SH WWW
> >>http://subversion.tigris.org
> >>.SH HISTORY
> >>.P
> >>.IR 2002-07-25 :
> >>Updated to 0.14.0 (Alpha) release. (David Waite)
> >>.SH "SEE ALSO"
> >>.BR svnadmin (1)
> >>
> >>---------------------------------------------------------------------
> >>To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> >>For additional commands, e-mail: dev-help@subversion.tigris.org
> >>
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org

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

Re: beginning manpage alterations

[David Waite <ma...@akuma.org>]

I'd love to devise a system where the manpage was generated from 
contents of the handbook, but I cannot think of any such system which 
doesn't require something like docbook-xml :-)

-David Waite

Karl Fogel wrote:

>David Waite <ma...@akuma.org> writes:
>  
>
>>Attached is a new manpage for the 'svn' application. The commands and
>>command-line arguments are documented, but there is still quite a bit
>>of cleanup, additional documenting of commands, datespec, command-line
>>arguments accepted by each command, svn-understood properties and
>>environment variables.
>>
>>However, since I'm going to take a break from working on the manpage
>>for right now, I figure I would send it back upstream to make sure it
>>isn't lost
>>    
>>
>
>Ah, thanks.  Okay: is anyone else interested in maintaining the man
>page?  If so, can you take a look at this update, make sure it's not
>missing anything major, and follow up here?
>
>I'd like to get this checked in; but even more, I'd like to know that
>it's not going to go stale again :-)...
>
>-K
>
>  
>
>>.\" You can view this file with:
>>.\" nroff -man [filename]
>>.\"
>>.TH svn 1 "27 Jul 2002" "svn 0.14.0" "Subversion Command Line Tool"
>>.SH NAME
>>svn \- Subversion command line tool
>>.SH SYNOPSIS
>>
>>.B svn
>>.I command
>>[
>>.I options
>>] [
>>.I args
>>]
>>
>>.SH NOTE
>>This manpage covers all the features of the 
>>.B svn
>>command line tool.
>>
>>.SH OVERVIEW
>>.B Subversion
>>is a version control system, which allows you to keep old versions of files 
>>(usually source code), keep a log of who, when, and why changes occurred, 
>>etc., like 
>>.BR "cvs(1)" ", " "rcs(1)" ", or " "sccs(1)" "." 
>>.B Subversion 
>>keeps a single copy of the master sources.  This copy is called the source 
>>``repository''; it contains all the information to permit extracting previous 
>>software releases at any time.  More about 
>>.B Subversion
>>as a general version control system is documented elsewhere.
>>
>>.SH OPTIONS
>>The options available to different subversion commands. Note that only some
>>of these options are valid with each command.
>>.TP
>>.BR -h " or " --help " or " -?
>>show help on a subcommand
>>.TP
>>.BR -v " or " --version
>>print client version info
>>.TP
>>.BR -q " or " --quiet
>>print as little as possible
>>.TP
>>.BR -v " or " --verbose
>>print extra information
>>.TP
>>.BR -V " or " --very-verbose
>>print maxmimum information
>>.TP
>>\fB-D\fP or \fB--date\fP \fIDATESPEC\fP
>>specify a date corresponding to 
>>.I DATESPEC 
>>(instead of a revision.)
>>.TP
>>\fB-r\fP or \fB--revision\fP \fIREVSPEC\fP
>>specify revision or range of revisions corresponding to 
>>.IR REVSPEC .
>>.TP
>>.BR -R " or " --recursive
>>descend recursively
>>.TP
>>.BR -N " or " --nonrecursive
>>operate on single directory only
>>.TP
>>.B --force
>>force operation to run
>>.TP
>>\fB-m\fP or \fB--message\fP \fImessage\fP
>>specify commit message 
>>.I message
>>.TP
>>\fB-F\fP or \fB--file\fP \fIfile\fP
>>read data from file 
>>.I file
>>.TP
>>.BI --xml-file " file
>>read/write xml to specified file 
>>.I file
>>.TP
>>.BI --message-encoding " encoding
>>take log message in charset encoding 
>>.I encoding
>>.TP
>>.BI --targets " file
>>pass contents of file 
>>.I file
>>as additional args
>>.TP
>>.BI --username " name
>>specify a username
>>.TP
>>.BI --password " password
>>specify a password
>>.TP
>>\fB-x\fP or \fB--extensions\fP \fIarguments\fP
>>pass
>>.I arguments
>>as bundled options to underlying diff util
>>.TP
>>.B --xml
>>output in XML
>>.TP
>>.B --strict
>>use strict semantics
>>.SH COMMANDS
>>svn has many options. Remember to run "
>>.B "svn help"
>>to display a list of all commands, and to request a help text for a particular
>>command, run
>>.B "svn help command" 
>>.
>>.TP
>>\fBadd\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
>>Put files and directories under revision control, scheduling them for addition
>>to repository.  They will be added in next commit.
>>
>>.B example:
>>svn add foo.c bar.h baz/ bat/*.m
>>.P
>>.
>>
>>.TP
>>\fBcheckout|co\fP [ \fIoptions\fP ] \fIrepository\fP [ \fIdestination\fP ]
>>Check out a working copy from a repository, into a subdirectory named either
>>based on the last portion of the repository path, or the optional
>>.I destination
>>
>>A necessary preliminary for most Subversion work: creates your private copy of
>>the source for \fIrepository\fP (the repository must be identified with a valid
>>URL string). You can work with this copy without interfering with others'
>>work.  At least one subdirectory level is always created.
>>.P
>>.
>>
>>.TP
>>\fBcleanup\fP [ \fItarget\|.\|.\|.\fP ]
>>Recursively clean up the working copy, removing locks, resuming unfinished
>>operations, etc.
>>.TP
>>\fBcommit|ci\fP [ \fIoptions\fP ] [ \fItarget\|.\|.\|.\fP ]
>>Use this command when you wish to ``post'' your changes to other
>>developers, by incorporating them into the source repository.
>>.TP
>>\fBcopy|cp\fP [ \fIoptions\fP ] \fIsource destination\fP
>>.RI Where " source " and " destination
>>can be directories or files, referenced locally by path and within a
>>repository by URL. `copy' is used where you want to make a copy of
>>.I source
>>so that
>>.I destination
>>will share ancestry of
>>.IR source .
>>Unless it is a directory, 
>>.I destination
>>must not exist (like traditional UNIX
>>.BR cp(1) , 
>>.I source
>>will be placed inside of a directory of 
>>.IR destination .)
>>
>>.TP
>>\fBdelete|del|remove|rm\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP )
>>Mark the given files/directories for deletion upon commit. When you
>>commit, the entries will be removed from the head revision in the
>>repository, and deleted from your working copy.
>>
>>If given a URL, the specified file is deleted with an immediate commit
>>
>>\fBexample:\fP svn delete foo.c bar.h
>>
>>.TP
>>\fBdiff\fP [ \fIoptions\fP ] ( \fItarget\|.\|.\|.\fP | \fIURL\fP[@\fIrev\fP] \fIURL\fP[@\fIrev\fP] )
>>Display file changes as contextual diffs. The target can be a
>>directory, in which it operates recursively. The target can be an URL,
>>although this is only useful if two revisions are also given.
>>
>>\fBexample:\fP svn diff README
>>
>>Compares the working copy version of the file with current repository
>>version.
>>
>>\fBexample:\fP svn diff -rHEAD README
>>
>>Compares the working copy with most recent repository version.
>>
>>\fBexample:\fP svn diff -r123:456 README
>>
>>Compares revisions 123 and 456 of the file in the repository.
>>
>>\fBexample:\fP
>>  svn diff -r123:456 http://rep.com/repo/README
>>
>>Compare revisions 123 and 456 of the file in the repository without
>>the need for a working copy.
>>
>>.TP
>>\fBexport\fP [ \fIoptions\fP ] ( \fIURL\fP [ \fIdestination\fP ]| \fIpath1\fP \fIpath2\fP )
>>exports a clean working version into a directory. If a URL is specified,
>>the latest version (or specified revision) is checked out either into
>>.I destination
>>or into a directory named after the last path component of the URL if
>>.I destination
>>was not specified.
>>
>>If two local paths were specified,
>>.I path2
>>gets a clean copy of the contents of
>>.IR path1 ,
>>preserving local changes but not copying files not under source control.
>>.TP
>>.BI help|h|? " [command]
>>Without a given command argument, this prints generic help, including a
>>list of acceptable commands . If a specific command is entered, a short
>>description on how to use that command is presented.
>>
>>.TP
>>\fBimport\fP [ \fIoptions\fP ] \fIURL\fP [ \fIpath\fP ] [ \fINew-Repository-Entry\fP ]
>>Import a file or tree into the repository.
>>
>>.TP
>>\fBinfo\fP [ \fItarget\|.\|.\|.\fP ]
>>Print info about a versioned resource.
>>
>>.TP
>>\fBlog\fP [ \fIoptions\fP ] [ \fIURL\fP ] [ \fItarget\|.\|.\|.\fP ]
>>Show log messages (and affected entities) for commits in which any of the
>>entities in question changed.  If none were specified, then recursive
>>inclusion is the default.  The set of messages can be further restricted
>>by a date or revision range specification (using -D or -r). A URL can also
>>be specific to retrieve logs from a remote repository. If the URL is
>>passed alone, then only that entry will be searched. If paths are also
>>supplied with the URL, then only those paths are searched, based at the
>>given URL.
>>
>>\fBexample:\fP svn log
>>
>>Recursively retrieve logs for all revision under "."
>>
>>\fBexample:\fP svn log README
>>
>>Retrieve logs for only those revisions where README was affected.
>>
>>\fBexample:\fP svn log http://rep.com/repo/README
>>
>>Retrieve logs for the file without the need for a local checkout of the
>>repository.
>>
>>\fBexample:\fP svn log README LICENSE
>>
>>Retrive logs for all revisions where both files were affected.
>>
>>\fBexample:\fP svn log http://rep.com/repo README LICENSE
>>
>>Retrieve logs for both files in the remote repository without the need for
>>a local checkout of the repository.
>>
>>.TP
>>\fBmerge\fI [ \fIoptions\fP ] \fIarguments\|.\|.\|.\fP [ \fItarget dir\fP ]
>>
>>apply the differences between two paths to a working copy path. If 
>>.I target dir
>>is not specified, it is assumed to be ``.'', the current working directory.
>>.TP
>>.BI mkdir " [directory...]
>>Create the directory(ies), if they do not already exist. The directories can
>>be specified as a local directory name, or as a URL.
>>
>>.TP
>>.BI "move|mv " "[options] source destination"
>>Rename
>>.IR "source " "to or into" " destination" ". Both " "source " "and"
>>.I destination
>>can be specified either as a file path in the local repository or as a URL.
>>
>>.TP
>>.BI "propdel|pdel" "[options] propname [target\|.\|.\|.]"
>>Remove property 
>>.I propname
>>on files and directories.
>>.TP
>>.BI "propedit|pedit|pe" "[options] propname [targets]"
>>Edit property 
>>.IR propname " with 
>>.B $EDITOR 
>>on files and directories.
>>.TP
>>.BI "propget|pget|pg " "[options] propname [targets]"
>>Get the value of 
>>.I propname
>>on files and directories.
>>.TP
>>.BI "proplist|plist|pl" " [options] [target\|.\|.\|.]"
>>List all properties for given files and directories.
>>.TP
>>.BI "propset|pset|ps ""[options] propname [value] [targets\|.\|.\|.]"
>>Set property 
>>.I propname
>>to 
>>.I value
>>on files and directories.
>>.TP
>>.BI "revert" " [options] [file\|.\|.\|.]"
>>Restore a pristine working copy version of file, undoing all local changes.
>>.TP
>>.BI "status|stat|st " "[options] [target\|.\|.\|.]"
>>Print the status of working copy files and directories.
>>
>>.TP
>>.BI "update|up " "[options] [file\|.\|.\|.]"
>>Execute this command from \fIwithin\fP your private source directory when you
>>wish to update your copies of source files from changes that other developers
>>have made to the source in the repository. Without a given argument, this
>>command will update everything, recursively.
>>
>>\fBexample:\fP svn update foo.c bar.h baz/ bat/*.m 
>>.SH WWW
>>http://subversion.tigris.org
>>.SH HISTORY
>>.P
>>.IR 2002-07-25 :
>>Updated to 0.14.0 (Alpha) release. (David Waite)
>>.SH "SEE ALSO"
>>.BR svnadmin (1)
>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
>>For additional commands, e-mail: dev-help@subversion.tigris.org
>>    
>>


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