Rev 1173: Crude help for 'bzr help svn'. in http://people.ubuntu.com/~robertc/baz2.0/plugins/svn/trunk

[Robert Collins]

At http://people.ubuntu.com/~robertc/baz2.0/plugins/svn/trunk

------------------------------------------------------------
revno: 1173
revision-id: robertc at robertcollins.net-20080520124028-wwx3jr7wb5g1cw1j
parent: jelmer at samba.org-20080515200318-przx9hsplqf1l1v1
committer: Robert Collins <robertc at robertcollins.net>
branch nick: trunk
timestamp: Tue 2008-05-20 22:40:28 +1000
message:
  Crude help for 'bzr help svn'.
modified:
  __init__.py                    __init__.py-20051008155114-eae558e6cf149e1d
=== modified file '__init__.py'
--- a/__init__.py	2008-05-15 01:23:34 +0000
+++ b/__init__.py	2008-05-20 12:40:28 +0000
@@ -14,8 +14,98 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-"""
-Support for Subversion branches
+"""Bazaar support for Subversion branches, working trees and repositories
+======================================================================
+
+.. contents::
+
+Introduction
+------------
+
+bzr-svn is a plugin that allows Bazaar_ direct access to Subversion_ 
+repositories. It allows most bzr commands to work directly against Subversion 
+repositories, as if you were using bzr with a native bzr repository.
+
+.. _Bazaar: http://bazaar-vcs.org/
+.. _Subversion: http://subversion.tigris.org/
+
+The plugin can at the moment be used to commit to, pull from, merge from, push 
+to and view logs of Subversion branches from Bazaar.
+
+
+Features
+--------
+
+The following features are currently present:
+
+- Connecting to remote Subversion repositories over all 
+  protocols supported by Subversion itself (at present: 
+  svn://, svn+ssh://, http:// (webdav), file://) 
+  as well as dump files. 
+
+  Checkouts, lightweight checkouts and branching works.
+
+- Integrates well with Bazaar.
+
+- Track Bazaar merges in Subversion. Merged revisions show up 
+  as ghosts.
+
+- Subversion working copies. Can be modified, queried 
+  (``bzr status`` on a svn- native working copy created with 
+  ``svn co`` works) and committed from.
+
+- Committing to Subversion from Bazaar.
+
+- Push Bazaar revisions to Subversion. 
+
+- Follow branch copies. Revision history is not 
+  truncated when a branch was copied in Subversion.
+
+- Efficiently uses network bandwidth.
+
+- Recognizes file metadata (executable bits, symbolic links).
+
+- 'svn-import' command with functionality similar to svn2bzr_.
+
+.. _svn2bzr: http://bazaar-vcs.org/svn2bzr
+
+- Ability to track merges done with SVK_ and write merges from SVK/Subversion branches in a format understandable by SVK.
+
+.. _SVK: http://svk.elixus.org/
+
+- Generates consistent file ids and revision ids. Two branches made using 
+  this plugin of the same Subversion branch will result in *exactly* the same 
+  Bazaar branch.
+
+- Handles complex operations in Subversion: committing to two branches at 
+  once, upgrading directories to branches, copies from early revisions, ...
+
+- Tested on Linux, Windows and Mac OS X. 
+
+Documentation
+-------------
+
+bzr-svn can be used through the regular Bazaar user interface, see the 
+`Bazaar Documentation Overview`_ for documentation on that.
+
+.. _Bazaar Documentation Overview: Documentation
+
+Some bzr-svn specific issues are answered by the FAQ_.
+
+.. _FAQ: http://samba.org/~jelmer/bzr-svn/FAQ.html
+
+The way Bazaar metadata is stored in Subversion and the other way around is specified in the `mapping specification`_.
+
+.. _mapping specification: BzrForeignBranches/Subversion/mapping
+
+Support
+-------
+Ask bzr-svn related questions on the `Bazaar mailing list`_ or in the 
+#bzr IRC channel on Freenode_.
+
+.. _Bazaar mailing list: http://lists.canonical.com/listinfo/bazaar/
+.. _Freenode: http://www.freenode.net/
+
 """
 import bzrlib
 from bzrlib.bzrdir import BzrDirFormat, format_registry