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
)
208 size_t len
= strlen (filename
);
210 put_filename (filename
);
211 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
212 return scan_lisp_file (filename
, READ_BINARY
);
213 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
214 return scan_lisp_file (filename
, READ_TEXT
);
216 return scan_c_file (filename
, READ_TEXT
);
221 /* Some state during the execution of `read_c_string_or_comment'. */
224 /* A count of spaces and newlines that have been read, but not output. */
225 unsigned pending_spaces
, pending_newlines
;
227 /* Where we're reading from. */
230 /* If non-zero, a buffer into which to copy characters. */
232 /* If non-zero, a file into which to copy characters. */
235 /* A keyword we look for at the beginning of lines. If found, it is
236 not copied, and SAW_KEYWORD is set to true. */
238 /* The current point we've reached in an occurrence of KEYWORD in
240 const char *cur_keyword_ptr
;
241 /* Set to true if we saw an occurrence of KEYWORD. */
245 /* Output CH to the file or buffer in STATE. Any pending newlines or
246 spaces are output first. */
249 put_char (int ch
, struct rcsoc_state
*state
)
254 if (state
->pending_newlines
> 0)
256 state
->pending_newlines
--;
259 else if (state
->pending_spaces
> 0)
261 state
->pending_spaces
--;
268 putc (out_ch
, state
->out_file
);
270 *state
->buf_ptr
++ = out_ch
;
272 while (out_ch
!= ch
);
275 /* If in the middle of scanning a keyword, continue scanning with
276 character CH, otherwise output CH to the file or buffer in STATE.
277 Any pending newlines or spaces are output first, as well as any
278 previously scanned characters that were thought to be part of a
279 keyword, but were in fact not. */
282 scan_keyword_or_put_char (int ch
, struct rcsoc_state
*state
)
285 && *state
->cur_keyword_ptr
== ch
286 && (state
->cur_keyword_ptr
> state
->keyword
287 || state
->pending_newlines
> 0))
288 /* We might be looking at STATE->keyword at some point.
289 Keep looking until we know for sure. */
291 if (*++state
->cur_keyword_ptr
== '\0')
292 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
294 state
->saw_keyword
= 1;
296 /* Reset the scanning pointer. */
297 state
->cur_keyword_ptr
= state
->keyword
;
299 /* Canonicalize whitespace preceding a usage string. */
300 state
->pending_newlines
= 2;
301 state
->pending_spaces
= 0;
303 /* Skip any whitespace between the keyword and the
306 ch
= getc (state
->in_file
);
307 while (ch
== ' ' || ch
== '\n');
309 /* Output the open-paren we just read. */
310 put_char (ch
, state
);
312 /* Skip the function name and replace it with `fn'. */
314 ch
= getc (state
->in_file
);
315 while (ch
!= ' ' && ch
!= ')');
316 put_char ('f', state
);
317 put_char ('n', state
);
319 /* Put back the last character. */
320 ungetc (ch
, state
->in_file
);
325 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
326 /* We scanned the beginning of a potential usage
327 keyword, but it was a false alarm. Output the
332 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
333 put_char (*p
, state
);
335 state
->cur_keyword_ptr
= state
->keyword
;
338 put_char (ch
, state
);
343 /* Skip a C string or C-style comment from INFILE, and return the
344 character that follows. COMMENT non-zero means skip a comment. If
345 PRINTFLAG is positive, output string contents to outfile. If it is
346 negative, store contents in buf. Convert escape sequences \n and
347 \t to newline and tab; discard \ followed by newline.
348 If SAW_USAGE is non-zero, then any occurrences of the string `usage:'
349 at the beginning of a line will be removed, and *SAW_USAGE set to
350 true if any were encountered. */
353 read_c_string_or_comment (FILE *infile
, int printflag
, int comment
, int *saw_usage
)
356 struct rcsoc_state state
;
358 state
.in_file
= infile
;
359 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
360 state
.out_file
= (printflag
> 0 ? outfile
: 0);
361 state
.pending_spaces
= 0;
362 state
.pending_newlines
= 0;
363 state
.keyword
= (saw_usage
? "usage:" : 0);
364 state
.cur_keyword_ptr
= state
.keyword
;
365 state
.saw_keyword
= 0;
369 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
374 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
379 if (c
== '\n' || c
== '\r')
391 state
.pending_spaces
++;
394 state
.pending_newlines
++;
395 state
.pending_spaces
= 0;
398 scan_keyword_or_put_char (c
, &state
);
414 scan_keyword_or_put_char ('*', &state
);
421 /* If we had a "", concatenate the two strings. */
430 *saw_usage
= state
.saw_keyword
;
437 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
438 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
441 write_c_args (FILE *out
, char *func
, char *buf
, int minargs
, int maxargs
)
446 size_t ident_length
= 0;
448 fprintf (out
, "(fn");
453 for (p
= buf
; *p
; p
++)
457 /* Notice when a new identifier starts. */
458 if ((('A' <= c
&& c
<= 'Z')
459 || ('a' <= c
&& c
<= 'z')
460 || ('0' <= c
&& c
<= '9')
472 ident_length
= p
- ident_start
;
476 /* Found the end of an argument, write out the last seen
478 if (c
== ',' || c
== ')')
480 if (ident_length
== 0)
482 error ("empty arg list for `%s' should be (void), not ()", func
);
486 if (strncmp (ident_start
, "void", ident_length
) == 0)
491 if (minargs
== 0 && maxargs
> 0)
492 fprintf (out
, "&optional ");
497 /* In C code, `default' is a reserved word, so we spell it
498 `defalt'; unmangle that here. */
499 if (ident_length
== 6 && strncmp (ident_start
, "defalt", 6) == 0)
500 fprintf (out
, "DEFAULT");
502 while (ident_length
-- > 0)
505 if (c
>= 'a' && c
<= 'z')
506 /* Upcase the letter. */
509 /* Print underscore as hyphen. */
519 /* Read through a c file. If a .o file is named,
520 the corresponding .c or .m file is read instead.
521 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
522 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
525 scan_c_file (char *filename
, const char *mode
)
530 register int defunflag
;
531 register int defvarperbufferflag
;
532 register int defvarflag
;
533 int minargs
, maxargs
;
534 int extension
= filename
[strlen (filename
) - 1];
536 if (extension
== 'o')
537 filename
[strlen (filename
) - 1] = 'c';
539 infile
= fopen (filename
, mode
);
541 if (infile
== NULL
&& extension
== 'o')
544 filename
[strlen (filename
) - 1] = 'm';
545 infile
= fopen (filename
, mode
);
547 filename
[strlen (filename
) - 1] = 'c'; /* don't confuse people */
550 /* No error if non-ex input file */
557 /* Reset extension to be able to detect duplicate files. */
558 filename
[strlen (filename
) - 1] = extension
;
561 while (!feof (infile
))
565 if (c
!= '\n' && c
!= '\r')
600 defvarperbufferflag
= (c
== 'P');
613 defunflag
= c
== 'U';
615 defvarperbufferflag
= 0;
626 /* Lisp variable or function name. */
630 c
= read_c_string_or_comment (infile
, -1, 0, 0);
632 /* DEFVAR_LISP ("name", addr, "doc")
633 DEFVAR_LISP ("name", addr /\* doc *\/)
634 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
638 else if (defvarperbufferflag
)
642 else /* For DEFSIMPLE and DEFPRED */
651 if (defunflag
&& (commas
== 1 || commas
== 2))
655 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
659 if (commas
== 2) /* pick up minargs */
660 fscanf (infile
, "%d", &minargs
);
661 else /* pick up maxargs */
662 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
665 fscanf (infile
, "%d", &maxargs
);
674 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
678 c
= read_c_string_or_comment (infile
, 0, 0, 0);
680 while (c
!= EOF
&& c
!= ',' && c
!= '/')
685 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
687 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
693 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
700 && (c
= getc (infile
),
704 int comment
= c
!= '"';
708 putc (defvarflag
? 'V' : 'F', outfile
);
709 fprintf (outfile
, "%s\n", buf
);
712 getc (infile
); /* Skip past `*' */
713 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
715 /* If this is a defun, find the arguments and print them. If
716 this function takes MANY or UNEVALLED args, then the C source
717 won't give the names of the arguments, so we shouldn't bother
720 Various doc-string styles:
721 0: DEFUN (..., "DOC") (args) [!comment]
722 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
723 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
725 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
727 char argbuf
[1024], *p
= argbuf
;
729 if (!comment
|| doc_keyword
)
737 /* Skip into arguments. */
744 /* Copy arguments into ARGBUF. */
747 *p
++ = c
= getc (infile
);
751 fprintf (outfile
, "\n\n");
752 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
754 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
755 /* The DOC should provide the usage form. */
756 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
764 /* Read a file of Lisp code, compiled or interpreted.
766 (defun NAME ARGS DOCSTRING ...)
767 (defmacro NAME ARGS DOCSTRING ...)
768 (defsubst NAME ARGS DOCSTRING ...)
769 (autoload (quote NAME) FILE DOCSTRING ...)
770 (defvar NAME VALUE DOCSTRING)
771 (defconst NAME VALUE DOCSTRING)
772 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
773 (fset (quote NAME) #[... DOCSTRING ...])
774 (defalias (quote NAME) #[... DOCSTRING ...])
775 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
776 starting in column zero.
777 (quote NAME) may appear as 'NAME as well.
779 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
780 When we find that, we save it for the following defining-form,
781 and we use that instead of reading a doc string within that defining-form.
783 For defvar, defconst, and fset we skip to the docstring with a kludgy
784 formatting convention: all docstrings must appear on the same line as the
785 initial open-paren (the one in column zero) and must contain a backslash
786 and a newline immediately after the initial double-quote. No newlines
787 must appear between the beginning of the form and the first double-quote.
788 For defun, defmacro, and autoload, we know how to skip over the
789 arglist, but the doc string must still have a backslash and newline
790 immediately after the double quote.
791 The only source files that must follow this convention are preloaded
792 uncompiled ones like loaddefs.el and bindings.el; aside
793 from that, it is always the .elc file that we look at, and they are no
794 problem because byte-compiler output follows this convention.
795 The NAME and DOCSTRING are output.
796 NAME is preceded by `F' for a function or `V' for a variable.
797 An entry is output only if DOCSTRING has \ newline just after the opening "
801 skip_white (FILE *infile
)
804 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
810 read_lisp_symbol (FILE *infile
, char *buffer
)
813 char *fillp
= buffer
;
820 *(++fillp
) = getc (infile
);
821 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
832 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
838 scan_lisp_file (const char *filename
, const char *mode
)
842 char *saved_string
= 0;
844 infile
= fopen (filename
, mode
);
848 return 0; /* No error */
852 while (!feof (infile
))
857 /* If not at end of line, skip till we get to one. */
858 if (c
!= '\n' && c
!= '\r')
863 /* Skip the line break. */
864 while (c
== '\n' || c
== '\r')
866 /* Detect a dynamic doc string and save it for the next expression. */
875 /* Read the length. */
876 while ((c
= getc (infile
),
877 c
>= '0' && c
<= '9'))
883 /* The next character is a space that is counted in the length
884 but not part of the doc string.
885 We already read it, so just ignore it. */
888 /* Read in the contents. */
890 saved_string
= (char *) xmalloc (length
);
891 for (i
= 0; i
< length
; i
++)
892 saved_string
[i
] = getc (infile
);
893 /* The last character is a ^_.
894 That is needed in the .elc file
895 but it is redundant in DOC. So get rid of it here. */
896 saved_string
[length
- 1] = 0;
897 /* Skip the line break. */
898 while (c
== '\n' && c
== '\r')
900 /* Skip the following line. */
901 while (c
!= '\n' && c
!= '\r')
910 read_lisp_symbol (infile
, buffer
);
912 if (! strcmp (buffer
, "defun")
913 || ! strcmp (buffer
, "defmacro")
914 || ! strcmp (buffer
, "defsubst"))
917 read_lisp_symbol (infile
, buffer
);
919 /* Skip the arguments: either "nil" or a list in parens */
922 if (c
== 'n') /* nil */
924 if ((c
= getc (infile
)) != 'i'
925 || (c
= getc (infile
)) != 'l')
927 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
934 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
943 /* If the next three characters aren't `dquote bslash newline'
944 then we're not reading a docstring.
946 if ((c
= getc (infile
)) != '"'
947 || (c
= getc (infile
)) != '\\'
948 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
951 fprintf (stderr
, "## non-docstring in %s (%s)\n",
958 else if (! strcmp (buffer
, "defvar")
959 || ! strcmp (buffer
, "defconst"))
963 read_lisp_symbol (infile
, buffer
);
965 if (saved_string
== 0)
968 /* Skip until the end of line; remember two previous chars. */
969 while (c
!= '\n' && c
!= '\r' && c
>= 0)
976 /* If two previous characters were " and \,
977 this is a doc string. Otherwise, there is none. */
978 if (c2
!= '"' || c1
!= '\\')
981 fprintf (stderr
, "## non-docstring in %s (%s)\n",
989 else if (! strcmp (buffer
, "custom-declare-variable")
990 || ! strcmp (buffer
, "defvaralias")
998 read_lisp_symbol (infile
, buffer
);
1004 "## unparsable name in custom-declare-variable in %s\n",
1008 read_lisp_symbol (infile
, buffer
);
1009 if (strcmp (buffer
, "quote"))
1012 "## unparsable name in custom-declare-variable in %s\n",
1016 read_lisp_symbol (infile
, buffer
);
1021 "## unparsable quoted name in custom-declare-variable in %s\n",
1027 if (saved_string
== 0)
1029 /* Skip to end of line; remember the two previous chars. */
1030 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1037 /* If two previous characters were " and \,
1038 this is a doc string. Otherwise, there is none. */
1039 if (c2
!= '"' || c1
!= '\\')
1042 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1050 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1052 char c1
= 0, c2
= 0;
1057 read_lisp_symbol (infile
, buffer
);
1062 fprintf (stderr
, "## unparsable name in fset in %s\n",
1066 read_lisp_symbol (infile
, buffer
);
1067 if (strcmp (buffer
, "quote"))
1069 fprintf (stderr
, "## unparsable name in fset in %s\n",
1073 read_lisp_symbol (infile
, buffer
);
1078 "## unparsable quoted name in fset in %s\n",
1084 if (saved_string
== 0)
1086 /* Skip to end of line; remember the two previous chars. */
1087 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1094 /* If two previous characters were " and \,
1095 this is a doc string. Otherwise, there is none. */
1096 if (c2
!= '"' || c1
!= '\\')
1099 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1107 else if (! strcmp (buffer
, "autoload"))
1112 read_lisp_symbol (infile
, buffer
);
1117 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1121 read_lisp_symbol (infile
, buffer
);
1122 if (strcmp (buffer
, "quote"))
1124 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1128 read_lisp_symbol (infile
, buffer
);
1133 "## unparsable quoted name in autoload in %s\n",
1138 skip_white (infile
);
1139 if ((c
= getc (infile
)) != '\"')
1141 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1145 read_c_string_or_comment (infile
, 0, 0, 0);
1146 skip_white (infile
);
1148 if (saved_string
== 0)
1150 /* If the next three characters aren't `dquote bslash newline'
1151 then we're not reading a docstring. */
1152 if ((c
= getc (infile
)) != '"'
1153 || (c
= getc (infile
)) != '\\'
1154 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1157 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1166 else if (! strcmp (buffer
, "if")
1167 || ! strcmp (buffer
, "byte-code"))
1174 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1180 /* At this point, we should either use the previous
1181 dynamic doc string in saved_string
1182 or gobble a doc string from the input file.
1184 In the latter case, the opening quote (and leading
1185 backslash-newline) have already been read. */
1187 putc (037, outfile
);
1188 putc (type
, outfile
);
1189 fprintf (outfile
, "%s\n", buffer
);
1192 fputs (saved_string
, outfile
);
1193 /* Don't use one dynamic doc string twice. */
1194 free (saved_string
);
1198 read_c_string_or_comment (infile
, 1, 0, 0);
1204 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1205 (do not change this comment) */
1207 /* make-docfile.c ends here */