From: Eric S. Raymond <esr@thyrsus.com>
Date: Thu, 13 Nov 2014 21:17:53 +0000 (-0500)
Subject: reak up help into topics.
X-Git-Tag: 0.8~12
X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=ee75618499381c3ec5da632167b5afedd6e1a44b;p=src.git

reak up help into topics.
---

diff --git a/src b/src
index 9c50d04..d319294 100755
--- a/src
+++ b/src
@@ -241,11 +241,51 @@ class History:
         "Map a revno to a native ID"
         return self.by_revno(revno).native
 
-def help_method(*_args):
-    "Summarize src commands, or (with argument) show help for a single command."
-    print("""
+help_topics = {
+    "topics": """
+The following help topics are available:
+
+intro     -- Basic concepts: commits, tags, branches. The form of commands.
+revisions -- How to specify ranges of commits to operate on
+commands  -- a summary of the commands
+""",
+    "intro": """
+SRC (or src) is designed for version control on single-file projects.
+
+A SRC history is a sequence of commits numbered in strict time order
+starting from 1.  Each holds a modification to the file, a comment,
+and the date-time of the commit.
+
+The sequence also has a branch structure.  By default there is just
+one branch named 'trunk'.  You can start a new named branch at any
+commit. Branches can later be renamed or deleted.  Because of
+branching, parent and child commits do not necessarily have
+consecutive numbers.
+
+You can assign tags (names) to point to commits. They too can be
+renamed later or deleted.
+
+The general form of a SRC command is
+
+	src verb [switches] [revision-spec] [files...]
+
+That is, a command verb is followed by optional switches, which is
+(sometimes) optionally followed by a range of commits to operate on,
+which is optionally followed by a list of files to operate on.
+
+The token "--" tells the command-line interpreter that subcommands,
+switches, and revision-specs are done - everything after it is a filename,
+even if it looks like a subcommand or revision number.
+
+Actually, at least one file operand is usually required.  The
+exceptional case is when you have only one SRC-controlled file
+in the directory; in that case SRC knows you must mean that one.
+
+A good help topics to read after this one would be 'revisions'.
+""",
+    "revisions": """
 A 'revision' is a 1-origin integer, or a tag name designating an
-integer revision, or a branch name esignatingthe tip revision of its
+integer revision, or a branch name designating the tip revision of its
 branch. Revision numbers always increase in commit-date order.
 
 A revision range is a single revision, or a pair of revisions M-N (all
@@ -255,14 +295,22 @@ branch ancestors of N and branch successors of M).
 If src complains that your revision spec looks like a nonexistent
 filename, you can prefix it with @ (this is always allowed).
 
+Some commands (help, commit, status, delete/rename commsands for tags
+and branches, ls, move, copy, fast-import, release, version) don't
+take a revision spec at all and will abort if you give one.
+
+Some commands (amend, checkout, cat, tag and branch creation) optionally
+take a singleton revision spec.
+
+Some commands (log, list, diff, fast-export) accept a range or a singleton.
+
 Unless otherwise noted under individual commands, the default revision
 is the tip revision on the current branch and the default range is all
 revisions on the current branch.
 
-The token "--" tells the command-line interpreter that revision-specs
-and subcommands are done - everything after it is a filename, even
-if it looks like a subcommand or revision number.
-
+A good topic to read next would be 'commands'.
+""",
+    "commands": """
 src help [command]
    Displays help for commands.
 
@@ -345,8 +393,18 @@ src version
    Report the version of src.
 
 The omission of 'src remove' is a deliberate speed bump.
-""")
+"""
+    }
 
+def help_method(*args):
+    "Summarize src commands, or (with argument) show help for a single command."
+    sys.stdout.write(help_topics['topics'])
+    for arg in args:
+        if arg in args:
+            if arg in help_topics:
+                sys.stdout.write(help_topics[arg])
+            else:
+                croak("%s is not a known help topic.\n%s" % (arg, help_topics['topics']))
 
 def parse_as_revspec(token):
     "Does this look like something that should be parsed as a revision spec?"