1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986, 1992, 1993, 1994 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.
34 #define NO_SHORTNAMES /* Tell config not to load remap.h */
35 #include <../src/config.h>
45 #endif /* WINDOWSNT */
48 #define READ_TEXT "rt"
49 #define READ_BINARY "rb"
50 #else /* not DOS_NT */
52 #define READ_BINARY "r"
53 #endif /* not DOS_NT */
56 int scan_lisp_file ();
59 /* Stdio stream for output to the DOC file. */
62 /* Name this program was invoked with. */
65 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
72 fprintf (stderr
, "%s: ", progname
);
73 fprintf (stderr
, s1
, s2
);
74 fprintf (stderr
, "\n");
77 /* Print error message and exit. */
88 /* Like malloc but get fatal error if memory is exhausted. */
94 long *result
= (long *) malloc (size
);
96 fatal ("virtual memory exhausted", 0);
111 /* Don't put CRs in the DOC file. */
114 (stdout
)->_flag
&= ~_IOTEXT
;
115 _setmode (fileno (stdout
), O_BINARY
);
119 _setmode (fileno (stdout
), O_BINARY
);
120 #endif /* WINDOWSNT */
124 /* If first two args are -o FILE, output to FILE. */
126 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
128 outfile
= fopen (argv
[i
+ 1], "w");
131 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
133 outfile
= fopen (argv
[i
+ 1], "a");
136 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
143 for (; i
< argc
; i
++)
146 /* Don't process one file twice. */
147 for (j
= first_infile
; j
< i
; j
++)
148 if (! strcmp (argv
[i
], argv
[j
]))
151 err_count
+= scan_file (argv
[i
]);
154 exit (err_count
> 0);
156 return err_count
> 0;
159 /* Read file FILENAME and output its doc strings to outfile. */
160 /* Return 1 if file is not found, 0 if it is found. */
166 int len
= strlen (filename
);
167 if (!strcmp (filename
+ len
- 4, ".elc"))
168 return scan_lisp_file (filename
, READ_BINARY
);
169 else if (!strcmp (filename
+ len
- 3, ".el"))
170 return scan_lisp_file (filename
, READ_TEXT
);
172 return scan_c_file (filename
, READ_TEXT
);
177 /* Skip a C string from INFILE,
178 and return the character that follows the closing ".
179 If printflag is positive, output string contents to outfile.
180 If it is negative, store contents in buf.
181 Convert escape sequences \n and \t to newline and tab;
182 discard \ followed by newline. */
185 read_c_string (infile
, printflag
)
195 while (c
!= '"' && c
!= EOF
)
212 else if (printflag
< 0)
219 /* If we had a "", concatenate the two strings. */
229 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
230 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
233 write_c_args (out
, func
, buf
, minargs
, maxargs
)
236 int minargs
, maxargs
;
243 fprintf (out
, "(%s", func
);
248 for (p
= buf
; *p
; p
++)
253 /* Notice when we start printing a new identifier. */
254 if ((('A' <= c
&& c
<= 'Z')
255 || ('a' <= c
&& c
<= 'z')
256 || ('0' <= c
&& c
<= '9')
268 if (minargs
== 0 && maxargs
> 0)
269 fprintf (out
, "&optional ");
279 /* Print the C argument list as it would appear in lisp:
280 print underscores as hyphens, and print commas as spaces.
281 Collapse adjacent spaces into one. */
282 if (c
== '_') c
= '-';
283 if (c
== ',') c
= ' ';
285 /* In C code, `default' is a reserved word, so we spell it
286 `defalt'; unmangle that here. */
288 && strncmp (p
, "defalt", 6) == 0
289 && ! (('A' <= p
[6] && p
[6] <= 'Z')
290 || ('a' <= p
[6] && p
[6] <= 'z')
291 || ('0' <= p
[6] && p
[6] <= '9')
294 fprintf (out
, "DEFAULT");
299 else if (c
!= ' ' || ! just_spaced
)
301 if (c
>= 'a' && c
<= 'z')
302 /* Upcase the letter. */
307 just_spaced
= (c
== ' ');
312 /* Read through a c file. If a .o file is named,
313 the corresponding .c file is read instead.
314 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
315 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
318 scan_c_file (filename
, mode
)
319 char *filename
, *mode
;
324 register int defunflag
;
325 register int defvarperbufferflag
;
326 register int defvarflag
;
327 int minargs
, maxargs
;
328 int extension
= filename
[strlen (filename
) - 1];
330 if (extension
== 'o')
331 filename
[strlen (filename
) - 1] = 'c';
333 infile
= fopen (filename
, mode
);
335 /* No error if non-ex input file */
342 /* Reset extension to be able to detect duplicate files. */
343 filename
[strlen (filename
) - 1] = extension
;
346 while (!feof (infile
))
383 defvarperbufferflag
= (c
== 'P');
396 defunflag
= c
== 'U';
411 c
= read_c_string (infile
, -1);
415 else if (defvarperbufferflag
)
419 else /* For DEFSIMPLE and DEFPRED */
427 if (defunflag
&& (commas
== 1 || commas
== 2))
431 while (c
== ' ' || c
== '\n' || c
== '\t');
435 if (commas
== 2) /* pick up minargs */
436 fscanf (infile
, "%d", &minargs
);
437 else /* pick up maxargs */
438 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
441 fscanf (infile
, "%d", &maxargs
);
448 while (c
== ' ' || c
== '\n' || c
== '\t')
451 c
= read_c_string (infile
, 0);
455 while (c
== ' ' || c
== '\n' || c
== '\t')
461 putc (defvarflag
? 'V' : 'F', outfile
);
462 fprintf (outfile
, "%s\n", buf
);
463 c
= read_c_string (infile
, 1);
465 /* If this is a defun, find the arguments and print them. If
466 this function takes MANY or UNEVALLED args, then the C source
467 won't give the names of the arguments, so we shouldn't bother
468 trying to find them. */
469 if (defunflag
&& maxargs
!= -1)
471 char argbuf
[1024], *p
= argbuf
;
478 /* Skip into arguments. */
485 /* Copy arguments into ARGBUF. */
488 *p
++ = c
= getc (infile
);
492 fprintf (outfile
, "\n\n");
493 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
502 /* Read a file of Lisp code, compiled or interpreted.
504 (defun NAME ARGS DOCSTRING ...)
505 (defmacro NAME ARGS DOCSTRING ...)
506 (autoload (quote NAME) FILE DOCSTRING ...)
507 (defvar NAME VALUE DOCSTRING)
508 (defconst NAME VALUE DOCSTRING)
509 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
510 (fset (quote NAME) #[... DOCSTRING ...])
511 (defalias (quote NAME) #[... DOCSTRING ...])
512 starting in column zero.
513 (quote NAME) may appear as 'NAME as well.
515 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
516 When we find that, we save it for the following defining-form,
517 and we use that instead of reading a doc string within that defining-form.
519 For defun, defmacro, and autoload, we know how to skip over the arglist.
520 For defvar, defconst, and fset we skip to the docstring with a kludgy
521 formatting convention: all docstrings must appear on the same line as the
522 initial open-paren (the one in column zero) and must contain a backslash
523 and a double-quote immediately after the initial double-quote. No newlines
524 must appear between the beginning of the form and the first double-quote.
525 The only source file that must follow this convention is loaddefs.el; aside
526 from that, it is always the .elc file that we look at, and they are no
527 problem because byte-compiler output follows this convention.
528 The NAME and DOCSTRING are output.
529 NAME is preceded by `F' for a function or `V' for a variable.
530 An entry is output only if DOCSTRING has \ newline just after the opening "
538 while (c
== ' ' || c
== '\t' || c
== '\n')
544 read_lisp_symbol (infile
, buffer
)
549 char *fillp
= buffer
;
556 *(++fillp
) = getc (infile
);
557 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '(' || c
== ')')
568 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
574 scan_lisp_file (filename
, mode
)
575 char *filename
, *mode
;
579 char *saved_string
= 0;
581 infile
= fopen (filename
, mode
);
585 return 0; /* No error */
589 while (!feof (infile
))
600 /* Detect a dynamic doc string and save it for the next expression. */
609 /* Read the length. */
610 while ((c
= getc (infile
),
611 c
>= '0' && c
<= '9'))
617 /* The next character is a space that is counted in the length
618 but not part of the doc string.
619 We already read it, so just ignore it. */
622 /* Read in the contents. */
623 if (saved_string
!= 0)
625 saved_string
= (char *) malloc (length
);
626 for (i
= 0; i
< length
; i
++)
627 saved_string
[i
] = getc (infile
);
628 /* The last character is a ^_.
629 That is needed in the .elc file
630 but it is redundant in DOC. So get rid of it here. */
631 saved_string
[length
- 1] = 0;
632 /* Skip the newline. */
643 read_lisp_symbol (infile
, buffer
);
645 if (! strcmp (buffer
, "defun") ||
646 ! strcmp (buffer
, "defmacro"))
649 read_lisp_symbol (infile
, buffer
);
651 /* Skip the arguments: either "nil" or a list in parens */
654 if (c
== 'n') /* nil */
656 if ((c
= getc (infile
)) != 'i' ||
657 (c
= getc (infile
)) != 'l')
659 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
666 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
675 /* If the next three characters aren't `dquote bslash newline'
676 then we're not reading a docstring.
678 if ((c
= getc (infile
)) != '"' ||
679 (c
= getc (infile
)) != '\\' ||
680 (c
= getc (infile
)) != '\n')
683 fprintf (stderr
, "## non-docstring in %s (%s)\n",
690 else if (! strcmp (buffer
, "defvar") ||
691 ! strcmp (buffer
, "defconst"))
695 read_lisp_symbol (infile
, buffer
);
697 if (saved_string
== 0)
700 /* Skip until the first newline; remember the two previous chars. */
701 while (c
!= '\n' && c
>= 0)
708 /* If two previous characters were " and \,
709 this is a doc string. Otherwise, there is none. */
710 if (c2
!= '"' || c1
!= '\\')
713 fprintf (stderr
, "## non-docstring in %s (%s)\n",
721 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
728 read_lisp_symbol (infile
, buffer
);
733 fprintf (stderr
, "## unparsable name in fset in %s\n",
737 read_lisp_symbol (infile
, buffer
);
738 if (strcmp (buffer
, "quote"))
740 fprintf (stderr
, "## unparsable name in fset in %s\n",
744 read_lisp_symbol (infile
, buffer
);
749 "## unparsable quoted name in fset in %s\n",
755 if (saved_string
== 0)
757 /* Skip until the first newline; remember the two previous chars. */
758 while (c
!= '\n' && c
>= 0)
765 /* If two previous characters were " and \,
766 this is a doc string. Otherwise, there is none. */
767 if (c2
!= '"' || c1
!= '\\')
770 fprintf (stderr
, "## non-docstring in %s (%s)\n",
778 else if (! strcmp (buffer
, "autoload"))
783 read_lisp_symbol (infile
, buffer
);
788 fprintf (stderr
, "## unparsable name in autoload in %s\n",
792 read_lisp_symbol (infile
, buffer
);
793 if (strcmp (buffer
, "quote"))
795 fprintf (stderr
, "## unparsable name in autoload in %s\n",
799 read_lisp_symbol (infile
, buffer
);
804 "## unparsable quoted name in autoload in %s\n",
810 if ((c
= getc (infile
)) != '\"')
812 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
816 read_c_string (infile
, 0);
819 if (saved_string
== 0)
821 /* If the next three characters aren't `dquote bslash newline'
822 then we're not reading a docstring. */
823 if ((c
= getc (infile
)) != '"' ||
824 (c
= getc (infile
)) != '\\' ||
825 (c
= getc (infile
)) != '\n')
828 fprintf (stderr
, "## non-docstring in %s (%s)\n",
837 else if (! strcmp (buffer
, "if") ||
838 ! strcmp (buffer
, "byte-code"))
845 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
851 /* At this point, we should either use the previous
852 dynamic doc string in saved_string
853 or gobble a doc string from the input file.
855 In the latter case, the opening quote (and leading
856 backslash-newline) have already been read. */
859 putc (type
, outfile
);
860 fprintf (outfile
, "%s\n", buffer
);
863 fputs (saved_string
, outfile
);
864 /* Don't use one dynamic doc string twice. */
869 read_c_string (infile
, 1);