1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 86, 92, 93, 94, 97, 1999, 2000, 2001
3 Free Software Foundation, Inc.
5 This file is part of GNU Emacs.
7 GNU Emacs is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
12 GNU Emacs is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Emacs; see the file COPYING. If not, write to
19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA. */
22 /* The arguments given to this program are all the C and Lisp source files
23 of GNU Emacs. .elc and .el and .c files are allowed.
24 A .o file can also be specified; the .c file it was made from is used.
25 This helps the makefile pass the correct list of files.
27 The results, which go to standard output or to a file
28 specified with -a or -o (-a to append, -o to start from nothing),
29 are entries containing function or variable names and their documentation.
30 Each entry starts with a ^_ character.
31 Then comes F for a function or V for a variable.
32 Then comes the function or variable name, terminated with a newline.
33 Then comes the documentation for that function or variable.
36 #define NO_SHORTNAMES /* Tell config not to load remap.h */
39 /* defined to be emacs_main, sys_fopen, etc. in config.h */
52 #endif /* WINDOWSNT */
55 #define READ_TEXT "rt"
56 #define READ_BINARY "rb"
57 #else /* not DOS_NT */
59 #define READ_BINARY "r"
60 #endif /* not DOS_NT */
63 int scan_lisp_file ();
67 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
68 file where that function is defined. */
76 /* Stdio stream for output to the DOC file. */
79 /* Name this program was invoked with. */
82 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
89 fprintf (stderr
, "%s: ", progname
);
90 fprintf (stderr
, s1
, s2
);
91 fprintf (stderr
, "\n");
94 /* Print error message and exit. */
105 /* Like malloc but get fatal error if memory is exhausted. */
111 long *result
= (long *) malloc (size
);
113 fatal ("virtual memory exhausted", 0);
130 /* Don't put CRs in the DOC file. */
133 #if 0 /* Suspicion is that this causes hanging.
134 So instead we require people to use -o on MSDOS. */
135 (stdout
)->_flag
&= ~_IOTEXT
;
136 _setmode (fileno (stdout
), O_BINARY
);
142 _setmode (fileno (stdout
), O_BINARY
);
143 #endif /* WINDOWSNT */
145 /* If first two args are -o FILE, output to FILE. */
147 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
149 outfile
= fopen (argv
[i
+ 1], "w");
152 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
154 outfile
= fopen (argv
[i
+ 1], "a");
157 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
164 fatal ("No output file specified", "");
167 for (; i
< argc
; i
++)
170 /* Don't process one file twice. */
171 for (j
= first_infile
; j
< i
; j
++)
172 if (! strcmp (argv
[i
], argv
[j
]))
175 err_count
+= scan_file (argv
[i
]);
178 exit (err_count
> 0);
180 return err_count
> 0;
183 /* Read file FILENAME and output its doc strings to outfile. */
184 /* Return 1 if file is not found, 0 if it is found. */
190 int len
= strlen (filename
);
191 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
192 return scan_lisp_file (filename
, READ_BINARY
);
193 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
194 return scan_lisp_file (filename
, READ_TEXT
);
196 return scan_c_file (filename
, READ_TEXT
);
201 /* Some state during the execution of `read_c_string_or_comment'. */
204 /* A count of spaces and newlines that have been read, but not output. */
205 unsigned pending_spaces
, pending_newlines
;
207 /* Where we're reading from. */
210 /* If non-zero, a buffer into which to copy characters. */
212 /* If non-zero, a file into which to copy characters. */
215 /* A keyword we look for at the beginning of lines. If found, it is
216 not copied, and SAW_KEYWORD is set to true. */
218 /* The current point we've reached in an occurance of KEYWORD in
220 char *cur_keyword_ptr
;
221 /* Set to true if we saw an occurance of KEYWORD. */
225 /* Output CH to the file or buffer in STATE. Any pending newlines or
226 spaces are output first. */
231 struct rcsoc_state
*state
;
236 if (state
->pending_newlines
> 0)
238 state
->pending_newlines
--;
241 else if (state
->pending_spaces
> 0)
243 state
->pending_spaces
--;
250 putc (out_ch
, state
->out_file
);
252 *state
->buf_ptr
++ = out_ch
;
254 while (out_ch
!= ch
);
257 /* If in the middle of scanning a keyword, continue scanning with
258 character CH, otherwise output CH to the file or buffer in STATE.
259 Any pending newlines or spaces are output first, as well as any
260 previously scanned characters that were thought to be part of a
261 keyword, but were in fact not. */
264 scan_keyword_or_put_char (ch
, state
)
266 struct rcsoc_state
*state
;
269 && *state
->cur_keyword_ptr
== ch
270 && (state
->cur_keyword_ptr
> state
->keyword
271 || state
->pending_newlines
> 0))
272 /* We might be looking at STATE->keyword at some point.
273 Keep looking until we know for sure. */
275 if (*++state
->cur_keyword_ptr
== '\0')
276 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
278 state
->saw_keyword
= 1;
280 /* Reset the scanning pointer. */
281 state
->cur_keyword_ptr
= state
->keyword
;
283 /* Canonicalize whitespace preceding a usage string. */
284 state
->pending_newlines
= 2;
285 state
->pending_spaces
= 0;
287 /* Skip any whitespace between the keyword and the
290 ch
= getc (state
->in_file
);
291 while (ch
== ' ' || ch
== '\n');
293 /* Put back the non-whitespace character. */
294 ungetc (ch
, state
->in_file
);
299 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
300 /* We scanned the beginning of a potential usage
301 keyword, but it was a false alarm. Output the
306 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
307 put_char (*p
, state
);
309 state
->cur_keyword_ptr
= state
->keyword
;
312 put_char (ch
, state
);
317 /* Skip a C string or C-style comment from INFILE, and return the
318 character that follows. COMMENT non-zero means skip a comment. If
319 PRINTFLAG is positive, output string contents to outfile. If it is
320 negative, store contents in buf. Convert escape sequences \n and
321 \t to newline and tab; discard \ followed by newline.
322 If SAW_USAGE is non-zero, then any occurances of the string `usage:'
323 at the beginning of a line will be removed, and *SAW_USAGE set to
324 true if any were encountered. */
327 read_c_string_or_comment (infile
, printflag
, comment
, saw_usage
)
333 struct rcsoc_state state
;
335 state
.in_file
= infile
;
336 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
337 state
.out_file
= (printflag
> 0 ? outfile
: 0);
338 state
.pending_spaces
= 0;
339 state
.pending_newlines
= 0;
340 state
.keyword
= (saw_usage
? "usage:" : 0);
341 state
.cur_keyword_ptr
= state
.keyword
;
342 state
.saw_keyword
= 0;
346 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
351 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
356 if (c
== '\n' || c
== '\r')
368 state
.pending_spaces
++;
371 state
.pending_newlines
++;
372 state
.pending_spaces
= 0;
375 scan_keyword_or_put_char (c
, &state
);
391 scan_keyword_or_put_char ('*', &state
);
398 /* If we had a "", concatenate the two strings. */
407 *saw_usage
= state
.saw_keyword
;
414 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
415 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
418 write_c_args (out
, func
, buf
, minargs
, maxargs
)
421 int minargs
, maxargs
;
428 fprintf (out
, "(%s", func
);
433 for (p
= buf
; *p
; p
++)
438 /* Notice when we start printing a new identifier. */
439 if ((('A' <= c
&& c
<= 'Z')
440 || ('a' <= c
&& c
<= 'z')
441 || ('0' <= c
&& c
<= '9')
453 if (minargs
== 0 && maxargs
> 0)
454 fprintf (out
, "&optional ");
464 /* Print the C argument list as it would appear in lisp:
465 print underscores as hyphens, and print commas and newlines
466 as spaces. Collapse adjacent spaces into one. */
469 else if (c
== ',' || c
== '\n')
472 /* In C code, `default' is a reserved word, so we spell it
473 `defalt'; unmangle that here. */
475 && strncmp (p
, "defalt", 6) == 0
476 && ! (('A' <= p
[6] && p
[6] <= 'Z')
477 || ('a' <= p
[6] && p
[6] <= 'z')
478 || ('0' <= p
[6] && p
[6] <= '9')
481 fprintf (out
, "DEFAULT");
486 else if (c
!= ' ' || !just_spaced
)
488 if (c
>= 'a' && c
<= 'z')
489 /* Upcase the letter. */
494 just_spaced
= c
== ' ';
499 /* Read through a c file. If a .o file is named,
500 the corresponding .c file is read instead.
501 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
502 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
505 scan_c_file (filename
, mode
)
506 char *filename
, *mode
;
511 register int defunflag
;
512 register int defvarperbufferflag
;
513 register int defvarflag
;
514 int minargs
, maxargs
;
515 int extension
= filename
[strlen (filename
) - 1];
517 if (extension
== 'o')
518 filename
[strlen (filename
) - 1] = 'c';
520 infile
= fopen (filename
, mode
);
522 /* No error if non-ex input file */
529 /* Reset extension to be able to detect duplicate files. */
530 filename
[strlen (filename
) - 1] = extension
;
533 while (!feof (infile
))
537 if (c
!= '\n' && c
!= '\r')
572 defvarperbufferflag
= (c
== 'P');
585 defunflag
= c
== 'U';
597 /* Lisp variable or function name. */
601 c
= read_c_string_or_comment (infile
, -1, 0, 0);
603 /* DEFVAR_LISP ("name", addr, "doc")
604 DEFVAR_LISP ("name", addr /\* doc *\/)
605 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
609 else if (defvarperbufferflag
)
613 else /* For DEFSIMPLE and DEFPRED */
622 if (defunflag
&& (commas
== 1 || commas
== 2))
626 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
630 if (commas
== 2) /* pick up minargs */
631 fscanf (infile
, "%d", &minargs
);
632 else /* pick up maxargs */
633 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
636 fscanf (infile
, "%d", &maxargs
);
645 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
649 c
= read_c_string_or_comment (infile
, 0, 0, 0);
651 while (c
!= EOF
&& c
!= ',' && c
!= '/')
656 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
658 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
664 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
671 && (c
= getc (infile
),
675 int comment
= c
!= '"';
679 putc (defvarflag
? 'V' : 'F', outfile
);
680 fprintf (outfile
, "%s\n", buf
);
683 getc (infile
); /* Skip past `*' */
684 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
686 /* If this is a defun, find the arguments and print them. If
687 this function takes MANY or UNEVALLED args, then the C source
688 won't give the names of the arguments, so we shouldn't bother
691 Various doc-string styles:
692 0: DEFUN (..., "DOC") (args) [!comment]
693 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
694 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
696 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
698 char argbuf
[1024], *p
= argbuf
;
700 if (!comment
|| doc_keyword
)
708 /* Skip into arguments. */
715 /* Copy arguments into ARGBUF. */
718 *p
++ = c
= getc (infile
);
722 fprintf (outfile
, "\n\n");
723 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
725 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
726 /* The DOC should provide the usage form. */
727 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
735 /* Read a file of Lisp code, compiled or interpreted.
737 (defun NAME ARGS DOCSTRING ...)
738 (defmacro NAME ARGS DOCSTRING ...)
739 (defsubst NAME ARGS DOCSTRING ...)
740 (autoload (quote NAME) FILE DOCSTRING ...)
741 (defvar NAME VALUE DOCSTRING)
742 (defconst NAME VALUE DOCSTRING)
743 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
744 (fset (quote NAME) #[... DOCSTRING ...])
745 (defalias (quote NAME) #[... DOCSTRING ...])
746 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
747 starting in column zero.
748 (quote NAME) may appear as 'NAME as well.
750 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
751 When we find that, we save it for the following defining-form,
752 and we use that instead of reading a doc string within that defining-form.
754 For defvar, defconst, and fset we skip to the docstring with a kludgy
755 formatting convention: all docstrings must appear on the same line as the
756 initial open-paren (the one in column zero) and must contain a backslash
757 and a newline immediately after the initial double-quote. No newlines
758 must appear between the beginning of the form and the first double-quote.
759 For defun, defmacro, and autoload, we know how to skip over the
760 arglist, but the doc string must still have a backslash and newline
761 immediately after the double quote.
762 The only source files that must follow this convention are preloaded
763 uncompiled ones like loaddefs.el and bindings.el; aside
764 from that, it is always the .elc file that we look at, and they are no
765 problem because byte-compiler output follows this convention.
766 The NAME and DOCSTRING are output.
767 NAME is preceded by `F' for a function or `V' for a variable.
768 An entry is output only if DOCSTRING has \ newline just after the opening "
776 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
782 read_lisp_symbol (infile
, buffer
)
787 char *fillp
= buffer
;
794 *(++fillp
) = getc (infile
);
795 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
806 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
812 scan_lisp_file (filename
, mode
)
813 char *filename
, *mode
;
817 char *saved_string
= 0;
819 infile
= fopen (filename
, mode
);
823 return 0; /* No error */
827 while (!feof (infile
))
832 /* If not at end of line, skip till we get to one. */
833 if (c
!= '\n' && c
!= '\r')
838 /* Skip the line break. */
839 while (c
== '\n' || c
== '\r')
841 /* Detect a dynamic doc string and save it for the next expression. */
850 /* Read the length. */
851 while ((c
= getc (infile
),
852 c
>= '0' && c
<= '9'))
858 /* The next character is a space that is counted in the length
859 but not part of the doc string.
860 We already read it, so just ignore it. */
863 /* Read in the contents. */
864 if (saved_string
!= 0)
866 saved_string
= (char *) malloc (length
);
867 for (i
= 0; i
< length
; i
++)
868 saved_string
[i
] = getc (infile
);
869 /* The last character is a ^_.
870 That is needed in the .elc file
871 but it is redundant in DOC. So get rid of it here. */
872 saved_string
[length
- 1] = 0;
873 /* Skip the line break. */
874 while (c
== '\n' && c
== '\r')
876 /* Skip the following line. */
877 while (c
!= '\n' && c
!= '\r')
886 read_lisp_symbol (infile
, buffer
);
888 if (! strcmp (buffer
, "defun")
889 || ! strcmp (buffer
, "defmacro")
890 || ! strcmp (buffer
, "defsubst"))
893 read_lisp_symbol (infile
, buffer
);
895 /* Skip the arguments: either "nil" or a list in parens */
898 if (c
== 'n') /* nil */
900 if ((c
= getc (infile
)) != 'i'
901 || (c
= getc (infile
)) != 'l')
903 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
910 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
919 /* If the next three characters aren't `dquote bslash newline'
920 then we're not reading a docstring.
922 if ((c
= getc (infile
)) != '"'
923 || (c
= getc (infile
)) != '\\'
924 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
927 fprintf (stderr
, "## non-docstring in %s (%s)\n",
934 else if (! strcmp (buffer
, "defvar")
935 || ! strcmp (buffer
, "defconst"))
939 read_lisp_symbol (infile
, buffer
);
941 if (saved_string
== 0)
944 /* Skip until the end of line; remember two previous chars. */
945 while (c
!= '\n' && c
!= '\r' && c
>= 0)
952 /* If two previous characters were " and \,
953 this is a doc string. Otherwise, there is none. */
954 if (c2
!= '"' || c1
!= '\\')
957 fprintf (stderr
, "## non-docstring in %s (%s)\n",
965 else if (! strcmp (buffer
, "custom-declare-variable"))
972 read_lisp_symbol (infile
, buffer
);
978 "## unparsable name in custom-declare-variable in %s\n",
982 read_lisp_symbol (infile
, buffer
);
983 if (strcmp (buffer
, "quote"))
986 "## unparsable name in custom-declare-variable in %s\n",
990 read_lisp_symbol (infile
, buffer
);
995 "## unparsable quoted name in custom-declare-variable in %s\n",
1001 if (saved_string
== 0)
1003 /* Skip to end of line; remember the two previous chars. */
1004 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1011 /* If two previous characters were " and \,
1012 this is a doc string. Otherwise, there is none. */
1013 if (c2
!= '"' || c1
!= '\\')
1016 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1024 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1026 char c1
= 0, c2
= 0;
1031 read_lisp_symbol (infile
, buffer
);
1036 fprintf (stderr
, "## unparsable name in fset in %s\n",
1040 read_lisp_symbol (infile
, buffer
);
1041 if (strcmp (buffer
, "quote"))
1043 fprintf (stderr
, "## unparsable name in fset in %s\n",
1047 read_lisp_symbol (infile
, buffer
);
1052 "## unparsable quoted name in fset in %s\n",
1058 if (saved_string
== 0)
1060 /* Skip to end of line; remember the two previous chars. */
1061 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1068 /* If two previous characters were " and \,
1069 this is a doc string. Otherwise, there is none. */
1070 if (c2
!= '"' || c1
!= '\\')
1073 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1081 else if (! strcmp (buffer
, "autoload"))
1086 read_lisp_symbol (infile
, buffer
);
1091 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1095 read_lisp_symbol (infile
, buffer
);
1096 if (strcmp (buffer
, "quote"))
1098 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1102 read_lisp_symbol (infile
, buffer
);
1107 "## unparsable quoted name in autoload in %s\n",
1112 skip_white (infile
);
1113 if ((c
= getc (infile
)) != '\"')
1115 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1119 read_c_string_or_comment (infile
, 0, 0, 0);
1120 skip_white (infile
);
1122 if (saved_string
== 0)
1124 /* If the next three characters aren't `dquote bslash newline'
1125 then we're not reading a docstring. */
1126 if ((c
= getc (infile
)) != '"'
1127 || (c
= getc (infile
)) != '\\'
1128 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1131 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1140 else if (! strcmp (buffer
, "if")
1141 || ! strcmp (buffer
, "byte-code"))
1148 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
1154 /* At this point, we should either use the previous
1155 dynamic doc string in saved_string
1156 or gobble a doc string from the input file.
1158 In the latter case, the opening quote (and leading
1159 backslash-newline) have already been read. */
1161 putc (037, outfile
);
1162 putc (type
, outfile
);
1163 fprintf (outfile
, "%s\n", buffer
);
1166 fputs (saved_string
, outfile
);
1167 /* Don't use one dynamic doc string twice. */
1168 free (saved_string
);
1172 read_c_string_or_comment (infile
, 1, 0, 0);