docs/man: update checkout man page

In a previous commit we revised the "git lfs checkout" command to
handle certain improper argument error conditions more gracefully,
including when too many paths to conficting files are provided along
with the --to option (plus the necessary file for the --to option
and one of the "stage" options: --base, --ours, or --theirs).

We therefore also update the git-lfs-checkout(1) manual page to
clarify that only a single path should be provided in this case,
and that it must reference a conflicting Git LFS object file,
not just any file with a merge conflict.

We also add some missing formatting in the Synposis section to
ensure the two alternative invocation formats are clearly
separated, and we adjust the terminology of some of the
user-provided arguments to align better with Git's manual and
with other Git LFS manual pages.  Specifically, we use <file>
to indicate any file in the filesystem, <glob-pattern> to indicate
a Git LFS glob pathspec pattern matched according to gitignore(5)
rules, and <path> (in this case, <conflict-obj-path>) to indicate
a path within the repository.  And we expand on the details of
each of these terms in the text of the manual page as well.

Finally, we refine and expand the Examples section by adding
an example use case for the --to option, and making all the
examples follow the same formatting style.

docs/man/git-lfs-checkout.1.ronn

@@ -3,26 +3,29 @@ git-lfs-checkout(1) -- Update working copy with file content if available
 
 ## SYNOPSIS
 
-`git lfs checkout` <filespec>...
-`git lfs checkout` --to <path> { --ours | --theirs | --base } <file>...
+`git lfs checkout` [<glob-pattern>...]<br>
+`git lfs checkout` --to <file> {--base|--ours|--theirs} <conflict-obj-path>
 
 ## DESCRIPTION
 
 Try to ensure that the working copy contains file content for Git LFS objects
 for the current ref, if the object data is available. Does not download any
-content, see git-lfs-fetch(1) for that.
+content; see git-lfs-fetch(1) for that.
 
 Checkout scans the current ref for all LFS objects that would be required, then
 where a file is either missing in the working copy, or contains placeholder
 pointer content with the same SHA, the real file content is written, provided
 we have it in the local store. Modified files are never overwritten.
 
-Filespecs can be provided as arguments to restrict the files which are updated.
+One or more <glob-pattern>s may be provided as arguments to restrict the
+set of files that are updated. Glob patterns are matched as per the format
+described in gitignore(5).
 
 When used with `--to` and the working tree is in a conflicted state due to a
-merge, this option checks out one of the three stages of the conflict into a
-separate file. This can make using diff tools to inspect and resolve merges
-easier.
+merge, this option checks out one of the three stages a conflicting Git LFS
+object into a separate file (which can be outside of the work tree).
+This can make using diff tools to inspect and resolve merges easier.
+A single Git LFS object's file path must be provided in <conflict-obj-path>.
 
 ## OPTIONS
 
@@ -43,17 +46,42 @@ easier.
 
 ## EXAMPLES
 
-* Checkout all files that are missing or placeholders
+* Checkout all files that are missing or placeholders:
 
-  `git lfs checkout`
+```
+$ git lfs checkout
+```
 
-* Checkout a specific couple of files
+* Checkout a specific couple of files:
 
-  `git lfs checkout path/to/file1.png path/to.file2.png`
+```
+$ git lfs checkout path/to/file1.png path/to.file2.png
+```
+
+* Checkout a path with a merge conflict into separate files:
+
+```
+# Attempt merge with a branch that has a merge conflict
+$ git merge conflicting-branch
+CONFLICT (content): Merge conflict in path/to/conflicting/file.dat
+
+# Checkout versions of the conflicting file into temp files
+$ git lfs checkout ours.dat --ours path/to/conflicting/file.dat
+$ git lfs checkout theirs.dat --theirs path/to/conflicting/file.dat
+
+# Compare conflicting versions in ours.dat and theirs.dat,
+# then resolve conflict (e.g., by choosing one version over
+# the other, or creating a new version)
+
+# Cleanup and continue with merge
+$ rm ours.dat theirs.dat
+$ git add path/to/conflicting/file.dat
+$ git merge --continue
+```
 
 ## SEE ALSO
 
-git-lfs-fetch(1), git-lfs-pull(1).
+git-lfs-fetch(1), git-lfs-pull(1), gitignore(5).
 
 Part of the git-lfs(1) suite.