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");
59 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
66 err_count
+= scan_file (argv
[i
]); /* err_count seems to be {mis,un}used */
68 exit (err_count
); /* see below - shane */
72 /* Read file FILENAME and output its doc strings to outfile. */
73 /* Return 1 if file is not found, 0 if it is found. */
78 int len
= strlen (filename
);
79 if (!strcmp (filename
+ len
- 4, ".elc"))
80 return scan_lisp_file (filename
);
81 else if (!strcmp (filename
+ len
- 3, ".el"))
82 return scan_lisp_file (filename
);
84 return scan_c_file (filename
);
89 /* Skip a C string from INFILE,
90 and return the character that follows the closing ".
91 If printflag is positive, output string contents to outfile.
92 If it is negative, store contents in buf.
93 Convert escape sequences \n and \t to newline and tab;
94 discard \ followed by newline. */
96 read_c_string (infile
, printflag
)
106 while (c
!= '"' && c
!= EOF
)
123 else if (printflag
< 0)
130 /* If we had a "", concatenate the two strings. */
140 /* Write to file OUT the argument names of the function whose text is in BUF.
141 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
143 write_c_args (out
, buf
, minargs
, maxargs
)
146 int minargs
, maxargs
;
152 fprintf (out
, "arguments: ");
154 for (p
= buf
; *p
; p
++)
159 /* Notice when we start printing a new identifier. */
160 if ((('A' <= c
&& c
<= 'Z')
161 || ('a' <= c
&& c
<= 'z')
162 || ('0' <= c
&& c
<= '9')
171 if (minargs
== 0 && maxargs
> 0)
172 fprintf (out
, "&optional ");
182 /* Print the C argument list as it would appear in lisp:
183 print underscores as hyphens, and print commas as spaces.
184 Collapse adjacent spaces into one. */
185 if (c
== '_') c
= '-';
186 if (c
== ',') c
= ' ';
188 /* In C code, `default' is a reserved word, so we spell it
189 `defalt'; unmangle that here. */
191 && strncmp (p
, "defalt", 6) == 0
192 && ! (('A' <= p
[6] && p
[6] <= 'Z')
193 || ('a' <= p
[6] && p
[6] <= 'z')
194 || ('0' <= p
[6] && p
[6] <= '9')
197 fprintf (out
, "default");
202 else if (c
!= ' ' || ! just_spaced
)
205 just_spaced
= (c
== ' ');
209 /* Read through a c file. If a .o file is named,
210 the corresponding .c file is read instead.
211 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
212 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
214 scan_c_file (filename
)
220 register int defunflag
;
221 register int defvarperbufferflag
;
222 register int defvarflag
;
223 int minargs
, maxargs
;
225 if (filename
[strlen (filename
) - 1] == 'o')
226 filename
[strlen (filename
) - 1] = 'c';
228 infile
= fopen (filename
, "r");
230 /* No error if non-ex input file */
238 while (!feof (infile
))
275 defvarperbufferflag
= (c
== 'P');
288 defunflag
= c
== 'U';
303 c
= read_c_string (infile
, -1);
307 else if (defvarperbufferflag
)
311 else /* For DEFSIMPLE and DEFPRED */
319 if (defunflag
&& (commas
== 1 || commas
== 2))
323 while (c
== ' ' || c
== '\n' || c
== '\t');
327 if (commas
== 2) /* pick up minargs */
328 fscanf (infile
, "%d", &minargs
);
329 else /* pick up maxargs */
330 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
333 fscanf (infile
, "%d", &maxargs
);
340 while (c
== ' ' || c
== '\n' || c
== '\t')
343 c
= read_c_string (infile
, 0);
347 while (c
== ' ' || c
== '\n' || c
== '\t')
353 putc (defvarflag
? 'V' : 'F', outfile
);
354 fprintf (outfile
, "%s\n", buf
);
355 c
= read_c_string (infile
, 1);
357 /* If this is a defun, find the arguments and print them. If
358 this function takes MANY or UNEVALLED args, then the C source
359 won't give the names of the arguments, so we shouldn't bother
360 trying to find them. */
361 if (defunflag
&& maxargs
!= -1)
363 char argbuf
[1024], *p
= argbuf
;
370 /* Skip into arguments. */
377 /* Copy arguments into ARGBUF. */
380 *p
++ = c
= getc (infile
);
384 fprintf (outfile
, "\n\n");
385 write_c_args (outfile
, argbuf
, minargs
, maxargs
);
394 /* Read a file of Lisp code, compiled or interpreted.
396 (defun NAME ARGS DOCSTRING ...)
397 (defmacro NAME ARGS DOCSTRING ...)
398 (autoload (quote NAME) FILE DOCSTRING ...)
399 (defvar NAME VALUE DOCSTRING)
400 (defconst NAME VALUE DOCSTRING)
401 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
402 (fset (quote NAME) #[... DOCSTRING ...])
403 (defalias (quote NAME) #[... DOCSTRING ...])
404 starting in column zero.
405 (quote NAME) may appear as 'NAME as well.
406 For defun, defmacro, and autoload, we know how to skip over the arglist.
407 For defvar, defconst, and fset we skip to the docstring with a kludgy
408 formatting convention: all docstrings must appear on the same line as the
409 initial open-paren (the one in column zero) and must contain a backslash
410 and a double-quote immediately after the initial double-quote. No newlines
411 must appear between the beginning of the form and the first double-quote.
412 The only source file that must follow this convention is loaddefs.el; aside
413 from that, it is always the .elc file that we look at, and they are no
414 problem because byte-compiler output follows this convention.
415 The NAME and DOCSTRING are output.
416 NAME is preceded by `F' for a function or `V' for a variable.
417 An entry is output only if DOCSTRING has \ newline just after the opening "
425 while (c
== ' ' || c
== '\t' || c
== '\n')
431 read_lisp_symbol (infile
, buffer
)
436 char *fillp
= buffer
;
443 *(++fillp
) = getc (infile
);
444 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '(' || c
== ')')
455 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
461 scan_lisp_file (filename
)
467 infile
= fopen (filename
, "r");
471 return 0; /* No error */
475 while (!feof (infile
))
477 char buffer
[BUFSIZ
];
478 char *fillp
= buffer
;
490 read_lisp_symbol (infile
, buffer
);
492 if (! strcmp (buffer
, "defun") ||
493 ! strcmp (buffer
, "defmacro"))
496 read_lisp_symbol (infile
, buffer
);
498 /* Skip the arguments: either "nil" or a list in parens */
501 if (c
== 'n') /* nil */
503 if ((c
= getc (infile
)) != 'i' ||
504 (c
= getc (infile
)) != 'l')
506 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
513 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
522 /* If the next three characters aren't `dquote bslash newline'
523 then we're not reading a docstring.
525 if ((c
= getc (infile
)) != '"' ||
526 (c
= getc (infile
)) != '\\' ||
527 (c
= getc (infile
)) != '\n')
530 fprintf (stderr
, "## non-docstring in %s (%s)\n",
537 else if (! strcmp (buffer
, "defvar") ||
538 ! strcmp (buffer
, "defconst"))
542 read_lisp_symbol (infile
, buffer
);
544 /* Skip until the first newline; remember the two previous chars. */
545 while (c
!= '\n' && c
>= 0)
552 /* If two previous characters were " and \,
553 this is a doc string. Otherwise, there is none. */
554 if (c2
!= '"' || c1
!= '\\')
557 fprintf (stderr
, "## non-docstring in %s (%s)\n",
564 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
571 read_lisp_symbol (infile
, buffer
);
576 fprintf (stderr
, "## unparsable name in fset in %s\n",
580 read_lisp_symbol (infile
, buffer
);
581 if (strcmp (buffer
, "quote"))
583 fprintf (stderr
, "## unparsable name in fset in %s\n",
587 read_lisp_symbol (infile
, buffer
);
592 "## unparsable quoted name in fset in %s\n",
598 /* Skip until the first newline; remember the two previous chars. */
599 while (c
!= '\n' && c
>= 0)
606 /* If two previous characters were " and \,
607 this is a doc string. Otherwise, there is none. */
608 if (c2
!= '"' || c1
!= '\\')
611 fprintf (stderr
, "## non-docstring in %s (%s)\n",
618 else if (! strcmp (buffer
, "autoload"))
623 read_lisp_symbol (infile
, buffer
);
628 fprintf (stderr
, "## unparsable name in autoload in %s\n",
632 read_lisp_symbol (infile
, buffer
);
633 if (strcmp (buffer
, "quote"))
635 fprintf (stderr
, "## unparsable name in autoload in %s\n",
639 read_lisp_symbol (infile
, buffer
);
644 "## unparsable quoted name in autoload in %s\n",
650 if ((c
= getc (infile
)) != '\"')
652 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
656 read_c_string (infile
, 0);
659 /* If the next three characters aren't `dquote bslash newline'
660 then we're not reading a docstring.
662 if ((c
= getc (infile
)) != '"' ||
663 (c
= getc (infile
)) != '\\' ||
664 (c
= getc (infile
)) != '\n')
667 fprintf (stderr
, "## non-docstring in %s (%s)\n",
675 else if (! strcmp (buffer
, "if") ||
676 ! strcmp (buffer
, "byte-code"))
683 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
689 /* At this point, there is a docstring that we should gobble.
690 The opening quote (and leading backslash-newline) have already
693 putc ('\n', outfile
);
695 putc (type
, outfile
);
696 fprintf (outfile
, "%s\n", buffer
);
697 read_c_string (infile
, 1);