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)
132 else if (printflag
< 0)
143 /* Write to file OUT the argument names of the function whose text is in BUF.
144 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
146 write_c_args (out
, buf
, minargs
, maxargs
)
149 int minargs
, maxargs
;
155 fprintf (out
, "arguments: ");
157 for (p
= buf
; *p
; p
++)
162 /* Notice when we start printing a new identifier. */
163 if ((('A' <= c
&& c
<= 'Z')
164 || ('a' <= c
&& c
<= 'z')
165 || ('0' <= c
&& c
<= '9')
174 if (minargs
== 0 && maxargs
> 0)
175 fprintf (out
, "&optional ");
185 /* Print the C argument list as it would appear in lisp:
186 print underscores as hyphens, and print commas as spaces.
187 Collapse adjacent spaces into one. */
188 if (c
== '_') c
= '-';
189 if (c
== ',') c
= ' ';
191 /* In C code, `default' is a reserved word, so we spell it
192 `defalt'; unmangle that here. */
194 && strncmp (p
, "defalt", 6) == 0
195 && ! (('A' <= p
[6] && p
[6] <= 'Z')
196 || ('a' <= p
[6] && p
[6] <= 'z')
197 || ('0' <= p
[6] && p
[6] <= '9')
200 fprintf (out
, "default");
205 else if (c
!= ' ' || ! just_spaced
)
208 just_spaced
= (c
== ' ');
212 /* Read through a c file. If a .o file is named,
213 the corresponding .c file is read instead.
214 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
215 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
217 scan_c_file (filename
)
223 register int defunflag
;
224 register int defvarperbufferflag
;
225 register int defvarflag
;
226 int minargs
, maxargs
;
228 if (filename
[strlen (filename
) - 1] == 'o')
229 filename
[strlen (filename
) - 1] = 'c';
231 infile
= fopen (filename
, "r");
233 /* No error if non-ex input file */
241 while (!feof (infile
))
278 defvarperbufferflag
= (c
== 'P');
291 defunflag
= c
== 'U';
306 c
= read_c_string (infile
, -1);
310 else if (defvarperbufferflag
)
314 else /* For DEFSIMPLE and DEFPRED */
322 if (defunflag
&& (commas
== 1 || commas
== 2))
326 while (c
== ' ' || c
== '\n' || c
== '\t');
330 if (commas
== 2) /* pick up minargs */
331 fscanf (infile
, "%d", &minargs
);
332 else /* pick up maxargs */
333 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
336 fscanf (infile
, "%d", &maxargs
);
343 while (c
== ' ' || c
== '\n' || c
== '\t')
346 c
= read_c_string (infile
, 0);
350 while (c
== ' ' || c
== '\n' || c
== '\t')
356 putc (defvarflag
? 'V' : 'F', outfile
);
357 fprintf (outfile
, "%s\n", buf
);
358 c
= read_c_string (infile
, 1);
360 /* If this is a defun, find the arguments and print them. If
361 this function takes MANY or UNEVALLED args, then the C source
362 won't give the names of the arguments, so we shouldn't bother
363 trying to find them. */
364 if (defunflag
&& maxargs
!= -1)
366 char argbuf
[1024], *p
= argbuf
;
373 /* Skip into arguments. */
380 /* Copy arguments into ARGBUF. */
383 *p
++ = c
= getc (infile
);
387 fprintf (outfile
, "\n\n");
388 write_c_args (outfile
, argbuf
, minargs
, maxargs
);
397 /* Read a file of Lisp code, compiled or interpreted.
399 (defun NAME ARGS DOCSTRING ...)
400 (defmacro NAME ARGS DOCSTRING ...)
401 (autoload (quote NAME) FILE DOCSTRING ...)
402 (defvar NAME VALUE DOCSTRING)
403 (defconst NAME VALUE DOCSTRING)
404 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
405 (fset (quote NAME) #[... DOCSTRING ...])
406 (defalias (quote NAME) #[... DOCSTRING ...])
407 starting in column zero.
408 (quote NAME) may appear as 'NAME as well.
409 For defun, defmacro, and autoload, we know how to skip over the arglist.
410 For defvar, defconst, and fset we skip to the docstring with a kludgy
411 formatting convention: all docstrings must appear on the same line as the
412 initial open-paren (the one in column zero) and must contain a backslash
413 and a double-quote immediately after the initial double-quote. No newlines
414 must appear between the beginning of the form and the first double-quote.
415 The only source file that must follow this convention is loaddefs.el; aside
416 from that, it is always the .elc file that we look at, and they are no
417 problem because byte-compiler output follows this convention.
418 The NAME and DOCSTRING are output.
419 NAME is preceded by `F' for a function or `V' for a variable.
420 An entry is output only if DOCSTRING has \ newline just after the opening "
428 while (c
== ' ' || c
== '\t' || c
== '\n')
434 read_lisp_symbol (infile
, buffer
)
439 char *fillp
= buffer
;
446 *(++fillp
) = getc (infile
);
447 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '(' || c
== ')')
458 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
464 scan_lisp_file (filename
)
470 infile
= fopen (filename
, "r");
474 return 0; /* No error */
478 while (!feof (infile
))
480 char buffer
[BUFSIZ
];
481 char *fillp
= buffer
;
493 read_lisp_symbol (infile
, buffer
);
495 if (! strcmp (buffer
, "defun") ||
496 ! strcmp (buffer
, "defmacro"))
499 read_lisp_symbol (infile
, buffer
);
501 /* Skip the arguments: either "nil" or a list in parens */
504 if (c
== 'n') /* nil */
506 if ((c
= getc (infile
)) != 'i' ||
507 (c
= getc (infile
)) != 'l')
509 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
516 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
525 /* If the next three characters aren't `dquote bslash newline'
526 then we're not reading a docstring.
528 if ((c
= getc (infile
)) != '"' ||
529 (c
= getc (infile
)) != '\\' ||
530 (c
= getc (infile
)) != '\n')
533 fprintf (stderr
, "## non-docstring in %s (%s)\n",
540 else if (! strcmp (buffer
, "defvar") ||
541 ! strcmp (buffer
, "defconst"))
545 read_lisp_symbol (infile
, buffer
);
547 /* Skip until the first newline; remember the two previous chars. */
548 while (c
!= '\n' && c
>= 0)
555 /* If two previous characters were " and \,
556 this is a doc string. Otherwise, there is none. */
557 if (c2
!= '"' || c1
!= '\\')
560 fprintf (stderr
, "## non-docstring in %s (%s)\n",
567 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
574 read_lisp_symbol (infile
, buffer
);
579 fprintf (stderr
, "## unparsable name in fset in %s\n",
583 read_lisp_symbol (infile
, buffer
);
584 if (strcmp (buffer
, "quote"))
586 fprintf (stderr
, "## unparsable name in fset in %s\n",
590 read_lisp_symbol (infile
, buffer
);
595 "## unparsable quoted name in fset in %s\n",
601 /* Skip until the first newline; remember the two previous chars. */
602 while (c
!= '\n' && c
>= 0)
609 /* If two previous characters were " and \,
610 this is a doc string. Otherwise, there is none. */
611 if (c2
!= '"' || c1
!= '\\')
614 fprintf (stderr
, "## non-docstring in %s (%s)\n",
621 else if (! strcmp (buffer
, "autoload"))
626 read_lisp_symbol (infile
, buffer
);
631 fprintf (stderr
, "## unparsable name in autoload in %s\n",
635 read_lisp_symbol (infile
, buffer
);
636 if (strcmp (buffer
, "quote"))
638 fprintf (stderr
, "## unparsable name in autoload in %s\n",
642 read_lisp_symbol (infile
, buffer
);
647 "## unparsable quoted name in autoload in %s\n",
653 if ((c
= getc (infile
)) != '\"')
655 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
659 read_c_string (infile
, 0);
662 /* If the next three characters aren't `dquote bslash newline'
663 then we're not reading a docstring.
665 if ((c
= getc (infile
)) != '"' ||
666 (c
= getc (infile
)) != '\\' ||
667 (c
= getc (infile
)) != '\n')
670 fprintf (stderr
, "## non-docstring in %s (%s)\n",
678 else if (! strcmp (buffer
, "if") ||
679 ! strcmp (buffer
, "byte-code"))
686 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
692 /* At this point, there is a docstring that we should gobble.
693 The opening quote (and leading backslash-newline) have already
696 putc ('\n', outfile
);
698 putc (type
, outfile
);
699 fprintf (outfile
, "%s\n", buffer
);
700 read_c_string (infile
, 1);