1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985-1986, 1992-1994, 1997, 1999-2011
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 3 of the License, or
10 (at your option) any later version.
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. If not, see <http://www.gnu.org/licenses/>. */
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.
25 Option -d DIR means change to DIR before looking for 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.
38 /* defined to be emacs_main, sys_fopen, etc. in config.h */
51 #endif /* WINDOWSNT */
54 #define READ_TEXT "rt"
55 #define READ_BINARY "rb"
56 #else /* not DOS_NT */
58 #define READ_BINARY "r"
59 #endif /* not DOS_NT */
62 #define DIRECTORY_SEP '/'
65 #ifndef IS_DIRECTORY_SEP
66 #define IS_DIRECTORY_SEP(_c_) ((_c_) == DIRECTORY_SEP)
69 int scan_file (char *filename
);
70 int scan_lisp_file (const char *filename
, const char *mode
);
71 int scan_c_file (char *filename
, const char *mode
);
72 void fatal (const char *s1
, const char *s2
) NO_RETURN
;
75 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
76 file where that function is defined. */
82 /* Stdio stream for output to the DOC file. */
85 /* Name this program was invoked with. */
88 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
92 error (const char *s1
, const char *s2
)
94 fprintf (stderr
, "%s: ", progname
);
95 fprintf (stderr
, s1
, s2
);
96 fprintf (stderr
, "\n");
99 /* Print error message and exit. */
103 fatal (const char *s1
, const char *s2
)
109 /* Like malloc but get fatal error if memory is exhausted. */
112 xmalloc (unsigned int size
)
114 void *result
= (void *) malloc (size
);
116 fatal ("virtual memory exhausted", 0);
121 main (int argc
, char **argv
)
131 /* Don't put CRs in the DOC file. */
134 #if 0 /* Suspicion is that this causes hanging.
135 So instead we require people to use -o on MSDOS. */
136 (stdout
)->_flag
&= ~_IOTEXT
;
137 _setmode (fileno (stdout
), O_BINARY
);
143 _setmode (fileno (stdout
), O_BINARY
);
144 #endif /* WINDOWSNT */
146 /* If first two args are -o FILE, output to FILE. */
148 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
150 outfile
= fopen (argv
[i
+ 1], "w");
153 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
155 outfile
= fopen (argv
[i
+ 1], "a");
158 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
160 if (chdir (argv
[i
+ 1]) != 0)
162 perror (argv
[i
+ 1]);
169 fatal ("No output file specified", "");
172 for (; i
< argc
; i
++)
175 /* Don't process one file twice. */
176 for (j
= first_infile
; j
< i
; j
++)
177 if (! strcmp (argv
[i
], argv
[j
]))
180 err_count
+= scan_file (argv
[i
]);
182 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
185 /* Add a source file name boundary marker in the output file. */
187 put_filename (char *filename
)
191 for (tmp
= filename
; *tmp
; tmp
++)
193 if (IS_DIRECTORY_SEP(*tmp
))
199 fprintf (outfile
, "%s\n", filename
);
202 /* Read file FILENAME and output its doc strings to outfile. */
203 /* Return 1 if file is not found, 0 if it is found. */
206 scan_file (char *filename
)
209 size_t len
= strlen (filename
);
211 put_filename (filename
);
212 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
213 return scan_lisp_file (filename
, READ_BINARY
);
214 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
215 return scan_lisp_file (filename
, READ_TEXT
);
217 return scan_c_file (filename
, READ_TEXT
);
222 /* Some state during the execution of `read_c_string_or_comment'. */
225 /* A count of spaces and newlines that have been read, but not output. */
226 unsigned pending_spaces
, pending_newlines
;
228 /* Where we're reading from. */
231 /* If non-zero, a buffer into which to copy characters. */
233 /* If non-zero, a file into which to copy characters. */
236 /* A keyword we look for at the beginning of lines. If found, it is
237 not copied, and SAW_KEYWORD is set to true. */
239 /* The current point we've reached in an occurrence of KEYWORD in
241 const char *cur_keyword_ptr
;
242 /* Set to true if we saw an occurrence of KEYWORD. */
246 /* Output CH to the file or buffer in STATE. Any pending newlines or
247 spaces are output first. */
250 put_char (int ch
, struct rcsoc_state
*state
)
255 if (state
->pending_newlines
> 0)
257 state
->pending_newlines
--;
260 else if (state
->pending_spaces
> 0)
262 state
->pending_spaces
--;
269 putc (out_ch
, state
->out_file
);
271 *state
->buf_ptr
++ = out_ch
;
273 while (out_ch
!= ch
);
276 /* If in the middle of scanning a keyword, continue scanning with
277 character CH, otherwise output CH to the file or buffer in STATE.
278 Any pending newlines or spaces are output first, as well as any
279 previously scanned characters that were thought to be part of a
280 keyword, but were in fact not. */
283 scan_keyword_or_put_char (int ch
, struct rcsoc_state
*state
)
286 && *state
->cur_keyword_ptr
== ch
287 && (state
->cur_keyword_ptr
> state
->keyword
288 || state
->pending_newlines
> 0))
289 /* We might be looking at STATE->keyword at some point.
290 Keep looking until we know for sure. */
292 if (*++state
->cur_keyword_ptr
== '\0')
293 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
295 state
->saw_keyword
= 1;
297 /* Reset the scanning pointer. */
298 state
->cur_keyword_ptr
= state
->keyword
;
300 /* Canonicalize whitespace preceding a usage string. */
301 state
->pending_newlines
= 2;
302 state
->pending_spaces
= 0;
304 /* Skip any whitespace between the keyword and the
307 ch
= getc (state
->in_file
);
308 while (ch
== ' ' || ch
== '\n');
310 /* Output the open-paren we just read. */
311 put_char (ch
, state
);
313 /* Skip the function name and replace it with `fn'. */
315 ch
= getc (state
->in_file
);
316 while (ch
!= ' ' && ch
!= ')');
317 put_char ('f', state
);
318 put_char ('n', state
);
320 /* Put back the last character. */
321 ungetc (ch
, state
->in_file
);
326 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
327 /* We scanned the beginning of a potential usage
328 keyword, but it was a false alarm. Output the
333 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
334 put_char (*p
, state
);
336 state
->cur_keyword_ptr
= state
->keyword
;
339 put_char (ch
, state
);
344 /* Skip a C string or C-style comment from INFILE, and return the
345 character that follows. COMMENT non-zero means skip a comment. If
346 PRINTFLAG is positive, output string contents to outfile. If it is
347 negative, store contents in buf. Convert escape sequences \n and
348 \t to newline and tab; discard \ followed by newline.
349 If SAW_USAGE is non-zero, then any occurrences of the string `usage:'
350 at the beginning of a line will be removed, and *SAW_USAGE set to
351 true if any were encountered. */
354 read_c_string_or_comment (FILE *infile
, int printflag
, int comment
, int *saw_usage
)
357 struct rcsoc_state state
;
359 state
.in_file
= infile
;
360 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
361 state
.out_file
= (printflag
> 0 ? outfile
: 0);
362 state
.pending_spaces
= 0;
363 state
.pending_newlines
= 0;
364 state
.keyword
= (saw_usage
? "usage:" : 0);
365 state
.cur_keyword_ptr
= state
.keyword
;
366 state
.saw_keyword
= 0;
370 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
375 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
380 if (c
== '\n' || c
== '\r')
392 state
.pending_spaces
++;
395 state
.pending_newlines
++;
396 state
.pending_spaces
= 0;
399 scan_keyword_or_put_char (c
, &state
);
415 scan_keyword_or_put_char ('*', &state
);
422 /* If we had a "", concatenate the two strings. */
431 *saw_usage
= state
.saw_keyword
;
438 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
439 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
442 write_c_args (FILE *out
, char *func
, char *buf
, int minargs
, int maxargs
)
447 size_t ident_length
= 0;
449 fprintf (out
, "(fn");
454 for (p
= buf
; *p
; p
++)
458 /* Notice when a new identifier starts. */
459 if ((('A' <= c
&& c
<= 'Z')
460 || ('a' <= c
&& c
<= 'z')
461 || ('0' <= c
&& c
<= '9')
473 ident_length
= p
- ident_start
;
477 /* Found the end of an argument, write out the last seen
479 if (c
== ',' || c
== ')')
481 if (ident_length
== 0)
483 error ("empty arg list for `%s' should be (void), not ()", func
);
487 if (strncmp (ident_start
, "void", ident_length
) == 0)
492 if (minargs
== 0 && maxargs
> 0)
493 fprintf (out
, "&optional ");
498 /* In C code, `default' is a reserved word, so we spell it
499 `defalt'; unmangle that here. */
500 if (ident_length
== 6 && strncmp (ident_start
, "defalt", 6) == 0)
501 fprintf (out
, "DEFAULT");
503 while (ident_length
-- > 0)
506 if (c
>= 'a' && c
<= 'z')
507 /* Upcase the letter. */
510 /* Print underscore as hyphen. */
520 /* Read through a c file. If a .o file is named,
521 the corresponding .c or .m file is read instead.
522 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
523 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
526 scan_c_file (char *filename
, const char *mode
)
531 register int defunflag
;
532 register int defvarperbufferflag
;
533 register int defvarflag
;
534 int minargs
, maxargs
;
535 int extension
= filename
[strlen (filename
) - 1];
537 if (extension
== 'o')
538 filename
[strlen (filename
) - 1] = 'c';
540 infile
= fopen (filename
, mode
);
542 if (infile
== NULL
&& extension
== 'o')
545 filename
[strlen (filename
) - 1] = 'm';
546 infile
= fopen (filename
, mode
);
548 filename
[strlen (filename
) - 1] = 'c'; /* don't confuse people */
551 /* No error if non-ex input file */
558 /* Reset extension to be able to detect duplicate files. */
559 filename
[strlen (filename
) - 1] = extension
;
562 while (!feof (infile
))
566 if (c
!= '\n' && c
!= '\r')
601 defvarperbufferflag
= (c
== 'P');
614 defunflag
= c
== 'U';
616 defvarperbufferflag
= 0;
627 /* Lisp variable or function name. */
631 c
= read_c_string_or_comment (infile
, -1, 0, 0);
633 /* DEFVAR_LISP ("name", addr, "doc")
634 DEFVAR_LISP ("name", addr /\* doc *\/)
635 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
639 else if (defvarperbufferflag
)
643 else /* For DEFSIMPLE and DEFPRED */
652 if (defunflag
&& (commas
== 1 || commas
== 2))
657 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
661 if (commas
== 2) /* pick up minargs */
662 scanned
= fscanf (infile
, "%d", &minargs
);
663 else /* pick up maxargs */
664 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
667 scanned
= fscanf (infile
, "%d", &maxargs
);
678 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
682 c
= read_c_string_or_comment (infile
, 0, 0, 0);
684 while (c
!= EOF
&& c
!= ',' && c
!= '/')
689 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
691 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
697 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
704 && (c
= getc (infile
),
708 int comment
= c
!= '"';
712 putc (defvarflag
? 'V' : 'F', outfile
);
713 fprintf (outfile
, "%s\n", buf
);
716 getc (infile
); /* Skip past `*' */
717 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
719 /* If this is a defun, find the arguments and print them. If
720 this function takes MANY or UNEVALLED args, then the C source
721 won't give the names of the arguments, so we shouldn't bother
724 Various doc-string styles:
725 0: DEFUN (..., "DOC") (args) [!comment]
726 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
727 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
729 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
731 char argbuf
[1024], *p
= argbuf
;
733 if (!comment
|| doc_keyword
)
741 /* Skip into arguments. */
748 /* Copy arguments into ARGBUF. */
751 *p
++ = c
= getc (infile
);
755 fprintf (outfile
, "\n\n");
756 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
758 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
759 /* The DOC should provide the usage form. */
760 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
768 /* Read a file of Lisp code, compiled or interpreted.
770 (defun NAME ARGS DOCSTRING ...)
771 (defmacro NAME ARGS DOCSTRING ...)
772 (defsubst NAME ARGS DOCSTRING ...)
773 (autoload (quote NAME) FILE DOCSTRING ...)
774 (defvar NAME VALUE DOCSTRING)
775 (defconst NAME VALUE DOCSTRING)
776 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
777 (fset (quote NAME) #[... DOCSTRING ...])
778 (defalias (quote NAME) #[... DOCSTRING ...])
779 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
780 starting in column zero.
781 (quote NAME) may appear as 'NAME as well.
783 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
784 When we find that, we save it for the following defining-form,
785 and we use that instead of reading a doc string within that defining-form.
787 For defvar, defconst, and fset we skip to the docstring with a kludgy
788 formatting convention: all docstrings must appear on the same line as the
789 initial open-paren (the one in column zero) and must contain a backslash
790 and a newline immediately after the initial double-quote. No newlines
791 must appear between the beginning of the form and the first double-quote.
792 For defun, defmacro, and autoload, we know how to skip over the
793 arglist, but the doc string must still have a backslash and newline
794 immediately after the double quote.
795 The only source files that must follow this convention are preloaded
796 uncompiled ones like loaddefs.el and bindings.el; aside
797 from that, it is always the .elc file that we look at, and they are no
798 problem because byte-compiler output follows this convention.
799 The NAME and DOCSTRING are output.
800 NAME is preceded by `F' for a function or `V' for a variable.
801 An entry is output only if DOCSTRING has \ newline just after the opening "
805 skip_white (FILE *infile
)
808 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
814 read_lisp_symbol (FILE *infile
, char *buffer
)
817 char *fillp
= buffer
;
824 *(++fillp
) = getc (infile
);
825 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
836 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
842 scan_lisp_file (const char *filename
, const char *mode
)
846 char *saved_string
= 0;
848 infile
= fopen (filename
, mode
);
852 return 0; /* No error */
856 while (!feof (infile
))
861 /* If not at end of line, skip till we get to one. */
862 if (c
!= '\n' && c
!= '\r')
867 /* Skip the line break. */
868 while (c
== '\n' || c
== '\r')
870 /* Detect a dynamic doc string and save it for the next expression. */
879 /* Read the length. */
880 while ((c
= getc (infile
),
881 c
>= '0' && c
<= '9'))
888 fatal ("invalid dynamic doc string length", "");
891 fatal ("space not found after dynamic doc string length", "");
893 /* The next character is a space that is counted in the length
894 but not part of the doc string.
895 We already read it, so just ignore it. */
898 /* Read in the contents. */
900 saved_string
= (char *) xmalloc (length
);
901 for (i
= 0; i
< length
; i
++)
902 saved_string
[i
] = getc (infile
);
903 /* The last character is a ^_.
904 That is needed in the .elc file
905 but it is redundant in DOC. So get rid of it here. */
906 saved_string
[length
- 1] = 0;
907 /* Skip the line break. */
908 while (c
== '\n' || c
== '\r')
910 /* Skip the following line. */
911 while (c
!= '\n' && c
!= '\r')
920 read_lisp_symbol (infile
, buffer
);
922 if (! strcmp (buffer
, "defun")
923 || ! strcmp (buffer
, "defmacro")
924 || ! strcmp (buffer
, "defsubst"))
927 read_lisp_symbol (infile
, buffer
);
929 /* Skip the arguments: either "nil" or a list in parens */
932 if (c
== 'n') /* nil */
934 if ((c
= getc (infile
)) != 'i'
935 || (c
= getc (infile
)) != 'l')
937 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
944 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
953 /* If the next three characters aren't `dquote bslash newline'
954 then we're not reading a docstring.
956 if ((c
= getc (infile
)) != '"'
957 || (c
= getc (infile
)) != '\\'
958 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
961 fprintf (stderr
, "## non-docstring in %s (%s)\n",
968 else if (! strcmp (buffer
, "defvar")
969 || ! strcmp (buffer
, "defconst"))
973 read_lisp_symbol (infile
, buffer
);
975 if (saved_string
== 0)
978 /* Skip until the end of line; remember two previous chars. */
979 while (c
!= '\n' && c
!= '\r' && c
>= 0)
986 /* If two previous characters were " and \,
987 this is a doc string. Otherwise, there is none. */
988 if (c2
!= '"' || c1
!= '\\')
991 fprintf (stderr
, "## non-docstring in %s (%s)\n",
999 else if (! strcmp (buffer
, "custom-declare-variable")
1000 || ! strcmp (buffer
, "defvaralias")
1003 char c1
= 0, c2
= 0;
1008 read_lisp_symbol (infile
, buffer
);
1014 "## unparsable name in custom-declare-variable in %s\n",
1018 read_lisp_symbol (infile
, buffer
);
1019 if (strcmp (buffer
, "quote"))
1022 "## unparsable name in custom-declare-variable in %s\n",
1026 read_lisp_symbol (infile
, buffer
);
1031 "## unparsable quoted name in custom-declare-variable in %s\n",
1037 if (saved_string
== 0)
1039 /* Skip to end of line; remember the two previous chars. */
1040 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1047 /* If two previous characters were " and \,
1048 this is a doc string. Otherwise, there is none. */
1049 if (c2
!= '"' || c1
!= '\\')
1052 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1060 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1062 char c1
= 0, c2
= 0;
1067 read_lisp_symbol (infile
, buffer
);
1072 fprintf (stderr
, "## unparsable name in fset in %s\n",
1076 read_lisp_symbol (infile
, buffer
);
1077 if (strcmp (buffer
, "quote"))
1079 fprintf (stderr
, "## unparsable name in fset in %s\n",
1083 read_lisp_symbol (infile
, buffer
);
1088 "## unparsable quoted name in fset in %s\n",
1094 if (saved_string
== 0)
1096 /* Skip to end of line; remember the two previous chars. */
1097 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1104 /* If two previous characters were " and \,
1105 this is a doc string. Otherwise, there is none. */
1106 if (c2
!= '"' || c1
!= '\\')
1109 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1117 else if (! strcmp (buffer
, "autoload"))
1122 read_lisp_symbol (infile
, buffer
);
1127 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1131 read_lisp_symbol (infile
, buffer
);
1132 if (strcmp (buffer
, "quote"))
1134 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1138 read_lisp_symbol (infile
, buffer
);
1143 "## unparsable quoted name in autoload in %s\n",
1148 skip_white (infile
);
1149 if ((c
= getc (infile
)) != '\"')
1151 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1155 read_c_string_or_comment (infile
, 0, 0, 0);
1156 skip_white (infile
);
1158 if (saved_string
== 0)
1160 /* If the next three characters aren't `dquote bslash newline'
1161 then we're not reading a docstring. */
1162 if ((c
= getc (infile
)) != '"'
1163 || (c
= getc (infile
)) != '\\'
1164 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1167 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1176 else if (! strcmp (buffer
, "if")
1177 || ! strcmp (buffer
, "byte-code"))
1184 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1190 /* At this point, we should either use the previous
1191 dynamic doc string in saved_string
1192 or gobble a doc string from the input file.
1194 In the latter case, the opening quote (and leading
1195 backslash-newline) have already been read. */
1197 putc (037, outfile
);
1198 putc (type
, outfile
);
1199 fprintf (outfile
, "%s\n", buffer
);
1202 fputs (saved_string
, outfile
);
1203 /* Don't use one dynamic doc string twice. */
1204 free (saved_string
);
1208 read_c_string_or_comment (infile
, 1, 0, 0);
1215 /* make-docfile.c ends here */