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
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, or (at your option)
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; see the file COPYING. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA. */
23 /* The arguments given to this program are all the C and Lisp source files
24 of GNU Emacs. .elc and .el and .c files are allowed.
25 A .o file can also be specified; the .c file it was made from is used.
26 This helps the makefile pass the correct list of files.
27 Option -d DIR means change to DIR before looking for files.
29 The results, which go to standard output or to a file
30 specified with -a or -o (-a to append, -o to start from nothing),
31 are entries containing function or variable names and their documentation.
32 Each entry starts with a ^_ character.
33 Then comes F for a function or V for a variable.
34 Then comes the function or variable name, terminated with a newline.
35 Then comes the documentation for that function or variable.
38 #define NO_SHORTNAMES /* Tell config not to load remap.h */
41 /* defined to be emacs_main, sys_fopen, etc. in config.h */
54 #endif /* WINDOWSNT */
57 #define READ_TEXT "rt"
58 #define READ_BINARY "rb"
59 #else /* not DOS_NT */
61 #define READ_BINARY "r"
62 #endif /* not DOS_NT */
66 #define DIRECTORY_SEP ':'
67 #else /* not MAC_OS8 */
68 #define DIRECTORY_SEP '/'
69 #endif /* not MAC_OS8 */
72 #ifndef IS_DIRECTORY_SEP
73 #define IS_DIRECTORY_SEP(_c_) ((_c_) == DIRECTORY_SEP)
77 int scan_lisp_file ();
81 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
82 file where that function is defined. */
90 /* Stdio stream for output to the DOC file. */
93 /* Name this program was invoked with. */
96 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
103 fprintf (stderr
, "%s: ", progname
);
104 fprintf (stderr
, s1
, s2
);
105 fprintf (stderr
, "\n");
108 /* Print error message and exit. */
119 /* Like malloc but get fatal error if memory is exhausted. */
125 void *result
= (void *) malloc (size
);
127 fatal ("virtual memory exhausted", 0);
144 /* Don't put CRs in the DOC file. */
147 #if 0 /* Suspicion is that this causes hanging.
148 So instead we require people to use -o on MSDOS. */
149 (stdout
)->_flag
&= ~_IOTEXT
;
150 _setmode (fileno (stdout
), O_BINARY
);
156 _setmode (fileno (stdout
), O_BINARY
);
157 #endif /* WINDOWSNT */
159 /* If first two args are -o FILE, output to FILE. */
161 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
163 outfile
= fopen (argv
[i
+ 1], "w");
166 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
168 outfile
= fopen (argv
[i
+ 1], "a");
171 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
178 fatal ("No output file specified", "");
181 for (; i
< argc
; i
++)
184 /* Don't process one file twice. */
185 for (j
= first_infile
; j
< i
; j
++)
186 if (! strcmp (argv
[i
], argv
[j
]))
189 err_count
+= scan_file (argv
[i
]);
191 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
194 /* Add a source file name boundary marker in the output file. */
196 put_filename (filename
)
201 for (tmp
= filename
; *tmp
; tmp
++)
203 if (IS_DIRECTORY_SEP(*tmp
))
209 fprintf (outfile
, "%s\n", filename
);
212 /* Read file FILENAME and output its doc strings to outfile. */
213 /* Return 1 if file is not found, 0 if it is found. */
219 int len
= strlen (filename
);
221 put_filename (filename
);
222 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
223 return scan_lisp_file (filename
, READ_BINARY
);
224 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
225 return scan_lisp_file (filename
, READ_TEXT
);
227 return scan_c_file (filename
, READ_TEXT
);
232 /* Some state during the execution of `read_c_string_or_comment'. */
235 /* A count of spaces and newlines that have been read, but not output. */
236 unsigned pending_spaces
, pending_newlines
;
238 /* Where we're reading from. */
241 /* If non-zero, a buffer into which to copy characters. */
243 /* If non-zero, a file into which to copy characters. */
246 /* A keyword we look for at the beginning of lines. If found, it is
247 not copied, and SAW_KEYWORD is set to true. */
249 /* The current point we've reached in an occurance of KEYWORD in
251 char *cur_keyword_ptr
;
252 /* Set to true if we saw an occurance of KEYWORD. */
256 /* Output CH to the file or buffer in STATE. Any pending newlines or
257 spaces are output first. */
262 struct rcsoc_state
*state
;
267 if (state
->pending_newlines
> 0)
269 state
->pending_newlines
--;
272 else if (state
->pending_spaces
> 0)
274 state
->pending_spaces
--;
281 putc (out_ch
, state
->out_file
);
283 *state
->buf_ptr
++ = out_ch
;
285 while (out_ch
!= ch
);
288 /* If in the middle of scanning a keyword, continue scanning with
289 character CH, otherwise output CH to the file or buffer in STATE.
290 Any pending newlines or spaces are output first, as well as any
291 previously scanned characters that were thought to be part of a
292 keyword, but were in fact not. */
295 scan_keyword_or_put_char (ch
, state
)
297 struct rcsoc_state
*state
;
300 && *state
->cur_keyword_ptr
== ch
301 && (state
->cur_keyword_ptr
> state
->keyword
302 || state
->pending_newlines
> 0))
303 /* We might be looking at STATE->keyword at some point.
304 Keep looking until we know for sure. */
306 if (*++state
->cur_keyword_ptr
== '\0')
307 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
309 state
->saw_keyword
= 1;
311 /* Reset the scanning pointer. */
312 state
->cur_keyword_ptr
= state
->keyword
;
314 /* Canonicalize whitespace preceding a usage string. */
315 state
->pending_newlines
= 2;
316 state
->pending_spaces
= 0;
318 /* Skip any whitespace between the keyword and the
321 ch
= getc (state
->in_file
);
322 while (ch
== ' ' || ch
== '\n');
324 /* Output the open-paren we just read. */
325 put_char (ch
, state
);
327 /* Skip the function name and replace it with `fn'. */
329 ch
= getc (state
->in_file
);
330 while (ch
!= ' ' && ch
!= ')');
331 put_char ('f', state
);
332 put_char ('n', state
);
334 /* Put back the last character. */
335 ungetc (ch
, state
->in_file
);
340 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
341 /* We scanned the beginning of a potential usage
342 keyword, but it was a false alarm. Output the
347 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
348 put_char (*p
, state
);
350 state
->cur_keyword_ptr
= state
->keyword
;
353 put_char (ch
, state
);
358 /* Skip a C string or C-style comment from INFILE, and return the
359 character that follows. COMMENT non-zero means skip a comment. If
360 PRINTFLAG is positive, output string contents to outfile. If it is
361 negative, store contents in buf. Convert escape sequences \n and
362 \t to newline and tab; discard \ followed by newline.
363 If SAW_USAGE is non-zero, then any occurances of the string `usage:'
364 at the beginning of a line will be removed, and *SAW_USAGE set to
365 true if any were encountered. */
368 read_c_string_or_comment (infile
, printflag
, comment
, saw_usage
)
375 struct rcsoc_state state
;
377 state
.in_file
= infile
;
378 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
379 state
.out_file
= (printflag
> 0 ? outfile
: 0);
380 state
.pending_spaces
= 0;
381 state
.pending_newlines
= 0;
382 state
.keyword
= (saw_usage
? "usage:" : 0);
383 state
.cur_keyword_ptr
= state
.keyword
;
384 state
.saw_keyword
= 0;
388 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
393 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
398 if (c
== '\n' || c
== '\r')
410 state
.pending_spaces
++;
413 state
.pending_newlines
++;
414 state
.pending_spaces
= 0;
417 scan_keyword_or_put_char (c
, &state
);
433 scan_keyword_or_put_char ('*', &state
);
440 /* If we had a "", concatenate the two strings. */
449 *saw_usage
= state
.saw_keyword
;
456 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
457 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
460 write_c_args (out
, func
, buf
, minargs
, maxargs
)
463 int minargs
, maxargs
;
470 fprintf (out
, "(fn");
475 for (p
= buf
; *p
; p
++)
480 /* Notice when we start printing a new identifier. */
481 if ((('A' <= c
&& c
<= 'Z')
482 || ('a' <= c
&& c
<= 'z')
483 || ('0' <= c
&& c
<= '9')
495 if (minargs
== 0 && maxargs
> 0)
496 fprintf (out
, "&optional ");
506 /* Print the C argument list as it would appear in lisp:
507 print underscores as hyphens, and print commas and newlines
508 as spaces. Collapse adjacent spaces into one. */
511 else if (c
== ',' || c
== '\n')
514 /* In C code, `default' is a reserved word, so we spell it
515 `defalt'; unmangle that here. */
517 && strncmp (p
, "defalt", 6) == 0
518 && ! (('A' <= p
[6] && p
[6] <= 'Z')
519 || ('a' <= p
[6] && p
[6] <= 'z')
520 || ('0' <= p
[6] && p
[6] <= '9')
523 fprintf (out
, "DEFAULT");
528 else if (c
!= ' ' || !just_spaced
)
530 if (c
>= 'a' && c
<= 'z')
531 /* Upcase the letter. */
536 just_spaced
= c
== ' ';
541 /* Read through a c file. If a .o file is named,
542 the corresponding .c file is read instead.
543 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
544 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
547 scan_c_file (filename
, mode
)
548 char *filename
, *mode
;
553 register int defunflag
;
554 register int defvarperbufferflag
;
555 register int defvarflag
;
556 int minargs
, maxargs
;
557 int extension
= filename
[strlen (filename
) - 1];
559 if (extension
== 'o')
560 filename
[strlen (filename
) - 1] = 'c';
562 infile
= fopen (filename
, mode
);
564 /* No error if non-ex input file */
571 /* Reset extension to be able to detect duplicate files. */
572 filename
[strlen (filename
) - 1] = extension
;
575 while (!feof (infile
))
579 if (c
!= '\n' && c
!= '\r')
614 defvarperbufferflag
= (c
== 'P');
627 defunflag
= c
== 'U';
629 defvarperbufferflag
= 0;
640 /* Lisp variable or function name. */
644 c
= read_c_string_or_comment (infile
, -1, 0, 0);
646 /* DEFVAR_LISP ("name", addr, "doc")
647 DEFVAR_LISP ("name", addr /\* doc *\/)
648 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
652 else if (defvarperbufferflag
)
656 else /* For DEFSIMPLE and DEFPRED */
665 if (defunflag
&& (commas
== 1 || commas
== 2))
669 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
673 if (commas
== 2) /* pick up minargs */
674 fscanf (infile
, "%d", &minargs
);
675 else /* pick up maxargs */
676 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
679 fscanf (infile
, "%d", &maxargs
);
688 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
692 c
= read_c_string_or_comment (infile
, 0, 0, 0);
694 while (c
!= EOF
&& c
!= ',' && c
!= '/')
699 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
701 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
707 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
714 && (c
= getc (infile
),
718 int comment
= c
!= '"';
722 putc (defvarflag
? 'V' : 'F', outfile
);
723 fprintf (outfile
, "%s\n", buf
);
726 getc (infile
); /* Skip past `*' */
727 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
729 /* If this is a defun, find the arguments and print them. If
730 this function takes MANY or UNEVALLED args, then the C source
731 won't give the names of the arguments, so we shouldn't bother
734 Various doc-string styles:
735 0: DEFUN (..., "DOC") (args) [!comment]
736 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
737 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
739 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
741 char argbuf
[1024], *p
= argbuf
;
743 if (!comment
|| doc_keyword
)
751 /* Skip into arguments. */
758 /* Copy arguments into ARGBUF. */
761 *p
++ = c
= getc (infile
);
765 fprintf (outfile
, "\n\n");
766 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
768 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
769 /* The DOC should provide the usage form. */
770 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
778 /* Read a file of Lisp code, compiled or interpreted.
780 (defun NAME ARGS DOCSTRING ...)
781 (defmacro NAME ARGS DOCSTRING ...)
782 (defsubst NAME ARGS DOCSTRING ...)
783 (autoload (quote NAME) FILE DOCSTRING ...)
784 (defvar NAME VALUE DOCSTRING)
785 (defconst NAME VALUE DOCSTRING)
786 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
787 (fset (quote NAME) #[... DOCSTRING ...])
788 (defalias (quote NAME) #[... DOCSTRING ...])
789 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
790 starting in column zero.
791 (quote NAME) may appear as 'NAME as well.
793 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
794 When we find that, we save it for the following defining-form,
795 and we use that instead of reading a doc string within that defining-form.
797 For defvar, defconst, and fset we skip to the docstring with a kludgy
798 formatting convention: all docstrings must appear on the same line as the
799 initial open-paren (the one in column zero) and must contain a backslash
800 and a newline immediately after the initial double-quote. No newlines
801 must appear between the beginning of the form and the first double-quote.
802 For defun, defmacro, and autoload, we know how to skip over the
803 arglist, but the doc string must still have a backslash and newline
804 immediately after the double quote.
805 The only source files that must follow this convention are preloaded
806 uncompiled ones like loaddefs.el and bindings.el; aside
807 from that, it is always the .elc file that we look at, and they are no
808 problem because byte-compiler output follows this convention.
809 The NAME and DOCSTRING are output.
810 NAME is preceded by `F' for a function or `V' for a variable.
811 An entry is output only if DOCSTRING has \ newline just after the opening "
819 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
825 read_lisp_symbol (infile
, buffer
)
830 char *fillp
= buffer
;
837 *(++fillp
) = getc (infile
);
838 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
849 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
855 scan_lisp_file (filename
, mode
)
856 char *filename
, *mode
;
860 char *saved_string
= 0;
862 infile
= fopen (filename
, mode
);
866 return 0; /* No error */
870 while (!feof (infile
))
875 /* If not at end of line, skip till we get to one. */
876 if (c
!= '\n' && c
!= '\r')
881 /* Skip the line break. */
882 while (c
== '\n' || c
== '\r')
884 /* Detect a dynamic doc string and save it for the next expression. */
893 /* Read the length. */
894 while ((c
= getc (infile
),
895 c
>= '0' && c
<= '9'))
901 /* The next character is a space that is counted in the length
902 but not part of the doc string.
903 We already read it, so just ignore it. */
906 /* Read in the contents. */
907 if (saved_string
!= 0)
909 saved_string
= (char *) malloc (length
);
910 for (i
= 0; i
< length
; i
++)
911 saved_string
[i
] = getc (infile
);
912 /* The last character is a ^_.
913 That is needed in the .elc file
914 but it is redundant in DOC. So get rid of it here. */
915 saved_string
[length
- 1] = 0;
916 /* Skip the line break. */
917 while (c
== '\n' && c
== '\r')
919 /* Skip the following line. */
920 while (c
!= '\n' && c
!= '\r')
929 read_lisp_symbol (infile
, buffer
);
931 if (! strcmp (buffer
, "defun")
932 || ! strcmp (buffer
, "defmacro")
933 || ! strcmp (buffer
, "defsubst"))
936 read_lisp_symbol (infile
, buffer
);
938 /* Skip the arguments: either "nil" or a list in parens */
941 if (c
== 'n') /* nil */
943 if ((c
= getc (infile
)) != 'i'
944 || (c
= getc (infile
)) != 'l')
946 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
953 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
962 /* If the next three characters aren't `dquote bslash newline'
963 then we're not reading a docstring.
965 if ((c
= getc (infile
)) != '"'
966 || (c
= getc (infile
)) != '\\'
967 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
970 fprintf (stderr
, "## non-docstring in %s (%s)\n",
977 else if (! strcmp (buffer
, "defvar")
978 || ! strcmp (buffer
, "defconst"))
982 read_lisp_symbol (infile
, buffer
);
984 if (saved_string
== 0)
987 /* Skip until the end of line; remember two previous chars. */
988 while (c
!= '\n' && c
!= '\r' && c
>= 0)
995 /* If two previous characters were " and \,
996 this is a doc string. Otherwise, there is none. */
997 if (c2
!= '"' || c1
!= '\\')
1000 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1008 else if (! strcmp (buffer
, "custom-declare-variable"))
1010 char c1
= 0, c2
= 0;
1015 read_lisp_symbol (infile
, buffer
);
1021 "## unparsable name in custom-declare-variable in %s\n",
1025 read_lisp_symbol (infile
, buffer
);
1026 if (strcmp (buffer
, "quote"))
1029 "## unparsable name in custom-declare-variable in %s\n",
1033 read_lisp_symbol (infile
, buffer
);
1038 "## unparsable quoted name in custom-declare-variable in %s\n",
1044 if (saved_string
== 0)
1046 /* Skip to end of line; remember the two previous chars. */
1047 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1054 /* If two previous characters were " and \,
1055 this is a doc string. Otherwise, there is none. */
1056 if (c2
!= '"' || c1
!= '\\')
1059 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1067 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1069 char c1
= 0, c2
= 0;
1074 read_lisp_symbol (infile
, buffer
);
1079 fprintf (stderr
, "## unparsable name in fset in %s\n",
1083 read_lisp_symbol (infile
, buffer
);
1084 if (strcmp (buffer
, "quote"))
1086 fprintf (stderr
, "## unparsable name in fset in %s\n",
1090 read_lisp_symbol (infile
, buffer
);
1095 "## unparsable quoted name in fset in %s\n",
1101 if (saved_string
== 0)
1103 /* Skip to end of line; remember the two previous chars. */
1104 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1111 /* If two previous characters were " and \,
1112 this is a doc string. Otherwise, there is none. */
1113 if (c2
!= '"' || c1
!= '\\')
1116 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1124 else if (! strcmp (buffer
, "autoload"))
1129 read_lisp_symbol (infile
, buffer
);
1134 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1138 read_lisp_symbol (infile
, buffer
);
1139 if (strcmp (buffer
, "quote"))
1141 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1145 read_lisp_symbol (infile
, buffer
);
1150 "## unparsable quoted name in autoload in %s\n",
1155 skip_white (infile
);
1156 if ((c
= getc (infile
)) != '\"')
1158 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1162 read_c_string_or_comment (infile
, 0, 0, 0);
1163 skip_white (infile
);
1165 if (saved_string
== 0)
1167 /* If the next three characters aren't `dquote bslash newline'
1168 then we're not reading a docstring. */
1169 if ((c
= getc (infile
)) != '"'
1170 || (c
= getc (infile
)) != '\\'
1171 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1174 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1183 else if (! strcmp (buffer
, "if")
1184 || ! strcmp (buffer
, "byte-code"))
1191 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
1197 /* At this point, we should either use the previous
1198 dynamic doc string in saved_string
1199 or gobble a doc string from the input file.
1201 In the latter case, the opening quote (and leading
1202 backslash-newline) have already been read. */
1204 putc (037, outfile
);
1205 putc (type
, outfile
);
1206 fprintf (outfile
, "%s\n", buffer
);
1209 fputs (saved_string
, outfile
);
1210 /* Don't use one dynamic doc string twice. */
1211 free (saved_string
);
1215 read_c_string_or_comment (infile
, 1, 0, 0);
1221 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1222 (do not change this comment) */
1224 /* make-docfile.c ends here */