NEWS item and doco tweaks

2 files changed, 86 insertions, 45 deletions

diff --git a/NEWS b/NEWS
index a4d5359..09eaf31 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,18 @@ Compatability Breaks
 New Features
 ------------
 
+* Wrapper commands simplifying the generation of fast-import
+  files from other tools are now provided. The general usage is:
+
+    bzr fast-export-from-xxx SOURCE project.fi
+
+  Before starting an export, these commands make an effort to
+  check that dependent tools are installed. The commands available
+  so far are fast-export-from-svn, fast-export-from-git,
+  fast-export-from-hg and fast-export-from-darcs. Similar wrappers
+  for other tools, particularly cvs and perforce, will hopefully
+  be added soon. (Ian Clatworthy)
+
 * darcs-fast-export is now bundled. In fact, the project has
   merged into this one for the purposes of ongoing bug fixing
   and development. (Miklos Vajna)
diff --git a/__init__.py b/__init__.py
index 79f4f97..d91ce59 100644
--- a/__init__.py
+++ b/__init__.py
@@ -17,9 +17,8 @@
 r"""FastImport Plugin
 =================
 
-The fastimport plugin provides stream-based importing of data into Bazaar.
-A bzr-fast-export.py script is also included providing exporting of data
-out of Bazaar to the same format. As well as enabling interchange between
+The fastimport plugin provides stream-based importing and exporting of
+data into and out of Bazaar. As well as enabling interchange between
 multiple VCS tools, fastimport/export can be useful for complex branch
 operations, e.g. partitioning off part of a code base in order to Open
 Source it.
@@ -27,20 +26,47 @@ Source it.
 The normal import recipe is::
 
   bzr init-repo .
-  front-end | bzr fast-import -
+  bzr fast-export-from-xxx SOURCE project.fi
+  bzr fast-import project.fi
 
-Numerous front-ends are provided in the exporters directory where
-the plugin is installed. The list of known front-ends and their
-status is documented on http://bazaar-vcs.org/BzrFastImport/FrontEnds.
-For further details, see http://bazaar-vcs.org/BzrFastImport and the
-online help for the commands::
+If fast-export-from-xxx doesn't exist yet for the tool you're importing
+from, the alternative recipe is::
+
+  bzr init-repo .
+  front-end > project.fi
+  bzr fast-import project.fi
+
+The list of known front-ends and their status is documented on
+http://bazaar-vcs.org/BzrFastImport/FrontEnds. The fast-export-from-xxx
+commands provide simplified access to these so that the majority of users
+can generate a fast-import dump file without needing to study up on all
+the options - and the best combination of them to use - for the front-end
+relevant to them. In some cases, a fast-export-from-xxx wrapper will require
+that certain dependencies are installed so it checks for these before
+starting. A wrapper may also provide a limited set of options. See the
+online help for the individual commands for details::
+
+  bzr help fast-export-from-darcs
+  bzr help fast-export-from-hg
+  bzr help fast-export-from-git
+  bzr help fast-export-from-svn
+
+Once a fast-import dump file is created, it can be imported into a
+Bazaar repository using the fast-import command. If required, you can
+manipulate the stream first using the fast-import-filter command.
+This is useful for creating a repository with just part of a project
+or for removing large old binaries (say) from history that are no longer
+valuable to retain. For further details on importing, manipulating and
+reporting on fast-import streams, see the online help for the commands::
 
   bzr help fast-import
-  bzr help fast-export
   bzr help fast-import-filter
   bzr help fast-import-info
   bzr help fast-import-query
 
+Finally, you may wish to generate a fast-import dump file from a Bazaar
+repository. The fast-export command is provided for that purpose.
+
 To report bugs or publish enhancements, visit the bzr-fastimport project
 page on Launchpad, https://launchpad.net/bzr-fastimport.
 """
@@ -80,13 +106,20 @@ class cmd_fast_import(Command):
 
     This command reads a mixed command/data stream and
     creates branches in the current repository accordingly.
-    To specify standard input as the input stream, use a
-    source name of '-'.
-    
     The usual recipe is::
 
-      bzr init-repo .
-      front-end | bzr fast-import -
+      bzr fast-import project.fi
+
+    To specify standard input as the input stream, use a
+    source name of '-' (instead of project.fi). Numerous commands
+    are provided for generating a fast-import stream to use as input.
+    These include fast-export-from-svn, fast-export-from-git,
+    fast-export-from-hg and fast-export-from-darcs.
+
+    If you wish to write a custom exporter for your project, see
+    http://bazaar-vcs.org/BzrFastImport for the detailed protocol
+    specification. In many cases, exporters can be written quite
+    quickly using whatever scripting/programming language you like.
 
     If run inside a branch using a shared repository, then
     the current branch is made the trunk and other branches,
@@ -102,25 +135,6 @@ class cmd_fast_import(Command):
     * */master is mapped to trunk, trunk.remote, etc.
     * */trunk is mapped to git-trunk, git-trunk.remote, etc.
 
-    The stream format is upwardly compatible with git-fast-import
-    so existing front-ends for that tool can typically be reused
-    without changes. See http://bazaar-vcs.org/BzrFastImport for
-    links to matching exporters from Subversion, CVS, Git,
-    Mercurial, Darcs, Perforce and SCCS.
-
-    While reusing an existing format with existing frontends is
-    great, it does mean a slightly more complex recipe when
-    importing large projects via exporters that reuse blob data
-    across commits, namely::
-
-      bzr init-repo .
-      front-end > xxx.fi
-      bzr fast-import-info -v xxx.fi > xxx.cfg
-      bzr fast-import xxx.fi --info xxx.cfg
-
-    In this scenario, the xxx.cfg file generated by the first pass
-    holds caching hints that the second pass uses to lower memory
-    usage.
 
     At checkpoints and on completion, the commit-id -> revision-id
     map is saved to a file called 'fastimport-id-map' in the control
@@ -133,25 +147,40 @@ class cmd_fast_import(Command):
     If and when Bazaar is used to manage the repository, this file
     can be safely deleted.
 
-    If you wish to write a custom exporter for your project, see
-    http://bazaar-vcs.org/BzrFastImport for the detailed protocol
-    specification. In many cases, exporters can be written quite
-    quickly using whatever scripting/programming language you like.
+    Note: A slightly more complex recipe is required when importing large
+    projects via exporters that reuse blob data across commits, namely::
+
+      bzr init-repo .
+      front-end > xxx.fi
+      bzr fast-import-info -v xxx.fi > xxx.cfg
+      bzr fast-import xxx.fi --info xxx.cfg
+
+    In this scenario, the xxx.cfg file generated by the first pass
+    holds caching hints that the second pass uses to lower memory
+    usage. Development is planned so that this recipe becomes obsolete
+    in the future, i.e. so that the simple recipe always works.
 
     Examples::
 
-     cd /git/repo/path
-     git-fast-export --signed-tags=warn | bzr fast-import -
+     Import a Subversion repository into Bazaar:
+
+       bzr fast-export-from-svn /svn/repo/path project.fi
+       bzr fast-import project.fi
+
+     Import a Git repository into Bazaar:
 
-        Import a Git repository into Bazaar.
+       bzr fast-export-from-git /git/repo/path project.fi
+       bzr fast-import project.fi
 
-     svn-fast-export.py /svn/repo/path | bzr fast-import -
+     Import a Mercurial repository into Bazaar:
 
-        Import a Subversion repository into Bazaar.
+       bzr fast-export-from-hg /hg/repo/path project.fi
+       bzr fast-import project.fi
 
-     hg-fast-export.py -r /hg/repo/path | bzr fast-import -
+     Import a Darcs repository into Bazaar:
 
-        Import a Mercurial repository into Bazaar.
+       bzr fast-export-from-darcs /darcs/repo/path project.fi
+       bzr fast-import project.fi
     """
     hidden = False
     _see_also = ['fast-export', 'fast-import-filter', 'fast-import-info']