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 if(!fgets(line_buf, BUFSIZ, fp)) {
152 if (!fgets(line_buf, BUFSIZ, fp)) {
158 if (strlen(p) <= 2 || strlen(p) >= (BUFSIZ - 5)) {
159 /* reject too short or too long lines */
162 p[strlen(p) - 2] = '\0';
169 write_doc_header(void)
171 char *tmp, *modout = strdup(modname), *modoutC;
174 if ((tmp = strrchr(modout, '.')) != NULL) {
176 tmp = strrchr(modout, '.');
181 /* the same for modoutC */
182 modoutC = strdup(modout);
183 modsz = strlen(modoutC);
185 for (size_t i = 0; i < modsz; i++) {
186 /* for the C version we have to convert any non-char to _ */
187 if (!isdigit(modoutC[i]) && !isalpha(modoutC[i])) {
192 fprintf(outfile, "/* DO NOT EDIT - AUTOMATICALLY GENERATED */\n\n");
193 fprintf(outfile, "#include <emodules-ng.h>\n\n");
196 fprintf(outfile, "const char *emodule_name = \"%s\";\n", modoutC);
197 fprintf(outfile, "const char *emodule_title = "
198 "\"SXEmacs module: %s\";\n", modout);
200 /* declare and start the LTX_docs() block */
201 fprintf(outfile, "\n\nextern void %s_LTX_docs(void);\n", modoutC);
202 fprintf(outfile, "\nvoid\n%s_LTX_docs(void)\n", modoutC);
206 int main(int argc, char **argv)
210 char *extra_elcs = NULL;
216 /* If first two args are -o FILE, output to FILE. */
217 for (i = 1; i < argc - 1;) {
218 if (!strcmp(argv[i], "-o")) {
219 outfile = fopen(argv[++i], WRITE_BINARY);
221 if (!strcmp(argv[i], "-a")) {
222 outfile = fopen(argv[++i], APPEND_BINARY);
224 if (!strcmp(argv[i], "-E")) {
225 if (modname == NULL) {
226 modname = strdup(argv[i+1]);
229 /*outfile = fopen(argv[++i], APPEND_BINARY);*/
230 outfile = fopen(argv[++i], WRITE_BINARY);
232 if (!strcmp(argv[i], "-d")) {
233 if (chdir(argv[++i]) < 0)
234 fatal("Could not change to directory ",argv[i]);
237 if (!strcmp(argv[i], "-i")) {
238 extra_elcs = argv[++i];
241 if (!strcmp(argv[i], "--modname") || !strcmp(argv[i], "-m")) {
242 modname = strdup(argv[++i]);
247 fatal("No output file specified", "");
251 fprintf(outfile, "{\n");
254 for (i = 1; i < argc; i++) {
257 if (argc > i + 1 && !strcmp (argv[i], "-d")) {
258 /* XEmacs change; allow more than one chdir. The
259 idea is that the second chdir is to source-lisp,
260 and that any Lisp files not under there have the
261 full path specified. */
263 if (chdir (argv[i]) < 0)
264 fatal("Could not change to directory ", argv[i]);
266 } else if (argv[i][0] == '-') {
270 /* Don't process one file twice. */
271 for (j = 1; j < i; j++)
272 if (!strcmp(argv[i], argv[j]))
275 /* err_count seems to be {mis,un}used */
276 err_count += scan_file(argv[i]);
283 while ((p = next_extra_elc(extra_elcs)) != NULL) {
284 err_count += scan_file(p);
290 fprintf(outfile, "}\n\n");
294 return err_count > 0;
297 /* Add a source file name boundary in the output file. */
298 static void put_filename (const char *filename)
300 /* XEmacs change; don't strip directory information. */
304 /* Why are we cutting this off? */
305 for (tmp = filename; *tmp; tmp++) {
306 if (IS_DIRECTORY_SEP(*tmp))
310 /* <= because sizeof includes the nul byte at the end. Not quite
311 right, because it should include the length of the symbol +
312 "\037[VF]" instead of simply 10. */
313 assert(sizeof("\037S\n") + strlen(filename) + 10
314 <= DOC_MAX_FILENAME_LENGTH);
318 fprintf (outfile, "%s\n", filename);
321 /* Read file FILENAME and output its doc strings to outfile. */
322 /* Return 1 if file is not found, 0 if it is found. */
324 static int scan_file(const char *filename)
326 int len = strlen(filename);
328 if (ellcc == 0 && len > 4 && !strcmp(filename + len - 4, ".elc")) {
329 Current_file_type = elc_file;
330 return scan_lisp_file(filename, READ_BINARY);
331 } else if (ellcc == 0 && len > 3 && !strcmp(filename + len - 3, ".el")) {
332 Current_file_type = el_file;
333 return scan_lisp_file(filename, READ_TEXT);
335 Current_file_type = c_file;
336 return scan_c_file(filename, READ_TEXT);
342 /* Skip a C string from INFILE,
343 and return the character that follows the closing ".
344 If printflag is positive, output string contents to outfile.
345 If it is negative, store contents in buf.
346 Convert escape sequences \n and \t to newline and tab;
347 discard \ followed by newline. */
349 #define MDGET do { prevc = c; c = getc (infile); } while (0)
350 static int read_c_string(FILE * infile, int printflag, int c_docstring)
352 register int prevc = 0, c = 0;
358 while ((c_docstring || c != '"') && c != EOF) {
360 int cc = getc(infile);
368 } else if (printflag < 0)
379 fprintf(outfile, "\\n\\");
381 } else if (printflag < 0)
392 if (!c_docstring && c == 'n')
402 if (ellcc && c == '"')
405 } else if (printflag < 0)
410 /* look for continuation of string */
411 if (Current_file_type == c_file) {
422 /* If we had a "", concatenate the two strings. */
433 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
434 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
437 write_c_args(FILE * out, const char *func, char *buff, int minargs, int maxargs)
445 fprintf(out, "(%s", func);
447 /* XEmacs - "arguments:" is for parsing the docstring. FSF's help system
448 doesn't parse the docstring for arguments like we do, so we're also
449 going to omit the function name to preserve compatibility with elisp
450 that parses the docstring. Finally, not prefixing the arglist with
451 anything is asking for trouble because it's not uncommon to have an
452 unescaped parenthesis at the beginning of a line. --Stig */
453 fprintf(out, "arguments: (");
459 for (p = buff; *p; p++) {
463 /* Add support for ANSI prototypes. Hop over
464 "Lisp_Object" string (the only C type allowed in DEFUNs) */
465 static char lo[] = "Lisp_Object";
466 if ((C_IDENTIFIER_CHAR_P(c) != in_ident) && !in_ident &&
467 (strncmp(p, lo, sizeof(lo) - 1) == 0) &&
468 isspace((unsigned char)(*(p + sizeof(lo) - 1)))) {
469 p += (sizeof(lo) - 1);
470 while (isspace((unsigned char)(*p)))
475 /* Notice when we start printing a new identifier. */
476 if (C_IDENTIFIER_CHAR_P(c) != in_ident) {
481 /* XEmacs - This goes along with the change above. */
485 if (minargs == 0 && maxargs > 0)
486 fprintf(out, "&optional ");
495 /* Print the C argument list as it would appear in lisp:
496 print underscores as hyphens, and print commas as spaces.
497 Collapse adjacent spaces into one. */
503 /* If the C argument name ends with `_', change it to ' ',
504 to allow use of C reserved words or global symbols as Lisp args. */
505 if (c == '-' && !C_IDENTIFIER_CHAR_P(p[1])) {
509 /* If the character is carriage return, escape it for the C compiler. */
510 else if (c == '\n') {
513 } else if (c != ' ' || !just_spaced) {
514 if (c >= 'a' && c <= 'z')
515 /* Upcase the letter. */
520 just_spaced = (c == ' ');
526 putc('\n', out); /* XEmacs addition */
529 /* Read through a c file. If a .o file is named,
530 the corresponding .c file is read instead.
531 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
532 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
534 static int scan_c_file(const char *filename, const char *mode)
539 register int defunflag;
540 register int defvarperbufferflag = 0;
541 register int defvarflag;
542 int minargs, maxargs;
543 size_t l = strlen(filename);
548 errno = ENAMETOOLONG;
558 infile = fopen(f, mode);
560 /* No error if non-ex input file */
561 if (infile == NULL) {
567 while (!feof(infile)) {
574 * SXEmacs uses proper indentation so we need to
575 * search for `\t' instead of ' ' here.
605 /* Note that this business doesn't apply under XEmacs.
606 DEFVAR_BUFFER_LOCAL in XEmacs behaves normally. */
607 defvarperbufferflag = (c == 'P');
610 } else if (c == 'D') {
618 defunflag = (c == 'U');
633 c = read_c_string(infile, -1, 0);
637 else if (defvarperbufferflag)
641 else /* For DEFSIMPLE and DEFPRED */
647 if (defunflag && (commas == 1 || commas == 2)) {
650 while (c == ' ' || c == '\n'
655 if (commas == 2) { /* pick up minargs */
656 if ( fscanf(infile, "%d", &minargs) != 1)
657 fprintf(stderr, "Failed to read minargs\n");
658 } else /* pick up maxargs */ if (c == 'M' || c == 'U') /* MANY || UNEVALLED */
661 if ( fscanf(infile, "%d", &maxargs) != 1)
662 fprintf(stderr, "Failed to read maxargs\n");;
669 while (c == ' ' || c == '\n' || c == '\t')
672 c = read_c_string(infile, 0, 0);
673 if (defunflag | defvarflag) {
684 while (c == ' ' || c == '\n' || c == '\t')
686 if (defunflag | defvarflag)
689 if (defunflag || defvarflag || c == '"') {
691 fprintf(outfile, "\tCDOC%s(\"%s\", \"\\\n",
692 defvarflag ? "SYM" : "SUBR", buf);
694 put_filename (filename); /* XEmacs addition */
696 putc(defvarflag ? 'V' : 'F', outfile);
697 fprintf(outfile, "%s\n", buf);
699 c = read_c_string(infile, 1, (defunflag || defvarflag));
701 /* If this is a defun, find the arguments and print
702 them. If this function takes MANY or UNEVALLED args,
703 then the C source won't give the names of the
704 arguments, so we shouldn't bother trying to find
706 if (defunflag && maxargs != -1) {
707 char argbuf[1024], *p = argbuf;
708 #if 0 /* For old DEFUN's only */
715 /* Skip into arguments. */
721 /* Copy arguments into ARGBUF. */
724 *p++ = c = getc(infile);
729 fprintf(outfile, "\\n\\\n\\n\\\n");
731 fprintf(outfile, "\n\n");
732 write_c_args(outfile, buf, argbuf, minargs,
736 fprintf(outfile, "\\n\");\n\n");
744 /* Read a file of Lisp code, compiled or interpreted.
746 (defun NAME ARGS DOCSTRING ...)
747 (defmacro NAME ARGS DOCSTRING ...)
748 (autoload (quote NAME) FILE DOCSTRING ...)
749 (defvar NAME VALUE DOCSTRING)
750 (defconst NAME VALUE DOCSTRING)
751 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
752 (fset (quote NAME) #[... DOCSTRING ...])
753 (defalias (quote NAME) #[... DOCSTRING ...])
754 starting in column zero.
755 (quote NAME) may appear as 'NAME as well.
757 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
758 When we find that, we save it for the following defining-form,
759 and we use that instead of reading a doc string within that defining-form.
761 For defun, defmacro, and autoload, we know how to skip over the arglist.
762 For defvar, defconst, and fset we skip to the docstring with a kludgy
763 formatting convention: all docstrings must appear on the same line as the
764 initial open-paren (the one in column zero) and must contain a backslash
765 and a double-quote immediately after the initial double-quote. No newlines
766 must appear between the beginning of the form and the first double-quote.
767 The only source file that must follow this convention is loaddefs.el; aside
768 from that, it is always the .elc file that we look at, and they are no
769 problem because byte-compiler output follows this convention.
770 The NAME and DOCSTRING are output.
771 NAME is preceded by `F' for a function or `V' for a variable.
772 An entry is output only if DOCSTRING has \ newline just after the opening "
774 Adds the filename a symbol or function was found in before its docstring;
775 there's no need for this with the load-history available, but we do it for
776 consistency with the C parsing code.
779 static void skip_white(FILE * infile)
782 while (c == ' ' || c == '\t' || c == '\n')
787 static void read_lisp_symbol(FILE * infile, char *buffer)
790 char *fillp = buffer;
796 /* FSF has *(++fillp), which is wrong. */
797 *fillp++ = getc(infile);
798 else if (c == ' ' || c == '\t' || c == '\n' || c == '('
808 fprintf(stderr, "## expected a symbol, got '%c'\n", c);
813 static int scan_lisp_file(const char *filename, const char *mode)
817 char *saved_string = 0;
819 infile = fopen(filename, mode);
820 if (infile == NULL) {
822 return 0; /* No error */
826 while (!feof(infile)) {
835 /* Detect a dynamic doc string and save it for the next expression. */
842 /* Read the length. */
843 while ((c = getc(infile), c >= '0' && c <= '9')) {
848 /* The next character is a space that is counted in the length
849 but not part of the doc string.
850 We already read it, so just ignore it. */
853 /* Read in the contents. */
854 if (saved_string != 0)
856 saved_string = (char *)xmalloc(length);
857 for (i = 0; i < length; i++)
858 saved_string[i] = getc(infile);
859 /* The last character is a ^_.
860 That is needed in the .elc file
861 but it is redundant in DOC. So get rid of it here. */
862 saved_string[length - 1] = 0;
863 /* Skip the newline. */
874 read_lisp_symbol(infile, buffer);
876 if (!strcmp(buffer, "defun") || !strcmp(buffer, "defmacro")) {
878 read_lisp_symbol(infile, buffer);
880 /* Skip the arguments: either "nil" or a list in parens */
883 if (c == 'n') { /* nil */
884 if ((c = getc(infile)) != 'i' ||
885 (c = getc(infile)) != 'l') {
887 "## unparsable arglist in %s (%s)\n",
891 } else if (c != '(') {
893 "## unparsable arglist in %s (%s)\n",
901 /* If the next three characters aren't `dquote bslash newline'
902 then we're not reading a docstring.
904 if ((c = getc(infile)) != '"' ||
905 (c = getc(infile)) != '\\' ||
906 (c = getc(infile)) != '\n') {
908 fprintf(stderr, "## non-docstring in %s (%s)\n",
915 else if (!strcmp(buffer, "defvar") ||
916 !strcmp(buffer, "defconst")) {
919 read_lisp_symbol(infile, buffer);
921 if (saved_string == 0) {
923 /* Skip until the first newline; remember the two previous chars. */
924 while (c != '\n' && c >= 0) {
925 /* #### Kludge -- Ignore any ESC x x ISO2022 sequences */
938 /* If two previous characters were " and \,
939 this is a doc string. Otherwise, there is none. */
940 if (c2 != '"' || c1 != '\\') {
943 "## non-docstring in %s (%s)\n",
951 else if (! strcmp (buffer, "custom-declare-variable"))
958 read_lisp_symbol (infile, buffer);
962 "## unparsable name in "
963 "custom-declare-variable "
968 read_lisp_symbol (infile, buffer);
969 if (strcmp (buffer, "quote")) {
971 "## unparsable name in "
972 "custom-declare-variable "
977 read_lisp_symbol (infile, buffer);
981 "## unparsable quoted name "
982 "in custom-declare-variable"
983 " in %s\n", filename);
988 if (saved_string == 0)
990 /* Skip to end of line; remember the two
992 while (c != '\n' && c >= 0) {
995 /* SXEmacs: shame we can't do this. */
996 /* c = getc_skipping_iso2022 (infile); */
1000 /* If two previous characters were " and \,
1001 this is a doc string. Otherwise, there is
1003 if (c2 != '"' || c1 != '\\') {
1005 fprintf (stderr, "## non-docstring in"
1014 else if (!strcmp(buffer, "fset") || !strcmp(buffer, "defalias")) {
1015 char c1 = 0, c2 = 0;
1020 read_lisp_symbol(infile, buffer);
1024 "## unparsable name in fset in %s\n",
1028 read_lisp_symbol(infile, buffer);
1029 if (strcmp(buffer, "quote")) {
1031 "## unparsable name in fset in %s\n",
1035 read_lisp_symbol(infile, buffer);
1039 "## unparsable quoted name in fset in %s\n",
1045 if (saved_string == 0) {
1046 /* Skip until the first newline; remember the two previous chars. */
1047 while (c != '\n' && c >= 0) {
1053 /* If two previous characters were " and \,
1054 this is a doc string. Otherwise, there is none. */
1055 if (c2 != '"' || c1 != '\\') {
1058 "## non-docstring in %s (%s)\n",
1066 else if (!strcmp(buffer, "autoload")) {
1070 read_lisp_symbol(infile, buffer);
1074 "## unparsable name in autoload in %s\n",
1078 read_lisp_symbol(infile, buffer);
1079 if (strcmp(buffer, "quote")) {
1081 "## unparsable name in autoload in %s\n",
1085 read_lisp_symbol(infile, buffer);
1089 "## unparsable quoted name in autoload in %s\n",
1095 if ((c = getc(infile)) != '\"') {
1097 "## autoload of %s unparsable (%s)\n",
1101 read_c_string(infile, 0, 0);
1104 if (saved_string == 0) {
1105 /* If the next three characters aren't `dquote bslash newline'
1106 then we're not reading a docstring. */
1107 if ((c = getc(infile)) != '"' ||
1108 (c = getc(infile)) != '\\' ||
1109 (c = getc(infile)) != '\n') {
1112 "## non-docstring in %s (%s)\n",
1119 #if 0 /* causes crash */
1120 else if (!strcmp(buffer, "if") ||
1121 !strcmp(buffer, "byte-code")) ;
1127 "## unrecognized top-level form, %s (%s)\n",
1133 /* At this point, we should either use the previous
1134 dynamic doc string in saved_string
1135 or gobble a doc string from the input file.
1137 In the latter case, the opening quote (and leading
1138 backslash-newline) have already been read. */
1139 put_filename (filename); /* XEmacs addition */
1141 putc(type, outfile);
1142 fprintf(outfile, "%s\n", buffer);
1144 fputs(saved_string, outfile);
1145 /* Don't use one dynamic doc string twice. */
1149 read_c_string(infile, 1, 0);
1152 /* If this is true then a dynamic doc string was
1153 detected without a next expression. We should not
1154 emit anything since the input was badly formed,
1155 but lets free the string...