[Debian] clisp-link.1 (was Re: debian clisp package)

[Luca Capello]

Hi Sam!

On Tue, 04 Nov 2008 18:49:52 +0100, Sam Steingold wrote:
>> On Fri, 24 Oct 2008 21:50:39 +0200, Sam Steingold wrote:
>>> A. clisp-link is rarely invoked by the user at the command line,
>>> usually it is used from Makefiles.
>>
>> While I agree on this, I also know that people tend to not follow
>> upstream recommendation and documentation.  And in my experience, the
>> first thing I do when I try a new program is to test the --help|-h
>> options and `man program` ;-)
>
> yes, clisp-link --help should point to the impnotes.

Since the --help option is not yet present in upstream clisp-link:

--8<---------------cut here---------------start------------->8---
--- clisp-link.in.~1~	2008-11-04 22:42:55.000000000 +0100
+++ clisp-link.in	2008-11-04 22:58:35.000000000 +0100
@@ -15,7 +15,6 @@
 
 usage () {
 echo "Usage: $0 [ link | create-module-set | add-module-set | add-module-sets | run ] ..." 1>&2
-exit 1
 }
 
 normalize(){                    # dir rel -> abs path for rel
@@ -177,6 +176,7 @@
 # Check number of arguments. Need at least one argument.
 if [ $# = 0 ] ; then
   usage
+  exit 1
 fi
 
 # Where is the link kit?
@@ -193,6 +193,12 @@
 # Dispatch according to the first argument.
 case "$1" in
 
+  -h|--help)
+    usage
+    echo
+    echo "For a full documentation, please refer to the Implementation Notes"
+    ;;
+
   link)
     # This is actually obsolete because it is easier done by a simple
     # "make" w.r.t. to the distmakefile.
@@ -548,6 +554,9 @@
     fi
     ;;
 
-  *) usage;;
+  *)
+    usage
+    exit 1
+    ;;
 esac
 
--8<---------------cut here---------------end--------------->8---

>>> B. clisp-link is already fully documented in the impnotes.
>>
>> Debian ships the impnotes as part of the clisp-doc package, which means
>> that in most of the case the impnotes will not be available together
>> with the clisp-link executable.
>
> "web is the computer" :-)

I agree, but I also tend at first to not install any -doc package ;-)

>> My idea was to provide the basic notions, i.e. the same thing we can
>> discover if you read the source.  Maybe should I add a note in the
>> manpage to direct the user to the full documentation in the impnotes?
>
> absolutely!

Here the patch against the quilt patch available at [1]:

--8<---------------cut here---------------start------------->8---
diff --git a/debian/patches/02_add-clisp-link-manpage.patch b/debian/patches/02_add-clisp-link-manpage.patch
index 073d578..6954e2c 100644
--- a/debian/patches/02_add-clisp-link-manpage.patch
+++ b/debian/patches/02_add-clisp-link-manpage.patch
@@ -1,6 +1,6 @@
 --- /dev/null
 +++ clisp/doc/_clisp-link.1
-@@ -0,0 +1,75 @@
+@@ -0,0 +1,78 @@
 +.\" -*- nroff -*-
 +.\"
 +.\" Copyright (c) 2008 Luca Capello <luca at pca.it>
@@ -23,6 +23,9 @@
 +.PP
 +Invokes \fBclisp\fR(1) to add an external module (written in C, for
 +example)\.
++.PP
++For a full documentation, please refer to the Implementation Notes
++provided in the Debian clisp-doc package.
 +
 +.SH "OPTIONS"
 +.PP
--8<---------------cut here---------------end--------------->8---

Please let me know if anything more is needed.

Thx, bye,
Gismo / Luca

Footnotes: 
[1] http://patch-tracking.debian.net/patch/series/view/clisp/1:2.44.1-4.1/02_add-clisp-link-manpage.patch
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 314 bytes
Desc: not available
Url : http://lists.alioth.debian.org/pipermail/pkg-common-lisp-devel/attachments/20081104/bbe625ee/attachment.pgp