| blob | 1b4a676eb531f4d0cc28b20ec6e73d086bdfe20d |
1 ;; texi-docstring-magic.el -- munge internal docstrings into texi
2 ;;
3 ;; Keywords: lisp, docs, tex
4 ;; Author: David Aspinall <da@dcs.ed.ac.uk>
5 ;; Copyright (C) 1998 David Aspinall
6 ;; Maintainer: David Aspinall <da@dcs.ed.ac.uk>
7 ;;
8 ;; Id: texi-docstring-magic.el,v 1.2 2004/04/11 17:56:47 karl Exp
9 ;;
10 ;; This package is distributed under the terms of the
11 ;; GNU General Public License, Version 2.
12 ;; You should have a copy of the GPL with your version of
13 ;; GNU Emacs or the Texinfo distribution.
14 ;;
15 ;;
16 ;; This package generates Texinfo source fragments from Emacs
17 ;; docstrings. This avoids documenting functions and variables
18 ;; in more than one place, and automatically adds Texinfo markup
19 ;; to docstrings.
20 ;;
21 ;; It relies heavily on you following the Elisp documentation
22 ;; conventions to produce sensible output, check the Elisp manual
23 ;; for details. In brief:
24 ;;
25 ;; * The first line of a docstring should be a complete sentence.
26 ;; * Arguments to functions should be written in upper case: ARG1..ARGN
27 ;; * User options (variables users may want to set) should have docstrings
28 ;; beginning with an asterisk.
29 ;;
30 ;; Usage:
31 ;;
32 ;; Write comments of the form:
33 ;;
34 ;; @c TEXI DOCSTRING MAGIC: my-package-function-or-variable-name
35 ;;
36 ;; In your texi source, mypackage.texi. From within an Emacs session
37 ;; where my-package is loaded, visit mypackage.texi and run
38 ;; M-x texi-docstring-magic to update all of the documentation strings.
39 ;;
40 ;; This will insert @defopt, @deffn and the like underneath the
41 ;; magic comment strings.
42 ;;
43 ;; The default value for user options will be printed.
44 ;;
45 ;; Symbols are recognized if they are defined for faces, functions,
46 ;; or variables (in that order).
47 ;;
48 ;; Automatic markup rules:
49 ;;
50 ;; 1. Indented lines are gathered into @lisp environment.
51 ;; 2. Pieces of text `stuff' or surrounded in quotes marked up with @samp.
52 ;; 3. Words *emphasized* are made @strong{emphasized}
53 ;; 4. Words sym-bol which are symbols become @code{sym-bol}.
54 ;; 5. Upper cased words ARG corresponding to arguments become @var{arg}.
55 ;; In fact, you can any word longer than three letters, so that
56 ;; metavariables can be used easily.
57 ;; FIXME: to escape this, use `ARG'
58 ;; 6. Words 'sym which are lisp-quoted are marked with @code{'sym}.
59 ;;
60 ;; -----
61 ;;
62 ;; Useful key binding when writing Texinfo:
63 ;;
64 ;; (define-key TeXinfo-mode-map "C-cC-d" 'texi-docstring-magic-insert-magic)
65 ;;
66 ;; -----
67 ;;
68 ;; Useful enhancements to do:
69 ;;
70 ;; * Use customize properties (e.g. group, simple types)
71 ;; * Look for a "texi-docstring" property for symbols
72 ;; so TeXInfo can be defined directly in case automatic markup
73 ;; goes badly wrong.
74 ;; * Add tags to special comments so that user can specify face,
75 ;; function, or variable binding for a symbol in case more than
76 ;; one binding exists.
77 ;;
78 ;; ------
81 "Return concatenation of STRINGS spliced together with separator SEP."
88 str))
93 t
97 ;; whitespace
99 line
102 ;; non-white space
107 line))))
108 ;; 2. Pieces of text `stuff' or surrounded in quotes
109 ;; are marked up with @samp. NB: Must be backquote
110 ;; followed by forward quote for this to work.
111 ;; Can't use two forward quotes else problems with
112 ;; symbols.
113 ;; Odd hack: because ' is a word constituent in text/texinfo
114 ;; mode, putting this first enables the recognition of args
115 ;; and symbols put inside quotes.
117 t
119 ;; 3. Words *emphasized* are made @strong{emphasized}
121 t
123 ;; 4. Words sym-bol which are symbols become @code{sym-bol}.
124 ;; Must have at least one hyphen to be recognized,
125 ;; terminated in whitespace, end of line, or punctuation.
126 ;; (Only consider symbols made from word constituents
127 ;; and hyphen.
133 ;; 5. Upper cased words ARG corresponding to arguments become
134 ;; @var{arg}
135 ;; In fact, include any word so long as it is more than 3 characters
136 ;; long. (Comes after symbols to avoid recognizing the
137 ;; lowercased form of an argument as a symbol)
138 ;; FIXME: maybe we don't want to downcase stuff already
139 ;; inside @samp
140 ;; FIXME: should - terminate? should _ be included?
147 ;; 6. Words 'sym which are lisp quoted are
148 ;; marked with @code.
150 t
154 ;; 7,8. Clean up for @lisp environments left with spurious newlines
155 ;; after 1.
158 "Table of regexp matches and replacements used to markup docstrings.
159 Format of table is a list of elements of the form
160 (regexp predicate replacement-form)
161 If regexp matches and predicate holds, then replacement-form is
162 evaluated to get the replacement for the match.
163 predicate and replacement-form can use variables arg,
164 and forms such as (match-string 1 docstring)
165 Match string 1 is assumed to determine the
166 length of the matched item, hence where parsing restarts from.
167 The replacement must cover the whole match (match string 0),
172 "Markup DOCSTRING for texi according to regexp matches."
179 in-quoted-region)
194 ;; Force a new line after (what should be) the first sentence,
195 ;; if not already a new paragraph.
207 docstring)))
210 "Make a texi def environment ENV for entity NAME with DOCSTRING."
212 " "
214 ;; " "
215 ;; (texi-docstring-magic-splice-sep extras " ")
223 "Make a default value string for the value DEFAULT.
224 Markup as @code{stuff} or @lisp stuff @end lisp."
229 ;; Carriage return will break @code, use @lisp
238 ;; Faces
246 ;; Chop off user option setting
251 ;; Functions.
252 ;; We don't handle macros, aliases, or compiled fns properly.
266 ;; Variables.
277 ;; Chop off user option setting
286 "@c TEXI DOCSTRING MAGIC:"
290 "Update all texi docstring magic annotations in buffer."
297 p
298 symbol)
303 ;; If comment already followed by an environment, delete it.