Re: where is what? - clarification (hopefully)
* Wed 1999-09-08 Keith Harbaugh <harbaugh@math.georgetown.edu>
> Thanks to all who have replied.
[[ please keep me on CC since I'm not subscribed to this list ]]
Hi Keith,
I've read all the replies by Ernest Johanson, Jim Foltz, Mark Buda,
Seth R Arnold and closest to the original spirit comes to Mark's explanation:
"what" is part of SCCS, the Source Code Control System, and looks for
magic strings inserted by SCCS that get compiled into a program.
Debian doesn't have SCCS because the free equivalent of SCCS is RCS,
which isn't quite the same thing.
The RCS equivalent of the SCCS "what" command is "ident".
I don't know if what(1) belongs to SCCS because I've been using what(1)
in HP-UX/SUN environments since 1994. It could be that it was installed
there and not part of the Unix distribution. I never checked.
However, one thing is for sure: what(1) is not equivalent of ident(1).
Their spirit may be the same, since they both can
extract documentation strings marked with special syntax
Note that this extraction can be done both to:
Uncompiled files (ie. text)
compiled files
That is running:
% what *
will apply to all files. grep(1) here would't work for binary files.
What suprises me, is that debian community doesn't know about the what(1)
utility. As Mark demonstrates:
Get /pub/debian/dists/slink/Contents-i386.gz
zgrep '/what[^a-z._-]'
Think "Oh, it printed nothing,
I think he means
zgrep "@\(#\)"
Anyway, I have been using the RCS identifier ident(1) syntax to se aside
"named-tags" to my files.
(notice that the RCS man page only lists certain keywords, but the
ident(1) actually prints anything marked with $Keyword: $ syntax)
$KeyWordHere: $
In addition I've been using the what(1) syntax:
@(#) Description string follows here
@(#) Description string follows here
Both to document an essential parts of my programs of text files
to give and overview of the files. It's like running
% files *
But in a little more verbose manner especially if you want to check the
version numbers and get brief overviiew about the content of the files. Eg.
My programil server can throw
% what *
on a directory and return a brief overview of included files in the
ftp-by-mail server directory to the recipient.
A typical lines which I use inside all my program files include:
csh-script, Perl, Procmail, anything that has # comment delimeter
# @(#) filename.csh -- One line decription string
# @(#) $Id$ <-- RCS or CVS id expanded
Emacs lisp
;; @(#) filename.el -- One line decription string
;; @(#) $Id$ <-- RCS or CVS id expanded
C++
// @(#) filename.cc -- One line decription string
// @(#) $Id$ <-- RCS or CVS id expanded
etc.
This gives uniform layout for all the files and it also gives
consistent one "quick view" window to all information that you need at
a glance (or head -5). A more fuller docs follows usually after these
lines. (Usually formatted according to TF. It can be ripped away and
converted to html easily. See http://poboxes.com/jari.aalto/t2html.html)
A live example how any program's documentation can be easily ripped
away from source files and turned into nice looking html can be found
from my procmail pages (see module descriptions at www.procmail.org)
and from my Emacs Tiny Tools project pages
(at http://poboxes.com/jari.aalto/ema-tiny.html)
For me, I have found "tagging" and "marking" the files this manner very
helpful and improving the documentation.
jari
> Actually what motivated my question was the advocacy of the procmailer
> Jari Aalto: please see his http://www.procmail.org/jari/pm-tips.html
> (`pm' here and below is for `procmail'),
> in particular, its
> 1.1 for its examples of the `@(#)' identifier (in addition to the normative
> RCS `$...$'), and
> 1.5 for its explicit advocacy of the `what' program, *in-addition-to*
> the RCS `ident' program
>
> To provide a self-contained reference for what we are talking about,
> here are excerpts from the text version `pm-tips.txt' of the html page,
> first for 1.1:
> .@(#) $Id: pm-tips.txt,v 1.74 1999/04/23 14:45:05 jaalto Exp $
> .$Keywords: procmail sendmail formail mail UBE UCE spam filter $
> .$URL: http://www.procmail.org/jari/ $
> .$Contactid: <jari.aalto@poboxes.com> $
> .$FileServer: send mail to Contactid with subject "send help" $
> .$UrlLinksLastChecked: 1999-04-30 $
> .@(#) This is a procmail tips page: a collection of procmail recipes,
> .@(#) instructions, howtos. The document also contains URL pointers to
> .@(#) the procmail mailing list and sites that fight against Internet
> .@(#) UBE. You will also find many other interesting subjects that
> .@(#) discuss about internet email: headers, mime and RFCs. There is
>
> then for 1.5:
> Please also familiarise yourself to unix what(1) and GNU RCS
> ident(1), if you have those commands in your system. It is
> important that you mark interesting text to these tools so that
> someone can get an overview of your supplied files
> % what FILES - Print @( # ) tags
> % ident FILES - Print $ $ keywords
>
> Further, if one retrieves his file pm-code.zip, one finds nearly 50
> source files commented using these conventions.
>
> Given this extensive use of `unix what(1)', and wondering how much else code
> is out there documented in a similar fashion,
> I think it is a reasonable question to ask what is the `open source status'
> of a tool to take advantage of those documentation conventions.
>
> As to whatis, whatis is to "display manual page descriptions" according to
> its man page, thus something from what Jari is requiring.
> As to grep, I suppose grep can do something reasonable in this regard,
> but in consideration of how long grep has been around, I suspect `what'
> must have had some added value to make it worth having an independent
> existence.
>
> Clearly this isn't the most critical lacuna for debian, or for anyone else,
> but I thought it might be worth bringing up. Thank you for your time.
>
> Keith
Reply to: