Re: [PATCH 2/2] Create a meld man page

[Kai <kai willadsen gmail com>]

On 27 September 2010 14:27, Peter Tyser <ptyser gmail com> wrote:
> This should reduce the effort required by distributions when packaging
> up meld and also provide a standard document describing its usage.

Generally, looks nice. I have a preference for listing the file,
directory and VC comparisons separately though. While what you've
written is correct, the command line listing given makes the VC
comparison look like a special case of the directory comparison.

> Signed-off-by: Peter Tyser <ptyser gmail com>
> ---
>  meld.1 |   79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 79 insertions(+), 0 deletions(-)
>  create mode 100644 meld.1
>
> diff --git a/meld.1 b/meld.1
> new file mode 100644
> index 0000000..07377bb
> --- /dev/null
> +++ b/meld.1
> @@ -0,0 +1,79 @@
> +.TH MELD 1 "26 Sept 2010"
> +.SH NAME
> +\fBmeld\fP \- Visual diff and merge tool for the GNOME Desktop
> +.SH SYNOPSIS
> +\fBmeld\fR [options]
> +.br
> +\fBmeld\fR [options] FILE1 [FILE2] [FILE3]
> +.br
> +\fBmeld\fR [options] DIR1 [DIR2] [DIR3]
> +.SH DESCRIPTION
> +.B Meld
> +is a graphical diff viewer and merge application for the Gnome desktop.
> +It supports 2 and 3-file diffs, rescursive directory diffs, diffing

recursive

> +of directories under version control (Arch, Bazaar, Codeville, CVS, Darcs,
> +Git, Mercurial, Monotone, RCS), as well as the ability to manually merge

Maybe "manually and automatically"? We should start advertising that we do this.

> +file differences.
> +.SH OPTIONS
> +.TP
> +\fB\-\-version\fR
> +.br
> +Print application version and exit.
> +.TP
> +\fB\-\-help, \-h\fR
> +.br
> +Print application help and usage.
> +.TP
> +\fB\-\-LABEL=<label>, \-L <label>\fR
> +.br
> +Set application window title to <label>.
> +.TP
> +\fB\-\-auto-compare, \-a\fR
> +.br
> +Automatically compare all differing files on startup.
> +.TP
> +\fB\-\-diff FILE1|DIR1 FILE2|DIR2 [FILE3|DIR3]\fR
> +.br
> +Create a diff tab for the given files or directories.  The \fB\-\-diff\fR
> +argument can be given multiple times for one invocation of meld.

Unfortunately, that this option duplicates all of the other three-mode
logic makes this really unclear. Can we come up with some wording
saying "like we do for normal extra arguments"?

> +.SH EXAMPLES
> +.TP
> +\fBmeld\fR
> +.br
> +Run \fBmeld\fR without initiating a diff.
> +.TP
> +\fBmeld\fR FILE1 FILE2
> +.br
> +Initiate a diff between FILE1 and FILE2.
> +.TP
> +\fBmeld\fR FILE1 FILE2 FILE3
> +.br
> +Initiate a 3-way diff between FILE1, FILE2, and FILE3.
> +.TP
> +\fBmeld\fR DIR1 DIR2
> +.br
> +Initiate a recursive diff between directory DIR1 and DIR2.
> +.TP
> +\fBmeld\fR DIR1 DIR2 DIR3
> +.br
> +Initiate a recursive 3-way diff between directory DIR1, DIR2, and DIR3.
> +.TP
> +\fBmeld\fR FILE1
> +.br
> +Initiate a diff between FILE1 and the version-controlled copy of FILE1.
> +.TP
> +\fBmeld\fR DIR1
> +.br
> +Initiate a recursive diff between DIR1 and the version-controlled copy of DIR1.
> +.TP
> +\fBmeld\fR --diff FILE1 FILE2 --diff FILE3 FILE4
> +.br
> +Initiate a diff between FILE1 and FILE2, and a separate diff between FILE3 and
> +FILE4.

Nice examples.

> +.SH BUGS
> +If you find a bug, please report it at
> +https://bugzilla.gnome.org/buglist.cgi?product=meld or mail a description of
> +the issue to meld-list gnome org 
> +.SH AUTHORS
> +See the AUTHORS text file in \fBmeld's\fR source code
> +(http://git.gnome.org/browse/meld/tree/AUTHORS).
> --
> 1.7.1.13.gcfb88
>
> _______________________________________________
> meld-list mailing list
> meld-list gnome org
> http://mail.gnome.org/mailman/listinfo/meld-list
>