1 /* Generate doc-string file for SXEmacs from source files.
2 Copyright (C) 1985, 1986, 1992, 1993, 1994 Free Software Foundation, Inc.
3 Copyright (C) 1995 Board of Trustees, University of Illinois.
4 Copyright (C) 1998, 1999 J. Kean Johnston.
5 Copyright (C) 2004 Steve Youngs.
7 This file is part of SXEmacs.
9 SXEmacs is free software: you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation, either version 3 of the License, or
12 (at your option) any later version.
14 SXEmacs is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program. If not, see <http://www.gnu.org/licenses/>. */
22 /* Synched up with: FSF 19.30. */
24 /* The arguments given to this program are all the C and Lisp source files
25 of SXEmacs. .elc and .el and .c files are allowed.
26 A .o file can also be specified; the .c file it was made from is used.
27 This helps the makefile pass the correct list of 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.
37 Added 19.15/20.1: `-i site-packages' allow installer to dump extra packages
38 without modifying Makefiles, etc.
41 #define NO_SHORTNAMES /* Tell config not to load remap.h */
46 #if __STDC__ || defined(STDC_HEADERS)
55 #include <sys/param.h>
57 /* How long can a source filename be in DOC (including "\037S" at the start
58 and "\n" at the end) ? */
59 #define DOC_MAX_FILENAME_LENGTH 2048
60 #define IS_DIRECTORY_SEP(arg) ('/' == arg)
62 /* Can't use the system assert on OS X, it can't find a definition for
63 __eprintf on linking */
64 #define assert(x) ((x) ? (void) 0 : (void) abort ())
67 #define READ_BINARY "r"
68 #define WRITE_BINARY "w"
69 #define APPEND_BINARY "a"
71 /* Stdio stream for output to the DOC file. */
73 static char *modname = NULL;
81 static void put_filename (const char *filename);
82 static int scan_file(const char *filename);
83 static int read_c_string(FILE *, int, int);
84 static void write_c_args(FILE * out, const char *func, char *buf, int minargs,
86 static int scan_c_file(const char *filename, const char *mode);
87 static void skip_white(FILE *);
88 static void read_lisp_symbol(FILE *, char *);
89 static int scan_lisp_file(const char *filename, const char *mode);
91 #define C_IDENTIFIER_CHAR_P(c) \
92 (('A' <= c && c <= 'Z') || \
93 ('a' <= c && c <= 'z') || \
94 ('0' <= c && c <= '9') || \
97 /* Name this program was invoked with. */
100 /* Set to 1 if this was invoked by ellcc */
103 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
105 static void error(const char *s1, const char *s2)
107 fprintf(stderr, "%s: ", progname);
108 fprintf(stderr, s1, s2);
109 fprintf(stderr, "\n");
112 /* Print error message and exit. */
114 static void fatal(const char *s1, const char *s2)
120 /* Like malloc but get fatal error if memory is exhausted. */
122 static long *xmalloc(unsigned int size)
124 long *result = (long *)malloc(size);
126 fatal("virtual memory exhausted", 0);
130 static char *next_extra_elc(char *extra_elcs)
132 static FILE *fp = NULL;
133 static char line_buf[BUFSIZ];
134 char *p = line_buf + 1;
139 } else if (!(fp = fopen(extra_elcs, READ_BINARY))) {
140 /* It is not an error if this file doesn't exist. */
141 /*fatal("error opening site package file list", 0); */
144 fgets(line_buf, BUFSIZ, fp);
148 if (!fgets(line_buf, BUFSIZ, fp)) {
154 if (strlen(p) <= 2 || strlen(p) >= (BUFSIZ - 5)) {
155 /* reject too short or too long lines */
158 p[strlen(p) - 2] = '\0';
165 write_doc_header(void)
167 char *tmp, *modout = strdup(modname), *modoutC;
170 if ((tmp = strrchr(modout, '.')) != NULL) {
172 tmp = strrchr(modout, '.');
177 /* the same for modoutC */
178 modoutC = strdup(modout);
179 modsz = strlen(modoutC);
181 for (size_t i = 0; i < modsz; i++) {
182 /* for the C version we have to convert any non-char to _ */
183 if (!isdigit(modoutC[i]) && !isalpha(modoutC[i])) {
188 fprintf(outfile, "/* DO NOT EDIT - AUTOMATICALLY GENERATED */\n\n");
189 fprintf(outfile, "#include <emodules-ng.h>\n\n");
192 fprintf(outfile, "const char *emodule_name = \"%s\";\n", modoutC);
193 fprintf(outfile, "const char *emodule_title = "
194 "\"SXEmacs module: %s\";\n", modout);
196 /* declare and start the LTX_docs() block */
197 fprintf(outfile, "\n\nextern void %s_LTX_docs(void);\n", modoutC);
198 fprintf(outfile, "\nvoid\n%s_LTX_docs(void)\n", modoutC);
202 int main(int argc, char **argv)
206 char *extra_elcs = NULL;
212 /* If first two args are -o FILE, output to FILE. */
213 for (i = 1; i < argc - 1;) {
214 if (!strcmp(argv[i], "-o")) {
215 outfile = fopen(argv[++i], WRITE_BINARY);
217 if (!strcmp(argv[i], "-a")) {
218 outfile = fopen(argv[++i], APPEND_BINARY);
220 if (!strcmp(argv[i], "-E")) {
221 if (modname == NULL) {
222 modname = strdup(argv[i+1]);
225 /*outfile = fopen(argv[++i], APPEND_BINARY);*/
226 outfile = fopen(argv[++i], WRITE_BINARY);
228 if (!strcmp(argv[i], "-d")) {
232 if (!strcmp(argv[i], "-i")) {
233 extra_elcs = argv[++i];
236 if (!strcmp(argv[i], "--modname") || !strcmp(argv[i], "-m")) {
237 modname = strdup(argv[++i]);
242 fatal("No output file specified", "");
246 fprintf(outfile, "{\n");
249 for (i = 1; i < argc; i++) {
252 if (argc > i + 1 && !strcmp (argv[i], "-d")) {
253 /* XEmacs change; allow more than one chdir. The
254 idea is that the second chdir is to source-lisp,
255 and that any Lisp files not under there have the
256 full path specified. */
260 } else if (argv[i][0] == '-') {
264 /* Don't process one file twice. */
265 for (j = 1; j < i; j++)
266 if (!strcmp(argv[i], argv[j]))
269 /* err_count seems to be {mis,un}used */
270 err_count += scan_file(argv[i]);
277 while ((p = next_extra_elc(extra_elcs)) != NULL) {
278 err_count += scan_file(p);
284 fprintf(outfile, "}\n\n");
288 return err_count > 0;
291 /* Add a source file name boundary in the output file. */
292 static void put_filename (const char *filename)
294 /* XEmacs change; don't strip directory information. */
298 /* Why are we cutting this off? */
299 for (tmp = filename; *tmp; tmp++) {
300 if (IS_DIRECTORY_SEP(*tmp))
304 /* <= because sizeof includes the nul byte at the end. Not quite
305 right, because it should include the length of the symbol +
306 "\037[VF]" instead of simply 10. */
307 assert(sizeof("\037S\n") + strlen(filename) + 10
308 <= DOC_MAX_FILENAME_LENGTH);
312 fprintf (outfile, "%s\n", filename);
315 /* Read file FILENAME and output its doc strings to outfile. */
316 /* Return 1 if file is not found, 0 if it is found. */
318 static int scan_file(const char *filename)
320 int len = strlen(filename);
322 if (ellcc == 0 && len > 4 && !strcmp(filename + len - 4, ".elc")) {
323 Current_file_type = elc_file;
324 return scan_lisp_file(filename, READ_BINARY);
325 } else if (ellcc == 0 && len > 3 && !strcmp(filename + len - 3, ".el")) {
326 Current_file_type = el_file;
327 return scan_lisp_file(filename, READ_TEXT);
329 Current_file_type = c_file;
330 return scan_c_file(filename, READ_TEXT);
336 /* Skip a C string from INFILE,
337 and return the character that follows the closing ".
338 If printflag is positive, output string contents to outfile.
339 If it is negative, store contents in buf.
340 Convert escape sequences \n and \t to newline and tab;
341 discard \ followed by newline. */
343 #define MDGET do { prevc = c; c = getc (infile); } while (0)
344 static int read_c_string(FILE * infile, int printflag, int c_docstring)
346 register int prevc = 0, c = 0;
352 while ((c_docstring || c != '"') && c != EOF) {
354 int cc = getc(infile);
362 } else if (printflag < 0)
373 fprintf(outfile, "\\n\\");
375 } else if (printflag < 0)
386 if (!c_docstring && c == 'n')
396 if (ellcc && c == '"')
399 } else if (printflag < 0)
404 /* look for continuation of string */
405 if (Current_file_type == c_file) {
416 /* If we had a "", concatenate the two strings. */
427 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
428 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
431 write_c_args(FILE * out, const char *func, char *buff, int minargs, int maxargs)
439 fprintf(out, "(%s", func);
441 /* XEmacs - "arguments:" is for parsing the docstring. FSF's help system
442 doesn't parse the docstring for arguments like we do, so we're also
443 going to omit the function name to preserve compatibility with elisp
444 that parses the docstring. Finally, not prefixing the arglist with
445 anything is asking for trouble because it's not uncommon to have an
446 unescaped parenthesis at the beginning of a line. --Stig */
447 fprintf(out, "arguments: (");
453 for (p = buff; *p; p++) {
457 /* Add support for ANSI prototypes. Hop over
458 "Lisp_Object" string (the only C type allowed in DEFUNs) */
459 static char lo[] = "Lisp_Object";
460 if ((C_IDENTIFIER_CHAR_P(c) != in_ident) && !in_ident &&
461 (strncmp(p, lo, sizeof(lo) - 1) == 0) &&
462 isspace((unsigned char)(*(p + sizeof(lo) - 1)))) {
463 p += (sizeof(lo) - 1);
464 while (isspace((unsigned char)(*p)))
469 /* Notice when we start printing a new identifier. */
470 if (C_IDENTIFIER_CHAR_P(c) != in_ident) {
475 /* XEmacs - This goes along with the change above. */
479 if (minargs == 0 && maxargs > 0)
480 fprintf(out, "&optional ");
489 /* Print the C argument list as it would appear in lisp:
490 print underscores as hyphens, and print commas as spaces.
491 Collapse adjacent spaces into one. */
497 /* If the C argument name ends with `_', change it to ' ',
498 to allow use of C reserved words or global symbols as Lisp args. */
499 if (c == '-' && !C_IDENTIFIER_CHAR_P(p[1])) {
503 /* If the character is carriage return, escape it for the C compiler. */
504 else if (c == '\n') {
507 } else if (c != ' ' || !just_spaced) {
508 if (c >= 'a' && c <= 'z')
509 /* Upcase the letter. */
514 just_spaced = (c == ' ');
520 putc('\n', out); /* XEmacs addition */
523 /* Read through a c file. If a .o file is named,
524 the corresponding .c file is read instead.
525 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
526 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
528 static int scan_c_file(const char *filename, const char *mode)
533 register int defunflag;
534 register int defvarperbufferflag = 0;
535 register int defvarflag;
536 int minargs, maxargs;
537 size_t l = strlen(filename);
542 errno = ENAMETOOLONG;
552 infile = fopen(f, mode);
554 /* No error if non-ex input file */
555 if (infile == NULL) {
561 while (!feof(infile)) {
568 * SXEmacs uses proper indentation so we need to
569 * search for `\t' instead of ' ' here.
599 /* Note that this business doesn't apply under XEmacs.
600 DEFVAR_BUFFER_LOCAL in XEmacs behaves normally. */
601 defvarperbufferflag = (c == 'P');
604 } else if (c == 'D') {
612 defunflag = (c == 'U');
627 c = read_c_string(infile, -1, 0);
631 else if (defvarperbufferflag)
635 else /* For DEFSIMPLE and DEFPRED */
641 if (defunflag && (commas == 1 || commas == 2)) {
644 while (c == ' ' || c == '\n'
649 if (commas == 2) /* pick up minargs */
650 fscanf(infile, "%d", &minargs);
651 else /* pick up maxargs */ if (c == 'M' || c == 'U') /* MANY || UNEVALLED */
654 fscanf(infile, "%d", &maxargs);
661 while (c == ' ' || c == '\n' || c == '\t')
664 c = read_c_string(infile, 0, 0);
665 if (defunflag | defvarflag) {
676 while (c == ' ' || c == '\n' || c == '\t')
678 if (defunflag | defvarflag)
681 if (defunflag || defvarflag || c == '"') {
683 fprintf(outfile, "\tCDOC%s(\"%s\", \"\\\n",
684 defvarflag ? "SYM" : "SUBR", buf);
686 put_filename (filename); /* XEmacs addition */
688 putc(defvarflag ? 'V' : 'F', outfile);
689 fprintf(outfile, "%s\n", buf);
691 c = read_c_string(infile, 1, (defunflag || defvarflag));
693 /* If this is a defun, find the arguments and print
694 them. If this function takes MANY or UNEVALLED args,
695 then the C source won't give the names of the
696 arguments, so we shouldn't bother trying to find
698 if (defunflag && maxargs != -1) {
699 char argbuf[1024], *p = argbuf;
700 #if 0 /* For old DEFUN's only */
707 /* Skip into arguments. */
713 /* Copy arguments into ARGBUF. */
716 *p++ = c = getc(infile);
721 fprintf(outfile, "\\n\\\n\\n\\\n");
723 fprintf(outfile, "\n\n");
724 write_c_args(outfile, buf, argbuf, minargs,
728 fprintf(outfile, "\\n\");\n\n");
736 /* Read a file of Lisp code, compiled or interpreted.
738 (defun NAME ARGS DOCSTRING ...)
739 (defmacro NAME ARGS DOCSTRING ...)
740 (autoload (quote NAME) FILE DOCSTRING ...)
741 (defvar NAME VALUE DOCSTRING)
742 (defconst NAME VALUE DOCSTRING)
743 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
744 (fset (quote NAME) #[... DOCSTRING ...])
745 (defalias (quote NAME) #[... DOCSTRING ...])
746 starting in column zero.
747 (quote NAME) may appear as 'NAME as well.
749 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
750 When we find that, we save it for the following defining-form,
751 and we use that instead of reading a doc string within that defining-form.
753 For defun, defmacro, and autoload, we know how to skip over the arglist.
754 For defvar, defconst, and fset we skip to the docstring with a kludgy
755 formatting convention: all docstrings must appear on the same line as the
756 initial open-paren (the one in column zero) and must contain a backslash
757 and a double-quote immediately after the initial double-quote. No newlines
758 must appear between the beginning of the form and the first double-quote.
759 The only source file that must follow this convention is loaddefs.el; aside
760 from that, it is always the .elc file that we look at, and they are no
761 problem because byte-compiler output follows this convention.
762 The NAME and DOCSTRING are output.
763 NAME is preceded by `F' for a function or `V' for a variable.
764 An entry is output only if DOCSTRING has \ newline just after the opening "
766 Adds the filename a symbol or function was found in before its docstring;
767 there's no need for this with the load-history available, but we do it for
768 consistency with the C parsing code.
771 static void skip_white(FILE * infile)
774 while (c == ' ' || c == '\t' || c == '\n')
779 static void read_lisp_symbol(FILE * infile, char *buffer)
782 char *fillp = buffer;
788 /* FSF has *(++fillp), which is wrong. */
789 *fillp++ = getc(infile);
790 else if (c == ' ' || c == '\t' || c == '\n' || c == '('
800 fprintf(stderr, "## expected a symbol, got '%c'\n", c);
805 static int scan_lisp_file(const char *filename, const char *mode)
809 char *saved_string = 0;
811 infile = fopen(filename, mode);
812 if (infile == NULL) {
814 return 0; /* No error */
818 while (!feof(infile)) {
827 /* Detect a dynamic doc string and save it for the next expression. */
834 /* Read the length. */
835 while ((c = getc(infile), c >= '0' && c <= '9')) {
840 /* The next character is a space that is counted in the length
841 but not part of the doc string.
842 We already read it, so just ignore it. */
845 /* Read in the contents. */
846 if (saved_string != 0)
848 saved_string = (char *)xmalloc(length);
849 for (i = 0; i < length; i++)
850 saved_string[i] = getc(infile);
851 /* The last character is a ^_.
852 That is needed in the .elc file
853 but it is redundant in DOC. So get rid of it here. */
854 saved_string[length - 1] = 0;
855 /* Skip the newline. */
866 read_lisp_symbol(infile, buffer);
868 if (!strcmp(buffer, "defun") || !strcmp(buffer, "defmacro")) {
870 read_lisp_symbol(infile, buffer);
872 /* Skip the arguments: either "nil" or a list in parens */
875 if (c == 'n') { /* nil */
876 if ((c = getc(infile)) != 'i' ||
877 (c = getc(infile)) != 'l') {
879 "## unparsable arglist in %s (%s)\n",
883 } else if (c != '(') {
885 "## unparsable arglist in %s (%s)\n",
893 /* If the next three characters aren't `dquote bslash newline'
894 then we're not reading a docstring.
896 if ((c = getc(infile)) != '"' ||
897 (c = getc(infile)) != '\\' ||
898 (c = getc(infile)) != '\n') {
900 fprintf(stderr, "## non-docstring in %s (%s)\n",
907 else if (!strcmp(buffer, "defvar") ||
908 !strcmp(buffer, "defconst")) {
911 read_lisp_symbol(infile, buffer);
913 if (saved_string == 0) {
915 /* Skip until the first newline; remember the two previous chars. */
916 while (c != '\n' && c >= 0) {
917 /* #### Kludge -- Ignore any ESC x x ISO2022 sequences */
930 /* If two previous characters were " and \,
931 this is a doc string. Otherwise, there is none. */
932 if (c2 != '"' || c1 != '\\') {
935 "## non-docstring in %s (%s)\n",
943 else if (! strcmp (buffer, "custom-declare-variable"))
950 read_lisp_symbol (infile, buffer);
954 "## unparsable name in "
955 "custom-declare-variable "
960 read_lisp_symbol (infile, buffer);
961 if (strcmp (buffer, "quote")) {
963 "## unparsable name in "
964 "custom-declare-variable "
969 read_lisp_symbol (infile, buffer);
973 "## unparsable quoted name "
974 "in custom-declare-variable"
975 " in %s\n", filename);
980 if (saved_string == 0)
982 /* Skip to end of line; remember the two
984 while (c != '\n' && c >= 0) {
987 /* SXEmacs: shame we can't do this. */
988 /* c = getc_skipping_iso2022 (infile); */
992 /* If two previous characters were " and \,
993 this is a doc string. Otherwise, there is
995 if (c2 != '"' || c1 != '\\') {
997 fprintf (stderr, "## non-docstring in"
1006 else if (!strcmp(buffer, "fset") || !strcmp(buffer, "defalias")) {
1007 char c1 = 0, c2 = 0;
1012 read_lisp_symbol(infile, buffer);
1016 "## unparsable name in fset in %s\n",
1020 read_lisp_symbol(infile, buffer);
1021 if (strcmp(buffer, "quote")) {
1023 "## unparsable name in fset in %s\n",
1027 read_lisp_symbol(infile, buffer);
1031 "## unparsable quoted name in fset in %s\n",
1037 if (saved_string == 0) {
1038 /* Skip until the first newline; remember the two previous chars. */
1039 while (c != '\n' && c >= 0) {
1045 /* If two previous characters were " and \,
1046 this is a doc string. Otherwise, there is none. */
1047 if (c2 != '"' || c1 != '\\') {
1050 "## non-docstring in %s (%s)\n",
1058 else if (!strcmp(buffer, "autoload")) {
1062 read_lisp_symbol(infile, buffer);
1066 "## unparsable name in autoload in %s\n",
1070 read_lisp_symbol(infile, buffer);
1071 if (strcmp(buffer, "quote")) {
1073 "## unparsable name in autoload in %s\n",
1077 read_lisp_symbol(infile, buffer);
1081 "## unparsable quoted name in autoload in %s\n",
1087 if ((c = getc(infile)) != '\"') {
1089 "## autoload of %s unparsable (%s)\n",
1093 read_c_string(infile, 0, 0);
1096 if (saved_string == 0) {
1097 /* If the next three characters aren't `dquote bslash newline'
1098 then we're not reading a docstring. */
1099 if ((c = getc(infile)) != '"' ||
1100 (c = getc(infile)) != '\\' ||
1101 (c = getc(infile)) != '\n') {
1104 "## non-docstring in %s (%s)\n",
1111 #if 0 /* causes crash */
1112 else if (!strcmp(buffer, "if") ||
1113 !strcmp(buffer, "byte-code")) ;
1119 "## unrecognized top-level form, %s (%s)\n",
1125 /* At this point, we should either use the previous
1126 dynamic doc string in saved_string
1127 or gobble a doc string from the input file.
1129 In the latter case, the opening quote (and leading
1130 backslash-newline) have already been read. */
1131 put_filename (filename); /* XEmacs addition */
1133 putc(type, outfile);
1134 fprintf(outfile, "%s\n", buffer);
1136 fputs(saved_string, outfile);
1137 /* Don't use one dynamic doc string twice. */
1141 read_c_string(infile, 1, 0);
1144 /* If this is true then a dynamic doc string was
1145 detected without a next expression. We should not
1146 emit anything since the input was badly formed,
1147 but lets free the string...