1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986 Free Software Foundation, Inc.
4 This file is part of GNU Emacs.
6 GNU Emacs is distributed in the hope that it will be useful,
7 but without any warranty. No author or distributor
8 accepts responsibility to anyone for the consequences of using it
9 or for whether it serves any particular purpose or works at all,
10 unless he says so in writing.
12 Everyone is granted permission to copy, modify and redistribute
13 GNU Emacs, but only under the conditions described in the
14 document "GNU Emacs copying permission notice". An exact copy
15 of the document is supposed to have been given to you along with
16 GNU Emacs so that you can know how you may redistribute it all.
17 It should be in a file named COPYING. Among other things, the
18 copyright notice and this notice must be preserved on all copies. */
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 stdout. */
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 stdout.
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
;
147 register char *p
= buf
;
150 fprintf (out
, "arguments:");
161 if (minargs
== 0 && maxargs
> 0)
162 fprintf (out
, "&optional ");
166 else if (c
== ' ' && space
)
174 /* Read through a c file. If a .o file is named,
175 the corresponding .c file is read instead.
176 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
177 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
179 scan_c_file (filename
)
185 register int defunflag
;
186 register int defvarflag
;
187 int minargs
, maxargs
;
189 if (filename
[strlen (filename
) - 1] == 'o')
190 filename
[strlen (filename
) - 1] = 'c';
192 infile
= fopen (filename
, "r");
194 /* No error if non-ex input file */
202 while (!feof (infile
))
238 defunflag
= c
== 'U';
253 c
= read_c_string (infile
, -1);
259 else /* For DEFSIMPLE and DEFPRED */
267 if (defunflag
&& (commas
== 1 || commas
== 2))
271 while (c
== ' ' || c
== '\n' || c
== '\t');
275 if (commas
== 2) /* pick up minargs */
276 fscanf (infile
, "%d", &minargs
);
277 else /* pick up maxargs */
278 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
281 fscanf (infile
, "%d", &maxargs
);
288 while (c
== ' ' || c
== '\n' || c
== '\t')
291 c
= read_c_string (infile
, 0);
295 while (c
== ' ' || c
== '\n' || c
== '\t')
301 putc (defvarflag
? 'V' : 'F', outfile
);
302 fprintf (outfile
, "%s\n", buf
);
303 read_c_string (infile
, 1);
306 char argbuf
[1024], *p
= argbuf
;
313 /* Skip into arguments. */
320 /* Copy arguments into ARGBUF. */
323 *p
++ = c
= getc (infile
);
327 fprintf (outfile
, "\n\n");
328 write_c_args (outfile
, argbuf
, minargs
, maxargs
);
337 /* Read a file of Lisp code, compiled or interpreted.
339 (defun NAME ARGS DOCSTRING ...)
340 (autoload 'NAME FILE DOCSTRING ...)
341 (defvar NAME VALUE DOCSTRING)
342 (defconst NAME VALUE DOCSTRING)
343 starting in column zero.
344 ARGS, FILE or VALUE is ignored. We do not know how to parse Lisp code
345 so we use a kludge to skip them:
346 In a function definition, the form of ARGS of FILE is known, and we
348 In a variable definition, we use a formatting convention:
349 the DOCSTRING, if present, must be followed by a closeparen and a newline,
350 and no newline must appear between the defvar or defconst and the docstring,
351 The only source file that must follow this convention is loaddefs.el;
352 aside from that, it is always the .elc file that we look at, and
353 they are no problem because byte-compiler output follows this convention.
354 The NAME and DOCSTRING are output.
355 NAME is preceded by `F' for a function or `V' for a variable.
356 An entry is output only if DOCSTRING has \ newline just after the opening "
359 scan_lisp_file (filename
)
368 infile
= fopen (filename
, "r");
372 return 0; /* No error */
376 while (!feof (infile
))
446 while (c
!= ' ' && c
!= ')')
463 c
= read_c_string (infile
, 0);
510 /* Now we have seen "defun" or "defvar" or "defconst". */
512 while (c
!= ' ' && c
!= '\n' && c
!= '\t')
515 while (c
== ' ' || c
== '\n' || c
== '\t')
518 /* Read and store name of function or variable being defined
519 Discard backslashes that are for quoting. */
521 while (c
!= ' ' && c
!= '\n' && c
!= '\t')
530 while (c
== ' ' || c
== '\n' || c
== '\t')
536 /* Skip the arguments: either "nil" or a list in parens */
539 while (c
!= ' ' && c
!= '\n' && c
!= '\t')
555 /* Skip until the first newline; remember
556 the two previous characters. */
559 while (c
!= '\n' && c
>= 0)
566 /* If two previous characters were " and \,
567 this is a doc string. Otherwise, there is none. */
568 if (c2
== '"' && c1
== '\\')
572 fprintf (outfile
, "%s\n", buf
);
573 read_c_string (infile
, 1);
581 /* Here for a function definition.
582 We have skipped the file name or arguments
583 and arrived at where the doc string is,
584 if there is a doc string. */
586 /* Skip whitespace */
588 while (c
== ' ' || c
== '\n' || c
== '\t')
591 /* " followed by \ and newline means a doc string we should gobble */
603 fprintf (outfile
, "%s\n", buf
);
604 read_c_string (infile
, 1);