... and yet more doc ups

[tig] / tig.c

diff --git a/tig.c b/tig.c
index 3b51c5a..b6c46ad 100644 (file)
--- a/tig.c
+++ b/tig.c
@@ -23,7 +23,7 @@
  * Browse changes in a git repository. Additionally, tig(1) can also act
  * as a pager for output of various git commands.
  *
- * When browsing repositories, tig(1) uses the underlaying git commands
+ * When browsing repositories, tig(1) uses the underlying git commands
  * to present the user with various views, such as summarized commit log
  * and showing the commit with the log message, diffstat, and the diff.
  *
@@ -294,8 +294,8 @@ parse_options(int argc, char *argv[])
 
                /**
                 * \--::
-                *      End of tig(1) options. Useful when specifying commands
-                *      for the main view. Example:
+                *      End of tig(1) options. Useful when specifying command
+                *      options for the main view. Example:
                 *
                 *              $ tig -- --since=1.month
                 **/
@@ -305,13 +305,13 @@ parse_options(int argc, char *argv[])
                }
 
                /**
-                * log [options]::
+                * log [git log options]::
                 *      Open log view using the given git log options.
                 *
-                * diff [options]::
+                * diff [git diff options]::
                 *      Open diff view using the given git diff options.
                 *
-                * show [options]::
+                * show [git show options]::
                 *      Open diff view using the given git show options.
                 **/
                if (!strcmp(opt, "log") ||
@@ -322,11 +322,16 @@ parse_options(int argc, char *argv[])
                        break;
                }
 
-               /* Make stuff like:
+               /**
+                * [git log options]::
+                *      tig(1) will stop the option parsing when the first
+                *      command line parameter not starting with "-" is
+                *      encountered. All options including this one will be
+                *      passed to git log when loading the main view.
+                *      This makes it possible to say:
                 *
                 *      $ tig tag-1.0..HEAD
-                *
-                * work. */
+                **/
                if (opt[0] && opt[0] != '-')
                        break;
 
@@ -367,10 +372,10 @@ parse_options(int argc, char *argv[])
                 *
                 *      $ tig log --pretty=fuller
                 *
-                * See the "Specifying revisions" section below for an introduction
-                * to revision options supported by the git commands. For
-                * details on specific git command options, refer to the man
-                * page of the command in question.
+                * See the <<refspec, "Specifying revisions">> section below
+                * for an introduction to revision options supported by the git
+                * commands. For details on specific git command options, refer
+                * to the man page of the command in question.
                 **/
 
                if (opt_request == REQ_VIEW_MAIN)
@@ -540,6 +545,7 @@ init_colors(void)
        "git ls-remote ."
 
 /**
+ * [[view-commands]]
  * View commands
  * ~~~~~~~~~~~~~
  * It is possible to alter which commands are used for the different views.
@@ -577,7 +583,7 @@ init_colors(void)
 #define TIG_MAIN_CMD \
        "git log --topo-order --stat --pretty=raw %s"
 
-/* We silently ignore that the following are also exported. */
+/* ... silently ignore that the following are also exported. */
 
 #define TIG_HELP_CMD \
        "man tig 2> /dev/null"
@@ -1702,7 +1708,7 @@ struct keymap keymap[] = {
         * h::
         *      Show man page.
         * Return::
-        *      If on a commit line show the commit diff. Addiionally, if in
+        *      If on a commit line show the commit diff. Additionally, if in
         *      main or log view this will split the view. To open the commit
         *      diff in full size view either use 'd' or press Return twice.
         * Tab::
@@ -1721,17 +1727,17 @@ struct keymap keymap[] = {
         * Cursor navigation
         * ~~~~~~~~~~~~~~~~~
         * Up::
-        *      Move curser one line up.
+        *      Move cursor one line up.
         * Down::
         *      Move cursor one line down.
         * k::
-        *      Move curser one line up and enter. When used in the main view
+        *      Move cursor one line up and enter. When used in the main view
         *      this will always show the diff of the current commit in the
         *      split diff view.
         * j::
         *      Move cursor one line down and enter.
         * PgUp::
-        *      Move curser one page up.
+        *      Move cursor one page up.
         * PgDown::
         *      Move cursor one page down.
         * Home::
@@ -1775,7 +1781,7 @@ struct keymap keymap[] = {
         * z::
         *      Stop all background loading. This can be useful if you use
         *      tig(1) in a repository with a long history without limiting
-        *      the log output.
+        *      the revision log.
         * v::
         *      Show version.
         * n::
@@ -2124,10 +2130,12 @@ main(int argc, char *argv[])
 }
 
 /**
+ * [[refspec]]
  * Specifying revisions
  * --------------------
- * This section describes various ways to specify what revisions to
- * display or otherwise limit the view to.
+ * This section describes various ways to specify what revisions to display
+ * or otherwise limit the view to. Note, that tig(1) does not itself parse
+ * the described revision options.
  *
  * Limit by date or number
  * ~~~~~~~~~~~~~~~~~~~~~~~
@@ -2136,10 +2144,8 @@ main(int argc, char *argv[])
  * e.g. `--since=1.month` or limit by the number of commits using `-n400`.
  *
  * NOTE: You can tune the interaction with git by making use of the options
- * explained in this section.
- *
- * NOTE: tig(1) does not itself parse the revision options
- * described in this section.
+ * explained in this section. For example, by configuring the environment
+ * variables described in the  <<view-commands, "View commands">> section.
  *
  * Ranges
  * ~~~~~~
@@ -2166,8 +2172,9 @@ main(int argc, char *argv[])
  *
  *     $ tig log tag-2.0 ^tag-1.0
  *
- * You can think of '^' as a negator. Using this alternate syntax, it is
- * possible to furthur prune commits by specifying multiple negators.
+ * You can think of '^' as a negation operator. Using this alternate syntax,
+ * it is possible to further prune commits by specifying multiple branch
+ * cut offs.
  *
  * BUGS
  * ----