Mercurial > emacs
changeset 39966:1c2d486200f3
Put doc strings in comments.
| author | Pavel Janík <Pavel@Janik.cz> |
|---|---|
| date | Mon, 15 Oct 2001 15:04:22 +0000 |
| parents | 46d26a4374ca |
| children | db6760d21d23 |
| files | src/editfns.c src/minibuf.c |
| diffstat | 2 files changed, 785 insertions(+), 769 deletions(-) [+] |
line wrap: on
line diff
--- a/src/editfns.c Mon Oct 15 14:55:28 2001 +0000 +++ b/src/editfns.c Mon Oct 15 15:04:22 2001 +0000 @@ -34,6 +34,7 @@ #include <unistd.h> #endif +#define DOC_STRINGS_IN_COMMENTS #include "lisp.h" #include "intervals.h" #include "buffer.h" @@ -164,8 +165,8 @@ } DEFUN ("char-to-string", Fchar_to_string, Schar_to_string, 1, 1, 0, - "Convert arg CHARACTER to a string containing that character.") - (character) + /* Convert arg CHARACTER to a string containing that character. */ + (character)) Lisp_Object character; { int len; @@ -180,9 +181,9 @@ } DEFUN ("string-to-char", Fstring_to_char, Sstring_to_char, 1, 1, 0, - "Convert arg STRING to a character, the first character of that string.\n\ -A multibyte character is handled correctly.") - (string) + /* Convert arg STRING to a character, the first character of that string. +A multibyte character is handled correctly. */ + (string)) register Lisp_Object string; { register Lisp_Object val; @@ -212,9 +213,9 @@ } DEFUN ("point", Fpoint, Spoint, 0, 0, 0, - "Return value of point, as an integer.\n\ -Beginning of buffer is position (point-min)") - () + /* Return value of point, as an integer. +Beginning of buffer is position (point-min). */ + ()) { Lisp_Object temp; XSETFASTINT (temp, PT); @@ -222,8 +223,8 @@ } DEFUN ("point-marker", Fpoint_marker, Spoint_marker, 0, 0, 0, - "Return value of point, as a marker object.") - () + /* Return value of point, as a marker object. */ + ()) { return buildmark (PT, PT_BYTE); } @@ -241,12 +242,12 @@ } DEFUN ("goto-char", Fgoto_char, Sgoto_char, 1, 1, "NGoto char: ", - "Set point to POSITION, a number or marker.\n\ -Beginning of buffer is position (point-min), end is (point-max).\n\ -If the position is in the middle of a multibyte form,\n\ -the actual point is set at the head of the multibyte form\n\ -except in the case that `enable-multibyte-characters' is nil.") - (position) + /* Set point to POSITION, a number or marker. +Beginning of buffer is position (point-min), end is (point-max). +If the position is in the middle of a multibyte form, +the actual point is set at the head of the multibyte form +except in the case that `enable-multibyte-characters' is nil. */ + (position)) register Lisp_Object position; { int pos; @@ -299,24 +300,24 @@ } DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0, - "Return position of beginning of region, as an integer.") - () + /* Return position of beginning of region, as an integer. */ + ()) { return region_limit (1); } DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0, - "Return position of end of region, as an integer.") - () + /* Return position of end of region, as an integer. */ + ()) { return region_limit (0); } DEFUN ("mark-marker", Fmark_marker, Smark_marker, 0, 0, 0, - "Return this buffer's mark, as a marker object.\n\ -Watch out! Moving this marker changes the mark position.\n\ -If you set the marker not to point anywhere, the buffer will have no mark.") - () + /* Return this buffer's mark, as a marker object. +Watch out! Moving this marker changes the mark position. +If you set the marker not to point anywhere, the buffer will have no mark. */ + ()) { return current_buffer->mark; } @@ -556,10 +557,10 @@ DEFUN ("delete-field", Fdelete_field, Sdelete_field, 0, 1, 0, - "Delete the field surrounding POS.\n\ -A field is a region of text with the same `field' property.\n\ -If POS is nil, the value of point is used for POS.") - (pos) + /* Delete the field surrounding POS. +A field is a region of text with the same `field' property. +If POS is nil, the value of point is used for POS. */ + (pos)) Lisp_Object pos; { int beg, end; @@ -570,10 +571,10 @@ } DEFUN ("field-string", Ffield_string, Sfield_string, 0, 1, 0, - "Return the contents of the field surrounding POS as a string.\n\ -A field is a region of text with the same `field' property.\n\ -If POS is nil, the value of point is used for POS.") - (pos) + /* Return the contents of the field surrounding POS as a string. +A field is a region of text with the same `field' property. +If POS is nil, the value of point is used for POS. */ + (pos)) Lisp_Object pos; { int beg, end; @@ -582,10 +583,10 @@ } DEFUN ("field-string-no-properties", Ffield_string_no_properties, Sfield_string_no_properties, 0, 1, 0, - "Return the contents of the field around POS, without text-properties.\n\ -A field is a region of text with the same `field' property.\n\ -If POS is nil, the value of point is used for POS.") - (pos) + /* Return the contents of the field around POS, without text-properties. +A field is a region of text with the same `field' property. +If POS is nil, the value of point is used for POS. */ + (pos)) Lisp_Object pos; { int beg, end; @@ -594,12 +595,12 @@ } DEFUN ("field-beginning", Ffield_beginning, Sfield_beginning, 0, 2, 0, - "Return the beginning of the field surrounding POS.\n\ -A field is a region of text with the same `field' property.\n\ -If POS is nil, the value of point is used for POS.\n\ -If ESCAPE-FROM-EDGE is non-nil and POS is at the beginning of its\n\ -field, then the beginning of the *previous* field is returned.") - (pos, escape_from_edge) + /* Return the beginning of the field surrounding POS. +A field is a region of text with the same `field' property. +If POS is nil, the value of point is used for POS. +If ESCAPE-FROM-EDGE is non-nil and POS is at the beginning of its +field, then the beginning of the *previous* field is returned. */ + (pos, escape_from_edge)) Lisp_Object pos, escape_from_edge; { int beg; @@ -608,12 +609,12 @@ } DEFUN ("field-end", Ffield_end, Sfield_end, 0, 2, 0, - "Return the end of the field surrounding POS.\n\ -A field is a region of text with the same `field' property.\n\ -If POS is nil, the value of point is used for POS.\n\ -If ESCAPE-FROM-EDGE is non-nil and POS is at the end of its field,\n\ -then the end of the *following* field is returned.") - (pos, escape_from_edge) + /* Return the end of the field surrounding POS. +A field is a region of text with the same `field' property. +If POS is nil, the value of point is used for POS. +If ESCAPE-FROM-EDGE is non-nil and POS is at the end of its field, +then the end of the *following* field is returned. */ + (pos, escape_from_edge)) Lisp_Object pos, escape_from_edge; { int end; @@ -622,33 +623,33 @@ } DEFUN ("constrain-to-field", Fconstrain_to_field, Sconstrain_to_field, 2, 5, 0, - "Return the position closest to NEW-POS that is in the same field as OLD-POS.\n\ -\n\ -A field is a region of text with the same `field' property.\n\ -If NEW-POS is nil, then the current point is used instead, and set to the\n\ -constrained position if that is different.\n\ -\n\ -If OLD-POS is at the boundary of two fields, then the allowable\n\ -positions for NEW-POS depends on the value of the optional argument\n\ -ESCAPE-FROM-EDGE: If ESCAPE-FROM-EDGE is nil, then NEW-POS is\n\ -constrained to the field that has the same `field' char-property\n\ -as any new characters inserted at OLD-POS, whereas if ESCAPE-FROM-EDGE\n\ -is non-nil, NEW-POS is constrained to the union of the two adjacent\n\ -fields. Additionally, if two fields are separated by another field with\n\ -the special value `boundary', then any point within this special field is\n\ -also considered to be `on the boundary'.\n\ -\n\ -If the optional argument ONLY-IN-LINE is non-nil and constraining\n\ -NEW-POS would move it to a different line, NEW-POS is returned\n\ -unconstrained. This useful for commands that move by line, like\n\ -\\[next-line] or \\[beginning-of-line], which should generally respect field boundaries\n\ -only in the case where they can still move to the right line.\n\ -\n\ -If the optional argument INHIBIT-CAPTURE-PROPERTY is non-nil, and OLD-POS has\n\ -a non-nil property of that name, then any field boundaries are ignored.\n\ -\n\ -Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil.") - (new_pos, old_pos, escape_from_edge, only_in_line, inhibit_capture_property) + /* Return the position closest to NEW-POS that is in the same field as OLD-POS. + +A field is a region of text with the same `field' property. +If NEW-POS is nil, then the current point is used instead, and set to the +constrained position if that is different. + +If OLD-POS is at the boundary of two fields, then the allowable +positions for NEW-POS depends on the value of the optional argument +ESCAPE-FROM-EDGE: If ESCAPE-FROM-EDGE is nil, then NEW-POS is +constrained to the field that has the same `field' char-property +as any new characters inserted at OLD-POS, whereas if ESCAPE-FROM-EDGE +is non-nil, NEW-POS is constrained to the union of the two adjacent +fields. Additionally, if two fields are separated by another field with +the special value `boundary', then any point within this special field is +also considered to be `on the boundary'. + +If the optional argument ONLY-IN-LINE is non-nil and constraining +NEW-POS would move it to a different line, NEW-POS is returned +unconstrained. This useful for commands that move by line, like +\\[next-line] or \\[beginning-of-line], which should generally respect field boundaries +only in the case where they can still move to the right line. + +If the optional argument INHIBIT-CAPTURE-PROPERTY is non-nil, and OLD-POS has +a non-nil property of that name, then any field boundaries are ignored. + +Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil. */ + (new_pos, old_pos, escape_from_edge, only_in_line, inhibit_capture_property)) Lisp_Object new_pos, old_pos; Lisp_Object escape_from_edge, only_in_line, inhibit_capture_property; { @@ -715,16 +716,16 @@ DEFUN ("line-beginning-position", Fline_beginning_position, Sline_beginning_position, 0, 1, 0, - "Return the character position of the first character on the current line.\n\ -With argument N not nil or 1, move forward N - 1 lines first.\n\ -If scan reaches end of buffer, return that position.\n\ -The scan does not cross a field boundary unless it would move\n\ -beyond there to a different line. Field boundaries are not noticed if\n\ -`inhibit-field-text-motion' is non-nil. .And if N is nil or 1,\n\ -and scan starts at a field boundary, the scan stops as soon as it starts.\n\ -\n\ -This function does not move point.") - (n) + /* Return the character position of the first character on the current line. +With argument N not nil or 1, move forward N - 1 lines first. +If scan reaches end of buffer, return that position. +The scan does not cross a field boundary unless it would move +beyond there to a different line. Field boundaries are not noticed if +`inhibit-field-text-motion' is non-nil. And if N is nil or 1, +and scan starts at a field boundary, the scan stops as soon as it starts. + +This function does not move point. */ + (n)) Lisp_Object n; { int orig, orig_byte, end; @@ -749,11 +750,11 @@ DEFUN ("line-end-position", Fline_end_position, Sline_end_position, 0, 1, 0, - "Return the character position of the last character on the current line.\n\ -With argument N not nil or 1, move forward N - 1 lines first.\n\ -If scan reaches end of buffer, return that position.\n\ -This function does not move point.") - (n) + /* Return the character position of the last character on the current line. +With argument N not nil or 1, move forward N - 1 lines first. +If scan reaches end of buffer, return that position. +This function does not move point. */ + (n)) Lisp_Object n; { int end_pos; @@ -870,17 +871,17 @@ } DEFUN ("save-excursion", Fsave_excursion, Ssave_excursion, 0, UNEVALLED, 0, - "Save point, mark, and current buffer; execute BODY; restore those things.\n\ -Executes BODY just like `progn'.\n\ -The values of point, mark and the current buffer are restored\n\ -even in case of abnormal exit (throw or error).\n\ -The state of activation of the mark is also restored.\n\ -\n\ -This construct does not save `deactivate-mark', and therefore\n\ -functions that change the buffer will still cause deactivation\n\ -of the mark at the end of the command. To prevent that, bind\n\ -`deactivate-mark' with `let'.") - (args) + /* Save point, mark, and current buffer; execute BODY; restore those things. +Executes BODY just like `progn'. +The values of point, mark and the current buffer are restored +even in case of abnormal exit (throw or error). +The state of activation of the mark is also restored. + +This construct does not save `deactivate-mark', and therefore +functions that change the buffer will still cause deactivation +of the mark at the end of the command. To prevent that, bind +`deactivate-mark' with `let'. */ + (args)) Lisp_Object args; { register Lisp_Object val; @@ -893,9 +894,9 @@ } DEFUN ("save-current-buffer", Fsave_current_buffer, Ssave_current_buffer, 0, UNEVALLED, 0, - "Save the current buffer; execute BODY; restore the current buffer.\n\ -Executes BODY just like `progn'.") - (args) + /* Save the current buffer; execute BODY; restore the current buffer. +Executes BODY just like `progn'. */ + (args)) Lisp_Object args; { Lisp_Object val; @@ -908,9 +909,9 @@ } DEFUN ("buffer-size", Fbufsize, Sbufsize, 0, 1, 0, - "Return the number of characters in the current buffer.\n\ -If BUFFER, return the number of characters in that buffer instead.") - (buffer) + /* Return the number of characters in the current buffer. +If BUFFER, return the number of characters in that buffer instead. */ + (buffer)) Lisp_Object buffer; { if (NILP (buffer)) @@ -924,9 +925,9 @@ } DEFUN ("point-min", Fpoint_min, Spoint_min, 0, 0, 0, - "Return the minimum permissible value of point in the current buffer.\n\ -This is 1, unless narrowing (a buffer restriction) is in effect.") - () + /* Return the minimum permissible value of point in the current buffer. +This is 1, unless narrowing (a buffer restriction) is in effect. */ + ()) { Lisp_Object temp; XSETFASTINT (temp, BEGV); @@ -934,18 +935,18 @@ } DEFUN ("point-min-marker", Fpoint_min_marker, Spoint_min_marker, 0, 0, 0, - "Return a marker to the minimum permissible value of point in this buffer.\n\ -This is the beginning, unless narrowing (a buffer restriction) is in effect.") - () + /* Return a marker to the minimum permissible value of point in this buffer. +This is the beginning, unless narrowing (a buffer restriction) is in effect. */ + ()) { return buildmark (BEGV, BEGV_BYTE); } DEFUN ("point-max", Fpoint_max, Spoint_max, 0, 0, 0, - "Return the maximum permissible value of point in the current buffer.\n\ -This is (1+ (buffer-size)), unless narrowing (a buffer restriction)\n\ -is in effect, in which case it is less.") - () + /* Return the maximum permissible value of point in the current buffer. +This is (1+ (buffer-size)), unless narrowing (a buffer restriction) +is in effect, in which case it is less. */ + ()) { Lisp_Object temp; XSETFASTINT (temp, ZV); @@ -953,18 +954,18 @@ } DEFUN ("point-max-marker", Fpoint_max_marker, Spoint_max_marker, 0, 0, 0, - "Return a marker to the maximum permissible value of point in this buffer.\n\ -This is (1+ (buffer-size)), unless narrowing (a buffer restriction)\n\ -is in effect, in which case it is less.") - () + /* Return a marker to the maximum permissible value of point in this buffer. +This is (1+ (buffer-size)), unless narrowing (a buffer restriction) +is in effect, in which case it is less. */ + ()) { return buildmark (ZV, ZV_BYTE); } DEFUN ("gap-position", Fgap_position, Sgap_position, 0, 0, 0, - "Return the position of the gap, in the current buffer.\n\ -See also `gap-size'.") - () + /* Return the position of the gap, in the current buffer. +See also `gap-size'. */ + ()) { Lisp_Object temp; XSETFASTINT (temp, GPT); @@ -972,9 +973,9 @@ } DEFUN ("gap-size", Fgap_size, Sgap_size, 0, 0, 0, - "Return the size of the current buffer's gap.\n\ -See also `gap-position'.") - () + /* Return the size of the current buffer's gap. +See also `gap-position'. */ + ()) { Lisp_Object temp; XSETFASTINT (temp, GAP_SIZE); @@ -982,9 +983,9 @@ } DEFUN ("position-bytes", Fposition_bytes, Sposition_bytes, 1, 1, 0, - "Return the byte position for character position POSITION.\n\ -If POSITION is out of range, the value is nil.") - (position) + /* Return the byte position for character position POSITION. +If POSITION is out of range, the value is nil. */ + (position)) Lisp_Object position; { CHECK_NUMBER_COERCE_MARKER (position, 1); @@ -994,9 +995,9 @@ } DEFUN ("byte-to-position", Fbyte_to_position, Sbyte_to_position, 1, 1, 0, - "Return the character position for byte position BYTEPOS.\n\ -If BYTEPOS is out of range, the value is nil.") - (bytepos) + /* Return the character position for byte position BYTEPOS. +If BYTEPOS is out of range, the value is nil. */ + (bytepos)) Lisp_Object bytepos; { CHECK_NUMBER (bytepos, 1); @@ -1006,9 +1007,9 @@ } DEFUN ("following-char", Ffollowing_char, Sfollowing_char, 0, 0, 0, - "Return the character following point, as a number.\n\ -At the end of the buffer or accessible region, return 0.") - () + /* Return the character following point, as a number. +At the end of the buffer or accessible region, return 0. */ + ()) { Lisp_Object temp; if (PT >= ZV) @@ -1019,9 +1020,9 @@ } DEFUN ("preceding-char", Fprevious_char, Sprevious_char, 0, 0, 0, - "Return the character preceding point, as a number.\n\ -At the beginning of the buffer or accessible region, return 0.") - () + /* Return the character preceding point, as a number. +At the beginning of the buffer or accessible region, return 0. */ + ()) { Lisp_Object temp; if (PT <= BEGV) @@ -1038,9 +1039,9 @@ } DEFUN ("bobp", Fbobp, Sbobp, 0, 0, 0, - "Return t if point is at the beginning of the buffer.\n\ -If the buffer is narrowed, this means the beginning of the narrowed part.") - () + /* Return t if point is at the beginning of the buffer. +If the buffer is narrowed, this means the beginning of the narrowed part. */ + ()) { if (PT == BEGV) return Qt; @@ -1048,9 +1049,9 @@ } DEFUN ("eobp", Feobp, Seobp, 0, 0, 0, - "Return t if point is at the end of the buffer.\n\ -If the buffer is narrowed, this means the end of the narrowed part.") - () + /* Return t if point is at the end of the buffer. +If the buffer is narrowed, this means the end of the narrowed part. */ + ()) { if (PT == ZV) return Qt; @@ -1058,8 +1059,8 @@ } DEFUN ("bolp", Fbolp, Sbolp, 0, 0, 0, - "Return t if point is at the beginning of a line.") - () + /* Return t if point is at the beginning of a line. */ + ()) { if (PT == BEGV || FETCH_BYTE (PT_BYTE - 1) == '\n') return Qt; @@ -1067,9 +1068,9 @@ } DEFUN ("eolp", Feolp, Seolp, 0, 0, 0, - "Return t if point is at the end of a line.\n\ -`End of a line' includes point being at the end of the buffer.") - () + /* Return t if point is at the end of a line. +`End of a line' includes point being at the end of the buffer. */ + ()) { if (PT == ZV || FETCH_BYTE (PT_BYTE) == '\n') return Qt; @@ -1077,10 +1078,10 @@ } DEFUN ("char-after", Fchar_after, Schar_after, 0, 1, 0, - "Return character in current buffer at position POS.\n\ -POS is an integer or a marker.\n\ -If POS is out of range, the value is nil.") - (pos) + /* Return character in current buffer at position POS. +POS is an integer or a marker. +If POS is out of range, the value is nil. */ + (pos)) Lisp_Object pos; { register int pos_byte; @@ -1110,10 +1111,10 @@ } DEFUN ("char-before", Fchar_before, Schar_before, 0, 1, 0, - "Return character in current buffer preceding position POS.\n\ -POS is an integer or a marker.\n\ -If POS is out of range, the value is nil.") - (pos) + /* Return character in current buffer preceding position POS. +POS is an integer or a marker. +If POS is out of range, the value is nil. */ + (pos)) Lisp_Object pos; { register Lisp_Object val; @@ -1156,13 +1157,14 @@ } DEFUN ("user-login-name", Fuser_login_name, Suser_login_name, 0, 1, 0, - "Return the name under which the user logged in, as a string.\n\ -This is based on the effective uid, not the real uid.\n\ -Also, if the environment variable LOGNAME or USER is set,\n\ -that determines the value of this function.\n\n\ -If optional argument UID is an integer, return the login name of the user\n\ -with that uid, or nil if there is no such user.") - (uid) + /* Return the name under which the user logged in, as a string. +This is based on the effective uid, not the real uid. +Also, if the environment variable LOGNAME or USER is set, +that determines the value of this function. + +If optional argument UID is an integer, return the login name of the user +with that uid, or nil if there is no such user. */ + (uid)) Lisp_Object uid; { struct passwd *pw; @@ -1183,10 +1185,10 @@ DEFUN ("user-real-login-name", Fuser_real_login_name, Suser_real_login_name, 0, 0, 0, - "Return the name of the user's real uid, as a string.\n\ -This ignores the environment variables LOGNAME and USER, so it differs from\n\ -`user-login-name' when running under `su'.") - () + /* Return the name of the user's real uid, as a string. +This ignores the environment variables LOGNAME and USER, so it differs from +`user-login-name' when running under `su'. */ + ()) { /* Set up the user name info if we didn't do it before. (That can happen if Emacs is dumpable @@ -1197,31 +1199,31 @@ } DEFUN ("user-uid", Fuser_uid, Suser_uid, 0, 0, 0, - "Return the effective uid of Emacs.\n\ -Value is an integer or float, depending on the value.") - () + /* Return the effective uid of Emacs. +Value is an integer or float, depending on the value. */ + ()) { return make_fixnum_or_float (geteuid ()); } DEFUN ("user-real-uid", Fuser_real_uid, Suser_real_uid, 0, 0, 0, - "Return the real uid of Emacs.\n\ -Value is an integer or float, depending on the value.") - () + /* Return the real uid of Emacs. +Value is an integer or float, depending on the value. */ + ()) { return make_fixnum_or_float (getuid ()); } DEFUN ("user-full-name", Fuser_full_name, Suser_full_name, 0, 1, 0, - "Return the full name of the user logged in, as a string.\n\ -If the full name corresponding to Emacs's userid is not known,\n\ -return \"unknown\".\n\ -\n\ -If optional argument UID is an integer or float, return the full name\n\ -of the user with that uid, or nil if there is no such user.\n\ -If UID is a string, return the full name of the user with that login\n\ -name, or nil if there is no such user.") - (uid) + /* Return the full name of the user logged in, as a string. +If the full name corresponding to Emacs's userid is not known, +return "unknown". + +If optional argument UID is an integer or float, return the full name +of the user with that uid, or nil if there is no such user. +If UID is a string, return the full name of the user with that login +name, or nil if there is no such user. */ + (uid)) Lisp_Object uid; { struct passwd *pw; @@ -1269,8 +1271,8 @@ } DEFUN ("system-name", Fsystem_name, Ssystem_name, 0, 0, 0, - "Return the name of the machine you are running on, as a string.") - () + /* Return the name of the machine you are running on, as a string. */ + ()) { return Vsystem_name; } @@ -1287,22 +1289,22 @@ } DEFUN ("emacs-pid", Femacs_pid, Semacs_pid, 0, 0, 0, - "Return the process ID of Emacs, as an integer.") - () + /* Return the process ID of Emacs, as an integer. */ + ()) { return make_number (getpid ()); } DEFUN ("current-time", Fcurrent_time, Scurrent_time, 0, 0, 0, - "Return the current time, as the number of seconds since 1970-01-01 00:00:00.\n\ -The time is returned as a list of three integers. The first has the\n\ -most significant 16 bits of the seconds, while the second has the\n\ -least significant 16 bits. The third integer gives the microsecond\n\ -count.\n\ -\n\ -The microsecond count is zero on systems that do not provide\n\ -resolution finer than a second.") - () + /* Return the current time, as the number of seconds since 1970-01-01 00:00:00. +The time is returned as a list of three integers. The first has the +most significant 16 bits of the seconds, while the second has the +least significant 16 bits. The third integer gives the microsecond +count. + +The microsecond count is zero on systems that do not provide +resolution finer than a second. */ + ()) { EMACS_TIME t; Lisp_Object result[3]; @@ -1368,16 +1370,16 @@ } DEFUN ("float-time", Ffloat_time, Sfloat_time, 0, 1, 0, - "Return the current time, as a float number of seconds since the epoch.\n\ -If an argument is given, it specifies a time to convert to float\n\ -instead of the current time. The argument should have the forms:\n\ - (HIGH . LOW) or (HIGH LOW USEC) or (HIGH LOW . USEC).\n\ -Thus, you can use times obtained from `current-time'\n\ -and from `file-attributes'.\n\ -\n\ -WARNING: Since the result is floating point, it may not be exact.\n\ -Do not use this function if precise time stamps are required.") - (specified_time) + /* Return the current time, as a float number of seconds since the epoch. +If an argument is given, it specifies a time to convert to float +instead of the current time. The argument should have the forms: + (HIGH . LOW) or (HIGH LOW USEC) or (HIGH LOW . USEC). +Thus, you can use times obtained from `current-time' +and from `file-attributes'. + +WARNING: Since the result is floating point, it may not be exact. +Do not use this function if precise time stamps are required. */ + (specified_time)) Lisp_Object specified_time; { time_t sec; @@ -1443,63 +1445,57 @@ } } -/* DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0, - "Use FORMAT-STRING to format the time TIME, or now if omitted.\n\ -TIME is specified as (HIGH LOW . IGNORED) or (HIGH . LOW), as returned by\n\ -`current-time' or `file-attributes'.\n\ -The third, optional, argument UNIVERSAL, if non-nil, means describe TIME\n\ -as Universal Time; nil means describe TIME in the local time zone.\n\ -The value is a copy of FORMAT-STRING, but with certain constructs replaced\n\ -by text that describes the specified date and time in TIME:\n\ -\n\ -%Y is the year, %y within the century, %C the century.\n\ -%G is the year corresponding to the ISO week, %g within the century.\n\ -%m is the numeric month.\n\ -%b and %h are the locale's abbreviated month name, %B the full name.\n\ -%d is the day of the month, zero-padded, %e is blank-padded.\n\ -%u is the numeric day of week from 1 (Monday) to 7, %w from 0 (Sunday) to 6.\n\ -%a is the locale's abbreviated name of the day of week, %A the full name.\n\ -%U is the week number starting on Sunday, %W starting on Monday,\n\ - %V according to ISO 8601.\n\ -%j is the day of the year.\n\ -\n\ -%H is the hour on a 24-hour clock, %I is on a 12-hour clock, %k is like %H\n\ - only blank-padded, %l is like %I blank-padded.\n\ -%p is the locale's equivalent of either AM or PM.\n\ -%M is the minute.\n\ -%S is the second.\n\ -%Z is the time zone name, %z is the numeric form.\n\ -%s is the number of seconds since 1970-01-01 00:00:00 +0000.\n\ -\n\ -%c is the locale's date and time format.\n\ -%x is the locale's \"preferred\" date format.\n\ -%D is like \"%m/%d/%y\".\n\ -\n\ -%R is like \"%H:%M\", %T is like \"%H:%M:%S\", %r is like \"%I:%M:%S %p\".\n\ -%X is the locale's \"preferred\" time format.\n\ -\n\ -Finally, %n is a newline, %t is a tab, %% is a literal %.\n\ -\n\ -Certain flags and modifiers are available with some format controls.\n\ -The flags are `_', `-', `^' and `#'. For certain characters X,\n\ -%_X is like %X, but padded with blanks; %-X is like %X,\n\ -ut without padding. %^X is like %X but with all textual\n\ -characters up-cased; %#X is like %X but with letter-case of\n\ -all textual characters reversed.\n\ -%NX (where N stands for an integer) is like %X,\n\ -but takes up at least N (a number) positions.\n\ -The modifiers are `E' and `O'. For certain characters X,\n\ -%EX is a locale's alternative version of %X;\n\ -%OX is like %X, but uses the locale's number symbols.\n\ -\n\ -For example, to produce full ISO 8601 format, use \"%Y-%m-%dT%T%z\".") - (format_string, time, universal) -*/ - -DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0, - 0 /* See immediately above */) - (format_string, time, universal) + /* Use FORMAT-STRING to format the time TIME, or now if omitted. +TIME is specified as (HIGH LOW . IGNORED) or (HIGH . LOW), as returned by +`current-time' or `file-attributes'. +The third, optional, argument UNIVERSAL, if non-nil, means describe TIME +as Universal Time; nil means describe TIME in the local time zone. +The value is a copy of FORMAT-STRING, but with certain constructs replaced +by text that describes the specified date and time in TIME: + +%Y is the year, %y within the century, %C the century. +%G is the year corresponding to the ISO week, %g within the century. +%m is the numeric month. +%b and %h are the locale's abbreviated month name, %B the full name. +%d is the day of the month, zero-padded, %e is blank-padded. +%u is the numeric day of week from 1 (Monday) to 7, %w from 0 (Sunday) to 6. +%a is the locale's abbreviated name of the day of week, %A the full name. +%U is the week number starting on Sunday, %W starting on Monday, + %V according to ISO 8601. +%j is the day of the year. + +%H is the hour on a 24-hour clock, %I is on a 12-hour clock, %k is like %H + only blank-padded, %l is like %I blank-padded. +%p is the locale's equivalent of either AM or PM. +%M is the minute. +%S is the second. +%Z is the time zone name, %z is the numeric form. +%s is the number of seconds since 1970-01-01 00:00:00 +0000. + +%c is the locale's date and time format. +%x is the locale's "preferred" date format. +%D is like "%m/%d/%y". + +%R is like "%H:%M", %T is like "%H:%M:%S", %r is like "%I:%M:%S %p". +%X is the locale's "preferred" time format. + +Finally, %n is a newline, %t is a tab, %% is a literal %. + +Certain flags and modifiers are available with some format controls. +The flags are `_', `-', `^' and `#'. For certain characters X, +%_X is like %X, but padded with blanks; %-X is like %X, +ut without padding. %^X is like %X but with all textual +characters up-cased; %#X is like %X but with letter-case of +all textual characters reversed. +%NX (where N stands for an integer) is like %X, +but takes up at least N (a number) positions. +The modifiers are `E' and `O'. For certain characters X, +%EX is a locale's alternative version of %X; +%OX is like %X, but uses the locale's number symbols. + +For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z". */ + (format_string, time, universal)) Lisp_Object format_string, time, universal; { time_t value; @@ -1547,19 +1543,19 @@ } DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 1, 0, - "Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE).\n\ -The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED)\n\ -or (HIGH . LOW), as from `current-time' and `file-attributes', or `nil'\n\ -to use the current time. The list has the following nine members:\n\ -SEC is an integer between 0 and 60; SEC is 60 for a leap second, which\n\ -only some operating systems support. MINUTE is an integer between 0 and 59.\n\ -HOUR is an integer between 0 and 23. DAY is an integer between 1 and 31.\n\ -MONTH is an integer between 1 and 12. YEAR is an integer indicating the\n\ -four-digit year. DOW is the day of week, an integer between 0 and 6, where\n\ -0 is Sunday. DST is t if daylight savings time is effect, otherwise nil.\n\ -ZONE is an integer indicating the number of seconds east of Greenwich.\n\ -\(Note that Common Lisp has different meanings for DOW and ZONE.)") - (specified_time) + /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE). +The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED) +or (HIGH . LOW), as from `current-time' and `file-attributes', or `nil' +to use the current time. The list has the following nine members: +SEC is an integer between 0 and 60; SEC is 60 for a leap second, which +only some operating systems support. MINUTE is an integer between 0 and 59. +HOUR is an integer between 0 and 23. DAY is an integer between 1 and 31. +MONTH is an integer between 1 and 12. YEAR is an integer indicating the +four-digit year. DOW is the day of week, an integer between 0 and 6, where +0 is Sunday. DST is t if daylight savings time is effect, otherwise nil. +ZONE is an integer indicating the number of seconds east of Greenwich. +(Note that Common Lisp has different meanings for DOW and ZONE.) */ + (specified_time)) Lisp_Object specified_time; { time_t time_spec; @@ -1593,23 +1589,23 @@ } DEFUN ("encode-time", Fencode_time, Sencode_time, 6, MANY, 0, - "Convert SECOND, MINUTE, HOUR, DAY, MONTH, YEAR and ZONE to internal time.\n\ -This is the reverse operation of `decode-time', which see.\n\ -ZONE defaults to the current time zone rule. This can\n\ -be a string or t (as from `set-time-zone-rule'), or it can be a list\n\ -\(as from `current-time-zone') or an integer (as from `decode-time')\n\ -applied without consideration for daylight savings time.\n\ -\n\ -You can pass more than 7 arguments; then the first six arguments\n\ -are used as SECOND through YEAR, and the *last* argument is used as ZONE.\n\ -The intervening arguments are ignored.\n\ -This feature lets (apply 'encode-time (decode-time ...)) work.\n\ -\n\ -Out-of-range values for SEC, MINUTE, HOUR, DAY, or MONTH are allowed;\n\ -for example, a DAY of 0 means the day preceding the given month.\n\ -Year numbers less than 100 are treated just like other year numbers.\n\ -If you want them to stand for years in this century, you must do that yourself.") - (nargs, args) + /* Convert SECOND, MINUTE, HOUR, DAY, MONTH, YEAR and ZONE to internal time. +This is the reverse operation of `decode-time', which see. +ZONE defaults to the current time zone rule. This can +be a string or t (as from `set-time-zone-rule'), or it can be a list +(as from `current-time-zone') or an integer (as from `decode-time') +applied without consideration for daylight savings time. + +You can pass more than 7 arguments; then the first six arguments +are used as SECOND through YEAR, and the *last* argument is used as ZONE. +The intervening arguments are ignored. +This feature lets (apply 'encode-time (decode-time ...)) work. + +Out-of-range values for SEC, MINUTE, HOUR, DAY, or MONTH are allowed; +for example, a DAY of 0 means the day preceding the given month. +Year numbers less than 100 are treated just like other year numbers. +If you want them to stand for years in this century, you must do that yourself. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -1678,21 +1674,21 @@ } DEFUN ("current-time-string", Fcurrent_time_string, Scurrent_time_string, 0, 1, 0, - "Return the current time, as a human-readable string.\n\ -Programs can use this function to decode a time,\n\ -since the number of columns in each field is fixed.\n\ -The format is `Sun Sep 16 01:03:52 1973'.\n\ -However, see also the functions `decode-time' and `format-time-string'\n\ -which provide a much more powerful and general facility.\n\ -\n\ -If an argument is given, it specifies a time to format\n\ -instead of the current time. The argument should have the form:\n\ - (HIGH . LOW)\n\ -or the form:\n\ - (HIGH LOW . IGNORED).\n\ -Thus, you can use times obtained from `current-time'\n\ -and from `file-attributes'.") - (specified_time) + /* Return the current time, as a human-readable string. +Programs can use this function to decode a time, +since the number of columns in each field is fixed. +The format is `Sun Sep 16 01:03:52 1973'. +However, see also the functions `decode-time' and `format-time-string' +which provide a much more powerful and general facility. + +If an argument is given, it specifies a time to format +instead of the current time. The argument should have the form: + (HIGH . LOW) +or the form: + (HIGH LOW . IGNORED). +Thus, you can use times obtained from `current-time' +and from `file-attributes'. */ + (specified_time)) Lisp_Object specified_time; { time_t value; @@ -1736,23 +1732,23 @@ } DEFUN ("current-time-zone", Fcurrent_time_zone, Scurrent_time_zone, 0, 1, 0, - "Return the offset and name for the local time zone.\n\ -This returns a list of the form (OFFSET NAME).\n\ -OFFSET is an integer number of seconds ahead of UTC (east of Greenwich).\n\ - A negative value means west of Greenwich.\n\ -NAME is a string giving the name of the time zone.\n\ -If an argument is given, it specifies when the time zone offset is determined\n\ -instead of using the current time. The argument should have the form:\n\ - (HIGH . LOW)\n\ -or the form:\n\ - (HIGH LOW . IGNORED).\n\ -Thus, you can use times obtained from `current-time'\n\ -and from `file-attributes'.\n\ -\n\ -Some operating systems cannot provide all this information to Emacs;\n\ -in this case, `current-time-zone' returns a list containing nil for\n\ -the data it can't find.") - (specified_time) + /* Return the offset and name for the local time zone. +This returns a list of the form (OFFSET NAME). +OFFSET is an integer number of seconds ahead of UTC (east of Greenwich). + A negative value means west of Greenwich. +NAME is a string giving the name of the time zone. +If an argument is given, it specifies when the time zone offset is determined +instead of using the current time. The argument should have the form: + (HIGH . LOW) +or the form: + (HIGH LOW . IGNORED). +Thus, you can use times obtained from `current-time' +and from `file-attributes'. + +Some operating systems cannot provide all this information to Emacs; +in this case, `current-time-zone' returns a list containing nil for +the data it can't find. */ + (specified_time)) Lisp_Object specified_time; { time_t value; @@ -1808,10 +1804,10 @@ static char **environbuf; DEFUN ("set-time-zone-rule", Fset_time_zone_rule, Sset_time_zone_rule, 1, 1, 0, - "Set the local time zone using TZ, a string specifying a time zone rule.\n\ -If TZ is nil, use implementation-defined default time zone information.\n\ -If TZ is t, use Universal Time.") - (tz) + /* Set the local time zone using TZ, a string specifying a time zone rule. +If TZ is nil, use implementation-defined default time zone information. +If TZ is t, use Universal Time. */ + (tz)) Lisp_Object tz; { char *tzstring; @@ -1995,16 +1991,16 @@ we don't care if it gets trashed. */ DEFUN ("insert", Finsert, Sinsert, 0, MANY, 0, - "Insert the arguments, either strings or characters, at point.\n\ -Point and before-insertion markers move forward to end up\n\ - after the inserted text.\n\ -Any other markers at the point of insertion remain before the text.\n\ -\n\ -If the current buffer is multibyte, unibyte strings are converted\n\ -to multibyte for insertion (see `unibyte-char-to-multibyte').\n\ -If the current buffer is unibyte, multibyte strings are converted\n\ -to unibyte for insertion.") - (nargs, args) + /* Insert the arguments, either strings or characters, at point. +Point and before-insertion markers move forward to end up + after the inserted text. +Any other markers at the point of insertion remain before the text. + +If the current buffer is multibyte, unibyte strings are converted +to multibyte for insertion (see `unibyte-char-to-multibyte'). +If the current buffer is unibyte, multibyte strings are converted +to unibyte for insertion. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -2014,16 +2010,16 @@ DEFUN ("insert-and-inherit", Finsert_and_inherit, Sinsert_and_inherit, 0, MANY, 0, - "Insert the arguments at point, inheriting properties from adjoining text.\n\ -Point and before-insertion markers move forward to end up\n\ - after the inserted text.\n\ -Any other markers at the point of insertion remain before the text.\n\ -\n\ -If the current buffer is multibyte, unibyte strings are converted\n\ -to multibyte for insertion (see `unibyte-char-to-multibyte').\n\ -If the current buffer is unibyte, multibyte strings are converted\n\ -to unibyte for insertion.") - (nargs, args) + /* Insert the arguments at point, inheriting properties from adjoining text. +Point and before-insertion markers move forward to end up + after the inserted text. +Any other markers at the point of insertion remain before the text. + +If the current buffer is multibyte, unibyte strings are converted +to multibyte for insertion (see `unibyte-char-to-multibyte'). +If the current buffer is unibyte, multibyte strings are converted +to unibyte for insertion. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -2033,14 +2029,14 @@ } DEFUN ("insert-before-markers", Finsert_before_markers, Sinsert_before_markers, 0, MANY, 0, - "Insert strings or characters at point, relocating markers after the text.\n\ -Point and markers move forward to end up after the inserted text.\n\ -\n\ -If the current buffer is multibyte, unibyte strings are converted\n\ -to multibyte for insertion (see `unibyte-char-to-multibyte').\n\ -If the current buffer is unibyte, multibyte strings are converted\n\ -to unibyte for insertion.") - (nargs, args) + /* Insert strings or characters at point, relocating markers after the text. +Point and markers move forward to end up after the inserted text. + +If the current buffer is multibyte, unibyte strings are converted +to multibyte for insertion (see `unibyte-char-to-multibyte'). +If the current buffer is unibyte, multibyte strings are converted +to unibyte for insertion. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -2052,14 +2048,14 @@ DEFUN ("insert-before-markers-and-inherit", Finsert_and_inherit_before_markers, Sinsert_and_inherit_before_markers, 0, MANY, 0, - "Insert text at point, relocating markers and inheriting properties.\n\ -Point and markers move forward to end up after the inserted text.\n\ -\n\ -If the current buffer is multibyte, unibyte strings are converted\n\ -to multibyte for insertion (see `unibyte-char-to-multibyte').\n\ -If the current buffer is unibyte, multibyte strings are converted\n\ -to unibyte for insertion.") - (nargs, args) + /* Insert text at point, relocating markers and inheriting properties. +Point and markers move forward to end up after the inserted text. + +If the current buffer is multibyte, unibyte strings are converted +to multibyte for insertion (see `unibyte-char-to-multibyte'). +If the current buffer is unibyte, multibyte strings are converted +to unibyte for insertion. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -2070,12 +2066,12 @@ } DEFUN ("insert-char", Finsert_char, Sinsert_char, 2, 3, 0, - "Insert COUNT (second arg) copies of CHARACTER (first arg).\n\ -Both arguments are required.\n\ -Point, and before-insertion markers, are relocated as in the function `insert'.\n\ -The optional third arg INHERIT, if non-nil, says to inherit text properties\n\ -from adjoining text, if those properties are sticky.") - (character, count, inherit) + /* Insert COUNT (second arg) copies of CHARACTER (first arg). +Both arguments are required. +Point, and before-insertion markers, are relocated as in the function `insert'. +The optional third arg INHERIT, if non-nil, says to inherit text properties +from adjoining text, if those properties are sticky. */ + (character, count, inherit)) Lisp_Object character, count, inherit; { register unsigned char *string; @@ -2226,15 +2222,15 @@ } DEFUN ("buffer-substring", Fbuffer_substring, Sbuffer_substring, 2, 2, 0, - "Return the contents of part of the current buffer as a string.\n\ -The two arguments START and END are character positions;\n\ -they can be in either order.\n\ -The string returned is multibyte if the buffer is multibyte.\n\ -\n\ -This function copies the text properties of that part of the buffer\n\ -into the result string; if you don't want the text properties,\n\ -use `buffer-substring-no-properties' instead.") - (start, end) + /* Return the contents of part of the current buffer as a string. +The two arguments START and END are character positions; +they can be in either order. +The string returned is multibyte if the buffer is multibyte. + +This function copies the text properties of that part of the buffer +into the result string; if you don't want the text properties, +use `buffer-substring-no-properties' instead. */ + (start, end)) Lisp_Object start, end; { register int b, e; @@ -2248,10 +2244,10 @@ DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, Sbuffer_substring_no_properties, 2, 2, 0, - "Return the characters of part of the buffer, without the text properties.\n\ -The two arguments START and END are character positions;\n\ -they can be in either order.") - (start, end) + /* Return the characters of part of the buffer, without the text properties. +The two arguments START and END are character positions; +they can be in either order. */ + (start, end)) Lisp_Object start, end; { register int b, e; @@ -2264,21 +2260,21 @@ } DEFUN ("buffer-string", Fbuffer_string, Sbuffer_string, 0, 0, 0, - "Return the contents of the current buffer as a string.\n\ -If narrowing is in effect, this function returns only the visible part\n\ -of the buffer.") - () + /* Return the contents of the current buffer as a string. +If narrowing is in effect, this function returns only the visible part +of the buffer. */ + ()) { return make_buffer_string (BEGV, ZV, 1); } DEFUN ("insert-buffer-substring", Finsert_buffer_substring, Sinsert_buffer_substring, 1, 3, 0, - "Insert before point a substring of the contents of buffer BUFFER.\n\ -BUFFER may be a buffer or a buffer name.\n\ -Arguments START and END are character numbers specifying the substring.\n\ -They default to the beginning and the end of BUFFER.") - (buf, start, end) + /* Insert before point a substring of the contents of buffer BUFFER. +BUFFER may be a buffer or a buffer name. +Arguments START and END are character numbers specifying the substring. +They default to the beginning and the end of BUFFER. */ + (buf, start, end)) Lisp_Object buf, start, end; { register int b, e, temp; @@ -2324,14 +2320,15 @@ DEFUN ("compare-buffer-substrings", Fcompare_buffer_substrings, Scompare_buffer_substrings, 6, 6, 0, - "Compare two substrings of two buffers; return result as number.\n\ -the value is -N if first string is less after N-1 chars,\n\ -+N if first string is greater after N-1 chars, or 0 if strings match.\n\ -Each substring is represented as three arguments: BUFFER, START and END.\n\ -That makes six args in all, three for each substring.\n\n\ -The value of `case-fold-search' in the current buffer\n\ -determines whether case is significant or ignored.") - (buffer1, start1, end1, buffer2, start2, end2) + /* Compare two substrings of two buffers; return result as number. +the value is -N if first string is less after N-1 chars, ++N if first string is greater after N-1 chars, or 0 if strings match. +Each substring is represented as three arguments: BUFFER, START and END. +That makes six args in all, three for each substring. + +The value of `case-fold-search' in the current buffer +determines whether case is significant or ignored. */ + (buffer1, start1, end1, buffer2, start2, end2)) Lisp_Object buffer1, start1, end1, buffer2, start2, end2; { register int begp1, endp1, begp2, endp2, temp; @@ -2495,11 +2492,11 @@ DEFUN ("subst-char-in-region", Fsubst_char_in_region, Ssubst_char_in_region, 4, 5, 0, - "From START to END, replace FROMCHAR with TOCHAR each time it occurs.\n\ -If optional arg NOUNDO is non-nil, don't record this change for undo\n\ -and don't mark the buffer as really changed.\n\ -Both characters must have the same length of multi-byte form.") - (start, end, fromchar, tochar, noundo) + /* From START to END, replace FROMCHAR with TOCHAR each time it occurs. +If optional arg NOUNDO is non-nil, don't record this change for undo +and don't mark the buffer as really changed. +Both characters must have the same length of multi-byte form. */ + (start, end, fromchar, tochar, noundo)) Lisp_Object start, end, fromchar, tochar, noundo; { register int pos, pos_byte, stop, i, len, end_byte; @@ -2662,12 +2659,12 @@ } DEFUN ("translate-region", Ftranslate_region, Stranslate_region, 3, 3, 0, - "From START to END, translate characters according to TABLE.\n\ -TABLE is a string; the Nth character in it is the mapping\n\ -for the character with code N.\n\ -This function does not alter multibyte characters.\n\ -It returns the number of characters changed.") - (start, end, table) + /* From START to END, translate characters according to TABLE. +TABLE is a string; the Nth character in it is the mapping +for the character with code N. +This function does not alter multibyte characters. +It returns the number of characters changed. */ + (start, end, table)) Lisp_Object start; Lisp_Object end; register Lisp_Object table; @@ -2751,10 +2748,10 @@ } DEFUN ("delete-region", Fdelete_region, Sdelete_region, 2, 2, "r", - "Delete the text between point and mark.\n\ -When called from a program, expects two arguments,\n\ -positions (integers or markers) specifying the stretch to be deleted.") - (start, end) + /* Delete the text between point and mark. +When called from a program, expects two arguments, +positions (integers or markers) specifying the stretch to be deleted. */ + (start, end)) Lisp_Object start, end; { validate_region (&start, &end); @@ -2764,8 +2761,8 @@ DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, Sdelete_and_extract_region, 2, 2, 0, - "Delete the text between START and END and return it.") - (start, end) + /* Delete the text between START and END and return it. */ + (start, end)) Lisp_Object start, end; { validate_region (&start, &end); @@ -2773,9 +2770,9 @@ } DEFUN ("widen", Fwiden, Swiden, 0, 0, "", - "Remove restrictions (narrowing) from current buffer.\n\ -This allows the buffer's full text to be seen and edited.") - () + /* Remove restrictions (narrowing) from current buffer. +This allows the buffer's full text to be seen and edited. */ + ()) { if (BEG != BEGV || Z != ZV) current_buffer->clip_changed = 1; @@ -2788,15 +2785,15 @@ } DEFUN ("narrow-to-region", Fnarrow_to_region, Snarrow_to_region, 2, 2, "r", - "Restrict editing in this buffer to the current region.\n\ -The rest of the text becomes temporarily invisible and untouchable\n\ -but is not deleted; if you save the buffer in a file, the invisible\n\ -text is included in the file. \\[widen] makes all visible again.\n\ -See also `save-restriction'.\n\ -\n\ -When calling from a program, pass two arguments; positions (integers\n\ -or markers) bounding the text that should remain visible.") - (start, end) + /* Restrict editing in this buffer to the current region. +The rest of the text becomes temporarily invisible and untouchable +but is not deleted; if you save the buffer in a file, the invisible +text is included in the file. \\[widen] makes all visible again. +See also `save-restriction'. + +When calling from a program, pass two arguments; positions (integers +or markers) bounding the text that should remain visible. */ + (start, end)) register Lisp_Object start, end; { CHECK_NUMBER_COERCE_MARKER (start, 0); @@ -2898,21 +2895,21 @@ } DEFUN ("save-restriction", Fsave_restriction, Ssave_restriction, 0, UNEVALLED, 0, - "Execute BODY, saving and restoring current buffer's restrictions.\n\ -The buffer's restrictions make parts of the beginning and end invisible.\n\ -\(They are set up with `narrow-to-region' and eliminated with `widen'.)\n\ -This special form, `save-restriction', saves the current buffer's restrictions\n\ -when it is entered, and restores them when it is exited.\n\ -So any `narrow-to-region' within BODY lasts only until the end of the form.\n\ -The old restrictions settings are restored\n\ -even in case of abnormal exit (throw or error).\n\ -\n\ -The value returned is the value of the last form in BODY.\n\ -\n\ -Note: if you are using both `save-excursion' and `save-restriction',\n\ -use `save-excursion' outermost:\n\ - (save-excursion (save-restriction ...))") - (body) + /* Execute BODY, saving and restoring current buffer's restrictions. +The buffer's restrictions make parts of the beginning and end invisible. +(They are set up with `narrow-to-region' and eliminated with `widen'.) +This special form, `save-restriction', saves the current buffer's restrictions +when it is entered, and restores them when it is exited. +So any `narrow-to-region' within BODY lasts only until the end of the form. +The old restrictions settings are restored +even in case of abnormal exit (throw or error). + +The value returned is the value of the last form in BODY. + +Note: if you are using both `save-excursion' and `save-restriction', +use `save-excursion' outermost: + (save-excursion (save-restriction ...)) */ + (body)) Lisp_Object body; { register Lisp_Object val; @@ -2930,13 +2927,13 @@ static int message_length; DEFUN ("message", Fmessage, Smessage, 1, MANY, 0, - "Print a one-line message at the bottom of the screen.\n\ -The first argument is a format control string, and the rest are data\n\ -to be formatted under control of the string. See `format' for details.\n\ -\n\ -If the first argument is nil, clear any existing message; let the\n\ -minibuffer contents show.") - (nargs, args) + /* Print a one-line message at the bottom of the screen. +The first argument is a format control string, and the rest are data +to be formatted under control of the string. See `format' for details. + +If the first argument is nil, clear any existing message; let the +minibuffer contents show. */ + (nargs, args)) int nargs; Lisp_Object *args; { @@ -2955,14 +2952,14 @@ } DEFUN ("message-box", Fmessage_box, Smessage_box, 1, MANY, 0, - "Display a message, in a dialog box if possible.\n\ -If a dialog box is not available, use the echo area.\n\ -The first argument is a format control string, and the rest are data\n\ -to be formatted under control of the string. See `format' for details.\n\ -\n\ -If the first argument is nil, clear any existing message; let the\n\ -minibuffer contents show.") - (nargs, args) + /* Display a message, in a dialog box if possible. +If a dialog box is not available, use the echo area. +The first argument is a format control string, and the rest are data +to be formatted under control of the string. See `format' for details. + +If the first argument is nil, clear any existing message; let the +minibuffer contents show. */ + (nargs, args)) int nargs; Lisp_Object *args; { @@ -3013,16 +3010,16 @@ #endif DEFUN ("message-or-box", Fmessage_or_box, Smessage_or_box, 1, MANY, 0, - "Display a message in a dialog box or in the echo area.\n\ -If this command was invoked with the mouse, use a dialog box if\n\ -`use-dialog-box' is non-nil.\n\ -Otherwise, use the echo area.\n\ -The first argument is a format control string, and the rest are data\n\ -to be formatted under control of the string. See `format' for details.\n\ -\n\ -If the first argument is nil, clear any existing message; let the\n\ -minibuffer contents show.") - (nargs, args) + /* Display a message in a dialog box or in the echo area. +If this command was invoked with the mouse, use a dialog box if +`use-dialog-box' is non-nil. +Otherwise, use the echo area. +The first argument is a format control string, and the rest are data +to be formatted under control of the string. See `format' for details. + +If the first argument is nil, clear any existing message; let the +minibuffer contents show. */ + (nargs, args)) int nargs; Lisp_Object *args; { @@ -3035,19 +3032,19 @@ } DEFUN ("current-message", Fcurrent_message, Scurrent_message, 0, 0, 0, - "Return the string currently displayed in the echo area, or nil if none.") - () + /* Return the string currently displayed in the echo area, or nil if none. */ + ()) { return current_message (); } DEFUN ("propertize", Fpropertize, Spropertize, 3, MANY, 0, - "Return a copy of STRING with text properties added.\n\ -First argument is the string to copy.\n\ -Remaining arguments form a sequence of PROPERTY VALUE pairs for text\n\ -properties to add to the result ") - (nargs, args) + /* Return a copy of STRING with text properties added. +First argument is the string to copy. +Remaining arguments form a sequence of PROPERTY VALUE pairs for text +properties to add to the result. */ + (nargs, args)) int nargs; Lisp_Object *args; { @@ -3089,22 +3086,22 @@ : STRING_BYTES (XSTRING (STRING))) DEFUN ("format", Fformat, Sformat, 1, MANY, 0, - "Format a string out of a control-string and arguments.\n\ -The first argument is a control string.\n\ -The other arguments are substituted into it to make the result, a string.\n\ -It may contain %-sequences meaning to substitute the next argument.\n\ -%s means print a string argument. Actually, prints any object, with `princ'.\n\ -%d means print as number in decimal (%o octal, %x hex).\n\ -%X is like %x, but uses upper case.\n\ -%e means print a number in exponential notation.\n\ -%f means print a number in decimal-point notation.\n\ -%g means print a number in exponential notation\n\ - or decimal-point notation, whichever uses fewer characters.\n\ -%c means print a number as a single character.\n\ -%S means print any object as an s-expression (using `prin1').\n\ - The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.\n\ -Use %% to put a single % into the output.") - (nargs, args) + /* Format a string out of a control-string and arguments. +The first argument is a control string. +The other arguments are substituted into it to make the result, a string. +It may contain %-sequences meaning to substitute the next argument. +%s means print a string argument. Actually, prints any object, with `princ'. +%d means print as number in decimal (%o octal, %x hex). +%X is like %x, but uses upper case. +%e means print a number in exponential notation. +%f means print a number in decimal-point notation. +%g means print a number in exponential notation + or decimal-point notation, whichever uses fewer characters. +%c means print a number as a single character. +%S means print any object as an s-expression (using `prin1'). + The argument used for %d, %o, %x, %e, %f, %g or %c must be a number. +Use %% to put a single % into the output. */ + (nargs, args)) int nargs; register Lisp_Object *args; { @@ -3528,10 +3525,10 @@ } DEFUN ("char-equal", Fchar_equal, Schar_equal, 2, 2, 0, - "Return t if two characters match, optionally ignoring case.\n\ -Both arguments must be characters (i.e. integers).\n\ -Case is ignored if `case-fold-search' is non-nil in the current buffer.") - (c1, c2) + /* Return t if two characters match, optionally ignoring case. +Both arguments must be characters (i.e. integers). +Case is ignored if `case-fold-search' is non-nil in the current buffer. */ + (c1, c2)) register Lisp_Object c1, c2; { int i1, i2; @@ -3637,15 +3634,15 @@ } DEFUN ("transpose-regions", Ftranspose_regions, Stranspose_regions, 4, 5, 0, - "Transpose region START1 to END1 with START2 to END2.\n\ -The regions may not be overlapping, because the size of the buffer is\n\ -never changed in a transposition.\n\ -\n\ -Optional fifth arg LEAVE_MARKERS, if non-nil, means don't update\n\ -any markers that happen to be located in the regions.\n\ -\n\ -Transposing beyond buffer boundaries is an error.") - (startr1, endr1, startr2, endr2, leave_markers) + /* Transpose region START1 to END1 with START2 to END2. +The regions may not be overlapping, because the size of the buffer is +never changed in a transposition. + +Optional fifth arg LEAVE_MARKERS, if non-nil, means don't update +any markers that happen to be located in the regions. + +Transposing beyond buffer boundaries is an error. */ + (startr1, endr1, startr2, endr2, leave_markers)) Lisp_Object startr1, endr1, startr2, endr2, leave_markers; { register int start1, end1, start2, end2; @@ -3935,15 +3932,15 @@ = intern ("buffer-access-fontify-functions"); staticpro (&Qbuffer_access_fontify_functions); - DEFVAR_LISP ("inhibit-field-text-motion", &Vinhibit_field_text_motion, - "Non-nil means.text motion commands don't notice fields."); + DEFVAR_LISP ("inhibit-field-text-motion", &Vinhibit_field_text_motion + /* Non-nil means.text motion commands don't notice fields. */); Vinhibit_field_text_motion = Qnil; DEFVAR_LISP ("buffer-access-fontify-functions", - &Vbuffer_access_fontify_functions, - "List of functions called by `buffer-substring' to fontify if necessary.\n\ -Each function is called with two arguments which specify the range\n\ -of the buffer being accessed."); + &Vbuffer_access_fontify_functions + /* List of functions called by `buffer-substring' to fontify if necessary. +Each function is called with two arguments which specify the range +of the buffer being accessed. */); Vbuffer_access_fontify_functions = Qnil; { @@ -3959,23 +3956,23 @@ } DEFVAR_LISP ("buffer-access-fontified-property", - &Vbuffer_access_fontified_property, - "Property which (if non-nil) indicates text has been fontified.\n\ -`buffer-substring' need not call the `buffer-access-fontify-functions'\n\ -functions if all the text being accessed has this property."); + &Vbuffer_access_fontified_property + /* Property which (if non-nil) indicates text has been fontified. +`buffer-substring' need not call the `buffer-access-fontify-functions' +functions if all the text being accessed has this property. */); Vbuffer_access_fontified_property = Qnil; - DEFVAR_LISP ("system-name", &Vsystem_name, - "The name of the machine Emacs is running on."); - - DEFVAR_LISP ("user-full-name", &Vuser_full_name, - "The full name of the user logged in."); - - DEFVAR_LISP ("user-login-name", &Vuser_login_name, - "The user's name, taken from environment variables if possible."); - - DEFVAR_LISP ("user-real-login-name", &Vuser_real_login_name, - "The user's name, based upon the real uid only."); + DEFVAR_LISP ("system-name", &Vsystem_name + /* The name of the machine Emacs is running on. */); + + DEFVAR_LISP ("user-full-name", &Vuser_full_name + /* The full name of the user logged in. */); + + DEFVAR_LISP ("user-login-name", &Vuser_login_name + /* The user's name, taken from environment variables if possible. */); + + DEFVAR_LISP ("user-real-login-name", &Vuser_real_login_name + /* The user's name, based upon the real uid only. */); defsubr (&Spropertize); defsubr (&Schar_equal);
--- a/src/minibuf.c Mon Oct 15 14:55:28 2001 +0000 +++ b/src/minibuf.c Mon Oct 15 15:04:22 2001 +0000 @@ -22,6 +22,7 @@ #include <config.h> #include <stdio.h> +#define DOC_STRINGS_IN_COMMENTS #include "lisp.h" #include "commands.h" #include "buffer.h" @@ -192,10 +193,10 @@ DEFUN ("set-minibuffer-window", Fset_minibuffer_window, Sset_minibuffer_window, 1, 1, 0, - "Specify which minibuffer window to use for the minibuffer.\n\ -This effects where the minibuffer is displayed if you put text in it\n\ -without invoking the usual minibuffer commands.") - (window) + /* Specify which minibuffer window to use for the minibuffer. +This effects where the minibuffer is displayed if you put text in it +without invoking the usual minibuffer commands. */ + (window)) Lisp_Object window; { CHECK_WINDOW (window, 1); @@ -325,9 +326,9 @@ DEFUN ("minibuffer-prompt-end", Fminibuffer_prompt_end, Sminibuffer_prompt_end, 0, 0, 0, - "Return the buffer position of the end of the minibuffer prompt.\n\ -Return (point-min) if current buffer is not a mini-buffer.") - () + /* Return the buffer position of the end of the minibuffer prompt. +Return (point-min) if current buffer is not a mini-buffer. */ + ()) { /* This function is written to be most efficient when there's a prompt. */ Lisp_Object beg = make_number (BEGV); @@ -341,9 +342,9 @@ DEFUN ("minibuffer-contents", Fminibuffer_contents, Sminibuffer_contents, 0, 0, 0, - "Return the user input in a minbuffer as a string.\n\ -The current buffer must be a minibuffer.") - () + /* Return the user input in a minbuffer as a string. +The current buffer must be a minibuffer. */ + ()) { int prompt_end = XINT (Fminibuffer_prompt_end ()); return make_buffer_string (prompt_end, ZV, 1); @@ -351,9 +352,9 @@ DEFUN ("minibuffer-contents-no-properties", Fminibuffer_contents_no_properties, Sminibuffer_contents_no_properties, 0, 0, 0, - "Return the user input in a minbuffer as a string, without text-properties.\n\ -The current buffer must be a minibuffer.") - () + /* Return the user input in a minbuffer as a string, without text-properties. +The current buffer must be a minibuffer. */ + ()) { int prompt_end = XINT (Fminibuffer_prompt_end ()); return make_buffer_string (prompt_end, ZV, 0); @@ -361,9 +362,9 @@ DEFUN ("delete-minibuffer-contents", Fdelete_minibuffer_contents, Sdelete_minibuffer_contents, 0, 0, 0, - "Delete all user input in a minibuffer.\n\ -The current buffer must be a minibuffer.") - () + /* Delete all user input in a minibuffer. +The current buffer must be a minibuffer. */ + ()) { int prompt_end = XINT (Fminibuffer_prompt_end ()); if (prompt_end < ZV) @@ -845,8 +846,33 @@ */ DEFUN ("read-from-minibuffer", Fread_from_minibuffer, Sread_from_minibuffer, 1, 7, 0, - 0 /* See immediately above */) - (prompt, initial_contents, keymap, read, hist, default_value, inherit_input_method) + /* Read a string from the minibuffer, prompting with string PROMPT. +If optional second arg INITIAL-CONTENTS is non-nil, it is a string + to be inserted into the minibuffer before reading input. + If INITIAL-CONTENTS is (STRING . POSITION), the initial input + is STRING, but point is placed at position POSITION in the minibuffer. +Third arg KEYMAP is a keymap to use whilst reading; + if omitted or nil, the default is `minibuffer-local-map'. +If fourth arg READ is non-nil, then interpret the result as a lisp object + and return that object: + in other words, do `(car (read-from-string INPUT-STRING))' +Fifth arg HIST, if non-nil, specifies a history list + and optionally the initial position in the list. + It can be a symbol, which is the history list variable to use, + or it can be a cons cell (HISTVAR . HISTPOS). + In that case, HISTVAR is the history list variable to use, + and HISTPOS is the initial position (the position in the list + which INITIAL-CONTENTS corresponds to). + Positions are counted starting from 1 at the beginning of the list. +Sixth arg DEFAULT-VALUE is the default value. If non-nil, it is available + for history commands; but `read-from-minibuffer' does NOT return DEFAULT-VALUE + if the user enters empty input! It returns the empty string. +Seventh arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits + the current input method and the setting of enable-multibyte-characters. +If the variable `minibuffer-allow-text-properties' is non-nil, + then the string which is returned includes whatever text properties + were present in the minibuffer. Otherwise the value has no text properties. */ + (prompt, initial_contents, keymap, read, hist, default_value, inherit_input_method)) Lisp_Object prompt, initial_contents, keymap, read, hist, default_value; Lisp_Object inherit_input_method; { @@ -908,10 +934,10 @@ } DEFUN ("read-minibuffer", Fread_minibuffer, Sread_minibuffer, 1, 2, 0, - "Return a Lisp object read using the minibuffer.\n\ -Prompt with PROMPT. If non-nil, optional second arg INITIAL-CONTENTS\n\ -is a string to insert in the minibuffer before reading.") - (prompt, initial_contents) + /* Return a Lisp object read using the minibuffer. +Prompt with PROMPT. If non-nil, optional second arg INITIAL-CONTENTS +is a string to insert in the minibuffer before reading. */ + (prompt, initial_contents)) Lisp_Object prompt, initial_contents; { CHECK_STRING (prompt, 0); @@ -923,10 +949,10 @@ } DEFUN ("eval-minibuffer", Feval_minibuffer, Seval_minibuffer, 1, 2, 0, - "Return value of Lisp expression read using the minibuffer.\n\ -Prompt with PROMPT. If non-nil, optional second arg INITIAL-CONTENTS\n\ -is a string to insert in the minibuffer before reading.") - (prompt, initial_contents) + /* Return value of Lisp expression read using the minibuffer. +Prompt with PROMPT. If non-nil, optional second arg INITIAL-CONTENTS +is a string to insert in the minibuffer before reading. */ + (prompt, initial_contents)) Lisp_Object prompt, initial_contents; { return Feval (Fread_minibuffer (prompt, initial_contents)); @@ -935,17 +961,17 @@ /* Functions that use the minibuffer to read various things. */ DEFUN ("read-string", Fread_string, Sread_string, 1, 5, 0, - "Read a string from the minibuffer, prompting with string PROMPT.\n\ -If non-nil, second arg INITIAL-INPUT is a string to insert before reading.\n\ -The third arg HISTORY, if non-nil, specifies a history list\n\ - and optionally the initial position in the list.\n\ -See `read-from-minibuffer' for details of HISTORY argument.\n\ -Fourth arg DEFAULT-VALUE is the default value. If non-nil, it is used\n\ - for history commands, and as the value to return if the user enters\n\ - the empty string.\n\ -Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits\n\ - the current input method and the setting of enable-multibyte-characters.") - (prompt, initial_input, history, default_value, inherit_input_method) + /* Read a string from the minibuffer, prompting with string PROMPT. +If non-nil, second arg INITIAL-INPUT is a string to insert before reading. +The third arg HISTORY, if non-nil, specifies a history list + and optionally the initial position in the list. +See `read-from-minibuffer' for details of HISTORY argument. +Fourth arg DEFAULT-VALUE is the default value. If non-nil, it is used + for history commands, and as the value to return if the user enters + the empty string. +Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits + the current input method and the setting of enable-multibyte-characters. */ + (prompt, initial_input, history, default_value, inherit_input_method)) Lisp_Object prompt, initial_input, history, default_value; Lisp_Object inherit_input_method; { @@ -959,11 +985,11 @@ } DEFUN ("read-no-blanks-input", Fread_no_blanks_input, Sread_no_blanks_input, 1, 3, 0, - "Read a string from the terminal, not allowing blanks.\n\ -Prompt with PROMPT, and provide INITIAL as an initial value of the input string.\n\ -Third arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits\n\ -the current input method and the setting of enable-multibyte-characters.") - (prompt, initial, inherit_input_method) + /* Read a string from the terminal, not allowing blanks. +Prompt with PROMPT, and provide INITIAL as an initial value of the input string. +Third arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits +the current input method and the setting of enable-multibyte-characters. */ + (prompt, initial, inherit_input_method)) Lisp_Object prompt, initial, inherit_input_method; { CHECK_STRING (prompt, 0); @@ -976,9 +1002,9 @@ } DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0, - "Read the name of a command and return as a symbol.\n\ -Prompts with PROMPT. By default, return DEFAULT-VALUE.") - (prompt, default_value) + /* Read the name of a command and return as a symbol. +Prompts with PROMPT. By default, return DEFAULT-VALUE. */ + (prompt, default_value)) Lisp_Object prompt, default_value; { Lisp_Object name, default_string; @@ -999,9 +1025,9 @@ #ifdef NOTDEF DEFUN ("read-function", Fread_function, Sread_function, 1, 1, 0, - "One arg PROMPT, a string. Read the name of a function and return as a symbol.\n\ -Prompts with PROMPT.") - (prompt) + /* One arg PROMPT, a string. Read the name of a function and return as a symbol. +Prompts with PROMPT. */ + (prompt)) Lisp_Object prompt; { return Fintern (Fcompleting_read (prompt, Vobarray, Qfboundp, Qt, Qnil, Qnil, Qnil, Qnil), @@ -1010,10 +1036,10 @@ #endif /* NOTDEF */ DEFUN ("read-variable", Fread_variable, Sread_variable, 1, 2, 0, - "Read the name of a user variable and return it as a symbol.\n\ -Prompts with PROMPT. By default, return DEFAULT-VALUE.\n\ -A user variable is one whose documentation starts with a `*' character.") - (prompt, default_value) + /* Read the name of a user variable and return it as a symbol. +Prompts with PROMPT. By default, return DEFAULT-VALUE. +A user variable is one whose documentation starts with a `*' character. */ + (prompt, default_value)) Lisp_Object prompt, default_value; { Lisp_Object name, default_string; @@ -1034,11 +1060,11 @@ } DEFUN ("read-buffer", Fread_buffer, Sread_buffer, 1, 3, 0, - "One arg PROMPT, a string. Read the name of a buffer and return as a string.\n\ -Prompts with PROMPT.\n\ -Optional second arg DEF is value to return if user enters an empty line.\n\ -If optional third arg REQUIRE-MATCH is non-nil, only existing buffer names are allowed.") - (prompt, def, require_match) + /* One arg PROMPT, a string. Read the name of a buffer and return as a string. +Prompts with PROMPT. +Optional second arg DEF is value to return if user enters an empty line. +If optional third arg REQUIRE-MATCH is non-nil, only existing buffer names are allowed. */ + (prompt, def, require_match)) Lisp_Object prompt, def, require_match; { Lisp_Object args[4]; @@ -1084,28 +1110,28 @@ } DEFUN ("try-completion", Ftry_completion, Stry_completion, 2, 3, 0, - "Return common substring of all completions of STRING in ALIST.\n\ -Each car of each element of ALIST is tested to see if it begins with STRING.\n\ -All that match are compared together; the longest initial sequence\n\ -common to all matches is returned as a string.\n\ -If there is no match at all, nil is returned.\n\ -For a unique match which is exact, t is returned.\n\ -\n\ -ALIST can be an obarray instead of an alist.\n\ -Then the print names of all symbols in the obarray are the possible matches.\n\ -\n\ -ALIST can also be a function to do the completion itself.\n\ -It receives three arguments: the values STRING, PREDICATE and nil.\n\ -Whatever it returns becomes the value of `try-completion'.\n\ -\n\ -If optional third argument PREDICATE is non-nil,\n\ -it is used to test each possible match.\n\ -The match is a candidate only if PREDICATE returns non-nil.\n\ -The argument given to PREDICATE is the alist element\n\ -or the symbol from the obarray.\n\ -Additionally to this predicate, `completion-regexp-list'\n\ -is used to further constrain the set of candidates.") - (string, alist, predicate) + /* Return common substring of all completions of STRING in ALIST. +Each car of each element of ALIST is tested to see if it begins with STRING. +All that match are compared together; the longest initial sequence +common to all matches is returned as a string. +If there is no match at all, nil is returned. +For a unique match which is exact, t is returned. + +ALIST can be an obarray instead of an alist. +Then the print names of all symbols in the obarray are the possible matches. + +ALIST can also be a function to do the completion itself. +It receives three arguments: the values STRING, PREDICATE and nil. +Whatever it returns becomes the value of `try-completion'. + +If optional third argument PREDICATE is non-nil, +it is used to test each possible match. +The match is a candidate only if PREDICATE returns non-nil. +The argument given to PREDICATE is the alist element +or the symbol from the obarray. +Additionally to this predicate, `completion-regexp-list' +is used to further constrain the set of candidates. */ + (string, alist, predicate)) Lisp_Object string, alist, predicate; { Lisp_Object bestmatch, tail, elt, eltstring; @@ -1335,29 +1361,29 @@ } DEFUN ("all-completions", Fall_completions, Sall_completions, 2, 4, 0, - "Search for partial matches to STRING in ALIST.\n\ -Each car of each element of ALIST is tested to see if it begins with STRING.\n\ -The value is a list of all the strings from ALIST that match.\n\ -\n\ -ALIST can be an obarray instead of an alist.\n\ -Then the print names of all symbols in the obarray are the possible matches.\n\ -\n\ -ALIST can also be a function to do the completion itself.\n\ -It receives three arguments: the values STRING, PREDICATE and t.\n\ -Whatever it returns becomes the value of `all-completions'.\n\ -\n\ -If optional third argument PREDICATE is non-nil,\n\ -it is used to test each possible match.\n\ -The match is a candidate only if PREDICATE returns non-nil.\n\ -The argument given to PREDICATE is the alist element\n\ -or the symbol from the obarray.\n\ -Additionally to this predicate, `completion-regexp-list'\n\ -is used to further constrain the set of candidates.\n\ -\n\ -If the optional fourth argument HIDE-SPACES is non-nil,\n\ -strings in ALIST that start with a space\n\ -are ignored unless STRING itself starts with a space.") - (string, alist, predicate, hide_spaces) + /* Search for partial matches to STRING in ALIST. +Each car of each element of ALIST is tested to see if it begins with STRING. +The value is a list of all the strings from ALIST that match. + +ALIST can be an obarray instead of an alist. +Then the print names of all symbols in the obarray are the possible matches. + +ALIST can also be a function to do the completion itself. +It receives three arguments: the values STRING, PREDICATE and t. +Whatever it returns becomes the value of `all-completions'. + +If optional third argument PREDICATE is non-nil, +it is used to test each possible match. +The match is a candidate only if PREDICATE returns non-nil. +The argument given to PREDICATE is the alist element +or the symbol from the obarray. +Additionally to this predicate, `completion-regexp-list' +is used to further constrain the set of candidates. + +If the optional fourth argument HIDE-SPACES is non-nil, +strings in ALIST that start with a space +are ignored unless STRING itself starts with a space. */ + (string, alist, predicate, hide_spaces)) Lisp_Object string, alist, predicate, hide_spaces; { Lisp_Object tail, elt, eltstring; @@ -1479,48 +1505,41 @@ Lisp_Object Vminibuffer_completion_confirm, Qminibuffer_completion_confirm; Lisp_Object Vminibuffer_completing_file_name; -/* This comment supplies the doc string for completing-read, - for make-docfile to see. We cannot put this in the real DEFUN - due to limits in the Unix cpp. +DEFUN ("completing-read", Fcompleting_read, Scompleting_read, 2, 8, 0, + /* Read a string in the minibuffer, with completion. +PROMPT is a string to prompt with; normally it ends in a colon and a space. +TABLE is an alist whose elements' cars are strings, or an obarray. +TABLE can also be a function to do the completion itself. +PREDICATE limits completion to a subset of TABLE. +See `try-completion' and `all-completions' for more details + on completion, TABLE, and PREDICATE. + +If REQUIRE-MATCH is non-nil, the user is not allowed to exit unless + the input is (or completes to) an element of TABLE or is null. + If it is also not t, Return does not exit if it does non-null completion. +If the input is null, `completing-read' returns an empty string, + regardless of the value of REQUIRE-MATCH. -DEFUN ("completing-read", Fcompleting_read, Scompleting_read, 2, 8, 0, - "Read a string in the minibuffer, with completion.\n\ -PROMPT is a string to prompt with; normally it ends in a colon and a space.\n\ -TABLE is an alist whose elements' cars are strings, or an obarray.\n\ -TABLE can also be a function to do the completion itself.\n\ -PREDICATE limits completion to a subset of TABLE.\n\ -See `try-completion' and `all-completions' for more details\n\ - on completion, TABLE, and PREDICATE.\n\ -\n\ -If REQUIRE-MATCH is non-nil, the user is not allowed to exit unless\n\ - the input is (or completes to) an element of TABLE or is null.\n\ - If it is also not t, Return does not exit if it does non-null completion.\n\ -If the input is null, `completing-read' returns an empty string,\n\ - regardless of the value of REQUIRE-MATCH.\n\ -\n\ -If INITIAL-INPUT is non-nil, insert it in the minibuffer initially.\n\ - If it is (STRING . POSITION), the initial input\n\ - is STRING, but point is placed POSITION characters into the string.\n\ - This feature is deprecated--it is best to pass nil for INITIAL.\n\ -HIST, if non-nil, specifies a history list\n\ - and optionally the initial position in the list.\n\ - It can be a symbol, which is the history list variable to use,\n\ - or it can be a cons cell (HISTVAR . HISTPOS).\n\ - In that case, HISTVAR is the history list variable to use,\n\ - and HISTPOS is the initial position (the position in the list\n\ - which INITIAL-INPUT corresponds to).\n\ - Positions are counted starting from 1 at the beginning of the list.\n\ -DEF, if non-nil, is the default value.\n\ -\n\ -If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits\n\ - the current input method and the setting of enable-multibyte-characters.\n\ -\n\ -Completion ignores case if the ambient value of\n\ - `completion-ignore-case' is non-nil." -*/ -DEFUN ("completing-read", Fcompleting_read, Scompleting_read, 2, 8, 0, - 0 /* See immediately above */) - (prompt, table, predicate, require_match, initial_input, hist, def, inherit_input_method) +If INITIAL-INPUT is non-nil, insert it in the minibuffer initially. + If it is (STRING . POSITION), the initial input + is STRING, but point is placed POSITION characters into the string. + This feature is deprecated--it is best to pass nil for INITIAL. +HIST, if non-nil, specifies a history list + and optionally the initial position in the list. + It can be a symbol, which is the history list variable to use, + or it can be a cons cell (HISTVAR . HISTPOS). + In that case, HISTVAR is the history list variable to use, + and HISTPOS is the initial position (the position in the list + which INITIAL-INPUT corresponds to). + Positions are counted starting from 1 at the beginning of the list. +DEF, if non-nil, is the default value. + +If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits + the current input method and the setting of enable-multibyte-characters. + +Completion ignores case if the ambient value of + `completion-ignore-case' is non-nil. */ + (prompt, table, predicate, require_match, initial_input, hist, def, inherit_input_method)) Lisp_Object prompt, table, predicate, require_match, initial_input; Lisp_Object hist, def, inherit_input_method; { @@ -1755,12 +1774,12 @@ } DEFUN ("minibuffer-complete", Fminibuffer_complete, Sminibuffer_complete, 0, 0, "", - "Complete the minibuffer contents as far as possible.\n\ -Return nil if there is no valid completion, else t.\n\ -If no characters can be completed, display a list of possible completions.\n\ -If you repeat this command after it displayed such a list,\n\ -scroll the window of possible completions.") - () + /* Complete the minibuffer contents as far as possible. +Return nil if there is no valid completion, else t. +If no characters can be completed, display a list of possible completions. +If you repeat this command after it displayed such a list, +scroll the window of possible completions. */ + ()) { register int i; Lisp_Object window, tem; @@ -1835,10 +1854,10 @@ DEFUN ("minibuffer-complete-and-exit", Fminibuffer_complete_and_exit, Sminibuffer_complete_and_exit, 0, 0, "", - "If the minibuffer contents is a valid completion then exit.\n\ -Otherwise try to complete it. If completion leads to a valid completion,\n\ -a repetition of this command will exit.") - () + /* If the minibuffer contents is a valid completion then exit. +Otherwise try to complete it. If completion leads to a valid completion, +a repetition of this command will exit. */ + ()) { register int i; Lisp_Object val; @@ -1880,11 +1899,11 @@ DEFUN ("minibuffer-complete-word", Fminibuffer_complete_word, Sminibuffer_complete_word, 0, 0, "", - "Complete the minibuffer contents at most a single word.\n\ -After one word is completed as much as possible, a space or hyphen\n\ -is added, provided that matches some possible completion.\n\ -Return nil if there is no valid completion, else t.") - () + /* Complete the minibuffer contents at most a single word. +After one word is completed as much as possible, a space or hyphen +is added, provided that matches some possible completion. +Return nil if there is no valid completion, else t. */ + ()) { Lisp_Object completion, tem, tem1; register int i, i_byte; @@ -2053,15 +2072,15 @@ DEFUN ("display-completion-list", Fdisplay_completion_list, Sdisplay_completion_list, 1, 1, 0, - "Display the list of completions, COMPLETIONS, using `standard-output'.\n\ -Each element may be just a symbol or string\n\ -or may be a list of two strings to be printed as if concatenated.\n\ -`standard-output' must be a buffer.\n\ -The actual completion alternatives, as inserted, are given `mouse-face'\n\ -properties of `highlight'.\n\ -At the end, this runs the normal hook `completion-setup-hook'.\n\ -It can find the completion buffer in `standard-output'.") - (completions) + /* Display the list of completions, COMPLETIONS, using `standard-output'. +Each element may be just a symbol or string +or may be a list of two strings to be printed as if concatenated. +`standard-output' must be a buffer. +The actual completion alternatives, as inserted, are given `mouse-face' +properties of `highlight'. +At the end, this runs the normal hook `completion-setup-hook'. +It can find the completion buffer in `standard-output'. */ + (completions)) Lisp_Object completions; { Lisp_Object tail, elt; @@ -2236,8 +2255,8 @@ DEFUN ("minibuffer-completion-help", Fminibuffer_completion_help, Sminibuffer_completion_help, 0, 0, "", - "Display a list of possible completions of the current minibuffer contents.") - () + /* Display a list of possible completions of the current minibuffer contents. */ + ()) { Lisp_Object completions; @@ -2261,8 +2280,8 @@ } DEFUN ("self-insert-and-exit", Fself_insert_and_exit, Sself_insert_and_exit, 0, 0, "", - "Terminate minibuffer input.") - () + /* Terminate minibuffer input. */ + ()) { if (INTEGERP (last_command_char)) internal_self_insert (XINT (last_command_char), 0); @@ -2273,23 +2292,23 @@ } DEFUN ("exit-minibuffer", Fexit_minibuffer, Sexit_minibuffer, 0, 0, "", - "Terminate this minibuffer argument.") - () + /* Terminate this minibuffer argument. */ + ()) { return Fthrow (Qexit, Qnil); } DEFUN ("minibuffer-depth", Fminibuffer_depth, Sminibuffer_depth, 0, 0, 0, - "Return current depth of activations of minibuffer, a nonnegative integer.") - () + /* Return current depth of activations of minibuffer, a nonnegative integer. */ + ()) { return make_number (minibuf_level); } DEFUN ("minibuffer-prompt", Fminibuffer_prompt, Sminibuffer_prompt, 0, 0, 0, - "Return the prompt string of the currently-active minibuffer.\n\ -If no minibuffer is active, return nil.") - () + /* Return the prompt string of the currently-active minibuffer. +If no minibuffer is active, return nil. */ + ()) { return Fcopy_sequence (minibuf_prompt); } @@ -2332,10 +2351,10 @@ DEFUN ("minibuffer-message", Fminibuffer_message, Sminibuffer_message, 1, 1, 0, - "Temporarily display STRING at the end of the minibuffer.\n\ -The text is displayed for two seconds,\n\ -or until the next input event arrives, whichever comes first.") - (string) + /* Temporarily display STRING at the end of the minibuffer. +The text is displayed for two seconds, +or until the next input event arrives, whichever comes first. */ + (string)) Lisp_Object string; { temp_echo_area_glyphs (XSTRING (string)->data); @@ -2406,102 +2425,102 @@ Qactivate_input_method = intern ("activate-input-method"); staticpro (&Qactivate_input_method); - DEFVAR_LISP ("read-buffer-function", &Vread_buffer_function, - "If this is non-nil, `read-buffer' does its work by calling this function."); + DEFVAR_LISP ("read-buffer-function", &Vread_buffer_function + /* If this is non-nil, `read-buffer' does its work by calling this function. */); Vread_buffer_function = Qnil; - DEFVAR_LISP ("minibuffer-setup-hook", &Vminibuffer_setup_hook, - "Normal hook run just after entry to minibuffer."); + DEFVAR_LISP ("minibuffer-setup-hook", &Vminibuffer_setup_hook + /* Normal hook run just after entry to minibuffer. */); Vminibuffer_setup_hook = Qnil; - DEFVAR_LISP ("minibuffer-exit-hook", &Vminibuffer_exit_hook, - "Normal hook run just after exit from minibuffer."); + DEFVAR_LISP ("minibuffer-exit-hook", &Vminibuffer_exit_hook + /* Normal hook run just after exit from minibuffer. */); Vminibuffer_exit_hook = Qnil; - DEFVAR_LISP ("history-length", &Vhistory_length, - "*Maximum length for history lists before truncation takes place.\n\ -A number means that length; t means infinite. Truncation takes place\n\ -just after a new element is inserted. Setting the history-length\n\ -property of a history variable overrides this default."); + DEFVAR_LISP ("history-length", &Vhistory_length + /* *Maximum length for history lists before truncation takes place. +A number means that length; t means infinite. Truncation takes place +just after a new element is inserted. Setting the history-length +property of a history variable overrides this default. */); XSETFASTINT (Vhistory_length, 30); - DEFVAR_LISP ("completion-auto-help", &Vcompletion_auto_help, - "*Non-nil means automatically provide help for invalid completion input."); + DEFVAR_LISP ("completion-auto-help", &Vcompletion_auto_help + /* *Non-nil means automatically provide help for invalid completion input. */); Vcompletion_auto_help = Qt; - DEFVAR_BOOL ("completion-ignore-case", &completion_ignore_case, - "Non-nil means don't consider case significant in completion."); + DEFVAR_BOOL ("completion-ignore-case", &completion_ignore_case + /* Non-nil means don't consider case significant in completion. */); completion_ignore_case = 0; - DEFVAR_BOOL ("enable-recursive-minibuffers", &enable_recursive_minibuffers, - "*Non-nil means to allow minibuffer commands while in the minibuffer.\n\ -This variable makes a difference whenever the minibuffer window is active."); + DEFVAR_BOOL ("enable-recursive-minibuffers", &enable_recursive_minibuffers + /* *Non-nil means to allow minibuffer commands while in the minibuffer. +This variable makes a difference whenever the minibuffer window is active. */); enable_recursive_minibuffers = 0; - DEFVAR_LISP ("minibuffer-completion-table", &Vminibuffer_completion_table, - "Alist or obarray used for completion in the minibuffer.\n\ -This becomes the ALIST argument to `try-completion' and `all-completion'.\n\ -\n\ -The value may alternatively be a function, which is given three arguments:\n\ - STRING, the current buffer contents;\n\ - PREDICATE, the predicate for filtering possible matches;\n\ - CODE, which says what kind of things to do.\n\ -CODE can be nil, t or `lambda'.\n\ -nil means to return the best completion of STRING, or nil if there is none.\n\ -t means to return a list of all possible completions of STRING.\n\ -`lambda' means to return t if STRING is a valid completion as it stands."); + DEFVAR_LISP ("minibuffer-completion-table", &Vminibuffer_completion_table + /* Alist or obarray used for completion in the minibuffer. +This becomes the ALIST argument to `try-completion' and `all-completion'. + +The value may alternatively be a function, which is given three arguments: + STRING, the current buffer contents; + PREDICATE, the predicate for filtering possible matches; + CODE, which says what kind of things to do. +CODE can be nil, t or `lambda'. +nil means to return the best completion of STRING, or nil if there is none. +t means to return a list of all possible completions of STRING. +`lambda' means to return t if STRING is a valid completion as it stands. */); Vminibuffer_completion_table = Qnil; - DEFVAR_LISP ("minibuffer-completion-predicate", &Vminibuffer_completion_predicate, - "Within call to `completing-read', this holds the PREDICATE argument."); + DEFVAR_LISP ("minibuffer-completion-predicate", &Vminibuffer_completion_predicate + /* Within call to `completing-read', this holds the PREDICATE argument. */); Vminibuffer_completion_predicate = Qnil; - DEFVAR_LISP ("minibuffer-completion-confirm", &Vminibuffer_completion_confirm, - "Non-nil => demand confirmation of completion before exiting minibuffer."); + DEFVAR_LISP ("minibuffer-completion-confirm", &Vminibuffer_completion_confirm + /* Non-nil => demand confirmation of completion before exiting minibuffer. */); Vminibuffer_completion_confirm = Qnil; DEFVAR_LISP ("minibuffer-completing-file-name", - &Vminibuffer_completing_file_name, - "Non-nil means completing file names."); + &Vminibuffer_completing_file_name + /* Non-nil means completing file names. */); Vminibuffer_completing_file_name = Qnil; - DEFVAR_LISP ("minibuffer-help-form", &Vminibuffer_help_form, - "Value that `help-form' takes on inside the minibuffer."); + DEFVAR_LISP ("minibuffer-help-form", &Vminibuffer_help_form + /* Value that `help-form' takes on inside the minibuffer. */); Vminibuffer_help_form = Qnil; - DEFVAR_LISP ("minibuffer-history-variable", &Vminibuffer_history_variable, - "History list symbol to add minibuffer values to.\n\ -Each string of minibuffer input, as it appears on exit from the minibuffer,\n\ -is added with\n\ - (set minibuffer-history-variable\n\ - (cons STRING (symbol-value minibuffer-history-variable)))"); + DEFVAR_LISP ("minibuffer-history-variable", &Vminibuffer_history_variable + /* History list symbol to add minibuffer values to. +Each string of minibuffer input, as it appears on exit from the minibuffer, +is added with + (set minibuffer-history-variable + (cons STRING (symbol-value minibuffer-history-variable))) */); XSETFASTINT (Vminibuffer_history_variable, 0); - DEFVAR_LISP ("minibuffer-history-position", &Vminibuffer_history_position, - "Current position of redoing in the history list."); + DEFVAR_LISP ("minibuffer-history-position", &Vminibuffer_history_position + /* Current position of redoing in the history list. */); Vminibuffer_history_position = Qnil; - DEFVAR_BOOL ("minibuffer-auto-raise", &minibuffer_auto_raise, - "*Non-nil means entering the minibuffer raises the minibuffer's frame.\n\ -Some uses of the echo area also raise that frame (since they use it too)."); + DEFVAR_BOOL ("minibuffer-auto-raise", &minibuffer_auto_raise + /* *Non-nil means entering the minibuffer raises the minibuffer's frame. +Some uses of the echo area also raise that frame (since they use it too). */); minibuffer_auto_raise = 0; - DEFVAR_LISP ("completion-regexp-list", &Vcompletion_regexp_list, - "List of regexps that should restrict possible completions."); + DEFVAR_LISP ("completion-regexp-list", &Vcompletion_regexp_list + /* List of regexps that should restrict possible completions. */); Vcompletion_regexp_list = Qnil; DEFVAR_BOOL ("minibuffer-allow-text-properties", - &minibuffer_allow_text_properties, - "Non-nil means `read-from-minibuffer' should not discard text properties.\n\ -This also affects `read-string', but it does not affect `read-minibuffer',\n\ -`read-no-blanks-input', or any of the functions that do minibuffer input\n\ -with completion; they always discard text properties."); + &minibuffer_allow_text_properties + /* Non-nil means `read-from-minibuffer' should not discard text properties. +This also affects `read-string', but it does not affect `read-minibuffer', +`read-no-blanks-input', or any of the functions that do minibuffer input +with completion; they always discard text properties. */); minibuffer_allow_text_properties = 0; - DEFVAR_LISP ("minibuffer-prompt-properties", &Vminibuffer_prompt_properties, - "Text properties that are added to minibuffer prompts.\n\ -These are in addition to the basic `field' property, and stickiness\n\ -properties."); + DEFVAR_LISP ("minibuffer-prompt-properties", &Vminibuffer_prompt_properties + /* Text properties that are added to minibuffer prompts. +These are in addition to the basic `field' property, and stickiness +properties. */); /* We use `intern' here instead of Qread_only to avoid initialization-order problems. */ Vminibuffer_prompt_properties