From: Jonas Fonseca <fonseca@diku.dk>
Date: Tue, 15 Nov 2005 12:55:16 GMT
Subject: [RFC] Add support for short help to Cogito commands
Message-ID: <20051115125516.GD13925@diku.dk>

Hi,

I hope I am not the only one feeling that -h can sometimes be a little
too verbose when you want to have a quick overview of a Cogito command.
I'd like to make -h show only a short summary of the available options
and keep the longer help text for --help. I have attached a patch that
does something like this. Example:

  $ cg diff -h
  Usage: cg-diff [-c] [-m] [-s] [-p] [-r FROM_ID[..TO_ID]] [FILE]...

  Options:
    -c                   Colorize the diff output
    -p                   Use parent commit to specified ID
    -s                   Summarize the diff
    -r FROM_ID[..TO_ID]  Specify the revisions to diff
    -m                   Base the diff at the merge base of specified revision
    -h                   Print short usage help
    --help               Print long usage help

If something like this is acceptable, I'd like to know how to proceed
with improving the option captions. I've considered two possibilities:

 - Get the caption from the first line of the option description.  This
   is similar to what the patch does (it also roughly removes everything
   after the first punctuation char). But it will require that all
   option descriptions are changed to have a one line caption at the
   start. Example:

	# ...
	#
	# -r FROM_ID[..TO_ID]::
	#	Specify revisions to diff. Revisions can be specified
	#	using either '-r rev1 ...

 - Add a special line with the caption. Since we already 'filters' the
   help text in the script headers this could go after the '::'.
   Example:

	# ...
	#
	# -r FROM_ID[..TO_ID]:: Specify revisions to diff
	#	Specify the revisions to diff using either '-r rev1
	#	...

   So that it will be easy to remove from the --help output and from the
   generated manpages.

The last option is less intrusive, but does make the syntax of the
script headers less clean. Comments?

diff --git a/cg-Xlib b/cg-Xlib
index fa3a059..a1c89dc 100755
--- a/cg-Xlib
+++ b/cg-Xlib
@@ -347,18 +347,39 @@ deprecated_alias()
 
 print_help()
 {
-	which "cg-$1" >/dev/null 2>&1 || exit 1
+	which "cg-$2" >/dev/null 2>&1 || exit 1
 	sed -n '/^USAGE=/,0s/.*"\(.*\)"/Usage: \1/p;
-	        /^deprecated_alias/,0s/^deprecated_alias \([^ ]*\)/\1 is the new name for/p' < $(which cg-$1) 
+	        /^deprecated_alias/,0s/^deprecated_alias \([^ ]*\)/\1 is the new name for/p' < $(which cg-$2) 
 	echo
-	sed -n '3,/^$/s/^# *//p' < $(which cg-$1)
+	if [ x"$1" = xshort ]; then
+		echo "Options:"
+		_cg_fmt="  %-20s %s\n"
+		sed -n '/# \(-.*::\)/,/^#/s/#//p' < $(which cg-$2) | while read line; do
+			case "$line" in
+			-*::)
+				_cg_option="$(echo -n " $line" | sed 's/ \(-.*\)::/\1/')"
+				;;
+			*)
+				printf "$_cg_fmt" "$_cg_option" \
+					"$(echo "$line" | sed 's/\([^-][^.,]*\)[.,].*/\1/')"
+				_cg_option=
+				;;
+			esac
+		done
+		printf "$_cg_fmt" "-h" "Print short usage help"
+		printf "$_cg_fmt" "--help" "Print long usage help"
+	else
+		sed -n '3,/^$/s/^# *//p' < $(which cg-$2)
+	fi
 	exit
 }
 
 for option in "$@"; do
 	[ x"$option" = x-- ] && break
-	if [ x"$option" = x"-h" -o x"$option" = x"--help" ]; then
-		print_help ${_cg_cmd##cg-}
+	if [ x"$option" = x"-h" ]; then
+		print_help short ${_cg_cmd##cg-}
+	elif [ x"$option" = x"--help" ]; then
+		print_help long ${_cg_cmd##cg-}
 	fi
 done
 
-- 
Jonas Fonseca