git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [RFC] Add support for short help to Cogito commands
@ 2005-11-15 12:55 Jonas Fonseca
  2005-11-15 22:17 ` Petr Baudis
  0 siblings, 1 reply; 3+ messages in thread
From: Jonas Fonseca @ 2005-11-15 12:55 UTC (permalink / raw)
  To: git

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

^ permalink raw reply related	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2005-11-16 17:18 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-11-15 12:55 [RFC] Add support for short help to Cogito commands Jonas Fonseca
2005-11-15 22:17 ` Petr Baudis
2005-11-16 17:18   ` [PATCH] Add " Jonas Fonseca

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).