1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986, 92, 93, 94, 1997 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, Inc., 59 Temple Place - Suite 330,
19 Boston, MA 02111-1307, USA. */
21 /* The arguments given to this program are all the C and Lisp source files
22 of GNU Emacs. .elc and .el and .c files are allowed.
23 A .o file can also be specified; the .c file it was made from is used.
24 This helps the makefile pass the correct list of files.
26 The results, which go to standard output or to a file
27 specified with -a or -o (-a to append, -o to start from nothing),
28 are entries containing function or variable names and their documentation.
29 Each entry starts with a ^_ character.
30 Then comes F for a function or V for a variable.
31 Then comes the function or variable name, terminated with a newline.
32 Then comes the documentation for that function or variable.
35 #define NO_SHORTNAMES /* Tell config not to load remap.h */
36 #include <../src/config.h>
46 #endif /* WINDOWSNT */
49 #define READ_TEXT "rt"
50 #define READ_BINARY "rb"
51 #else /* not DOS_NT */
53 #define READ_BINARY "r"
54 #endif /* not DOS_NT */
57 int scan_lisp_file ();
61 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
62 file where that function is defined. */
66 /* Stdio stream for output to the DOC file. */
69 /* Name this program was invoked with. */
72 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
79 fprintf (stderr
, "%s: ", progname
);
80 fprintf (stderr
, s1
, s2
);
81 fprintf (stderr
, "\n");
84 /* Print error message and exit. */
95 /* Like malloc but get fatal error if memory is exhausted. */
101 long *result
= (long *) malloc (size
);
103 fatal ("virtual memory exhausted", 0);
120 /* Don't put CRs in the DOC file. */
123 #if 0 /* Suspicion is that this causes hanging.
124 So instead we require people to use -o on MSDOS. */
125 (stdout
)->_flag
&= ~_IOTEXT
;
126 _setmode (fileno (stdout
), O_BINARY
);
132 _setmode (fileno (stdout
), O_BINARY
);
133 #endif /* WINDOWSNT */
135 /* If first two args are -o FILE, output to FILE. */
137 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
139 outfile
= fopen (argv
[i
+ 1], "w");
142 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
144 outfile
= fopen (argv
[i
+ 1], "a");
147 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
154 fatal ("No output file specified", "");
157 for (; i
< argc
; i
++)
160 /* Don't process one file twice. */
161 for (j
= first_infile
; j
< i
; j
++)
162 if (! strcmp (argv
[i
], argv
[j
]))
165 err_count
+= scan_file (argv
[i
]);
168 exit (err_count
> 0);
170 return err_count
> 0;
173 /* Read file FILENAME and output its doc strings to outfile. */
174 /* Return 1 if file is not found, 0 if it is found. */
180 int len
= strlen (filename
);
181 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
182 return scan_lisp_file (filename
, READ_BINARY
);
183 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
184 return scan_lisp_file (filename
, READ_TEXT
);
186 return scan_c_file (filename
, READ_TEXT
);
191 /* Skip a C string from INFILE,
192 and return the character that follows the closing ".
193 If printflag is positive, output string contents to outfile.
194 If it is negative, store contents in buf.
195 Convert escape sequences \n and \t to newline and tab;
196 discard \ followed by newline. */
199 read_c_string (infile
, printflag
)
209 while (c
!= '"' && c
!= EOF
)
226 else if (printflag
< 0)
233 /* If we had a "", concatenate the two strings. */
243 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
244 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
247 write_c_args (out
, func
, buf
, minargs
, maxargs
)
250 int minargs
, maxargs
;
257 fprintf (out
, "(%s", func
);
262 for (p
= buf
; *p
; p
++)
267 /* Notice when we start printing a new identifier. */
268 if ((('A' <= c
&& c
<= 'Z')
269 || ('a' <= c
&& c
<= 'z')
270 || ('0' <= c
&& c
<= '9')
282 if (minargs
== 0 && maxargs
> 0)
283 fprintf (out
, "&optional ");
293 /* Print the C argument list as it would appear in lisp:
294 print underscores as hyphens, and print commas as spaces.
295 Collapse adjacent spaces into one. */
296 if (c
== '_') c
= '-';
297 if (c
== ',') c
= ' ';
299 /* In C code, `default' is a reserved word, so we spell it
300 `defalt'; unmangle that here. */
302 && strncmp (p
, "defalt", 6) == 0
303 && ! (('A' <= p
[6] && p
[6] <= 'Z')
304 || ('a' <= p
[6] && p
[6] <= 'z')
305 || ('0' <= p
[6] && p
[6] <= '9')
308 fprintf (out
, "DEFAULT");
313 else if (c
!= ' ' || ! just_spaced
)
315 if (c
>= 'a' && c
<= 'z')
316 /* Upcase the letter. */
321 just_spaced
= (c
== ' ');
326 /* Read through a c file. If a .o file is named,
327 the corresponding .c file is read instead.
328 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
329 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
332 scan_c_file (filename
, mode
)
333 char *filename
, *mode
;
338 register int defunflag
;
339 register int defvarperbufferflag
;
340 register int defvarflag
;
341 int minargs
, maxargs
;
342 int extension
= filename
[strlen (filename
) - 1];
344 if (extension
== 'o')
345 filename
[strlen (filename
) - 1] = 'c';
347 infile
= fopen (filename
, mode
);
349 /* No error if non-ex input file */
356 /* Reset extension to be able to detect duplicate files. */
357 filename
[strlen (filename
) - 1] = extension
;
360 while (!feof (infile
))
397 defvarperbufferflag
= (c
== 'P');
410 defunflag
= c
== 'U';
425 c
= read_c_string (infile
, -1);
429 else if (defvarperbufferflag
)
433 else /* For DEFSIMPLE and DEFPRED */
441 if (defunflag
&& (commas
== 1 || commas
== 2))
445 while (c
== ' ' || c
== '\n' || c
== '\t');
449 if (commas
== 2) /* pick up minargs */
450 fscanf (infile
, "%d", &minargs
);
451 else /* pick up maxargs */
452 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
455 fscanf (infile
, "%d", &maxargs
);
462 while (c
== ' ' || c
== '\n' || c
== '\t')
465 c
= read_c_string (infile
, 0);
469 while (c
== ' ' || c
== '\n' || c
== '\t')
475 putc (defvarflag
? 'V' : 'F', outfile
);
476 fprintf (outfile
, "%s\n", buf
);
477 c
= read_c_string (infile
, 1);
479 /* If this is a defun, find the arguments and print them. If
480 this function takes MANY or UNEVALLED args, then the C source
481 won't give the names of the arguments, so we shouldn't bother
482 trying to find them. */
483 if (defunflag
&& maxargs
!= -1)
485 char argbuf
[1024], *p
= argbuf
;
492 /* Skip into arguments. */
499 /* Copy arguments into ARGBUF. */
502 *p
++ = c
= getc (infile
);
506 fprintf (outfile
, "\n\n");
507 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
516 /* Read a file of Lisp code, compiled or interpreted.
518 (defun NAME ARGS DOCSTRING ...)
519 (defmacro NAME ARGS DOCSTRING ...)
520 (autoload (quote NAME) FILE DOCSTRING ...)
521 (defvar NAME VALUE DOCSTRING)
522 (defconst NAME VALUE DOCSTRING)
523 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
524 (fset (quote NAME) #[... DOCSTRING ...])
525 (defalias (quote NAME) #[... DOCSTRING ...])
526 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
527 starting in column zero.
528 (quote NAME) may appear as 'NAME as well.
530 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
531 When we find that, we save it for the following defining-form,
532 and we use that instead of reading a doc string within that defining-form.
534 For defun, defmacro, and autoload, we know how to skip over the arglist.
535 For defvar, defconst, and fset we skip to the docstring with a kludgy
536 formatting convention: all docstrings must appear on the same line as the
537 initial open-paren (the one in column zero) and must contain a backslash
538 and a double-quote immediately after the initial double-quote. No newlines
539 must appear between the beginning of the form and the first double-quote.
540 The only source file that must follow this convention is loaddefs.el; aside
541 from that, it is always the .elc file that we look at, and they are no
542 problem because byte-compiler output follows this convention.
543 The NAME and DOCSTRING are output.
544 NAME is preceded by `F' for a function or `V' for a variable.
545 An entry is output only if DOCSTRING has \ newline just after the opening "
553 while (c
== ' ' || c
== '\t' || c
== '\n')
559 read_lisp_symbol (infile
, buffer
)
564 char *fillp
= buffer
;
571 *(++fillp
) = getc (infile
);
572 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '(' || c
== ')')
583 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
589 scan_lisp_file (filename
, mode
)
590 char *filename
, *mode
;
594 char *saved_string
= 0;
596 infile
= fopen (filename
, mode
);
600 return 0; /* No error */
604 while (!feof (infile
))
615 /* Detect a dynamic doc string and save it for the next expression. */
624 /* Read the length. */
625 while ((c
= getc (infile
),
626 c
>= '0' && c
<= '9'))
632 /* The next character is a space that is counted in the length
633 but not part of the doc string.
634 We already read it, so just ignore it. */
637 /* Read in the contents. */
638 if (saved_string
!= 0)
640 saved_string
= (char *) malloc (length
);
641 for (i
= 0; i
< length
; i
++)
642 saved_string
[i
] = getc (infile
);
643 /* The last character is a ^_.
644 That is needed in the .elc file
645 but it is redundant in DOC. So get rid of it here. */
646 saved_string
[length
- 1] = 0;
647 /* Skip the newline. */
658 read_lisp_symbol (infile
, buffer
);
660 if (! strcmp (buffer
, "defun") ||
661 ! strcmp (buffer
, "defmacro"))
664 read_lisp_symbol (infile
, buffer
);
666 /* Skip the arguments: either "nil" or a list in parens */
669 if (c
== 'n') /* nil */
671 if ((c
= getc (infile
)) != 'i' ||
672 (c
= getc (infile
)) != 'l')
674 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
681 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
690 /* If the next three characters aren't `dquote bslash newline'
691 then we're not reading a docstring.
693 if ((c
= getc (infile
)) != '"' ||
694 (c
= getc (infile
)) != '\\' ||
695 (c
= getc (infile
)) != '\n')
698 fprintf (stderr
, "## non-docstring in %s (%s)\n",
705 else if (! strcmp (buffer
, "defvar") ||
706 ! strcmp (buffer
, "defconst"))
710 read_lisp_symbol (infile
, buffer
);
712 if (saved_string
== 0)
715 /* Skip until the first newline; remember the two previous chars. */
716 while (c
!= '\n' && c
>= 0)
723 /* If two previous characters were " and \,
724 this is a doc string. Otherwise, there is none. */
725 if (c2
!= '"' || c1
!= '\\')
728 fprintf (stderr
, "## non-docstring in %s (%s)\n",
736 else if (! strcmp (buffer
, "custom-declare-variable"))
743 read_lisp_symbol (infile
, buffer
);
749 "## unparsable name in custom-declare-variable in %s\n",
753 read_lisp_symbol (infile
, buffer
);
754 if (strcmp (buffer
, "quote"))
757 "## unparsable name in custom-declare-variable in %s\n",
761 read_lisp_symbol (infile
, buffer
);
766 "## unparsable quoted name in custom-declare-variable in %s\n",
772 if (saved_string
== 0)
774 /* Skip until the first newline; remember the two previous
776 while (c
!= '\n' && c
>= 0)
783 /* If two previous characters were " and \,
784 this is a doc string. Otherwise, there is none. */
785 if (c2
!= '"' || c1
!= '\\')
788 fprintf (stderr
, "## non-docstring in %s (%s)\n",
796 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
803 read_lisp_symbol (infile
, buffer
);
808 fprintf (stderr
, "## unparsable name in fset in %s\n",
812 read_lisp_symbol (infile
, buffer
);
813 if (strcmp (buffer
, "quote"))
815 fprintf (stderr
, "## unparsable name in fset in %s\n",
819 read_lisp_symbol (infile
, buffer
);
824 "## unparsable quoted name in fset in %s\n",
830 if (saved_string
== 0)
832 /* Skip until the first newline; remember the two previous chars. */
833 while (c
!= '\n' && c
>= 0)
840 /* If two previous characters were " and \,
841 this is a doc string. Otherwise, there is none. */
842 if (c2
!= '"' || c1
!= '\\')
845 fprintf (stderr
, "## non-docstring in %s (%s)\n",
853 else if (! strcmp (buffer
, "autoload"))
858 read_lisp_symbol (infile
, buffer
);
863 fprintf (stderr
, "## unparsable name in autoload in %s\n",
867 read_lisp_symbol (infile
, buffer
);
868 if (strcmp (buffer
, "quote"))
870 fprintf (stderr
, "## unparsable name in autoload in %s\n",
874 read_lisp_symbol (infile
, buffer
);
879 "## unparsable quoted name in autoload in %s\n",
885 if ((c
= getc (infile
)) != '\"')
887 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
891 read_c_string (infile
, 0);
894 if (saved_string
== 0)
896 /* If the next three characters aren't `dquote bslash newline'
897 then we're not reading a docstring. */
898 if ((c
= getc (infile
)) != '"' ||
899 (c
= getc (infile
)) != '\\' ||
900 (c
= getc (infile
)) != '\n')
903 fprintf (stderr
, "## non-docstring in %s (%s)\n",
912 else if (! strcmp (buffer
, "if") ||
913 ! strcmp (buffer
, "byte-code"))
920 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
926 /* At this point, we should either use the previous
927 dynamic doc string in saved_string
928 or gobble a doc string from the input file.
930 In the latter case, the opening quote (and leading
931 backslash-newline) have already been read. */
934 putc (type
, outfile
);
935 fprintf (outfile
, "%s\n", buffer
);
938 fputs (saved_string
, outfile
);
939 /* Don't use one dynamic doc string twice. */
944 read_c_string (infile
, 1);