1 /* Generate doc-string file for GNU Emacs from source files.
2 Copyright (C) 1985, 1986, 1992, 1993, 1994, 1997, 1999, 2000, 2001,
3 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
4 Free Software Foundation, Inc.
6 This file is part of GNU Emacs.
8 GNU Emacs is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
13 GNU Emacs is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
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.
26 Option -d DIR means change to DIR before looking for files.
28 The results, which go to standard output or to a file
29 specified with -a or -o (-a to append, -o to start from nothing),
30 are entries containing function or variable names and their documentation.
31 Each entry starts with a ^_ character.
32 Then comes F for a function or V for a variable.
33 Then comes the function or variable name, terminated with a newline.
34 Then comes the documentation for that function or variable.
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 #define DIRECTORY_SEP '/'
66 #ifndef IS_DIRECTORY_SEP
67 #define IS_DIRECTORY_SEP(_c_) ((_c_) == DIRECTORY_SEP)
70 int scan_file (char *filename
);
71 int scan_lisp_file (const char *filename
, const char *mode
);
72 int scan_c_file (char *filename
, const char *mode
);
73 void fatal (const char *s1
, const char *s2
) NO_RETURN
;
76 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
77 file where that function is defined. */
85 /* Stdio stream for output to the DOC file. */
88 /* Name this program was invoked with. */
91 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
95 error (const char *s1
, const char *s2
)
97 fprintf (stderr
, "%s: ", progname
);
98 fprintf (stderr
, s1
, s2
);
99 fprintf (stderr
, "\n");
102 /* Print error message and exit. */
106 fatal (const char *s1
, const char *s2
)
112 /* Like malloc but get fatal error if memory is exhausted. */
115 xmalloc (unsigned int size
)
117 void *result
= (void *) malloc (size
);
119 fatal ("virtual memory exhausted", 0);
124 main (int argc
, char **argv
)
134 /* Don't put CRs in the DOC file. */
137 #if 0 /* Suspicion is that this causes hanging.
138 So instead we require people to use -o on MSDOS. */
139 (stdout
)->_flag
&= ~_IOTEXT
;
140 _setmode (fileno (stdout
), O_BINARY
);
146 _setmode (fileno (stdout
), O_BINARY
);
147 #endif /* WINDOWSNT */
149 /* If first two args are -o FILE, output to FILE. */
151 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
153 outfile
= fopen (argv
[i
+ 1], "w");
156 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
158 outfile
= fopen (argv
[i
+ 1], "a");
161 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
168 fatal ("No output file specified", "");
171 for (; i
< argc
; i
++)
174 /* Don't process one file twice. */
175 for (j
= first_infile
; j
< i
; j
++)
176 if (! strcmp (argv
[i
], argv
[j
]))
179 err_count
+= scan_file (argv
[i
]);
181 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
184 /* Add a source file name boundary marker in the output file. */
186 put_filename (char *filename
)
190 for (tmp
= filename
; *tmp
; tmp
++)
192 if (IS_DIRECTORY_SEP(*tmp
))
198 fprintf (outfile
, "%s\n", filename
);
201 /* Read file FILENAME and output its doc strings to outfile. */
202 /* Return 1 if file is not found, 0 if it is found. */
205 scan_file (char *filename
)
207 int len
= strlen (filename
);
209 put_filename (filename
);
210 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
211 return scan_lisp_file (filename
, READ_BINARY
);
212 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
213 return scan_lisp_file (filename
, READ_TEXT
);
215 return scan_c_file (filename
, READ_TEXT
);
220 /* Some state during the execution of `read_c_string_or_comment'. */
223 /* A count of spaces and newlines that have been read, but not output. */
224 unsigned pending_spaces
, pending_newlines
;
226 /* Where we're reading from. */
229 /* If non-zero, a buffer into which to copy characters. */
231 /* If non-zero, a file into which to copy characters. */
234 /* A keyword we look for at the beginning of lines. If found, it is
235 not copied, and SAW_KEYWORD is set to true. */
237 /* The current point we've reached in an occurrence of KEYWORD in
239 const char *cur_keyword_ptr
;
240 /* Set to true if we saw an occurrence of KEYWORD. */
244 /* Output CH to the file or buffer in STATE. Any pending newlines or
245 spaces are output first. */
248 put_char (int ch
, struct rcsoc_state
*state
)
253 if (state
->pending_newlines
> 0)
255 state
->pending_newlines
--;
258 else if (state
->pending_spaces
> 0)
260 state
->pending_spaces
--;
267 putc (out_ch
, state
->out_file
);
269 *state
->buf_ptr
++ = out_ch
;
271 while (out_ch
!= ch
);
274 /* If in the middle of scanning a keyword, continue scanning with
275 character CH, otherwise output CH to the file or buffer in STATE.
276 Any pending newlines or spaces are output first, as well as any
277 previously scanned characters that were thought to be part of a
278 keyword, but were in fact not. */
281 scan_keyword_or_put_char (int ch
, struct rcsoc_state
*state
)
284 && *state
->cur_keyword_ptr
== ch
285 && (state
->cur_keyword_ptr
> state
->keyword
286 || state
->pending_newlines
> 0))
287 /* We might be looking at STATE->keyword at some point.
288 Keep looking until we know for sure. */
290 if (*++state
->cur_keyword_ptr
== '\0')
291 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
293 state
->saw_keyword
= 1;
295 /* Reset the scanning pointer. */
296 state
->cur_keyword_ptr
= state
->keyword
;
298 /* Canonicalize whitespace preceding a usage string. */
299 state
->pending_newlines
= 2;
300 state
->pending_spaces
= 0;
302 /* Skip any whitespace between the keyword and the
305 ch
= getc (state
->in_file
);
306 while (ch
== ' ' || ch
== '\n');
308 /* Output the open-paren we just read. */
309 put_char (ch
, state
);
311 /* Skip the function name and replace it with `fn'. */
313 ch
= getc (state
->in_file
);
314 while (ch
!= ' ' && ch
!= ')');
315 put_char ('f', state
);
316 put_char ('n', state
);
318 /* Put back the last character. */
319 ungetc (ch
, state
->in_file
);
324 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
325 /* We scanned the beginning of a potential usage
326 keyword, but it was a false alarm. Output the
331 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
332 put_char (*p
, state
);
334 state
->cur_keyword_ptr
= state
->keyword
;
337 put_char (ch
, state
);
342 /* Skip a C string or C-style comment from INFILE, and return the
343 character that follows. COMMENT non-zero means skip a comment. If
344 PRINTFLAG is positive, output string contents to outfile. If it is
345 negative, store contents in buf. Convert escape sequences \n and
346 \t to newline and tab; discard \ followed by newline.
347 If SAW_USAGE is non-zero, then any occurrences of the string `usage:'
348 at the beginning of a line will be removed, and *SAW_USAGE set to
349 true if any were encountered. */
352 read_c_string_or_comment (FILE *infile
, int printflag
, int comment
, int *saw_usage
)
355 struct rcsoc_state state
;
357 state
.in_file
= infile
;
358 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
359 state
.out_file
= (printflag
> 0 ? outfile
: 0);
360 state
.pending_spaces
= 0;
361 state
.pending_newlines
= 0;
362 state
.keyword
= (saw_usage
? "usage:" : 0);
363 state
.cur_keyword_ptr
= state
.keyword
;
364 state
.saw_keyword
= 0;
368 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
373 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
378 if (c
== '\n' || c
== '\r')
390 state
.pending_spaces
++;
393 state
.pending_newlines
++;
394 state
.pending_spaces
= 0;
397 scan_keyword_or_put_char (c
, &state
);
413 scan_keyword_or_put_char ('*', &state
);
420 /* If we had a "", concatenate the two strings. */
429 *saw_usage
= state
.saw_keyword
;
436 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
437 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
440 write_c_args (FILE *out
, char *func
, char *buf
, int minargs
, int maxargs
)
445 int ident_length
= 0;
447 fprintf (out
, "(fn");
452 for (p
= buf
; *p
; p
++)
456 /* Notice when a new identifier starts. */
457 if ((('A' <= c
&& c
<= 'Z')
458 || ('a' <= c
&& c
<= 'z')
459 || ('0' <= c
&& c
<= '9')
471 ident_length
= p
- ident_start
;
475 /* Found the end of an argument, write out the last seen
477 if (c
== ',' || c
== ')')
479 if (ident_length
== 0)
481 error ("empty arg list for `%s' should be (void), not ()", func
);
485 if (strncmp (ident_start
, "void", ident_length
) == 0)
490 if (minargs
== 0 && maxargs
> 0)
491 fprintf (out
, "&optional ");
496 /* In C code, `default' is a reserved word, so we spell it
497 `defalt'; unmangle that here. */
498 if (ident_length
== 6 && strncmp (ident_start
, "defalt", 6) == 0)
499 fprintf (out
, "DEFAULT");
501 while (ident_length
-- > 0)
504 if (c
>= 'a' && c
<= 'z')
505 /* Upcase the letter. */
508 /* Print underscore as hyphen. */
518 /* Read through a c file. If a .o file is named,
519 the corresponding .c or .m file is read instead.
520 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
521 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
524 scan_c_file (char *filename
, const char *mode
)
529 register int defunflag
;
530 register int defvarperbufferflag
;
531 register int defvarflag
;
532 int minargs
, maxargs
;
533 int extension
= filename
[strlen (filename
) - 1];
535 if (extension
== 'o')
536 filename
[strlen (filename
) - 1] = 'c';
538 infile
= fopen (filename
, mode
);
540 if (infile
== NULL
&& extension
== 'o')
543 filename
[strlen (filename
) - 1] = 'm';
544 infile
= fopen (filename
, mode
);
546 filename
[strlen (filename
) - 1] = 'c'; /* don't confuse people */
549 /* No error if non-ex input file */
556 /* Reset extension to be able to detect duplicate files. */
557 filename
[strlen (filename
) - 1] = extension
;
560 while (!feof (infile
))
564 if (c
!= '\n' && c
!= '\r')
599 defvarperbufferflag
= (c
== 'P');
612 defunflag
= c
== 'U';
614 defvarperbufferflag
= 0;
625 /* Lisp variable or function name. */
629 c
= read_c_string_or_comment (infile
, -1, 0, 0);
631 /* DEFVAR_LISP ("name", addr, "doc")
632 DEFVAR_LISP ("name", addr /\* doc *\/)
633 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
637 else if (defvarperbufferflag
)
641 else /* For DEFSIMPLE and DEFPRED */
650 if (defunflag
&& (commas
== 1 || commas
== 2))
654 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
658 if (commas
== 2) /* pick up minargs */
659 fscanf (infile
, "%d", &minargs
);
660 else /* pick up maxargs */
661 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
664 fscanf (infile
, "%d", &maxargs
);
673 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
677 c
= read_c_string_or_comment (infile
, 0, 0, 0);
679 while (c
!= EOF
&& c
!= ',' && c
!= '/')
684 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
686 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
692 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
699 && (c
= getc (infile
),
703 int comment
= c
!= '"';
707 putc (defvarflag
? 'V' : 'F', outfile
);
708 fprintf (outfile
, "%s\n", buf
);
711 getc (infile
); /* Skip past `*' */
712 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
714 /* If this is a defun, find the arguments and print them. If
715 this function takes MANY or UNEVALLED args, then the C source
716 won't give the names of the arguments, so we shouldn't bother
719 Various doc-string styles:
720 0: DEFUN (..., "DOC") (args) [!comment]
721 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
722 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
724 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
726 char argbuf
[1024], *p
= argbuf
;
728 if (!comment
|| doc_keyword
)
736 /* Skip into arguments. */
743 /* Copy arguments into ARGBUF. */
746 *p
++ = c
= getc (infile
);
750 fprintf (outfile
, "\n\n");
751 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
753 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
754 /* The DOC should provide the usage form. */
755 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
763 /* Read a file of Lisp code, compiled or interpreted.
765 (defun NAME ARGS DOCSTRING ...)
766 (defmacro NAME ARGS DOCSTRING ...)
767 (defsubst NAME ARGS DOCSTRING ...)
768 (autoload (quote NAME) FILE DOCSTRING ...)
769 (defvar NAME VALUE DOCSTRING)
770 (defconst NAME VALUE DOCSTRING)
771 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
772 (fset (quote NAME) #[... DOCSTRING ...])
773 (defalias (quote NAME) #[... DOCSTRING ...])
774 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
775 starting in column zero.
776 (quote NAME) may appear as 'NAME as well.
778 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
779 When we find that, we save it for the following defining-form,
780 and we use that instead of reading a doc string within that defining-form.
782 For defvar, defconst, and fset we skip to the docstring with a kludgy
783 formatting convention: all docstrings must appear on the same line as the
784 initial open-paren (the one in column zero) and must contain a backslash
785 and a newline immediately after the initial double-quote. No newlines
786 must appear between the beginning of the form and the first double-quote.
787 For defun, defmacro, and autoload, we know how to skip over the
788 arglist, but the doc string must still have a backslash and newline
789 immediately after the double quote.
790 The only source files that must follow this convention are preloaded
791 uncompiled ones like loaddefs.el and bindings.el; aside
792 from that, it is always the .elc file that we look at, and they are no
793 problem because byte-compiler output follows this convention.
794 The NAME and DOCSTRING are output.
795 NAME is preceded by `F' for a function or `V' for a variable.
796 An entry is output only if DOCSTRING has \ newline just after the opening "
800 skip_white (FILE *infile
)
803 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
809 read_lisp_symbol (FILE *infile
, char *buffer
)
812 char *fillp
= buffer
;
819 *(++fillp
) = getc (infile
);
820 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
831 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
837 scan_lisp_file (const char *filename
, const char *mode
)
841 char *saved_string
= 0;
843 infile
= fopen (filename
, mode
);
847 return 0; /* No error */
851 while (!feof (infile
))
856 /* If not at end of line, skip till we get to one. */
857 if (c
!= '\n' && c
!= '\r')
862 /* Skip the line break. */
863 while (c
== '\n' || c
== '\r')
865 /* Detect a dynamic doc string and save it for the next expression. */
874 /* Read the length. */
875 while ((c
= getc (infile
),
876 c
>= '0' && c
<= '9'))
882 /* The next character is a space that is counted in the length
883 but not part of the doc string.
884 We already read it, so just ignore it. */
887 /* Read in the contents. */
889 saved_string
= (char *) xmalloc (length
);
890 for (i
= 0; i
< length
; i
++)
891 saved_string
[i
] = getc (infile
);
892 /* The last character is a ^_.
893 That is needed in the .elc file
894 but it is redundant in DOC. So get rid of it here. */
895 saved_string
[length
- 1] = 0;
896 /* Skip the line break. */
897 while (c
== '\n' && c
== '\r')
899 /* Skip the following line. */
900 while (c
!= '\n' && c
!= '\r')
909 read_lisp_symbol (infile
, buffer
);
911 if (! strcmp (buffer
, "defun")
912 || ! strcmp (buffer
, "defmacro")
913 || ! strcmp (buffer
, "defsubst"))
916 read_lisp_symbol (infile
, buffer
);
918 /* Skip the arguments: either "nil" or a list in parens */
921 if (c
== 'n') /* nil */
923 if ((c
= getc (infile
)) != 'i'
924 || (c
= getc (infile
)) != 'l')
926 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
933 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
942 /* If the next three characters aren't `dquote bslash newline'
943 then we're not reading a docstring.
945 if ((c
= getc (infile
)) != '"'
946 || (c
= getc (infile
)) != '\\'
947 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
950 fprintf (stderr
, "## non-docstring in %s (%s)\n",
957 else if (! strcmp (buffer
, "defvar")
958 || ! strcmp (buffer
, "defconst"))
962 read_lisp_symbol (infile
, buffer
);
964 if (saved_string
== 0)
967 /* Skip until the end of line; remember two previous chars. */
968 while (c
!= '\n' && c
!= '\r' && c
>= 0)
975 /* If two previous characters were " and \,
976 this is a doc string. Otherwise, there is none. */
977 if (c2
!= '"' || c1
!= '\\')
980 fprintf (stderr
, "## non-docstring in %s (%s)\n",
988 else if (! strcmp (buffer
, "custom-declare-variable")
989 || ! strcmp (buffer
, "defvaralias")
997 read_lisp_symbol (infile
, buffer
);
1003 "## unparsable name in custom-declare-variable in %s\n",
1007 read_lisp_symbol (infile
, buffer
);
1008 if (strcmp (buffer
, "quote"))
1011 "## unparsable name in custom-declare-variable in %s\n",
1015 read_lisp_symbol (infile
, buffer
);
1020 "## unparsable quoted name in custom-declare-variable in %s\n",
1026 if (saved_string
== 0)
1028 /* Skip to end of line; remember the two previous chars. */
1029 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1036 /* If two previous characters were " and \,
1037 this is a doc string. Otherwise, there is none. */
1038 if (c2
!= '"' || c1
!= '\\')
1041 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1049 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1051 char c1
= 0, c2
= 0;
1056 read_lisp_symbol (infile
, buffer
);
1061 fprintf (stderr
, "## unparsable name in fset in %s\n",
1065 read_lisp_symbol (infile
, buffer
);
1066 if (strcmp (buffer
, "quote"))
1068 fprintf (stderr
, "## unparsable name in fset in %s\n",
1072 read_lisp_symbol (infile
, buffer
);
1077 "## unparsable quoted name in fset in %s\n",
1083 if (saved_string
== 0)
1085 /* Skip to end of line; remember the two previous chars. */
1086 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1093 /* If two previous characters were " and \,
1094 this is a doc string. Otherwise, there is none. */
1095 if (c2
!= '"' || c1
!= '\\')
1098 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1106 else if (! strcmp (buffer
, "autoload"))
1111 read_lisp_symbol (infile
, buffer
);
1116 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1120 read_lisp_symbol (infile
, buffer
);
1121 if (strcmp (buffer
, "quote"))
1123 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1127 read_lisp_symbol (infile
, buffer
);
1132 "## unparsable quoted name in autoload in %s\n",
1137 skip_white (infile
);
1138 if ((c
= getc (infile
)) != '\"')
1140 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1144 read_c_string_or_comment (infile
, 0, 0, 0);
1145 skip_white (infile
);
1147 if (saved_string
== 0)
1149 /* If the next three characters aren't `dquote bslash newline'
1150 then we're not reading a docstring. */
1151 if ((c
= getc (infile
)) != '"'
1152 || (c
= getc (infile
)) != '\\'
1153 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1156 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1165 else if (! strcmp (buffer
, "if")
1166 || ! strcmp (buffer
, "byte-code"))
1173 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1179 /* At this point, we should either use the previous
1180 dynamic doc string in saved_string
1181 or gobble a doc string from the input file.
1183 In the latter case, the opening quote (and leading
1184 backslash-newline) have already been read. */
1186 putc (037, outfile
);
1187 putc (type
, outfile
);
1188 fprintf (outfile
, "%s\n", buffer
);
1191 fputs (saved_string
, outfile
);
1192 /* Don't use one dynamic doc string twice. */
1193 free (saved_string
);
1197 read_c_string_or_comment (infile
, 1, 0, 0);
1203 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1204 (do not change this comment) */
1206 /* make-docfile.c ends here */