1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986, 1992 Free Software Foundation, Inc.
4 This file is part of GNU Emacs.
6 GNU Emacs is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Emacs is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Emacs; see the file COPYING. If not, write to
18 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. */
20 /* The arguments given to this program are all the C and Lisp source files
21 of GNU Emacs. .elc and .el and .c files are allowed.
22 A .o file can also be specified; the .c file it was made from is used.
23 This helps the makefile pass the correct list of files.
25 The results, which go to standard output or to a file
26 specified with -a or -o (-a to append, -o to start from nothing),
27 are entries containing function or variable names and their documentation.
28 Each entry starts with a ^_ character.
29 Then comes F for a function or V for a variable.
30 Then comes the function or variable name, terminated with a newline.
31 Then comes the documentation for that function or variable.
47 /* If first two args are -o FILE, output to FILE. */
49 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
51 outfile
= fopen (argv
[i
+ 1], "w");
54 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
56 outfile
= fopen (argv
[i
+ 1], "a");
61 err_count
+= scan_file (argv
[i
]); /* err_count seems to be {mis,un}used */
63 exit (err_count
); /* see below - shane */
67 /* Read file FILENAME and output its doc strings to outfile. */
68 /* Return 1 if file is not found, 0 if it is found. */
73 int len
= strlen (filename
);
74 if (!strcmp (filename
+ len
- 4, ".elc"))
75 return scan_lisp_file (filename
);
76 else if (!strcmp (filename
+ len
- 3, ".el"))
77 return scan_lisp_file (filename
);
79 return scan_c_file (filename
);
84 /* Skip a C string from INFILE,
85 and return the character that follows the closing ".
86 If printflag is positive, output string contents to outfile.
87 If it is negative, store contents in buf.
88 Convert escape sequences \n and \t to newline and tab;
89 discard \ followed by newline. */
91 read_c_string (infile
, printflag
)
101 while (c
!= '"' && c
!= EOF
)
118 else if (printflag
< 0)
127 else if (printflag
< 0)
138 /* Write to file OUT the argument names of the function whose text is in BUF.
139 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
141 write_c_args (out
, buf
, minargs
, maxargs
)
144 int minargs
, maxargs
;
150 fprintf (out
, "arguments: ");
152 for (p
= buf
; *p
; p
++)
156 /* Notice when we start printing a new identifier. */
157 if ((('A' <= c
&& c
<= 'Z')
158 || ('a' <= c
&& c
<= 'z')
159 || ('0' <= c
&& c
<= '9')
167 if (minargs
== 0 && maxargs
> 0)
168 fprintf (out
, "&optional ");
178 /* Print the C argument list as it would appear in lisp:
179 print underscores as hyphens, and print commas as spaces.
180 Collapse adjacent spaces into one. */
181 if (c
== '_') c
= '-';
182 if (c
== ',') c
= ' ';
184 if (c
!= ' ' || ! just_spaced
)
187 just_spaced
= (c
== ' ');
191 /* Read through a c file. If a .o file is named,
192 the corresponding .c file is read instead.
193 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
194 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
196 scan_c_file (filename
)
202 register int defunflag
;
203 register int defvarflag
;
204 int minargs
, maxargs
;
206 if (filename
[strlen (filename
) - 1] == 'o')
207 filename
[strlen (filename
) - 1] = 'c';
209 infile
= fopen (filename
, "r");
211 /* No error if non-ex input file */
219 while (!feof (infile
))
255 defunflag
= c
== 'U';
270 c
= read_c_string (infile
, -1);
276 else /* For DEFSIMPLE and DEFPRED */
284 if (defunflag
&& (commas
== 1 || commas
== 2))
288 while (c
== ' ' || c
== '\n' || c
== '\t');
292 if (commas
== 2) /* pick up minargs */
293 fscanf (infile
, "%d", &minargs
);
294 else /* pick up maxargs */
295 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
298 fscanf (infile
, "%d", &maxargs
);
305 while (c
== ' ' || c
== '\n' || c
== '\t')
308 c
= read_c_string (infile
, 0);
312 while (c
== ' ' || c
== '\n' || c
== '\t')
318 putc (defvarflag
? 'V' : 'F', outfile
);
319 fprintf (outfile
, "%s\n", buf
);
320 c
= read_c_string (infile
, 1);
322 /* If this is a defun, find the arguments and print them. If
323 this function takes MANY or UNEVALLED args, then the C source
324 won't give the names of the arguments, so we shouldn't bother
325 trying to find them. */
326 if (defunflag
&& maxargs
!= -1)
328 char argbuf
[1024], *p
= argbuf
;
335 /* Skip into arguments. */
342 /* Copy arguments into ARGBUF. */
345 *p
++ = c
= getc (infile
);
349 fprintf (outfile
, "\n\n");
350 write_c_args (outfile
, argbuf
, minargs
, maxargs
);
359 /* Read a file of Lisp code, compiled or interpreted.
361 (defun NAME ARGS DOCSTRING ...)
362 (defmacro NAME ARGS DOCSTRING ...)
363 (autoload (quote NAME) FILE DOCSTRING ...)
364 (defvar NAME VALUE DOCSTRING)
365 (defconst NAME VALUE DOCSTRING)
366 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
367 (fset (quote NAME) #[... DOCSTRING ...])
368 starting in column zero.
369 (quote NAME) may appear as 'NAME as well.
370 For defun, defmacro, and autoload, we know how to skip over the arglist.
371 For defvar, defconst, and fset we skip to the docstring with a klugey
372 formatting convention: all docstrings must appear on the same line as the
373 initial open-paren (the one in column zero) and must contain a backslash
374 and a double-quote immediately after the initial double-quote. No newlines
375 must appear between the beginning of the form and the first double-quote.
376 The only source file that must follow this convention is loaddefs.el; aside
377 from that, it is always the .elc file that we look at, and they are no
378 problem because byte-compiler output follows this convention.
379 The NAME and DOCSTRING are output.
380 NAME is preceded by `F' for a function or `V' for a variable.
381 An entry is output only if DOCSTRING has \ newline just after the opening "
389 while (c
== ' ' || c
== '\t' || c
== '\n')
395 read_lisp_symbol (infile
, buffer
)
400 char *fillp
= buffer
;
407 *(++fillp
) = getc (infile
);
408 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '(' || c
== ')')
419 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
425 scan_lisp_file (filename
)
431 infile
= fopen (filename
, "r");
435 return 0; /* No error */
439 while (!feof (infile
))
441 char buffer
[BUFSIZ
];
442 char *fillp
= buffer
;
454 read_lisp_symbol (infile
, buffer
);
456 if (! strcmp (buffer
, "defun") ||
457 ! strcmp (buffer
, "defmacro"))
460 read_lisp_symbol (infile
, buffer
);
462 /* Skip the arguments: either "nil" or a list in parens */
465 if (c
== 'n') /* nil */
467 if ((c
= getc (infile
)) != 'i' ||
468 (c
= getc (infile
)) != 'l')
470 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
477 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
486 /* If the next three characters aren't `dquote bslash newline'
487 then we're not reading a docstring.
489 if ((c
= getc (infile
)) != '"' ||
490 (c
= getc (infile
)) != '\\' ||
491 (c
= getc (infile
)) != '\n')
494 fprintf (stderr
, "## non-docstring in %s (%s)\n",
501 else if (! strcmp (buffer
, "defvar") ||
502 ! strcmp (buffer
, "defconst"))
506 read_lisp_symbol (infile
, buffer
);
508 /* Skip until the first newline; remember the two previous chars. */
509 while (c
!= '\n' && c
>= 0)
516 /* If two previous characters were " and \,
517 this is a doc string. Otherwise, there is none. */
518 if (c2
!= '"' || c1
!= '\\')
521 fprintf (stderr
, "## non-docstring in %s (%s)\n",
528 else if (! strcmp (buffer
, "fset"))
535 read_lisp_symbol (infile
, buffer
);
540 fprintf (stderr
, "## unparsable name in fset in %s\n",
544 read_lisp_symbol (infile
, buffer
);
545 if (strcmp (buffer
, "quote"))
547 fprintf (stderr
, "## unparsable name in fset in %s\n",
551 read_lisp_symbol (infile
, buffer
);
556 "## unparsable quoted name in fset in %s\n",
562 /* Skip until the first newline; remember the two previous chars. */
563 while (c
!= '\n' && c
>= 0)
570 /* If two previous characters were " and \,
571 this is a doc string. Otherwise, there is none. */
572 if (c2
!= '"' || c1
!= '\\')
575 fprintf (stderr
, "## non-docstring in %s (%s)\n",
582 else if (! strcmp (buffer
, "autoload"))
587 read_lisp_symbol (infile
, buffer
);
592 fprintf (stderr
, "## unparsable name in autoload in %s\n",
596 read_lisp_symbol (infile
, buffer
);
597 if (strcmp (buffer
, "quote"))
599 fprintf (stderr
, "## unparsable name in autoload in %s\n",
603 read_lisp_symbol (infile
, buffer
);
608 "## unparsable quoted name in autoload in %s\n",
614 if ((c
= getc (infile
)) != '\"')
616 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
620 read_c_string (infile
, 0);
623 /* If the next three characters aren't `dquote bslash newline'
624 then we're not reading a docstring.
626 if ((c
= getc (infile
)) != '"' ||
627 (c
= getc (infile
)) != '\\' ||
628 (c
= getc (infile
)) != '\n')
631 fprintf (stderr
, "## non-docstring in %s (%s)\n",
639 else if (! strcmp (buffer
, "if") ||
640 ! strcmp (buffer
, "byte-code"))
647 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
653 /* At this point, there is a docstring that we should gobble.
654 The opening quote (and leading backslash-newline) have already
657 putc ('\n', outfile
);
659 putc (type
, outfile
);
660 fprintf (outfile
, "%s\n", buffer
);
661 read_c_string (infile
, 1);