]>
code.delx.au - gnu-emacs/blob - lib-src/make-docfile.c
1 /* Generate doc-string file for GNU Emacs from source files.
3 Copyright (C) 1985-1986, 1992-1994, 1997, 1999-2015 Free Software
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 of the License, or
11 (at your option) any later version.
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. If not, see <http://www.gnu.org/licenses/>. */
22 /* The arguments given to this program are all the C and Lisp source files
23 of GNU Emacs. .elc and .el and .c files are allowed.
24 A .o file can also be specified; the .c file it was made from is used.
25 This helps the makefile pass the correct list of files.
26 Option -d DIR means change to DIR before looking for files.
28 The results, which go to standard output or to a file
29 specified with -a or -o (-a to append, -o to start from nothing),
30 are entries containing function or variable names and their documentation.
31 Each entry starts with a ^_ character.
32 Then comes F for a function or V for a variable.
33 Then comes the function or variable name, terminated with a newline.
34 Then comes the documentation for that function or variable.
41 #include <stdlib.h> /* config.h unconditionally includes this anyway */
44 /* Defined to be sys_fopen in ms-w32.h, but only #ifdef emacs, so this
45 is really just insurance. */
48 #endif /* WINDOWSNT */
50 #include <binary-io.h>
53 /* Defined to be sys_chdir in ms-w32.h, but only #ifdef emacs, so this
54 is really just insurance.
56 Similarly, msdos defines this as sys_chdir, but we're not linking with the
57 file where that function is defined. */
59 #define IS_SLASH(c) ((c) == '/' || (c) == '\\' || (c) == ':')
60 #else /* not DOS_NT */
61 #define IS_SLASH(c) ((c) == '/')
62 #endif /* not DOS_NT */
64 static int scan_file (char *filename
);
65 static int scan_lisp_file (const char *filename
, const char *mode
);
66 static int scan_c_file (char *filename
, const char *mode
);
67 static int scan_c_stream (FILE *infile
);
68 static void start_globals (void);
69 static void write_globals (void);
73 /* Name this program was invoked with. */
76 /* Nonzero if this invocation is generating globals.h. */
79 /* Print error message. `s1' is printf control string, `s2' is arg for it. */
83 error (const char *s1
, const char *s2
)
85 fprintf (stderr
, "%s: ", progname
);
86 fprintf (stderr
, s1
, s2
);
87 fprintf (stderr
, "\n");
90 /* Print error message and exit. */
94 fatal (const char *s1
, const char *s2
)
100 /* Like malloc but get fatal error if memory is exhausted. */
103 xmalloc (unsigned int size
)
105 void *result
= (void *) malloc (size
);
107 fatal ("virtual memory exhausted", 0);
111 /* Like strdup, but get fatal error if memory is exhausted. */
116 char *result
= strdup (s
);
118 fatal ("virtual memory exhausted", 0);
122 /* Like realloc but get fatal error if memory is exhausted. */
125 xrealloc (void *arg
, unsigned int size
)
127 void *result
= (void *) realloc (arg
, size
);
129 fatal ("virtual memory exhausted", 0);
135 main (int argc
, char **argv
)
142 /* If first two args are -o FILE, output to FILE. */
144 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
146 if (! freopen (argv
[i
+ 1], "w", stdout
))
148 perror (argv
[i
+ 1]);
153 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
155 if (! freopen (argv
[i
+ 1], "a", stdout
))
157 perror (argv
[i
+ 1]);
162 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
164 if (chdir (argv
[i
+ 1]) != 0)
166 perror (argv
[i
+ 1]);
171 if (argc
> i
&& !strcmp (argv
[i
], "-g"))
173 generate_globals
= 1;
177 set_binary_mode (fileno (stdout
), O_BINARY
);
179 if (generate_globals
)
183 scan_c_stream (stdin
);
186 int first_infile
= i
;
187 for (; i
< argc
; i
++)
190 /* Don't process one file twice. */
191 for (j
= first_infile
; j
< i
; j
++)
192 if (strcmp (argv
[i
], argv
[j
]) == 0)
195 err_count
+= scan_file (argv
[i
]);
199 if (err_count
== 0 && generate_globals
)
202 return (err_count
> 0 ? EXIT_FAILURE
: EXIT_SUCCESS
);
205 /* Add a source file name boundary marker in the output file. */
207 put_filename (char *filename
)
211 for (tmp
= filename
; *tmp
; tmp
++)
213 if (IS_DIRECTORY_SEP (*tmp
))
217 printf ("\037S%s\n", filename
);
220 /* Read file FILENAME and output its doc strings to stdout.
221 Return 1 if file is not found, 0 if it is found. */
224 scan_file (char *filename
)
227 size_t len
= strlen (filename
);
229 if (!generate_globals
)
230 put_filename (filename
);
231 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
232 return scan_lisp_file (filename
, "rb");
233 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
234 return scan_lisp_file (filename
, "r");
236 return scan_c_file (filename
, "r");
242 puts ("/* This file was auto-generated by make-docfile. */");
243 puts ("/* DO NOT EDIT. */");
244 puts ("struct emacs_globals {");
247 static char input_buffer
[128];
249 /* Some state during the execution of `read_c_string_or_comment'. */
252 /* A count of spaces and newlines that have been read, but not output. */
253 unsigned pending_spaces
, pending_newlines
;
255 /* Where we're reading from. */
258 /* If non-zero, a buffer into which to copy characters. */
260 /* If non-zero, a file into which to copy characters. */
263 /* A keyword we look for at the beginning of lines. If found, it is
264 not copied, and SAW_KEYWORD is set to true. */
266 /* The current point we've reached in an occurrence of KEYWORD in
268 const char *cur_keyword_ptr
;
269 /* Set to true if we saw an occurrence of KEYWORD. */
273 /* Output CH to the file or buffer in STATE. Any pending newlines or
274 spaces are output first. */
277 put_char (int ch
, struct rcsoc_state
*state
)
282 if (state
->pending_newlines
> 0)
284 state
->pending_newlines
--;
287 else if (state
->pending_spaces
> 0)
289 state
->pending_spaces
--;
296 putc (out_ch
, state
->out_file
);
298 *state
->buf_ptr
++ = out_ch
;
300 while (out_ch
!= ch
);
303 /* If in the middle of scanning a keyword, continue scanning with
304 character CH, otherwise output CH to the file or buffer in STATE.
305 Any pending newlines or spaces are output first, as well as any
306 previously scanned characters that were thought to be part of a
307 keyword, but were in fact not. */
310 scan_keyword_or_put_char (int ch
, struct rcsoc_state
*state
)
313 && *state
->cur_keyword_ptr
== ch
314 && (state
->cur_keyword_ptr
> state
->keyword
315 || state
->pending_newlines
> 0))
316 /* We might be looking at STATE->keyword at some point.
317 Keep looking until we know for sure. */
319 if (*++state
->cur_keyword_ptr
== '\0')
320 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
322 state
->saw_keyword
= 1;
324 /* Reset the scanning pointer. */
325 state
->cur_keyword_ptr
= state
->keyword
;
327 /* Canonicalize whitespace preceding a usage string. */
328 state
->pending_newlines
= 2;
329 state
->pending_spaces
= 0;
331 /* Skip any whitespace between the keyword and the
334 ch
= getc (state
->in_file
);
335 while (ch
== ' ' || ch
== '\n');
337 /* Output the open-paren we just read. */
338 put_char (ch
, state
);
340 /* Skip the function name and replace it with `fn'. */
342 ch
= getc (state
->in_file
);
343 while (ch
!= ' ' && ch
!= ')');
344 put_char ('f', state
);
345 put_char ('n', state
);
347 /* Put back the last character. */
348 ungetc (ch
, state
->in_file
);
353 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
354 /* We scanned the beginning of a potential usage
355 keyword, but it was a false alarm. Output the
360 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
361 put_char (*p
, state
);
363 state
->cur_keyword_ptr
= state
->keyword
;
366 put_char (ch
, state
);
371 /* Skip a C string or C-style comment from INFILE, and return the
372 character that follows. COMMENT non-zero means skip a comment. If
373 PRINTFLAG is positive, output string contents to stdout. If it is
374 negative, store contents in buf. Convert escape sequences \n and
375 \t to newline and tab; discard \ followed by newline.
376 If SAW_USAGE is non-zero, then any occurrences of the string `usage:'
377 at the beginning of a line will be removed, and *SAW_USAGE set to
378 true if any were encountered. */
381 read_c_string_or_comment (FILE *infile
, int printflag
, int comment
, int *saw_usage
)
384 struct rcsoc_state state
;
386 state
.in_file
= infile
;
387 state
.buf_ptr
= (printflag
< 0 ? input_buffer
: 0);
388 state
.out_file
= (printflag
> 0 ? stdout
: 0);
389 state
.pending_spaces
= 0;
390 state
.pending_newlines
= 0;
391 state
.keyword
= (saw_usage
? "usage:" : 0);
392 state
.cur_keyword_ptr
= state
.keyword
;
393 state
.saw_keyword
= 0;
397 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
402 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
407 if (c
== '\n' || c
== '\r')
419 state
.pending_spaces
++;
422 state
.pending_newlines
++;
423 state
.pending_spaces
= 0;
426 scan_keyword_or_put_char (c
, &state
);
442 scan_keyword_or_put_char ('*', &state
);
449 /* If we had a "", concatenate the two strings. */
458 *saw_usage
= state
.saw_keyword
;
465 /* Write to stdout the argument names of function FUNC, whose text is in BUF.
466 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
469 write_c_args (char *func
, char *buf
, int minargs
, int maxargs
)
473 char *ident_start
IF_LINT (= NULL
);
474 size_t ident_length
= 0;
476 fputs ("(fn", stdout
);
481 for (p
= buf
; *p
; p
++)
485 /* Notice when a new identifier starts. */
486 if ((('A' <= c
&& c
<= 'Z')
487 || ('a' <= c
&& c
<= 'z')
488 || ('0' <= c
&& c
<= '9')
500 ident_length
= p
- ident_start
;
504 /* Found the end of an argument, write out the last seen
506 if (c
== ',' || c
== ')')
508 if (ident_length
== 0)
510 error ("empty arg list for `%s' should be (void), not ()", func
);
514 if (strncmp (ident_start
, "void", ident_length
) == 0)
519 if (minargs
== 0 && maxargs
> 0)
520 fputs ("&optional ", stdout
);
525 /* In C code, `default' is a reserved word, so we spell it
526 `defalt'; demangle that here. */
527 if (ident_length
== 6 && memcmp (ident_start
, "defalt", 6) == 0)
528 fputs ("DEFAULT", stdout
);
530 while (ident_length
-- > 0)
533 if (c
>= 'a' && c
<= 'z')
534 /* Upcase the letter. */
537 /* Print underscore as hyphen. */
547 /* The types of globals. These are sorted roughly in decreasing alignment
548 order to avoid allocation gaps, except that symbols and functions
560 /* A single global. */
563 enum global_type type
;
572 /* All the variable names we saw while scanning C sources in `-g'
575 int num_globals_allocated
;
576 struct global
*globals
;
579 add_global (enum global_type type
, char *name
, int value
, char const *svalue
)
581 /* Ignore the one non-symbol that can occur. */
582 if (strcmp (name
, "..."))
586 if (num_globals_allocated
== 0)
588 num_globals_allocated
= 100;
589 globals
= xmalloc (num_globals_allocated
* sizeof (struct global
));
591 else if (num_globals
== num_globals_allocated
)
593 num_globals_allocated
*= 2;
594 globals
= xrealloc (globals
,
595 num_globals_allocated
* sizeof (struct global
));
598 globals
[num_globals
- 1].type
= type
;
599 globals
[num_globals
- 1].name
= name
;
601 globals
[num_globals
- 1].v
.svalue
= svalue
;
603 globals
[num_globals
- 1].v
.value
= value
;
608 compare_globals (const void *a
, const void *b
)
610 const struct global
*ga
= a
;
611 const struct global
*gb
= b
;
613 if (ga
->type
!= gb
->type
)
614 return ga
->type
- gb
->type
;
616 /* Consider "nil" to be the least, so that iQnil is zero. That
617 way, Qnil's internal representation is zero, which is a bit faster. */
618 if (ga
->type
== SYMBOL
)
620 bool a_nil
= strcmp (ga
->name
, "Qnil") == 0;
621 bool b_nil
= strcmp (gb
->name
, "Qnil") == 0;
623 return b_nil
- a_nil
;
626 return strcmp (ga
->name
, gb
->name
);
630 close_emacs_globals (int num_symbols
)
633 "extern struct emacs_globals globals;\n"
635 "#ifndef DEFINE_SYMBOLS\n"
638 "struct Lisp_Symbol alignas (GCALIGNMENT) lispsym[%d];\n"),
646 bool seen_defun
= false;
649 qsort (globals
, num_globals
, sizeof (struct global
), compare_globals
);
652 for (i
= 0; i
< num_globals
; i
++)
654 while (i
+ 1 < num_globals
655 && strcmp (globals
[i
].name
, globals
[i
+ 1].name
) == 0)
657 if (globals
[i
].type
== FUNCTION
658 && globals
[i
].v
.value
!= globals
[i
+ 1].v
.value
)
659 error ("function '%s' defined twice with differing signatures",
663 num_symbols
+= globals
[i
].type
== SYMBOL
;
664 globals
[j
++] = globals
[i
];
668 for (i
= 0; i
< num_globals
; ++i
)
670 char const *type
= 0;
672 switch (globals
[i
].type
)
681 type
= "Lisp_Object";
687 close_emacs_globals (num_symbols
);
693 fatal ("not a recognized DEFVAR_", 0);
698 printf (" %s f_%s;\n", type
, globals
[i
].name
);
699 printf ("#define %s globals.f_%s\n",
700 globals
[i
].name
, globals
[i
].name
);
702 else if (globals
[i
].type
== SYMBOL
)
703 printf (("DEFINE_LISP_SYMBOL_BEGIN (%s)\n"
705 "#define %s builtin_lisp_symbol (i%s)\n"
706 "DEFINE_LISP_SYMBOL_END (%s)\n\n"),
707 globals
[i
].name
, globals
[i
].name
, symnum
++,
708 globals
[i
].name
, globals
[i
].name
, globals
[i
].name
);
711 /* It would be nice to have a cleaner way to deal with these
713 if (strcmp (globals
[i
].name
, "Fthrow") == 0
714 || strcmp (globals
[i
].name
, "Ftop_level") == 0
715 || strcmp (globals
[i
].name
, "Fkill_emacs") == 0
716 || strcmp (globals
[i
].name
, "Fexit_recursive_edit") == 0
717 || strcmp (globals
[i
].name
, "Fabort_recursive_edit") == 0)
718 fputs ("_Noreturn ", stdout
);
720 printf ("EXFUN (%s, ", globals
[i
].name
);
721 if (globals
[i
].v
.value
== -1)
722 fputs ("MANY", stdout
);
723 else if (globals
[i
].v
.value
== -2)
724 fputs ("UNEVALLED", stdout
);
726 printf ("%d", globals
[i
].v
.value
);
729 /* It would be nice to have a cleaner way to deal with these
730 special hacks, too. */
731 if (strcmp (globals
[i
].name
, "Fatom") == 0
732 || strcmp (globals
[i
].name
, "Fbyteorder") == 0
733 || strcmp (globals
[i
].name
, "Fcharacterp") == 0
734 || strcmp (globals
[i
].name
, "Fchar_or_string_p") == 0
735 || strcmp (globals
[i
].name
, "Fconsp") == 0
736 || strcmp (globals
[i
].name
, "Feq") == 0
737 || strcmp (globals
[i
].name
, "Fface_attribute_relative_p") == 0
738 || strcmp (globals
[i
].name
, "Fframe_windows_min_size") == 0
739 || strcmp (globals
[i
].name
, "Fgnutls_errorp") == 0
740 || strcmp (globals
[i
].name
, "Fidentity") == 0
741 || strcmp (globals
[i
].name
, "Fintegerp") == 0
742 || strcmp (globals
[i
].name
, "Finteractive") == 0
743 || strcmp (globals
[i
].name
, "Ffloatp") == 0
744 || strcmp (globals
[i
].name
, "Flistp") == 0
745 || strcmp (globals
[i
].name
, "Fmax_char") == 0
746 || strcmp (globals
[i
].name
, "Fnatnump") == 0
747 || strcmp (globals
[i
].name
, "Fnlistp") == 0
748 || strcmp (globals
[i
].name
, "Fnull") == 0
749 || strcmp (globals
[i
].name
, "Fnumberp") == 0
750 || strcmp (globals
[i
].name
, "Fstringp") == 0
751 || strcmp (globals
[i
].name
, "Fsymbolp") == 0
752 || strcmp (globals
[i
].name
, "Ftool_bar_height") == 0
753 || strcmp (globals
[i
].name
, "Fwindow__sanitize_window_sizes") == 0
755 || strcmp (globals
[i
].name
, "Fgnutls_available_p") == 0
756 || strcmp (globals
[i
].name
, "Fzlib_available_p") == 0
759 fputs (" ATTRIBUTE_CONST", stdout
);
766 close_emacs_globals (num_symbols
);
768 puts ("#ifdef DEFINE_SYMBOLS");
769 puts ("static char const *const defsym_name[] = {");
770 for (int i
= 0; i
< num_globals
; i
++)
772 if (globals
[i
].type
== SYMBOL
)
773 printf ("\t\"%s\",\n", globals
[i
].v
.svalue
);
774 while (i
+ 1 < num_globals
775 && strcmp (globals
[i
].name
, globals
[i
+ 1].name
) == 0)
783 /* Read through a c file. If a .o file is named,
784 the corresponding .c or .m file is read instead.
785 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
786 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
789 scan_c_file (char *filename
, const char *mode
)
792 int extension
= filename
[strlen (filename
) - 1];
794 if (extension
== 'o')
795 filename
[strlen (filename
) - 1] = 'c';
797 infile
= fopen (filename
, mode
);
799 if (infile
== NULL
&& extension
== 'o')
802 filename
[strlen (filename
) - 1] = 'm';
803 infile
= fopen (filename
, mode
);
805 filename
[strlen (filename
) - 1] = 'c'; /* Don't confuse people. */
808 /* No error if non-ex input file. */
815 /* Reset extension to be able to detect duplicate files. */
816 filename
[strlen (filename
) - 1] = extension
;
817 return scan_c_stream (infile
);
821 scan_c_stream (FILE *infile
)
823 int commas
, minargs
, maxargs
;
826 while (!feof (infile
))
830 int defvarperbufferflag
= 0;
832 enum global_type type
= INVALID
;
833 char *name
IF_LINT (= 0);
835 if (c
!= '\n' && c
!= '\r')
863 if (c
!= ' ' && c
!= '\t' && c
!= '(')
882 defvarperbufferflag
= (c
== 'P');
883 if (generate_globals
)
886 type
= EMACS_INTEGER
;
894 /* We need to distinguish between DEFVAR_BOOL and
895 DEFVAR_BUFFER_DEFAULTS. */
896 if (generate_globals
&& type
== BOOLEAN
&& c
!= 'O')
911 defunflag
= c
== 'U';
916 && (!defvarflag
|| defvarperbufferflag
|| type
== INVALID
)
917 && !defunflag
&& type
!= SYMBOL
)
929 /* Lisp variable or function name. */
933 c
= read_c_string_or_comment (infile
, -1, 0, 0);
936 if (generate_globals
)
939 char const *svalue
= 0;
941 /* Skip "," and whitespace. */
946 while (c
== ',' || c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r');
948 /* Read in the identifier. */
953 input_buffer
[i
++] = c
;
956 while (! (c
== ',' || c
== ' ' || c
== '\t'
957 || c
== '\n' || c
== '\r'));
958 input_buffer
[i
] = '\0';
960 name
= xmalloc (i
+ 1);
961 memcpy (name
, input_buffer
, i
+ 1);
967 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r');
970 c
= read_c_string_or_comment (infile
, -1, 0, 0);
971 svalue
= xstrdup (input_buffer
);
976 add_global (type
, name
, 0, svalue
);
984 /* DEFVAR_LISP ("name", addr, "doc")
985 DEFVAR_LISP ("name", addr /\* doc *\/)
986 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
989 commas
= generate_globals
? 4 : 5;
990 else if (defvarperbufferflag
)
994 else /* For DEFSIMPLE and DEFPRED. */
1003 if (defunflag
&& (commas
== 1 || commas
== 2))
1008 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
1012 if (commas
== 2) /* Pick up minargs. */
1013 scanned
= fscanf (infile
, "%d", &minargs
);
1014 else /* Pick up maxargs. */
1015 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
1017 if (generate_globals
)
1018 maxargs
= (c
== 'M') ? -1 : -2;
1023 scanned
= fscanf (infile
, "%d", &maxargs
);
1034 if (generate_globals
)
1036 add_global (FUNCTION
, name
, maxargs
, 0);
1040 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1044 c
= read_c_string_or_comment (infile
, 0, 0, 0);
1046 while (c
!= EOF
&& c
!= ',' && c
!= '/')
1051 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1053 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
1059 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1066 && (c
= getc (infile
),
1070 int comment
= c
!= '"';
1073 printf ("\037%c%s\n", defvarflag
? 'V' : 'F', input_buffer
);
1076 getc (infile
); /* Skip past `*'. */
1077 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
1079 /* If this is a defun, find the arguments and print them. If
1080 this function takes MANY or UNEVALLED args, then the C source
1081 won't give the names of the arguments, so we shouldn't bother
1082 trying to find them.
1084 Various doc-string styles:
1085 0: DEFUN (..., "DOC") (args) [!comment]
1086 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
1087 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
1089 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
1091 char argbuf
[1024], *p
= argbuf
;
1093 if (!comment
|| doc_keyword
)
1101 /* Skip into arguments. */
1108 /* Copy arguments into ARGBUF. */
1111 *p
++ = c
= getc (infile
);
1115 fputs ("\n\n", stdout
);
1116 write_c_args (input_buffer
, argbuf
, minargs
, maxargs
);
1118 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
1119 /* The DOC should provide the usage form. */
1120 fprintf (stderr
, "Missing `usage' for function `%s'.\n",
1129 /* Read a file of Lisp code, compiled or interpreted.
1131 (defun NAME ARGS DOCSTRING ...)
1132 (defmacro NAME ARGS DOCSTRING ...)
1133 (defsubst NAME ARGS DOCSTRING ...)
1134 (autoload (quote NAME) FILE DOCSTRING ...)
1135 (defvar NAME VALUE DOCSTRING)
1136 (defconst NAME VALUE DOCSTRING)
1137 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
1138 (fset (quote NAME) #[... DOCSTRING ...])
1139 (defalias (quote NAME) #[... DOCSTRING ...])
1140 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
1141 starting in column zero.
1142 (quote NAME) may appear as 'NAME as well.
1144 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
1145 When we find that, we save it for the following defining-form,
1146 and we use that instead of reading a doc string within that defining-form.
1148 For defvar, defconst, and fset we skip to the docstring with a kludgy
1149 formatting convention: all docstrings must appear on the same line as the
1150 initial open-paren (the one in column zero) and must contain a backslash
1151 and a newline immediately after the initial double-quote. No newlines
1152 must appear between the beginning of the form and the first double-quote.
1153 For defun, defmacro, and autoload, we know how to skip over the
1154 arglist, but the doc string must still have a backslash and newline
1155 immediately after the double quote.
1156 The only source files that must follow this convention are preloaded
1157 uncompiled ones like loaddefs.el; aside from that, it is always the .elc
1158 file that we should look at, and they are no problem because byte-compiler
1159 output follows this convention.
1160 The NAME and DOCSTRING are output.
1161 NAME is preceded by `F' for a function or `V' for a variable.
1162 An entry is output only if DOCSTRING has \ newline just after the opening ".
1166 skip_white (FILE *infile
)
1169 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
1175 read_lisp_symbol (FILE *infile
, char *buffer
)
1178 char *fillp
= buffer
;
1180 skip_white (infile
);
1185 *(++fillp
) = getc (infile
);
1186 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
1197 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
1199 skip_white (infile
);
1203 search_lisp_doc_at_eol (FILE *infile
)
1205 int c
= 0, c1
= 0, c2
= 0;
1207 /* Skip until the end of line; remember two previous chars. */
1208 while (c
!= '\n' && c
!= '\r' && c
!= EOF
)
1215 /* If two previous characters were " and \,
1216 this is a doc string. Otherwise, there is none. */
1217 if (c2
!= '"' || c1
!= '\\')
1220 fprintf (stderr
, "## non-docstring found\n");
1229 #define DEF_ELISP_FILE(fn) { #fn, sizeof(#fn) - 1 }
1232 scan_lisp_file (const char *filename
, const char *mode
)
1236 char *saved_string
= 0;
1237 /* These are the only files that are loaded uncompiled, and must
1238 follow the conventions of the doc strings expected by this
1239 function. These conventions are automatically followed by the
1240 byte compiler when it produces the .elc files. */
1244 } const uncompiled
[] = {
1245 DEF_ELISP_FILE (loaddefs
.el
),
1246 DEF_ELISP_FILE (loadup
.el
),
1247 DEF_ELISP_FILE (charprop
.el
),
1248 DEF_ELISP_FILE (cp51932
.el
),
1249 DEF_ELISP_FILE (eucjp
-ms
.el
)
1252 size_t flen
= strlen (filename
);
1254 if (generate_globals
)
1255 fatal ("scanning lisp file when -g specified", 0);
1256 if (flen
> 3 && !strcmp (filename
+ flen
- 3, ".el"))
1258 for (i
= 0, match
= 0; i
< sizeof (uncompiled
) / sizeof (uncompiled
[0]);
1261 if (uncompiled
[i
].fl
<= flen
1262 && !strcmp (filename
+ flen
- uncompiled
[i
].fl
, uncompiled
[i
].fn
)
1263 && (flen
== uncompiled
[i
].fl
1264 || IS_SLASH (filename
[flen
- uncompiled
[i
].fl
- 1])))
1271 fatal ("uncompiled lisp file %s is not supported", filename
);
1274 infile
= fopen (filename
, mode
);
1278 return 0; /* No error. */
1282 while (!feof (infile
))
1284 char buffer
[BUFSIZ
];
1287 /* If not at end of line, skip till we get to one. */
1288 if (c
!= '\n' && c
!= '\r')
1293 /* Skip the line break. */
1294 while (c
== '\n' || c
== '\r')
1296 /* Detect a dynamic doc string and save it for the next expression. */
1305 /* Read the length. */
1306 while ((c
= getc (infile
),
1307 c
>= '0' && c
<= '9'))
1314 fatal ("invalid dynamic doc string length", "");
1317 fatal ("space not found after dynamic doc string length", "");
1319 /* The next character is a space that is counted in the length
1320 but not part of the doc string.
1321 We already read it, so just ignore it. */
1324 /* Read in the contents. */
1325 free (saved_string
);
1326 saved_string
= (char *) xmalloc (length
);
1327 for (i
= 0; i
< length
; i
++)
1328 saved_string
[i
] = getc (infile
);
1329 /* The last character is a ^_.
1330 That is needed in the .elc file
1331 but it is redundant in DOC. So get rid of it here. */
1332 saved_string
[length
- 1] = 0;
1333 /* Skip the line break. */
1334 while (c
== '\n' || c
== '\r')
1336 /* Skip the following line. */
1337 while (c
!= '\n' && c
!= '\r')
1346 read_lisp_symbol (infile
, buffer
);
1348 if (! strcmp (buffer
, "defun")
1349 || ! strcmp (buffer
, "defmacro")
1350 || ! strcmp (buffer
, "defsubst"))
1353 read_lisp_symbol (infile
, buffer
);
1355 /* Skip the arguments: either "nil" or a list in parens. */
1358 if (c
== 'n') /* nil */
1360 if ((c
= getc (infile
)) != 'i'
1361 || (c
= getc (infile
)) != 'l')
1363 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
1370 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
1377 skip_white (infile
);
1379 /* If the next three characters aren't `dquote bslash newline'
1380 then we're not reading a docstring.
1382 if ((c
= getc (infile
)) != '"'
1383 || (c
= getc (infile
)) != '\\'
1384 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1387 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1394 /* defcustom can only occur in uncompiled Lisp files. */
1395 else if (! strcmp (buffer
, "defvar")
1396 || ! strcmp (buffer
, "defconst")
1397 || ! strcmp (buffer
, "defcustom"))
1400 read_lisp_symbol (infile
, buffer
);
1402 if (saved_string
== 0)
1403 if (!search_lisp_doc_at_eol (infile
))
1407 else if (! strcmp (buffer
, "custom-declare-variable")
1408 || ! strcmp (buffer
, "defvaralias")
1415 read_lisp_symbol (infile
, buffer
);
1421 "## unparsable name in custom-declare-variable in %s\n",
1425 read_lisp_symbol (infile
, buffer
);
1426 if (strcmp (buffer
, "quote"))
1429 "## unparsable name in custom-declare-variable in %s\n",
1433 read_lisp_symbol (infile
, buffer
);
1438 "## unparsable quoted name in custom-declare-variable in %s\n",
1444 if (saved_string
== 0)
1445 if (!search_lisp_doc_at_eol (infile
))
1449 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1455 read_lisp_symbol (infile
, buffer
);
1460 fprintf (stderr
, "## unparsable name in fset in %s\n",
1464 read_lisp_symbol (infile
, buffer
);
1465 if (strcmp (buffer
, "quote"))
1467 fprintf (stderr
, "## unparsable name in fset in %s\n",
1471 read_lisp_symbol (infile
, buffer
);
1476 "## unparsable quoted name in fset in %s\n",
1482 if (saved_string
== 0)
1483 if (!search_lisp_doc_at_eol (infile
))
1487 else if (! strcmp (buffer
, "autoload"))
1492 read_lisp_symbol (infile
, buffer
);
1497 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1501 read_lisp_symbol (infile
, buffer
);
1502 if (strcmp (buffer
, "quote"))
1504 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1508 read_lisp_symbol (infile
, buffer
);
1513 "## unparsable quoted name in autoload in %s\n",
1518 skip_white (infile
);
1519 if ((c
= getc (infile
)) != '\"')
1521 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1525 read_c_string_or_comment (infile
, 0, 0, 0);
1527 if (saved_string
== 0)
1528 if (!search_lisp_doc_at_eol (infile
))
1533 else if (! strcmp (buffer
, "if")
1534 || ! strcmp (buffer
, "byte-code"))
1541 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1547 /* At this point, we should either use the previous dynamic doc string in
1548 saved_string or gobble a doc string from the input file.
1549 In the latter case, the opening quote (and leading backslash-newline)
1550 have already been read. */
1552 printf ("\037%c%s\n", type
, buffer
);
1555 fputs (saved_string
, stdout
);
1556 /* Don't use one dynamic doc string twice. */
1557 free (saved_string
);
1561 read_c_string_or_comment (infile
, 1, 0, 0);
1568 /* make-docfile.c ends here */