1 /* Generate doc-string file for XEmacs 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.
6 This file is part of XEmacs.
8 XEmacs is free software; you can redistribute it and/or modify it
9 under the terms of the GNU General Public License as published by the
10 Free Software Foundation; either version 2, or (at your option) any
13 XEmacs is distributed in the hope that it will be useful, but WITHOUT
14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
18 You should have received a copy of the GNU General Public License
19 along with XEmacs; see the file COPYING. If not, write to
20 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 Boston, MA 02111-1307, USA. */
23 /* Synched up with: FSF 19.30. */
25 /* The arguments given to this program are all the C and Lisp source files
26 of XEmacs. .elc and .el and .c files are allowed.
27 A .o file can also be specified; the .c file it was made from is used.
28 This helps the makefile pass the correct list of files.
30 The results, which go to standard output or to a file
31 specified with -a or -o (-a to append, -o to start from nothing),
32 are entries containing function or variable names and their documentation.
33 Each entry starts with a ^_ character.
34 Then comes F for a function or V for a variable.
35 Then comes the function or variable name, terminated with a newline.
36 Then comes the documentation for that function or variable.
38 Added 19.15/20.1: `-i site-packages' allow installer to dump extra packages
39 without modifying Makefiles, etc.
42 #define NO_SHORTNAMES /* Tell config not to load remap.h */
47 #if __STDC__ || defined(STDC_HEADERS)
54 #if defined(MSDOS) || defined(__CYGWIN32__)
62 #endif /* WINDOWSNT */
64 #include <sys/param.h>
66 #if defined(DOS_NT) || defined(__CYGWIN32__)
67 #define READ_TEXT "rt"
68 #define READ_BINARY "rb"
69 #define WRITE_BINARY "wb"
70 #define APPEND_BINARY "ab"
71 #else /* not DOS_NT */
73 #define READ_BINARY "r"
74 #define WRITE_BINARY "w"
75 #define APPEND_BINARY "a"
76 #endif /* not DOS_NT */
79 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
80 file where that function is defined. */
84 /* Stdio stream for output to the DOC file. */
94 static int scan_file (CONST char *filename);
95 static int read_c_string (FILE *, int, int);
96 static void write_c_args (FILE *out, CONST char *func, char *buf, int minargs,
98 static int scan_c_file (CONST char *filename, CONST char *mode);
99 static void skip_white (FILE *);
100 static void read_lisp_symbol (FILE *, char *);
101 static int scan_lisp_file (CONST char *filename, CONST char *mode);
103 #define C_IDENTIFIER_CHAR_P(c) \
104 (('A' <= c && c <= 'Z') || \
105 ('a' <= c && c <= 'z') || \
106 ('0' <= c && c <= '9') || \
109 /* Name this program was invoked with. */
112 /* Set to 1 if this was invoked by ellcc */
115 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
118 error (CONST char *s1, CONST char *s2)
120 fprintf (stderr, "%s: ", progname);
121 fprintf (stderr, s1, s2);
122 fprintf (stderr, "\n");
125 /* Print error message and exit. */
128 fatal (CONST char *s1, CONST char *s2)
134 /* Like malloc but get fatal error if memory is exhausted. */
137 xmalloc (unsigned int size)
139 long *result = (long *) malloc (size);
141 fatal ("virtual memory exhausted", 0);
146 next_extra_elc(char *extra_elcs)
148 static FILE *fp = NULL;
149 static char line_buf[BUFSIZ];
150 char *p = line_buf+1;
155 } else if (!(fp = fopen(extra_elcs, READ_BINARY))) {
156 /* It is not an error if this file doesn't exist. */
157 /*fatal("error opening site package file list", 0);*/
160 fgets(line_buf, BUFSIZ, fp);
164 if (!fgets(line_buf, BUFSIZ, fp)) {
170 if (strlen(p) <= 2 || strlen(p) >= (BUFSIZ - 5)) {
171 /* reject too short or too long lines */
174 p[strlen(p) - 2] = '\0';
182 main (int argc, char **argv)
187 char *extra_elcs = NULL;
193 /* Don't put CRs in the DOC file. */
196 #if 0 /* Suspicion is that this causes hanging.
197 So instead we require people to use -o on MSDOS. */
198 (stdout)->_flag &= ~_IOTEXT;
199 _setmode (fileno (stdout), O_BINARY);
205 _setmode (fileno (stdout), O_BINARY);
206 #endif /* WINDOWSNT */
208 /* If first two args are -o FILE, output to FILE. */
210 if (argc > i + 1 && !strcmp (argv[i], "-o"))
212 outfile = fopen (argv[i + 1], WRITE_BINARY);
215 if (argc > i + 1 && !strcmp (argv[i], "-a"))
217 outfile = fopen (argv[i + 1], APPEND_BINARY);
220 if (argc > i + 1 && !strcmp (argv[i], "-E"))
222 outfile = fopen (argv[i + 1], APPEND_BINARY);
226 if (argc > i + 1 && !strcmp (argv[i], "-d"))
232 if (argc > (i + 1) && !strcmp(argv[i], "-i")) {
233 extra_elcs = argv[i + 1];
238 fatal ("No output file specified", "");
241 fprintf (outfile, "{\n");
244 for (; i < argc; i++)
247 /* Don't process one file twice. */
248 for (j = first_infile; j < i; j++)
249 if (! strcmp (argv[i], argv[j]))
252 /* err_count seems to be {mis,un}used */
253 err_count += scan_file (argv[i]);
259 while ((p = next_extra_elc(extra_elcs)) != NULL) {
260 err_count += scan_file(p);
264 putc ('\n', outfile);
266 fprintf (outfile, "}\n\n");
268 exit (err_count > 0);
270 return err_count > 0;
273 /* Read file FILENAME and output its doc strings to outfile. */
274 /* Return 1 if file is not found, 0 if it is found. */
277 scan_file (CONST char *filename)
279 int len = strlen (filename);
280 if (ellcc == 0 && len > 4 && !strcmp (filename + len - 4, ".elc"))
282 Current_file_type = elc_file;
283 return scan_lisp_file (filename, READ_BINARY);
285 else if (ellcc == 0 && len > 3 && !strcmp (filename + len - 3, ".el"))
287 Current_file_type = el_file;
288 return scan_lisp_file (filename, READ_TEXT);
292 Current_file_type = c_file;
293 return scan_c_file (filename, READ_TEXT);
299 /* Skip a C string from INFILE,
300 and return the character that follows the closing ".
301 If printflag is positive, output string contents to outfile.
302 If it is negative, store contents in buf.
303 Convert escape sequences \n and \t to newline and tab;
304 discard \ followed by newline. */
307 read_c_string (FILE *infile, int printflag, int c_docstring)
316 while ((c_docstring || c != '"') && c != EOF)
322 int cc = getc (infile);
334 fprintf (outfile, "\\n\\");
335 putc ('\n', outfile);
337 else if (printflag < 0)
351 if (!c_docstring && c == 'n')
362 if (ellcc && c == '"')
363 putc ('\\', outfile);
366 else if (printflag < 0)
371 /* look for continuation of string */
372 if (Current_file_type == c_file)
374 while (isspace (c = getc (infile)))
384 /* If we had a "", concatenate the two strings. */
395 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
396 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
399 write_c_args (FILE *out, CONST char *func, char *buff, int minargs,
408 fprintf (out, "(%s", func);
410 /* XEmacs - "arguments:" is for parsing the docstring. FSF's help system
411 doesn't parse the docstring for arguments like we do, so we're also
412 going to omit the function name to preserve compatibility with elisp
413 that parses the docstring. Finally, not prefixing the arglist with
414 anything is asking for trouble because it's not uncommon to have an
415 unescaped parenthesis at the beginning of a line. --Stig */
416 fprintf (out, "arguments: (");
422 for (p = buff; *p; p++)
427 /* Add support for ANSI prototypes. Hop over
428 "Lisp_Object" string (the only C type allowed in DEFUNs) */
429 static char lo[] = "Lisp_Object";
430 if ((C_IDENTIFIER_CHAR_P (c) != in_ident) && !in_ident &&
431 (strncmp (p, lo, sizeof (lo) - 1) == 0) &&
432 isspace((unsigned char) (* (p + sizeof (lo) - 1))))
434 p += (sizeof (lo) - 1);
435 while (isspace ((unsigned char) (*p)))
440 /* Notice when we start printing a new identifier. */
441 if (C_IDENTIFIER_CHAR_P (c) != in_ident)
448 /* XEmacs - This goes along with the change above. */
452 if (minargs == 0 && maxargs > 0)
453 fprintf (out, "&optional ");
463 /* Print the C argument list as it would appear in lisp:
464 print underscores as hyphens, and print commas as spaces.
465 Collapse adjacent spaces into one. */
466 if (c == '_') c = '-';
467 if (c == ',') c = ' ';
469 /* If the C argument name ends with `_', change it to ' ',
470 to allow use of C reserved words or global symbols as Lisp args. */
471 if (c == '-' && ! C_IDENTIFIER_CHAR_P (p[1]))
476 else if (c != ' ' || ! just_spaced)
478 if (c >= 'a' && c <= 'z')
479 /* Upcase the letter. */
484 just_spaced = (c == ' ');
490 putc ('\n', out); /* XEmacs addition */
493 /* Read through a c file. If a .o file is named,
494 the corresponding .c file is read instead.
495 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
496 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
499 scan_c_file (CONST char *filename, CONST char *mode)
504 register int defunflag;
505 register int defvarperbufferflag = 0;
506 register int defvarflag;
507 int minargs, maxargs;
508 int l = strlen (filename);
514 errno = ENAMETOOLONG;
521 strcpy (f, filename);
524 infile = fopen (f, mode);
526 /* No error if non-ex input file */
534 while (!feof (infile))
571 /* Note that this business doesn't apply under XEmacs.
572 DEFVAR_BUFFER_LOCAL in XEmacs behaves normally. */
573 defvarperbufferflag = (c == 'P');
586 defunflag = (c == 'U');
602 c = read_c_string (infile, -1, 0);
606 else if (defvarperbufferflag)
610 else /* For DEFSIMPLE and DEFPRED */
618 if (defunflag && (commas == 1 || commas == 2))
622 while (c == ' ' || c == '\n' || c == '\t')
627 if (commas == 2) /* pick up minargs */
628 fscanf (infile, "%d", &minargs);
629 else /* pick up maxargs */
630 if (c == 'M' || c == 'U') /* MANY || UNEVALLED */
633 fscanf (infile, "%d", &maxargs);
640 while (c == ' ' || c == '\n' || c == '\t')
643 c = read_c_string (infile, 0, 0);
644 if (defunflag | defvarflag)
658 while (c == ' ' || c == '\n' || c == '\t')
660 if (defunflag | defvarflag)
663 if (defunflag || defvarflag || c == '"')
666 fprintf (outfile, " CDOC%s(\"%s\", \"\\\n",
667 defvarflag ? "SYM" : "SUBR", buf);
671 putc (defvarflag ? 'V' : 'F', outfile);
672 fprintf (outfile, "%s\n", buf);
674 c = read_c_string (infile, 1, (defunflag || defvarflag));
676 /* If this is a defun, find the arguments and print them. If
677 this function takes MANY or UNEVALLED args, then the C source
678 won't give the names of the arguments, so we shouldn't bother
679 trying to find them. */
680 if (defunflag && maxargs != -1)
682 char argbuf[1024], *p = argbuf;
683 #if 0 /* For old DEFUN's only */
691 /* Skip into arguments. */
698 /* Copy arguments into ARGBUF. */
701 *p++ = c = getc (infile);
706 fprintf (outfile, "\\n\\\n\\n\\\n");
708 fprintf (outfile, "\n\n");
709 write_c_args (outfile, buf, argbuf, minargs, maxargs);
712 fprintf (outfile, "\\n\");\n\n");
720 /* Read a file of Lisp code, compiled or interpreted.
722 (defun NAME ARGS DOCSTRING ...)
723 (defmacro NAME ARGS DOCSTRING ...)
724 (autoload (quote NAME) FILE DOCSTRING ...)
725 (defvar NAME VALUE DOCSTRING)
726 (defconst NAME VALUE DOCSTRING)
727 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
728 (fset (quote NAME) #[... DOCSTRING ...])
729 (defalias (quote NAME) #[... DOCSTRING ...])
730 starting in column zero.
731 (quote NAME) may appear as 'NAME as well.
733 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
734 When we find that, we save it for the following defining-form,
735 and we use that instead of reading a doc string within that defining-form.
737 For defun, defmacro, and autoload, we know how to skip over the arglist.
738 For defvar, defconst, and fset we skip to the docstring with a kludgy
739 formatting convention: all docstrings must appear on the same line as the
740 initial open-paren (the one in column zero) and must contain a backslash
741 and a double-quote immediately after the initial double-quote. No newlines
742 must appear between the beginning of the form and the first double-quote.
743 The only source file that must follow this convention is loaddefs.el; aside
744 from that, it is always the .elc file that we look at, and they are no
745 problem because byte-compiler output follows this convention.
746 The NAME and DOCSTRING are output.
747 NAME is preceded by `F' for a function or `V' for a variable.
748 An entry is output only if DOCSTRING has \ newline just after the opening "
752 skip_white (FILE *infile)
755 while (c == ' ' || c == '\t' || c == '\n')
761 read_lisp_symbol (FILE *infile, char *buffer)
764 char *fillp = buffer;
771 /* FSF has *(++fillp), which is wrong. */
772 *fillp++ = getc (infile);
773 else if (c == ' ' || c == '\t' || c == '\n' || c == '(' || c == ')')
784 fprintf (stderr, "## expected a symbol, got '%c'\n", c);
790 scan_lisp_file (CONST char *filename, CONST char *mode)
794 char *saved_string = 0;
796 infile = fopen (filename, mode);
800 return 0; /* No error */
804 while (!feof (infile))
815 /* Detect a dynamic doc string and save it for the next expression. */
824 /* Read the length. */
825 while ((c = getc (infile),
826 c >= '0' && c <= '9'))
832 /* The next character is a space that is counted in the length
833 but not part of the doc string.
834 We already read it, so just ignore it. */
837 /* Read in the contents. */
838 if (saved_string != 0)
840 saved_string = (char *) xmalloc (length);
841 for (i = 0; i < length; i++)
842 saved_string[i] = getc (infile);
843 /* The last character is a ^_.
844 That is needed in the .elc file
845 but it is redundant in DOC. So get rid of it here. */
846 saved_string[length - 1] = 0;
847 /* Skip the newline. */
858 read_lisp_symbol (infile, buffer);
860 if (! strcmp (buffer, "defun") ||
861 ! strcmp (buffer, "defmacro"))
864 read_lisp_symbol (infile, buffer);
866 /* Skip the arguments: either "nil" or a list in parens */
869 if (c == 'n') /* nil */
871 if ((c = getc (infile)) != 'i' ||
872 (c = getc (infile)) != 'l')
874 fprintf (stderr, "## unparsable arglist in %s (%s)\n",
881 fprintf (stderr, "## unparsable arglist in %s (%s)\n",
890 /* If the next three characters aren't `dquote bslash newline'
891 then we're not reading a docstring.
893 if ((c = getc (infile)) != '"' ||
894 (c = getc (infile)) != '\\' ||
895 (c = getc (infile)) != '\n')
898 fprintf (stderr, "## non-docstring in %s (%s)\n",
905 else if (! strcmp (buffer, "defvar") ||
906 ! strcmp (buffer, "defconst"))
910 read_lisp_symbol (infile, buffer);
912 if (saved_string == 0)
915 /* Skip until the first newline; remember the two previous chars. */
916 while (c != '\n' && c >= 0)
918 /* ### Kludge -- Ignore any ESC x x ISO2022 sequences */
932 /* If two previous characters were " and \,
933 this is a doc string. Otherwise, there is none. */
934 if (c2 != '"' || c1 != '\\')
937 fprintf (stderr, "## non-docstring in %s (%s)\n",
945 else if (! strcmp (buffer, "fset") || ! strcmp (buffer, "defalias"))
952 read_lisp_symbol (infile, buffer);
957 fprintf (stderr, "## unparsable name in fset in %s\n",
961 read_lisp_symbol (infile, buffer);
962 if (strcmp (buffer, "quote"))
964 fprintf (stderr, "## unparsable name in fset in %s\n",
968 read_lisp_symbol (infile, buffer);
973 "## unparsable quoted name in fset in %s\n",
979 if (saved_string == 0)
981 /* Skip until the first newline; remember the two previous chars. */
982 while (c != '\n' && c >= 0)
989 /* If two previous characters were " and \,
990 this is a doc string. Otherwise, there is none. */
991 if (c2 != '"' || c1 != '\\')
994 fprintf (stderr, "## non-docstring in %s (%s)\n",
1002 else if (! strcmp (buffer, "autoload"))
1007 read_lisp_symbol (infile, buffer);
1012 fprintf (stderr, "## unparsable name in autoload in %s\n",
1016 read_lisp_symbol (infile, buffer);
1017 if (strcmp (buffer, "quote"))
1019 fprintf (stderr, "## unparsable name in autoload in %s\n",
1023 read_lisp_symbol (infile, buffer);
1028 "## unparsable quoted name in autoload in %s\n",
1033 skip_white (infile);
1034 if ((c = getc (infile)) != '\"')
1036 fprintf (stderr, "## autoload of %s unparsable (%s)\n",
1040 read_c_string (infile, 0, 0);
1041 skip_white (infile);
1043 if (saved_string == 0)
1045 /* If the next three characters aren't `dquote bslash newline'
1046 then we're not reading a docstring. */
1047 if ((c = getc (infile)) != '"' ||
1048 (c = getc (infile)) != '\\' ||
1049 (c = getc (infile)) != '\n')
1052 fprintf (stderr, "## non-docstring in %s (%s)\n",
1060 #if 0 /* causes crash */
1061 else if (! strcmp (buffer, "if") ||
1062 ! strcmp (buffer, "byte-code"))
1069 fprintf (stderr, "## unrecognized top-level form, %s (%s)\n",
1075 /* At this point, we should either use the previous
1076 dynamic doc string in saved_string
1077 or gobble a doc string from the input file.
1079 In the latter case, the opening quote (and leading
1080 backslash-newline) have already been read. */
1081 putc ('\n', outfile); /* XEmacs addition */
1082 putc (037, outfile);
1083 putc (type, outfile);
1084 fprintf (outfile, "%s\n", buffer);
1087 fputs (saved_string, outfile);
1088 /* Don't use one dynamic doc string twice. */
1089 free (saved_string);
1093 read_c_string (infile, 1, 0);