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 (char *filename
, char *mode
);
72 int scan_c_file (char *filename
, char *mode
);
73 void fatal (char *s1
, 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 (char *s1
, char *s2
)
97 fprintf (stderr
, "%s: ", progname
);
98 fprintf (stderr
, s1
, s2
);
99 fprintf (stderr
, "\n");
102 /* Print error message and exit. */
106 fatal (char *s1
, 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 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
)
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 (strncmp (ident_start
, "void", ident_length
) == 0)
484 if (minargs
== 0 && maxargs
> 0)
485 fprintf (out
, "&optional ");
490 /* In C code, `default' is a reserved word, so we spell it
491 `defalt'; unmangle that here. */
492 if (ident_length
== 6 && strncmp (ident_start
, "defalt", 6) == 0)
493 fprintf (out
, "DEFAULT");
495 while (ident_length
-- > 0)
498 if (c
>= 'a' && c
<= 'z')
499 /* Upcase the letter. */
502 /* Print underscore as hyphen. */
512 /* Read through a c file. If a .o file is named,
513 the corresponding .c or .m file is read instead.
514 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
515 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
518 scan_c_file (char *filename
, char *mode
)
523 register int defunflag
;
524 register int defvarperbufferflag
;
525 register int defvarflag
;
526 int minargs
, maxargs
;
527 int extension
= filename
[strlen (filename
) - 1];
529 if (extension
== 'o')
530 filename
[strlen (filename
) - 1] = 'c';
532 infile
= fopen (filename
, mode
);
534 if (infile
== NULL
&& extension
== 'o')
537 filename
[strlen (filename
) - 1] = 'm';
538 infile
= fopen (filename
, mode
);
540 filename
[strlen (filename
) - 1] = 'c'; /* don't confuse people */
543 /* No error if non-ex input file */
550 /* Reset extension to be able to detect duplicate files. */
551 filename
[strlen (filename
) - 1] = extension
;
554 while (!feof (infile
))
558 if (c
!= '\n' && c
!= '\r')
593 defvarperbufferflag
= (c
== 'P');
606 defunflag
= c
== 'U';
608 defvarperbufferflag
= 0;
619 /* Lisp variable or function name. */
623 c
= read_c_string_or_comment (infile
, -1, 0, 0);
625 /* DEFVAR_LISP ("name", addr, "doc")
626 DEFVAR_LISP ("name", addr /\* doc *\/)
627 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
631 else if (defvarperbufferflag
)
635 else /* For DEFSIMPLE and DEFPRED */
644 if (defunflag
&& (commas
== 1 || commas
== 2))
648 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
652 if (commas
== 2) /* pick up minargs */
653 fscanf (infile
, "%d", &minargs
);
654 else /* pick up maxargs */
655 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
658 fscanf (infile
, "%d", &maxargs
);
667 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
671 c
= read_c_string_or_comment (infile
, 0, 0, 0);
673 while (c
!= EOF
&& c
!= ',' && c
!= '/')
678 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
680 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
686 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
693 && (c
= getc (infile
),
697 int comment
= c
!= '"';
701 putc (defvarflag
? 'V' : 'F', outfile
);
702 fprintf (outfile
, "%s\n", buf
);
705 getc (infile
); /* Skip past `*' */
706 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
708 /* If this is a defun, find the arguments and print them. If
709 this function takes MANY or UNEVALLED args, then the C source
710 won't give the names of the arguments, so we shouldn't bother
713 Various doc-string styles:
714 0: DEFUN (..., "DOC") (args) [!comment]
715 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
716 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
718 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
720 char argbuf
[1024], *p
= argbuf
;
722 if (!comment
|| doc_keyword
)
730 /* Skip into arguments. */
737 /* Copy arguments into ARGBUF. */
740 *p
++ = c
= getc (infile
);
744 fprintf (outfile
, "\n\n");
745 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
747 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
748 /* The DOC should provide the usage form. */
749 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
757 /* Read a file of Lisp code, compiled or interpreted.
759 (defun NAME ARGS DOCSTRING ...)
760 (defmacro NAME ARGS DOCSTRING ...)
761 (defsubst NAME ARGS DOCSTRING ...)
762 (autoload (quote NAME) FILE DOCSTRING ...)
763 (defvar NAME VALUE DOCSTRING)
764 (defconst NAME VALUE DOCSTRING)
765 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
766 (fset (quote NAME) #[... DOCSTRING ...])
767 (defalias (quote NAME) #[... DOCSTRING ...])
768 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
769 starting in column zero.
770 (quote NAME) may appear as 'NAME as well.
772 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
773 When we find that, we save it for the following defining-form,
774 and we use that instead of reading a doc string within that defining-form.
776 For defvar, defconst, and fset we skip to the docstring with a kludgy
777 formatting convention: all docstrings must appear on the same line as the
778 initial open-paren (the one in column zero) and must contain a backslash
779 and a newline immediately after the initial double-quote. No newlines
780 must appear between the beginning of the form and the first double-quote.
781 For defun, defmacro, and autoload, we know how to skip over the
782 arglist, but the doc string must still have a backslash and newline
783 immediately after the double quote.
784 The only source files that must follow this convention are preloaded
785 uncompiled ones like loaddefs.el and bindings.el; aside
786 from that, it is always the .elc file that we look at, and they are no
787 problem because byte-compiler output follows this convention.
788 The NAME and DOCSTRING are output.
789 NAME is preceded by `F' for a function or `V' for a variable.
790 An entry is output only if DOCSTRING has \ newline just after the opening "
794 skip_white (FILE *infile
)
797 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
803 read_lisp_symbol (FILE *infile
, char *buffer
)
806 char *fillp
= buffer
;
813 *(++fillp
) = getc (infile
);
814 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
825 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
831 scan_lisp_file (char *filename
, char *mode
)
835 char *saved_string
= 0;
837 infile
= fopen (filename
, mode
);
841 return 0; /* No error */
845 while (!feof (infile
))
850 /* If not at end of line, skip till we get to one. */
851 if (c
!= '\n' && c
!= '\r')
856 /* Skip the line break. */
857 while (c
== '\n' || c
== '\r')
859 /* Detect a dynamic doc string and save it for the next expression. */
868 /* Read the length. */
869 while ((c
= getc (infile
),
870 c
>= '0' && c
<= '9'))
876 /* The next character is a space that is counted in the length
877 but not part of the doc string.
878 We already read it, so just ignore it. */
881 /* Read in the contents. */
883 saved_string
= (char *) xmalloc (length
);
884 for (i
= 0; i
< length
; i
++)
885 saved_string
[i
] = getc (infile
);
886 /* The last character is a ^_.
887 That is needed in the .elc file
888 but it is redundant in DOC. So get rid of it here. */
889 saved_string
[length
- 1] = 0;
890 /* Skip the line break. */
891 while (c
== '\n' && c
== '\r')
893 /* Skip the following line. */
894 while (c
!= '\n' && c
!= '\r')
903 read_lisp_symbol (infile
, buffer
);
905 if (! strcmp (buffer
, "defun")
906 || ! strcmp (buffer
, "defmacro")
907 || ! strcmp (buffer
, "defsubst"))
910 read_lisp_symbol (infile
, buffer
);
912 /* Skip the arguments: either "nil" or a list in parens */
915 if (c
== 'n') /* nil */
917 if ((c
= getc (infile
)) != 'i'
918 || (c
= getc (infile
)) != 'l')
920 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
927 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
936 /* If the next three characters aren't `dquote bslash newline'
937 then we're not reading a docstring.
939 if ((c
= getc (infile
)) != '"'
940 || (c
= getc (infile
)) != '\\'
941 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
944 fprintf (stderr
, "## non-docstring in %s (%s)\n",
951 else if (! strcmp (buffer
, "defvar")
952 || ! strcmp (buffer
, "defconst"))
956 read_lisp_symbol (infile
, buffer
);
958 if (saved_string
== 0)
961 /* Skip until the end of line; remember two previous chars. */
962 while (c
!= '\n' && c
!= '\r' && c
>= 0)
969 /* If two previous characters were " and \,
970 this is a doc string. Otherwise, there is none. */
971 if (c2
!= '"' || c1
!= '\\')
974 fprintf (stderr
, "## non-docstring in %s (%s)\n",
982 else if (! strcmp (buffer
, "custom-declare-variable")
983 || ! strcmp (buffer
, "defvaralias")
991 read_lisp_symbol (infile
, buffer
);
997 "## unparsable name in custom-declare-variable in %s\n",
1001 read_lisp_symbol (infile
, buffer
);
1002 if (strcmp (buffer
, "quote"))
1005 "## unparsable name in custom-declare-variable in %s\n",
1009 read_lisp_symbol (infile
, buffer
);
1014 "## unparsable quoted name in custom-declare-variable in %s\n",
1020 if (saved_string
== 0)
1022 /* Skip to end of line; remember the two previous chars. */
1023 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1030 /* If two previous characters were " and \,
1031 this is a doc string. Otherwise, there is none. */
1032 if (c2
!= '"' || c1
!= '\\')
1035 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1043 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1045 char c1
= 0, c2
= 0;
1050 read_lisp_symbol (infile
, buffer
);
1055 fprintf (stderr
, "## unparsable name in fset in %s\n",
1059 read_lisp_symbol (infile
, buffer
);
1060 if (strcmp (buffer
, "quote"))
1062 fprintf (stderr
, "## unparsable name in fset in %s\n",
1066 read_lisp_symbol (infile
, buffer
);
1071 "## unparsable quoted name in fset in %s\n",
1077 if (saved_string
== 0)
1079 /* Skip to end of line; remember the two previous chars. */
1080 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1087 /* If two previous characters were " and \,
1088 this is a doc string. Otherwise, there is none. */
1089 if (c2
!= '"' || c1
!= '\\')
1092 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1100 else if (! strcmp (buffer
, "autoload"))
1105 read_lisp_symbol (infile
, buffer
);
1110 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1114 read_lisp_symbol (infile
, buffer
);
1115 if (strcmp (buffer
, "quote"))
1117 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1121 read_lisp_symbol (infile
, buffer
);
1126 "## unparsable quoted name in autoload in %s\n",
1131 skip_white (infile
);
1132 if ((c
= getc (infile
)) != '\"')
1134 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1138 read_c_string_or_comment (infile
, 0, 0, 0);
1139 skip_white (infile
);
1141 if (saved_string
== 0)
1143 /* If the next three characters aren't `dquote bslash newline'
1144 then we're not reading a docstring. */
1145 if ((c
= getc (infile
)) != '"'
1146 || (c
= getc (infile
)) != '\\'
1147 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1150 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1159 else if (! strcmp (buffer
, "if")
1160 || ! strcmp (buffer
, "byte-code"))
1167 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1173 /* At this point, we should either use the previous
1174 dynamic doc string in saved_string
1175 or gobble a doc string from the input file.
1177 In the latter case, the opening quote (and leading
1178 backslash-newline) have already been read. */
1180 putc (037, outfile
);
1181 putc (type
, outfile
);
1182 fprintf (outfile
, "%s\n", buffer
);
1185 fputs (saved_string
, outfile
);
1186 /* Don't use one dynamic doc string twice. */
1187 free (saved_string
);
1191 read_c_string_or_comment (infile
, 1, 0, 0);
1197 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1198 (do not change this comment) */
1200 /* make-docfile.c ends here */