Update README
authorAndrew Young <youngar17@gmail.com>
Tue, 14 Aug 2012 06:53:40 +0000 (02:53 -0400)
committerAndrew Young <youngar17@gmail.com>
Tue, 14 Aug 2012 06:53:40 +0000 (02:53 -0400)
README

diff --git a/README b/README
index d2413cf..d5707a9 100755 (executable)
--- a/README
+++ b/README
@@ -7,45 +7,45 @@ files.
 This project is currently being developed under Google Summer of Code
 2012 for the Gnu organization.
 
-The project page can be found [[http://orgmode.org/worg/org-contrib/gsoc2012/student-projects/git-merge-tool/index.html][here]].
+- The project page can be found [[http://orgmode.org/worg/org-contrib/gsoc2012/student-projects/git-merge-tool/index.html][here]].
+- The homepage of Org-mode is [[http://orgmode.org][here]].
 
-The homepage of Org is [[http://orgmode.org][here]].
+* Obtaining the source code
+The source code may be obtained from the GIT repository hosted at
+Orgmode.org.
 
-* Dependancies
-This program requires [[http://www.gnu.org/software/gnulib/][Gnulib]], Flex (not lex) and GNU Autotools to compile.
-
-To obtain Gnulib:
 #+begin_src sh
-git clone git://git.savannah.gnu.org/gnulib.git
-or
-cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
+  git clone git://orgmode.org/org-merge-driver.git
 #+end_src
 
 * Compiling
+Compiling this program requires that you have autotools installed. To
+compile this program, you should only have to run:
 
-To Compile simply run:
 #+begin_src sh
-cd $(top_srcdir)
-~/gnulib/gnulib-tool --add-import
-autoreconf -i
-./configure && make
+  autoreconf --install && ./configure && make
 #+end_src
 
-* Using
+If this fails because of missing dependencies, please see [[Dependencies][dependencies]]
+below.
+
+* Quick Start
 ** Using and Installation
 ** Git users:
-1. Add to .git/config of the checkout (or to your ~/.gitconfig) the
-   lines
+1. Add to your git configuration located in either
+   ${GIT_DIR}/.git/config (for repository local configuration) or
+   ~/.gitconfig (for global configuration) the following lines:
 
-#+begin_src
-[merge "merge-orgmode"]
-name = Org Mode merge driver
-driver = /usr/local/bin/org-merge-driver %O %A %B
+#+begin_src sh
+  [merge "merge-orgmode"]
+  name = Org Mode merge driver
+  driver = /usr/local/bin/org-merge-driver -- %O %A %B %A
 #+end_src
 
-2. In every directory with ormode files make a .gitattributes , or
-   .git/info/attributes if you don't want to have the file committed
-   with the project.  Add the following line to the file:
+2. In every work tree you wish to you the org-merge-driver, make a
+   .gitattributes file or .git/info/attributes if you don't want to have
+   the file committed with the project.  Add the following line to this
+   file:
 
 #+begin_src
 *.org merge=merge-orgmode
@@ -57,26 +57,124 @@ driver = /usr/local/bin/org-merge-driver %O %A %B
 1. Install the [[http://doc.bazaar.canonical.com/plugins/en/index.html][extmerge bzr plug-in]]
 2. Add to your ~/.bazaar/bazaar.conf the line
 
-#+begin_src
-external_merge = org-merge-driver %b %T %o
+#+begin_src sh
+  external_merge = org-merge-driver -- %b %T %o %T
 #+end_src
 
 3. Then, to merge a conflict in a ChangeLog file, use
 
-#+begin_src
-$ bzr extmerge --all --verbose
+#+begin_src sh
+  bzr extmerge --all --verbose
 #+end_src
+
 ** Mercurial users:
 1. Add to your $HOME/.hgrc the lines
 
-#+begin_src
-[merge-patterns]
-**.org = org-merge-driver
-
-[merge-tools]
-org-merge-driver.executable = /usr/local/bin/org-merge-driver
-org-merge-driver.args = $base $local $other
+#+begin_src sh
+  [merge-patterns]
+  ,**.org = org-merge-driver
+  
+  [merge-tools]
+  org-merge-driver.executable = /usr/local/bin/org-merge-driver
+  org-merge-driver.args = -- $base $local $other $local
 #+end_src
 
 See [[http://www.selenic.com/mercurial/hgrc.5.html][Configuration files for Mercurial]], section merge-tools for
-reference.
\ No newline at end of file
+reference.
+
+* Options
+This program currently supports the following options:
+
+| Short | Long                | Description                         |
+|-------+---------------------+-------------------------------------|
+| -m,   | --rmargin=COLUMN    | Set the right margin of headings    |
+| -N,   | --notabs            | Use only spaces in the output       |
+| -p,   | --priority=PRIORITY | Specify an accepted prority         |
+| -t,   | --todo=STATE        | Specify an accepted todo state.     |
+| -T,   | --usetabs           | Use tabs in the output, unused.     |
+| -W,   | --tabwidth=WIDTH    | The width of tabs in spaces, unused |
+| -?,   | --help              | Give this help list                 |
+|       | --usage             | Give a short usage message          |
+| -V,   | --version           | Print program version               |
+
+** "TODO" States
+If you have defined TODO states, you can describe them with this
+command. The defaults are set to "TODO" and "DONE". Declaring a single
+todo state causes the default set of todo states to be
+discarded. Because of this, you must declare all TODO states used.
+
+At this time, Todo states can only be configured on the command line.
+
+#+begin_example
+  org-merge-driver -tDONE --todo=TODO
+#+end_example
+
+** Priority Cookies
+If you have defined more priority states system-wide, you can describe
+them with this command. The defaults are set to 'A', 'B', and 'C'. You
+must declare all priority states used (all defaults are immediately
+overridden). Currently, priority cookies may only be a single ASCII
+character.
+
+#+begin_example
+  org-merge-driver -pA -pB --priority=C
+#+end_example
+
+** Right Margin
+Org-merge-driver will attempt to minimize reformatting, but it is
+sometimes necessary for org-merge-driver to realign text on the right
+margin of the text. This can happen after merging lists of heading
+TAGS.
+
+You can set the preferred right margin value (in spaces) with the
+=--rmargin== command. If the margin is not large enough to fit a line
+of text, it will extend past the margin. The default margin value is
+77 spaces.
+
+#+begin_example
+  org-merge-driver -m77
+#+end_example
+
+** Specify Input and Out Files
+To perform a merge, org-merge-driver requires three files -- your copy
+of a file, a remotely updated file, and a common ancestor file. These
+are given to org-merge-driver in the order ancestor, local, remote.
+
+To ensure that the file names are not confused with command line
+options, you can seperate them from the rest of the arguments with
+=--=.
+
+By default, org-merge-driver prints the merged file to stdout.  To
+have the output printed to a file, specify a fourth file on the
+command line.
+
+#+begin_example
+  org-merge-driver -- ancestor.org local-update.org remote-update.org output.org
+#+end_example
+
+* Dependencies
+To compile org-merge-driver, you may need: [[http://www.gnu.org/software/gnulib/][Gnulib]], [[http://flex.sourceforge.net/][Flex]] (not lex) and
+GNU Autotools installed.  Install Flex and autotools using your desired
+package manager.  To obtain gnulib follow the instructions below.
+
+** To obtain Gnulib:
+You must obtain Gnulib by it's source code, there is no binary
+distribution.  Through git or cvs:
+#+begin_src sh
+  git clone git://git.savannah.gnu.org/gnulib.git
+  # or
+  cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
+#+end_src
+
+** Reimporting gnulib-tool dependencies
+#+begin_src sh
+  cd $(top_srcdir)
+  /PATH/TO/GNULIB/gnulib-tool --add-import
+#+end_src
+
+** Compiling
+To compile,  run:
+#+begin_src sh
+  autoreconf -i
+  ./configure && make
+#+end_src