git-svn(1): improve asciidoc markup

Use list continuation to have better wrapping. This accounts for most of
the changes because it reindents a lot of text without applying other
changes.

Use cross-referencing for interlinking and the gitlink macro for pointing
to other tools in the git suite.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/git-svn.txt

@@ -12,10 +12,8 @@ SYNOPSIS
 DESCRIPTION
 -----------
 git-svn is a simple conduit for changesets between a single Subversion
-branch and git.
-
-git-svn is not to be confused with git-svnimport.  The were designed
-with very different goals in mind.
+branch and git. It is not to be confused with gitlink:git-svnimport[1].
+They were designed with very different goals in mind.
 
 git-svn is designed for an individual developer who wants a
 bidirectional flow of changesets between a single branch in Subversion
@@ -34,167 +32,192 @@ git-svnimport is designed for.
 
 COMMANDS
 --------
-init::
+--
+
+'init'::
 	Creates an empty git repository with additional metadata
 	directories for git-svn.  The Subversion URL must be specified
 	as a command-line argument.
 
-fetch::
-	Fetch unfetched revisions from the Subversion URL we are
-	tracking.  refs/remotes/git-svn will be updated to the
-	latest revision.
+'fetch'::
 
-	Note: You should never attempt to modify the remotes/git-svn
-	branch outside of git-svn.  Instead, create a branch from
-	remotes/git-svn and work on that branch.  Use the 'commit'
-	command (see below) to write git commits back to
-	remotes/git-svn.
+Fetch unfetched revisions from the Subversion URL we are
+tracking.  refs/remotes/git-svn will be updated to the
+latest revision.
 
-	See 'Additional Fetch Arguments' if you are interested in
-	manually joining branches on commit.
+Note: You should never attempt to modify the remotes/git-svn
+branch outside of git-svn.  Instead, create a branch from
+remotes/git-svn and work on that branch.  Use the 'commit'
+command (see below) to write git commits back to
+remotes/git-svn.
 
-commit::
+See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
+manually joining branches on commit.
+
+'commit'::
 	Commit specified commit or tree objects to SVN.  This relies on
 	your imported fetch data being up-to-date.  This makes
 	absolutely no attempts to do patching when committing to SVN, it
 	simply overwrites files with those specified in the tree or
 	commit.  All merging is assumed to have taken place
 	independently of git-svn functions.
 
-rebuild::
+'rebuild'::
 	Not a part of daily usage, but this is a useful command if
-	you've just cloned a repository (using git-clone) that was
+	you've just cloned a repository (using gitlink:git-clone[1]) that was
 	tracked with git-svn.  Unfortunately, git-clone does not clone
 	git-svn metadata and the svn working tree that git-svn uses for
 	its operations.  This rebuilds the metadata so git-svn can
 	resume fetch operations.  A Subversion URL may be optionally
 	specified at the command-line if the directory/repository you're
 	tracking has moved or changed protocols.
 
-show-ignore::
+'show-ignore'::
 	Recursively finds and lists the svn:ignore property on
 	directories.  The output is suitable for appending to
 	the $GIT_DIR/info/exclude file.
 
+--
+
 OPTIONS
 -------
+--
+
 -r <ARG>::
 --revision <ARG>::
-	Only used with the 'fetch' command.
 
-	Takes any valid -r<argument> svn would accept and passes it
-	directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
-	is also supported.  This is passed directly to svn, see svn
-	documentation for more details.
+Only used with the 'fetch' command.
+
+Takes any valid -r<argument> svn would accept and passes it
+directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
+is also supported.  This is passed directly to svn, see svn
+documentation for more details.
 
-	This can allow you to make partial mirrors when running fetch.
+This can allow you to make partial mirrors when running fetch.
 
 -::
 --stdin::
-	Only used with the 'commit' command.
 
-	Read a list of commits from stdin and commit them in reverse
-	order.  Only the leading sha1 is read from each line, so
-	git-rev-list --pretty=oneline output can be used.
+Only used with the 'commit' command.
+
+Read a list of commits from stdin and commit them in reverse
+order.  Only the leading sha1 is read from each line, so
+git-rev-list --pretty=oneline output can be used.
 
 --rmdir::
-	Only used with the 'commit' command.
 
-	Remove directories from the SVN tree if there are no files left
-	behind.  SVN can version empty directories, and they are not
-	removed by default if there are no files left in them.  git
-	cannot version empty directories.  Enabling this flag will make
-	the commit to SVN act like git.
+Only used with the 'commit' command.
+
+Remove directories from the SVN tree if there are no files left
+behind.  SVN can version empty directories, and they are not
+removed by default if there are no files left in them.  git
+cannot version empty directories.  Enabling this flag will make
+the commit to SVN act like git.
 
-	repo-config key: svn.rmdir
+repo-config key: svn.rmdir
 
 -e::
 --edit::
-	Only used with the 'commit' command.
 
-	Edit the commit message before committing to SVN.  This is off by
-	default for objects that are commits, and forced on when committing
-	tree objects.
+Only used with the 'commit' command.
 
-	repo-config key: svn.edit
+Edit the commit message before committing to SVN.  This is off by
+default for objects that are commits, and forced on when committing
+tree objects.
+
+repo-config key: svn.edit
 
 -l<num>::
 --find-copies-harder::
-	Both of these are only used with the 'commit' command.
 
-	They are both passed directly to git-diff-tree see
-	git-diff-tree(1) for more information.
+Both of these are only used with the 'commit' command.
+
+They are both passed directly to git-diff-tree see
+gitlink:git-diff-tree[1] for more information.
 
-	repo-config key: svn.l
-	repo-config key: svn.findcopiesharder
+[verse]
+repo-config key: svn.l
+repo-config key: svn.findcopiesharder
 
 -A<filename>::
 --authors-file=<filename>::
 
-	Syntax is compatible with the files used by git-svnimport and
-	git-cvsimport:
+Syntax is compatible with the files used by git-svnimport and
+git-cvsimport:
 
 ------------------------------------------------------------------------
-loginname = Joe User <user@example.com>
+	loginname = Joe User <user@example.com>
 ------------------------------------------------------------------------
 
-	If this option is specified and git-svn encounters an SVN
-	committer name that does not exist in the authors-file, git-svn
-	will abort operation. The user will then have to add the
-	appropriate entry.  Re-running the previous git-svn command
-	after the authors-file is modified should continue operation.
+If this option is specified and git-svn encounters an SVN
+committer name that does not exist in the authors-file, git-svn
+will abort operation. The user will then have to add the
+appropriate entry.  Re-running the previous git-svn command
+after the authors-file is modified should continue operation.
 
-	repo-config key: svn.authors-file
+repo-config key: svn.authors-file
+
+--
 
 ADVANCED OPTIONS
 ----------------
+--
+
 -b<refname>::
 --branch <refname>::
-	Used with 'fetch' or 'commit'.
+Used with 'fetch' or 'commit'.
 
-	This can be used to join arbitrary git branches to remotes/git-svn
-	on new commits where the tree object is equivalent.
+This can be used to join arbitrary git branches to remotes/git-svn
+on new commits where the tree object is equivalent.
 
-	When used with different GIT_SVN_ID values, tags and branches in
-	SVN can be tracked this way, as can some merges where the heads
-	end up having completely equivalent content.  This can even be
-	used to track branches across multiple SVN _repositories_.
+When used with different GIT_SVN_ID values, tags and branches in
+SVN can be tracked this way, as can some merges where the heads
+end up having completely equivalent content.  This can even be
+used to track branches across multiple SVN _repositories_.
 
-	This option may be specified multiple times, once for each
-	branch.
+This option may be specified multiple times, once for each
+branch.
 
-	repo-config key: svn.branch
+repo-config key: svn.branch
 
 -i<GIT_SVN_ID>::
 --id <GIT_SVN_ID>::
-	This sets GIT_SVN_ID (instead of using the environment).  See
-	the section on "Tracking Multiple Repositories or Branches" for
-	more information on using GIT_SVN_ID.
+
+This sets GIT_SVN_ID (instead of using the environment).  See the
+section on
+'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
+for more information on using GIT_SVN_ID.
+
+--
 
 COMPATIBILITY OPTIONS
 ---------------------
+--
+
 --upgrade::
-	Only used with the 'rebuild' command.
+Only used with the 'rebuild' command.
 
-	Run this if you used an old version of git-svn that used
-	"git-svn-HEAD" instead of "remotes/git-svn" as the branch
-	for tracking the remote.
+Run this if you used an old version of git-svn that used
+"git-svn-HEAD" instead of "remotes/git-svn" as the branch
+for tracking the remote.
 
 --no-ignore-externals::
-	Only used with the 'fetch' and 'rebuild' command.
+Only used with the 'fetch' and 'rebuild' command.
+
+By default, git-svn passes --ignore-externals to svn to avoid
+fetching svn:external trees into git.  Pass this flag to enable
+externals tracking directly via git.
 
-	By default, git-svn passes --ignore-externals to svn to avoid
-	fetching svn:external trees into git.  Pass this flag to enable
-	externals tracking directly via git.
+Versions of svn that do not support --ignore-externals are
+automatically detected and this flag will be automatically
+enabled for them.
 
-	Versions of svn that do not support --ignore-externals are
-	automatically detected and this flag will be automatically
-	enabled for them.
+Otherwise, do not enable this flag unless you know what you're
+doing.
 
-	Otherwise, do not enable this flag unless you know what you're
-	doing.
+repo-config key: svn.noignoreexternals
 
-	repo-config key: svn.noignoreexternals
+--
 
 Basic Examples
 ~~~~~~~~~~~~~~
@@ -226,6 +249,7 @@ any automated merge/branch tracking on the Subversion side and leaves it
 entirely up to the user on the git side.  It's simply not worth it to do
 a useful translation when the original signal is weak.
 
+[[tracking-multiple-repos]]
 TRACKING MULTIPLE REPOSITORIES OR BRANCHES
 ------------------------------------------
 This is for advanced users, most users should ignore this section.
@@ -241,6 +265,7 @@ invocation.  The interface branch will be remotes/$GIT_SVN_ID, instead of
 remotes/git-svn.  Any remotes/$GIT_SVN_ID branch should never be modified
 by the user outside of git-svn commands.
 
+[[fetch-args]]
 ADDITIONAL FETCH ARGUMENTS
 --------------------------
 This is for advanced users, most users should ignore this section.
@@ -251,11 +276,15 @@ optionally be specified in the form of sha1 hex sums at the
 command-line.  Unfetched SVN revisions may also be tied to particular
 git commits with the following syntax:
 
+------------------------------------------------
 	svn_revision_number=git_commit_sha1
+------------------------------------------------
 
-This allows you to tie unfetched SVN revision 375 to your current HEAD::
+This allows you to tie unfetched SVN revision 375 to your current HEAD:
 
-	`git-svn fetch 375=$(git-rev-parse HEAD)`
+------------------------------------------------
+	git-svn fetch 375=$(git-rev-parse HEAD)
+------------------------------------------------
 
 Advanced Example: Tracking a Reorganized Repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~