1 /* Record indices of function doc strings stored in a file.
2 Copyright (C) 1985, 1986, 1993, 1994 Free Software Foundation, Inc.
4 This file is part of GNU Emacs.
6 GNU Emacs is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 1, or (at your option)
11 GNU Emacs is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Emacs; see the file COPYING. If not, write to
18 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. */
23 #include <sys/types.h>
24 #include <sys/file.h> /* Must be after sys/types.h for USG and BSD4_1*/
42 Lisp_Object Vdoc_file_name
;
44 extern Lisp_Object Voverriding_local_map
;
46 /* For VMS versions with limited file name syntax,
47 convert the name to something VMS will allow. */
49 munge_doc_file_name (name
)
54 /* For VMS versions with limited file name syntax,
55 convert the name to something VMS will allow. */
63 #endif /* not VMS4_4 */
65 strcpy (name
, sys_translate_unix (name
));
71 get_doc_string (filepos
)
74 char buf
[512 * 32 + 1];
77 register char *p
, *p1
;
80 extern char *index ();
82 if (!STRINGP (Vdoc_directory
) || !STRINGP (Vdoc_file_name
))
85 minsize
= XSTRING (Vdoc_directory
)->size
;
86 /* sizeof ("../etc/") == 8 */
89 name
= (char *) alloca (minsize
+ XSTRING (Vdoc_file_name
)->size
+ 8);
90 strcpy (name
, XSTRING (Vdoc_directory
)->data
);
91 strcat (name
, XSTRING (Vdoc_file_name
)->data
);
92 munge_doc_file_name (name
);
94 fd
= open (name
, O_RDONLY
, 0);
98 if (!NILP (Vpurify_flag
))
100 /* Preparing to dump; DOC file is probably not installed.
101 So check in ../etc. */
102 strcpy (name
, "../etc/");
103 strcat (name
, XSTRING (Vdoc_file_name
)->data
);
104 munge_doc_file_name (name
);
106 fd
= open (name
, O_RDONLY
, 0);
111 error ("Cannot open doc string file \"%s\"", name
);
114 if (0 > lseek (fd
, filepos
, 0))
117 error ("Position %ld out of range in doc string file \"%s\"",
121 while (p
!= buf
+ sizeof buf
- 1)
123 count
= read (fd
, p
, 512);
127 p1
= index (p
, '\037');
137 return make_string (buf
, p
- buf
);
140 DEFUN ("documentation", Fdocumentation
, Sdocumentation
, 1, 2, 0,
141 "Return the documentation string of FUNCTION.\n\
142 Unless a non-nil second argument is given, the\n\
143 string is passed through `substitute-command-keys'.")
145 Lisp_Object function
, raw
;
149 Lisp_Object tem
, doc
;
151 fun
= Findirect_function (function
);
155 if (XSUBR (fun
)->doc
== 0) return Qnil
;
156 if ((EMACS_INT
) XSUBR (fun
)->doc
>= 0)
157 doc
= build_string (XSUBR (fun
)->doc
);
159 doc
= get_doc_string (- (EMACS_INT
) XSUBR (fun
)->doc
);
161 else if (COMPILEDP (fun
))
163 if (XVECTOR (fun
)->size
<= COMPILED_DOC_STRING
)
165 tem
= XVECTOR (fun
)->contents
[COMPILED_DOC_STRING
];
168 else if (NATNUMP (tem
))
169 doc
= get_doc_string (XFASTINT (tem
));
173 else if (STRINGP (fun
) || VECTORP (fun
))
175 return build_string ("Keyboard macro.");
177 else if (CONSP (fun
))
180 if (!SYMBOLP (funcar
))
181 return Fsignal (Qinvalid_function
, Fcons (fun
, Qnil
));
182 else if (EQ (funcar
, Qkeymap
))
183 return build_string ("Prefix command (definition is a keymap associating keystrokes with\n\
185 else if (EQ (funcar
, Qlambda
)
186 || EQ (funcar
, Qautoload
))
188 tem
= Fcar (Fcdr (Fcdr (fun
)));
191 else if (NATNUMP (tem
))
192 doc
= get_doc_string (XFASTINT (tem
));
196 else if (EQ (funcar
, Qmocklisp
))
198 else if (EQ (funcar
, Qmacro
))
199 return Fdocumentation (Fcdr (fun
), raw
);
206 Fsignal (Qinvalid_function
, Fcons (fun
, Qnil
));
214 doc
= Fsubstitute_command_keys (doc
);
220 DEFUN ("documentation-property", Fdocumentation_property
, Sdocumentation_property
, 2, 3, 0,
221 "Return the documentation string that is SYMBOL's PROP property.\n\
222 This is like `get', but it can refer to strings stored in the\n\
223 `etc/DOC' file; and if the value is a string, it is passed through\n\
224 `substitute-command-keys'. A non-nil third argument avoids this\n\
227 Lisp_Object sym
, prop
, raw
;
229 register Lisp_Object tem
;
231 tem
= Fget (sym
, prop
);
233 tem
= get_doc_string (XINT (tem
) > 0 ? XINT (tem
) : - XINT (tem
));
234 if (NILP (raw
) && STRINGP (tem
))
235 return Fsubstitute_command_keys (tem
);
239 /* Scanning the DOC files and placing docstring offsets into functions. */
242 store_function_docstring (fun
, offset
)
246 fun
= indirect_function (fun
);
248 /* The type determines where the docstring is stored. */
250 /* Lisp_Subrs have a slot for it. */
252 XSUBR (fun
)->doc
= (char *) - offset
;
254 /* If it's a lisp form, stick it in the form. */
255 else if (CONSP (fun
))
259 tem
= XCONS (fun
)->car
;
260 if (EQ (tem
, Qlambda
) || EQ (tem
, Qautoload
))
262 tem
= Fcdr (Fcdr (fun
));
263 if (CONSP (tem
) && INTEGERP (XCONS (tem
)->car
))
264 XSETFASTINT (XCONS (tem
)->car
, offset
);
266 else if (EQ (tem
, Qmacro
))
267 store_function_docstring (XCONS (fun
)->cdr
, offset
);
270 /* Bytecode objects sometimes have slots for it. */
271 else if (COMPILEDP (fun
))
273 /* This bytecode object must have a slot for the
274 docstring, since we've found a docstring for it. */
275 if (XVECTOR (fun
)->size
> COMPILED_DOC_STRING
)
276 XSETFASTINT (XVECTOR (fun
)->contents
[COMPILED_DOC_STRING
], offset
);
281 DEFUN ("Snarf-documentation", Fsnarf_documentation
, Ssnarf_documentation
,
283 "Used during Emacs initialization, before dumping runnable Emacs,\n\
284 to find pointers to doc strings stored in `etc/DOC...' and\n\
285 record them in function definitions.\n\
286 One arg, FILENAME, a string which does not include a directory.\n\
287 The file is found in `../etc' now; found in the `data-directory'\n\
288 when doc strings are referred to later in the dumped Emacs.")
290 Lisp_Object filename
;
296 register char *p
, *end
;
297 Lisp_Object sym
, fun
, tem
;
299 extern char *index ();
302 if (NILP (Vpurify_flag
))
303 error ("Snarf-documentation can only be called in an undumped Emacs");
306 CHECK_STRING (filename
, 0);
309 name
= (char *) alloca (XSTRING (filename
)->size
+ 14);
310 strcpy (name
, "../etc/");
311 #else /* CANNOT_DUMP */
312 CHECK_STRING (Vdoc_directory
, 0);
313 name
= (char *) alloca (XSTRING (filename
)->size
+
314 XSTRING (Vdoc_directory
)->size
+ 1);
315 strcpy (name
, XSTRING (Vdoc_directory
)->data
);
316 #endif /* CANNOT_DUMP */
317 strcat (name
, XSTRING (filename
)->data
); /*** Add this line ***/
320 /* For VMS versions with limited file name syntax,
321 convert the name to something VMS will allow. */
329 #endif /* not VMS4_4 */
331 strcpy (name
, sys_translate_unix (name
));
335 fd
= open (name
, O_RDONLY
, 0);
337 report_file_error ("Opening doc string file",
338 Fcons (build_string (name
), Qnil
));
339 Vdoc_file_name
= filename
;
345 filled
+= read (fd
, &buf
[filled
], sizeof buf
- 1 - filled
);
351 end
= buf
+ (filled
< 512 ? filled
: filled
- 128);
352 while (p
!= end
&& *p
!= '\037') p
++;
353 /* p points to ^_Ffunctionname\n or ^_Vvarname\n. */
356 end
= index (p
, '\n');
357 sym
= oblookup (Vobarray
, p
+ 2, end
- p
- 2);
360 /* Attach a docstring to a variable? */
363 /* Install file-position as variable-documentation property
364 and make it negative for a user-variable
365 (doc starts with a `*'). */
366 Fput (sym
, Qvariable_documentation
,
367 make_number ((pos
+ end
+ 1 - buf
)
368 * (end
[1] == '*' ? -1 : 1)));
371 /* Attach a docstring to a function? */
372 else if (p
[1] == 'F')
373 store_function_docstring (sym
, pos
+ end
+ 1 - buf
);
376 error ("DOC file invalid at position %d", pos
);
381 bcopy (end
, buf
, filled
);
387 DEFUN ("substitute-command-keys", Fsubstitute_command_keys
,
388 Ssubstitute_command_keys
, 1, 1, 0,
389 "Substitute key descriptions for command names in STRING.\n\
390 Return a new string which is STRING with substrings of the form \\=\\[COMMAND]\n\
391 replaced by either: a keystroke sequence that will invoke COMMAND,\n\
392 or \"M-x COMMAND\" if COMMAND is not on any keys.\n\
393 Substrings of the form \\=\\{MAPVAR} are replaced by summaries\n\
394 \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.\n\
395 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR\n\
396 as the keymap for future \\=\\[COMMAND] substrings.\n\
397 \\=\\= quotes the following character and is discarded;\n\
398 thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.")
404 register unsigned char *strp
;
405 register unsigned char *bufp
;
411 unsigned char *start
;
414 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
419 CHECK_STRING (str
, 0);
423 GCPRO4 (str
, tem
, keymap
, name
);
425 /* KEYMAP is either nil (which means search all the active keymaps)
426 or a specified local map (which means search just that and the
427 global map). If non-nil, it might come from Voverriding_local_map,
428 or from a \\<mapname> construct in STR itself.. */
429 keymap
= Voverriding_local_map
;
431 bsize
= XSTRING (str
)->size
;
432 bufp
= buf
= (unsigned char *) xmalloc (bsize
);
434 strp
= (unsigned char *) XSTRING (str
)->data
;
435 while (strp
< (unsigned char *) XSTRING (str
)->data
+ XSTRING (str
)->size
)
437 if (strp
[0] == '\\' && strp
[1] == '=')
439 /* \= quotes the next character;
440 thus, to put in \[ without its special meaning, use \=\[. */
445 else if (strp
[0] == '\\' && strp
[1] == '[')
447 Lisp_Object firstkey
;
450 strp
+= 2; /* skip \[ */
453 while ((strp
- (unsigned char *) XSTRING (str
)->data
454 < XSTRING (str
)->size
)
457 length
= strp
- start
;
460 /* Save STRP in IDX. */
461 idx
= strp
- (unsigned char *) XSTRING (str
)->data
;
462 tem
= Fintern (make_string (start
, length
), Qnil
);
463 tem
= Fwhere_is_internal (tem
, keymap
, Qt
, Qnil
);
465 /* Disregard menu bar bindings; it is positively annoying to
466 mention them when there's no menu bar, and it isn't terribly
467 useful even when there is a menu bar. */
470 firstkey
= Faref (tem
, make_number (0));
471 if (EQ (firstkey
, Qmenu_bar
))
475 if (NILP (tem
)) /* but not on any keys */
477 new = (unsigned char *) xrealloc (buf
, bsize
+= 4);
480 bcopy ("M-x ", bufp
, 4);
485 { /* function is on a key */
486 tem
= Fkey_description (tem
);
490 /* \{foo} is replaced with a summary of the keymap (symbol-value foo).
491 \<foo> just sets the keymap used for \[cmd]. */
492 else if (strp
[0] == '\\' && (strp
[1] == '{' || strp
[1] == '<'))
494 struct buffer
*oldbuf
;
497 strp
+= 2; /* skip \{ or \< */
500 while ((strp
- (unsigned char *) XSTRING (str
)->data
501 < XSTRING (str
)->size
)
502 && *strp
!= '}' && *strp
!= '>')
504 length
= strp
- start
;
505 strp
++; /* skip } or > */
507 /* Save STRP in IDX. */
508 idx
= strp
- (unsigned char *) XSTRING (str
)->data
;
510 /* Get the value of the keymap in TEM, or nil if undefined.
511 Do this while still in the user's current buffer
512 in case it is a local variable. */
513 name
= Fintern (make_string (start
, length
), Qnil
);
514 tem
= Fboundp (name
);
517 tem
= Fsymbol_value (name
);
519 tem
= get_keymap_1 (tem
, 0, 1);
522 /* Now switch to a temp buffer. */
523 oldbuf
= current_buffer
;
524 set_buffer_internal (XBUFFER (Vprin1_to_string_buffer
));
528 name
= Fsymbol_name (name
);
529 insert_string ("\nUses keymap \"");
530 insert_from_string (name
, 0, XSTRING (name
)->size
, 1);
531 insert_string ("\", which is not currently defined.\n");
532 if (start
[-1] == '<') keymap
= Qnil
;
534 else if (start
[-1] == '<')
537 describe_map_tree (tem
, 1, Qnil
, Qnil
, 0, 1);
538 tem
= Fbuffer_string ();
540 set_buffer_internal (oldbuf
);
543 start
= XSTRING (tem
)->data
;
544 length
= XSTRING (tem
)->size
;
546 new = (unsigned char *) xrealloc (buf
, bsize
+= length
);
549 bcopy (start
, bufp
, length
);
551 /* Check STR again in case gc relocated it. */
552 strp
= (unsigned char *) XSTRING (str
)->data
+ idx
;
554 else /* just copy other chars */
558 if (changed
) /* don't bother if nothing substituted */
559 tem
= make_string (buf
, bufp
- buf
);
563 RETURN_UNGCPRO (tem
);
568 DEFVAR_LISP ("internal-doc-file-name", &Vdoc_file_name
,
569 "Name of file containing documentation strings of built-in symbols.");
570 Vdoc_file_name
= Qnil
;
572 defsubr (&Sdocumentation
);
573 defsubr (&Sdocumentation_property
);
574 defsubr (&Ssnarf_documentation
);
575 defsubr (&Ssubstitute_command_keys
);