Path: utzoo!attcan!uunet!munnari!moncskermit!goanna!yabbie!koel!cit5!olympic!jim!brw
From: brw@jim.odr.oz (Brian Wallis)
Newsgroups: comp.emacs
Subject: Re: GNU Emacs Lisp Documentation
Keywords: emacs documentation
Message-ID: <516@jim.odr.oz>
Date: 5 Jul 88 03:23:31 GMT
References: <269@laic.UUCP>
Organization: O'Dowd Research Pty. Ltd., Melbourne, Australia.
Lines: 346
From article <269@laic.UUCP>, by eric@nova.laic.uucp (Eric A. Raymond):
> Has there ever been any documentation published about the Lisp used in
> GNU Emacs. The GNU Emacs doc sez that a Lisp manual will be available
> real soon now. I suppose were stuck with apropos until then.
>
> Eric A. Raymond - ...ucbvax!sun!sunncal!leadsv!laic!eric
Jon Wells and I wrote a function that extracts documentation strings
from emacs and produces a latex file of that including a table of
contents and index on key words. I have found this an invaluable
reference, particularly the index when looking for that function that
you can't quit remember the name of...
The document is formated to fill as much of an A4 page as possible and
should be printed double sided.
NOTE: this has only been tested with Emacs 17.49, which is all we have
for now.
-------------------------------- Cut Here --------------------------------
#!/bin/sh
# shar: Shell Archiver (v1.22)
# Packed Tue Jul 5 13:19:44 EST 1988 by jim!brw
# from directory /usr/brw/src/emacs/lisp
#
# Run the following text with /bin/sh to create:
# README
# gendoc.el
# makeindex
#
if test -f README; then echo "File README exists"; else
echo "x - extracting README (Text)"
sed 's/^X//' << 'SHAR_EOF' > README &&
X
XExtracting emacs lisp function and variable documentation.
X
XThere are two files included here gendoc.el, the lisp to extract the
Xdocumentation strings and Makeindex a shell script which uses perl 1.0
X(patch level 29) to sort the index.
X
XTo extract the basic emacs lisp documentation run emacs in batch mode
Xthus:
X
X42% emacs -batch -l gendoc.el -f make-documentation -kill
X
X(this will take about 15 minutes)
X
XIf you run make-documentation interactively you may get extra
Xfunctions loaded by your .emacs or by any commands you have run before
Xmake-documentation, which you may want. The above command will give
Xthe documentation for the basic set of lisp functions in your emacs.
XThis will produce two files 'doc-info.tex' and 'doc-info.sty'.
X'doc-info.tex' is about 340K with emacs 17.49.
X
XNext, latex the file 'doc-info.tex' _TWICE_ so that the size of the
Xtable of contents is taken into account in the index and in the table
Xof contents. (I suppose I could number the table of contents i, ii,
Xetc.) The latex will produce LOTS of underfull hbox messages, nothing
Xto worry about! Then run makeindex to produce doc-info.ind from
Xdoc-info.idx and run latex on doc-info.tex one more time!
X
XYou will now have a dvi file suitable for printing on A4 paper (about
X40 sheets double sided). You will have to adjust the lisp that
Xgenerates doc-info.sty for other paper sizes.
X
XWritten by Jon Wells originally, index added and latex format changed
Xby B.Wallis.
SHAR_EOF
chmod 0640 README || echo "restore of README fails"
set `wc -c README`;Sum=$1
if test "$Sum" != "1452"
then echo original size 1452, current size $Sum;fi
fi
if test -f gendoc.el; then echo "File gendoc.el exists"; else
echo "x - extracting gendoc.el (Text)"
sed 's/^X//' << 'SHAR_EOF' > gendoc.el &&
X(defun caseless-string< (arg1 arg2) "GENDOC"
X (string< (downcase arg1) (downcase arg2)))
X
X(defun make-documentation () "GENDOC"
X (interactive nil)
X (let ((functions
X (progn
X (message "sorting functions...")
X (sort (all-completions "" obarray 'fboundp ) 'caseless-string<)))
X (variables
X (progn
X (message "sorting variables...")
X (sort (all-completions "" obarray 'boundp ) 'caseless-string<))))
X (get-buffer-create "doc-info.tex")
X (with-output-to-temp-buffer "doc-info.tex"
X (switch-to-buffer "doc-info.tex")
X (erase-buffer)
X (message "%s" "generating function info")
X (insert "\\documentstyle[twoside,twocolumn,doc-info]{article}
X\\makeindex
X\\title{Emacs Variables and Functions\\\\" (emacs-version) "}
X\\author{gendoc.el}
X\\begin{document}
X\\maketitle
X\\clearpage
X\\footnotesize
X\\tableofcontents
X\\clearpage
X\\sloppy
X
X\\section{Functions}
X")
X (while functions
X (if (car functions)
X (print-doc (car functions)))
X (setq functions (cdr functions)))
X (terpri)
X (insert "
X\\newpage
X
X\\index{-----}
X
X\\section{Variables}
X")
X (message "%s" "generating variable info")
X (while variables
X (if (car variables)
X (print-var-doc (car variables)))
X (setq variables (cdr variables)))
X (insert "
X\\input{doc-info.ind}
X
X\\end{document}
X")
X (message "%s" "running replace-regexp")
X (goto-char 1)
X (while (re-search-forward
X "^\\\\\\(subsection\\|index\\){.*[$%<>].*$" nil t)
X (save-restriction
X (narrow-to-region (match-beginning 0) (match-end 0))
X (replace-string "$" "\\$")(goto-char (point-min))
X (replace-string "%" "\\%")(goto-char (point-min))
X (replace-string ">" "$>$")(goto-char (point-min))
X (replace-string "<" "$<$"))
X (goto-char (match-end 0)))
X (write-file "doc-info.tex")
X;;
X;; create a file doc-info.sty for our latex option `doc-info' which gives a bit
X;; more room for the `section.subsection' number before the text of
X;; the section heading in the index. When we had `x.xxx' the text
X;; was hard up against the last number. We changed the 2.3em to 2.8em
X;; for extra space.
X;; Also set the margins to mostly fill an A4 page.
X;;
X (get-buffer-create "doc-info.sty")
X (with-output-to-temp-buffer "doc-info.sty"
X (switch-to-buffer "doc-info.sty")
X (erase-buffer)
X (insert "\\def\\l@subsection{\\@dottedtocline{2}{1.5em}{2.8em}}
X\\oddsidemargin -16pt
X\\evensidemargin -36pt
X\\topmargin -60pt
X\\textheight 707pt
X\\textwidth 500pt
X")
X (write-file "doc-info.sty")))))
X
X
X(defun print-doc (func) "GENDOC"
X (interactive nil)
X (let ((Func (intern func)))
X (let ((doc-str (documentation Func)))
X (if (equal doc-str "GENDOC")
X (message "Discarding Function %s..." func)
X (message "Function %s..." func)
X (insert "\\subsection{" func "}
X")
X (index-entry func)
X (insert "
X\\begin{verbatim}
X")
X (if (setq keys (where-is-internal Func))
X (let ((next-key (car keys)))
X (insert "Key-Mapping: ")
X (while next-key
X (insert " `" (key-description next-key) "'")
X (setq next-key (car (setq keys (cdr keys)))))
X (insert "
X
X")))
X (insert
X (if doc-str
X (if (equal doc-str "")
X "I don't know about this one"
X doc-str)
X "undocumented")
X "
X\\end{verbatim}
X
X")
X nil))))
X
X(defun pretty-string (str) "GENDOC"
X (let ((newstr "")(a 0)(len (length str)))
X (while (/= len a)
X (setq newstr (concat
X newstr
X (text-char-description
X (string-to-char (substring str a (1+ a))))))
X (setq a (1+ a)))
X newstr))
X
X(defun print-var-doc (var) "GENDOC"
X (interactive nil)
X (let ((Var (intern var)))
X (let ((doc-str (substitute-command-keys
X (get Var 'variable-documentation))))
X (message "Variable %s..." var)
X (insert "\\subsection{" var "}
X")
X (index-entry var)
X (insert "
X\\begin{verbatim}
XValue: "
X (let ((valstr (prin1-to-string (eval Var))))
X (if (> (length valstr) 100)
X "..."
X (pretty-string valstr))) "
X
X"
X (if doc-str
X (if (equal doc-str "")
X "I don't know about this one!"
X doc-str)
X "variable not documented.")
X "
X\\end{verbatim}
X
X")
X nil)))
X
X(defun index-entry (name) "GENDOC"
X (interactive nil)
X;;
X;; do a couple of special cases first
X;;
X (if (or (string-equal name "1-") (string-equal name "-"))
X (insert "\\index{" name " " name "}
X")
X;;
X;; OK general case of "xx-yy" ignore trailing '-'s and double '--'s
X;; and produce index entries for 'xx' and 'yy'.
X;;
X (let ((func-name name) end)
X (while (and func-name (> (length func-name) 0))
X (if (not (setq end (string-match "-" func-name)))
X (setq end (length func-name)))
X (if (not (= 0 (length (setq substr (substring func-name 0 end)))))
X (insert "\\index{" substr " " name "}
X"))
X (setq func-name (if (not (= end (length func-name)))
X (substring func-name (1+ end) nil)))))))
SHAR_EOF
chmod 0640 gendoc.el || echo "restore of gendoc.el fails"
set `wc -c gendoc.el`;Sum=$1
if test "$Sum" != "4817"
then echo original size 4817, current size $Sum;fi
fi
if test -f makeindex; then echo "File makeindex exists"; else
echo "x - extracting makeindex (Text)"
sed 's/^X//' << 'SHAR_EOF' > makeindex &&
X#!/bin/sh
X
Xif ( [ ! \( $# -eq 1 -o $# -eq 2 \) ] ) then
X echo Usage: $0 \<\'.idx\' filename\>
X exit 1;
Xfi
Xif ( [ ! -r $1 ] ) then
X echo Can\'t open \"$1\"
X exit 1
Xfi
XDEST=''
Xif ( [ $# -eq 2 ] ) then
X if ( [ $1 = $2 ] ) then
X echo Infile \"$1\" and Outfile \"$2\" can\'t be the same
X exit 1
X fi
X if ( touch $2 ) then
X echo -n
X else
X echo Can\'t write \"$2\"
X exit 1
X fi
X DEST=$2
Xfi
X
X
Xperl \
X-e '$varpage = 0;' \
X-e 'while(<>) {' \
X-e ' if(/\\indexentry{-----}{(.*)}$/) {' \
X-e ' $varpage = $1;' \
X-e ' next;' \
X-e ' }' \
X-e ' elsif($varpage == 0) {' \
X-e ' if(! s/^\\indexentry{((.).*) (..*)}{([0-9]+)}$/$2:$1:$3:$4:B/) {' \
X-e ' next;' \
X-e ' }' \
X-e ' }' \
X-e ' else {' \
X-e ' if(! s/^\\indexentry{((.).*) (..*)}{([0-9]+)}$/$2:$1:$3:$4:I/) {' \
X-e ' next;' \
X-e ' }' \
X-e ' }' \
X-e ' s/^\\:(.(.))/$2:$1/;' \
X-e ' print;' \
X-e '}' $1 \
X| sort -u -t: +1f -2 +1 -2 +2f -3 +2 -3 +3n -4 | perl \
X-e '$cur_topic = 0;' \
X-e 'print "\\begin{theindex}";' \
X-e 'while() {' \
X-e ' chop;' \
X-e ' if(! /^(.):(.+):(.+):(.+):(.)$/) {die "bad file after sort, line \"$_\"";}' \
X-e ' $F1 = $1; $F2 = $2; $F3 = $3; $F4 = $4; $F5 = $5;' \
X-e ' if($cur_topic eq $F2) {' \
X-e ' printf "\\subitem %s {\\dotfill\\%s %s}\n",$F3,($F5 eq "B")?"bf":"em",$F4;' \
X-e ' }' \
X-e ' else {' \
X-e ' print "\n";' \
X-e ' if(($F1 =~ /^[a-zA-Z]/ || $cur_topic =~ /^[a-zA-Z]/) &&' \
X-e ' $cur_topic !~ /^$F1/i) {' \
X-e ' print "\\indexspace\n";' \
X-e ' }' \
X-e ' printf "\\item %s\n",$F2;' \
X-e ' printf "\\subitem %s {\\dotfill\\%s %s}\n",$F3,($F5 eq "B")?"bf":"em",$F4;' \
X-e ' $cur_topic = $F2;' \
X-e ' }' \
X-e '}' \
X-e 'print "\n\\end{theindex}\n";' > $DEST
SHAR_EOF
chmod 0750 makeindex || echo "restore of makeindex fails"
set `wc -c makeindex`;Sum=$1
if test "$Sum" != "1732"
then echo original size 1732, current size $Sum;fi
fi
exit 0
--
Brian Wallis (brw@jim.odr.oz) O'Dowd Research P/L.
(03) 562-0100 Fax: (03) 562-0616,
Telex: Jacobs Radio (Bayswater) 152093