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 */
65 #define DIRECTORY_SEP '/'
68 #ifndef IS_DIRECTORY_SEP
69 #define IS_DIRECTORY_SEP(_c_) ((_c_) == DIRECTORY_SEP)
73 int scan_lisp_file ();
77 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
78 file where that function is defined. */
86 /* Stdio stream for output to the DOC file. */
89 /* Name this program was invoked with. */
92 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
99 fprintf (stderr
, "%s: ", progname
);
100 fprintf (stderr
, s1
, s2
);
101 fprintf (stderr
, "\n");
104 /* Print error message and exit. */
115 /* Like malloc but get fatal error if memory is exhausted. */
121 void *result
= (void *) malloc (size
);
123 fatal ("virtual memory exhausted", 0);
140 /* Don't put CRs in the DOC file. */
143 #if 0 /* Suspicion is that this causes hanging.
144 So instead we require people to use -o on MSDOS. */
145 (stdout
)->_flag
&= ~_IOTEXT
;
146 _setmode (fileno (stdout
), O_BINARY
);
152 _setmode (fileno (stdout
), O_BINARY
);
153 #endif /* WINDOWSNT */
155 /* If first two args are -o FILE, output to FILE. */
157 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
159 outfile
= fopen (argv
[i
+ 1], "w");
162 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
164 outfile
= fopen (argv
[i
+ 1], "a");
167 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
174 fatal ("No output file specified", "");
177 for (; i
< argc
; i
++)
180 /* Don't process one file twice. */
181 for (j
= first_infile
; j
< i
; j
++)
182 if (! strcmp (argv
[i
], argv
[j
]))
185 err_count
+= scan_file (argv
[i
]);
187 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
190 /* Add a source file name boundary marker in the output file. */
192 put_filename (filename
)
197 for (tmp
= filename
; *tmp
; tmp
++)
199 if (IS_DIRECTORY_SEP(*tmp
))
205 fprintf (outfile
, "%s\n", filename
);
208 /* Read file FILENAME and output its doc strings to outfile. */
209 /* Return 1 if file is not found, 0 if it is found. */
215 int len
= strlen (filename
);
217 put_filename (filename
);
218 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
219 return scan_lisp_file (filename
, READ_BINARY
);
220 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
221 return scan_lisp_file (filename
, READ_TEXT
);
223 return scan_c_file (filename
, READ_TEXT
);
228 /* Some state during the execution of `read_c_string_or_comment'. */
231 /* A count of spaces and newlines that have been read, but not output. */
232 unsigned pending_spaces
, pending_newlines
;
234 /* Where we're reading from. */
237 /* If non-zero, a buffer into which to copy characters. */
239 /* If non-zero, a file into which to copy characters. */
242 /* A keyword we look for at the beginning of lines. If found, it is
243 not copied, and SAW_KEYWORD is set to true. */
245 /* The current point we've reached in an occurance of KEYWORD in
247 char *cur_keyword_ptr
;
248 /* Set to true if we saw an occurance of KEYWORD. */
252 /* Output CH to the file or buffer in STATE. Any pending newlines or
253 spaces are output first. */
258 struct rcsoc_state
*state
;
263 if (state
->pending_newlines
> 0)
265 state
->pending_newlines
--;
268 else if (state
->pending_spaces
> 0)
270 state
->pending_spaces
--;
277 putc (out_ch
, state
->out_file
);
279 *state
->buf_ptr
++ = out_ch
;
281 while (out_ch
!= ch
);
284 /* If in the middle of scanning a keyword, continue scanning with
285 character CH, otherwise output CH to the file or buffer in STATE.
286 Any pending newlines or spaces are output first, as well as any
287 previously scanned characters that were thought to be part of a
288 keyword, but were in fact not. */
291 scan_keyword_or_put_char (ch
, state
)
293 struct rcsoc_state
*state
;
296 && *state
->cur_keyword_ptr
== ch
297 && (state
->cur_keyword_ptr
> state
->keyword
298 || state
->pending_newlines
> 0))
299 /* We might be looking at STATE->keyword at some point.
300 Keep looking until we know for sure. */
302 if (*++state
->cur_keyword_ptr
== '\0')
303 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
305 state
->saw_keyword
= 1;
307 /* Reset the scanning pointer. */
308 state
->cur_keyword_ptr
= state
->keyword
;
310 /* Canonicalize whitespace preceding a usage string. */
311 state
->pending_newlines
= 2;
312 state
->pending_spaces
= 0;
314 /* Skip any whitespace between the keyword and the
317 ch
= getc (state
->in_file
);
318 while (ch
== ' ' || ch
== '\n');
320 /* Output the open-paren we just read. */
321 put_char (ch
, state
);
323 /* Skip the function name and replace it with `fn'. */
325 ch
= getc (state
->in_file
);
326 while (ch
!= ' ' && ch
!= ')');
327 put_char ('f', state
);
328 put_char ('n', state
);
330 /* Put back the last character. */
331 ungetc (ch
, state
->in_file
);
336 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
337 /* We scanned the beginning of a potential usage
338 keyword, but it was a false alarm. Output the
343 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
344 put_char (*p
, state
);
346 state
->cur_keyword_ptr
= state
->keyword
;
349 put_char (ch
, state
);
354 /* Skip a C string or C-style comment from INFILE, and return the
355 character that follows. COMMENT non-zero means skip a comment. If
356 PRINTFLAG is positive, output string contents to outfile. If it is
357 negative, store contents in buf. Convert escape sequences \n and
358 \t to newline and tab; discard \ followed by newline.
359 If SAW_USAGE is non-zero, then any occurances of the string `usage:'
360 at the beginning of a line will be removed, and *SAW_USAGE set to
361 true if any were encountered. */
364 read_c_string_or_comment (infile
, printflag
, comment
, saw_usage
)
371 struct rcsoc_state state
;
373 state
.in_file
= infile
;
374 state
.buf_ptr
= (printflag
< 0 ? buf
: 0);
375 state
.out_file
= (printflag
> 0 ? outfile
: 0);
376 state
.pending_spaces
= 0;
377 state
.pending_newlines
= 0;
378 state
.keyword
= (saw_usage
? "usage:" : 0);
379 state
.cur_keyword_ptr
= state
.keyword
;
380 state
.saw_keyword
= 0;
384 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
389 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
394 if (c
== '\n' || c
== '\r')
406 state
.pending_spaces
++;
409 state
.pending_newlines
++;
410 state
.pending_spaces
= 0;
413 scan_keyword_or_put_char (c
, &state
);
429 scan_keyword_or_put_char ('*', &state
);
436 /* If we had a "", concatenate the two strings. */
445 *saw_usage
= state
.saw_keyword
;
452 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
453 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
456 write_c_args (out
, func
, buf
, minargs
, maxargs
)
459 int minargs
, maxargs
;
466 fprintf (out
, "(fn");
471 for (p
= buf
; *p
; p
++)
476 /* Notice when we start printing a new identifier. */
477 if ((('A' <= c
&& c
<= 'Z')
478 || ('a' <= c
&& c
<= 'z')
479 || ('0' <= c
&& c
<= '9')
491 if (minargs
== 0 && maxargs
> 0)
492 fprintf (out
, "&optional ");
502 /* Print the C argument list as it would appear in lisp:
503 print underscores as hyphens, and print commas and newlines
504 as spaces. Collapse adjacent spaces into one. */
507 else if (c
== ',' || c
== '\n')
510 /* In C code, `default' is a reserved word, so we spell it
511 `defalt'; unmangle that here. */
513 && strncmp (p
, "defalt", 6) == 0
514 && ! (('A' <= p
[6] && p
[6] <= 'Z')
515 || ('a' <= p
[6] && p
[6] <= 'z')
516 || ('0' <= p
[6] && p
[6] <= '9')
519 fprintf (out
, "DEFAULT");
524 else if (c
!= ' ' || !just_spaced
)
526 if (c
>= 'a' && c
<= 'z')
527 /* Upcase the letter. */
532 just_spaced
= c
== ' ';
537 /* Read through a c file. If a .o file is named,
538 the corresponding .c file is read instead.
539 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
540 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
543 scan_c_file (filename
, mode
)
544 char *filename
, *mode
;
549 register int defunflag
;
550 register int defvarperbufferflag
;
551 register int defvarflag
;
552 int minargs
, maxargs
;
553 int extension
= filename
[strlen (filename
) - 1];
555 if (extension
== 'o')
556 filename
[strlen (filename
) - 1] = 'c';
558 infile
= fopen (filename
, mode
);
560 /* No error if non-ex input file */
567 /* Reset extension to be able to detect duplicate files. */
568 filename
[strlen (filename
) - 1] = extension
;
571 while (!feof (infile
))
575 if (c
!= '\n' && c
!= '\r')
610 defvarperbufferflag
= (c
== 'P');
623 defunflag
= c
== 'U';
625 defvarperbufferflag
= 0;
636 /* Lisp variable or function name. */
640 c
= read_c_string_or_comment (infile
, -1, 0, 0);
642 /* DEFVAR_LISP ("name", addr, "doc")
643 DEFVAR_LISP ("name", addr /\* doc *\/)
644 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
648 else if (defvarperbufferflag
)
652 else /* For DEFSIMPLE and DEFPRED */
661 if (defunflag
&& (commas
== 1 || commas
== 2))
665 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
669 if (commas
== 2) /* pick up minargs */
670 fscanf (infile
, "%d", &minargs
);
671 else /* pick up maxargs */
672 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
675 fscanf (infile
, "%d", &maxargs
);
684 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
688 c
= read_c_string_or_comment (infile
, 0, 0, 0);
690 while (c
!= EOF
&& c
!= ',' && c
!= '/')
695 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
697 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
703 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
710 && (c
= getc (infile
),
714 int comment
= c
!= '"';
718 putc (defvarflag
? 'V' : 'F', outfile
);
719 fprintf (outfile
, "%s\n", buf
);
722 getc (infile
); /* Skip past `*' */
723 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
725 /* If this is a defun, find the arguments and print them. If
726 this function takes MANY or UNEVALLED args, then the C source
727 won't give the names of the arguments, so we shouldn't bother
730 Various doc-string styles:
731 0: DEFUN (..., "DOC") (args) [!comment]
732 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
733 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
735 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
737 char argbuf
[1024], *p
= argbuf
;
739 if (!comment
|| doc_keyword
)
747 /* Skip into arguments. */
754 /* Copy arguments into ARGBUF. */
757 *p
++ = c
= getc (infile
);
761 fprintf (outfile
, "\n\n");
762 write_c_args (outfile
, buf
, argbuf
, minargs
, maxargs
);
764 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
765 /* The DOC should provide the usage form. */
766 fprintf (stderr
, "Missing `usage' for function `%s'.\n", buf
);
774 /* Read a file of Lisp code, compiled or interpreted.
776 (defun NAME ARGS DOCSTRING ...)
777 (defmacro NAME ARGS DOCSTRING ...)
778 (defsubst NAME ARGS DOCSTRING ...)
779 (autoload (quote NAME) FILE DOCSTRING ...)
780 (defvar NAME VALUE DOCSTRING)
781 (defconst NAME VALUE DOCSTRING)
782 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
783 (fset (quote NAME) #[... DOCSTRING ...])
784 (defalias (quote NAME) #[... DOCSTRING ...])
785 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
786 starting in column zero.
787 (quote NAME) may appear as 'NAME as well.
789 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
790 When we find that, we save it for the following defining-form,
791 and we use that instead of reading a doc string within that defining-form.
793 For defvar, defconst, and fset we skip to the docstring with a kludgy
794 formatting convention: all docstrings must appear on the same line as the
795 initial open-paren (the one in column zero) and must contain a backslash
796 and a newline immediately after the initial double-quote. No newlines
797 must appear between the beginning of the form and the first double-quote.
798 For defun, defmacro, and autoload, we know how to skip over the
799 arglist, but the doc string must still have a backslash and newline
800 immediately after the double quote.
801 The only source files that must follow this convention are preloaded
802 uncompiled ones like loaddefs.el and bindings.el; aside
803 from that, it is always the .elc file that we look at, and they are no
804 problem because byte-compiler output follows this convention.
805 The NAME and DOCSTRING are output.
806 NAME is preceded by `F' for a function or `V' for a variable.
807 An entry is output only if DOCSTRING has \ newline just after the opening "
815 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
821 read_lisp_symbol (infile
, buffer
)
826 char *fillp
= buffer
;
833 *(++fillp
) = getc (infile
);
834 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
845 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
851 scan_lisp_file (filename
, mode
)
852 char *filename
, *mode
;
856 char *saved_string
= 0;
858 infile
= fopen (filename
, mode
);
862 return 0; /* No error */
866 while (!feof (infile
))
871 /* If not at end of line, skip till we get to one. */
872 if (c
!= '\n' && c
!= '\r')
877 /* Skip the line break. */
878 while (c
== '\n' || c
== '\r')
880 /* Detect a dynamic doc string and save it for the next expression. */
889 /* Read the length. */
890 while ((c
= getc (infile
),
891 c
>= '0' && c
<= '9'))
897 /* The next character is a space that is counted in the length
898 but not part of the doc string.
899 We already read it, so just ignore it. */
902 /* Read in the contents. */
903 if (saved_string
!= 0)
905 saved_string
= (char *) malloc (length
);
906 for (i
= 0; i
< length
; i
++)
907 saved_string
[i
] = getc (infile
);
908 /* The last character is a ^_.
909 That is needed in the .elc file
910 but it is redundant in DOC. So get rid of it here. */
911 saved_string
[length
- 1] = 0;
912 /* Skip the line break. */
913 while (c
== '\n' && c
== '\r')
915 /* Skip the following line. */
916 while (c
!= '\n' && c
!= '\r')
925 read_lisp_symbol (infile
, buffer
);
927 if (! strcmp (buffer
, "defun")
928 || ! strcmp (buffer
, "defmacro")
929 || ! strcmp (buffer
, "defsubst"))
932 read_lisp_symbol (infile
, buffer
);
934 /* Skip the arguments: either "nil" or a list in parens */
937 if (c
== 'n') /* nil */
939 if ((c
= getc (infile
)) != 'i'
940 || (c
= getc (infile
)) != 'l')
942 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
949 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
958 /* If the next three characters aren't `dquote bslash newline'
959 then we're not reading a docstring.
961 if ((c
= getc (infile
)) != '"'
962 || (c
= getc (infile
)) != '\\'
963 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
966 fprintf (stderr
, "## non-docstring in %s (%s)\n",
973 else if (! strcmp (buffer
, "defvar")
974 || ! strcmp (buffer
, "defconst"))
978 read_lisp_symbol (infile
, buffer
);
980 if (saved_string
== 0)
983 /* Skip until the end of line; remember two previous chars. */
984 while (c
!= '\n' && c
!= '\r' && c
>= 0)
991 /* If two previous characters were " and \,
992 this is a doc string. Otherwise, there is none. */
993 if (c2
!= '"' || c1
!= '\\')
996 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1004 else if (! strcmp (buffer
, "custom-declare-variable"))
1006 char c1
= 0, c2
= 0;
1011 read_lisp_symbol (infile
, buffer
);
1017 "## unparsable name in custom-declare-variable in %s\n",
1021 read_lisp_symbol (infile
, buffer
);
1022 if (strcmp (buffer
, "quote"))
1025 "## unparsable name in custom-declare-variable in %s\n",
1029 read_lisp_symbol (infile
, buffer
);
1034 "## unparsable quoted name in custom-declare-variable in %s\n",
1040 if (saved_string
== 0)
1042 /* Skip to end of line; remember the two previous chars. */
1043 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1050 /* If two previous characters were " and \,
1051 this is a doc string. Otherwise, there is none. */
1052 if (c2
!= '"' || c1
!= '\\')
1055 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1063 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1065 char c1
= 0, c2
= 0;
1070 read_lisp_symbol (infile
, buffer
);
1075 fprintf (stderr
, "## unparsable name in fset in %s\n",
1079 read_lisp_symbol (infile
, buffer
);
1080 if (strcmp (buffer
, "quote"))
1082 fprintf (stderr
, "## unparsable name in fset in %s\n",
1086 read_lisp_symbol (infile
, buffer
);
1091 "## unparsable quoted name in fset in %s\n",
1097 if (saved_string
== 0)
1099 /* Skip to end of line; remember the two previous chars. */
1100 while (c
!= '\n' && c
!= '\r' && c
>= 0)
1107 /* If two previous characters were " and \,
1108 this is a doc string. Otherwise, there is none. */
1109 if (c2
!= '"' || c1
!= '\\')
1112 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1120 else if (! strcmp (buffer
, "autoload"))
1125 read_lisp_symbol (infile
, buffer
);
1130 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1134 read_lisp_symbol (infile
, buffer
);
1135 if (strcmp (buffer
, "quote"))
1137 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1141 read_lisp_symbol (infile
, buffer
);
1146 "## unparsable quoted name in autoload in %s\n",
1151 skip_white (infile
);
1152 if ((c
= getc (infile
)) != '\"')
1154 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1158 read_c_string_or_comment (infile
, 0, 0, 0);
1159 skip_white (infile
);
1161 if (saved_string
== 0)
1163 /* If the next three characters aren't `dquote bslash newline'
1164 then we're not reading a docstring. */
1165 if ((c
= getc (infile
)) != '"'
1166 || (c
= getc (infile
)) != '\\'
1167 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1170 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1179 else if (! strcmp (buffer
, "if")
1180 || ! strcmp (buffer
, "byte-code"))
1187 fprintf (stderr
, "## unrecognised top-level form, %s (%s)\n",
1193 /* At this point, we should either use the previous
1194 dynamic doc string in saved_string
1195 or gobble a doc string from the input file.
1197 In the latter case, the opening quote (and leading
1198 backslash-newline) have already been read. */
1200 putc (037, outfile
);
1201 putc (type
, outfile
);
1202 fprintf (outfile
, "%s\n", buffer
);
1205 fputs (saved_string
, outfile
);
1206 /* Don't use one dynamic doc string twice. */
1207 free (saved_string
);
1211 read_c_string_or_comment (infile
, 1, 0, 0);
1217 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1218 (do not change this comment) */
1220 /* make-docfile.c ends here */