Put doc strings in comments.

8 files changed, 625 insertions, 611 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index fb6ea360aaf..c2f027c6347 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,8 +1,7 @@
 2001-10-14  Gerd Moellmann  <gerd@gnu.org>
 
         * xfns.c, dispnew.c, xterm.c, xdisp.c, xfaces.c, xmenu.c
-        * term.c:
-        Put doc strings in comments.
+        * term.c, alloc.c: Put doc strings in comments.
 
 2001-10-13  Gerd Moellmann  <gerd@gnu.org>
 
diff --git a/src/alloc.c b/src/alloc.c
index b67f3942ba1..3a9dcc3c59d 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -38,6 +38,7 @@ Boston, MA 02111-1307, USA.  */
    replaced, this file likely will not be used.  */
 
 #undef HIDE_LISP_IMPLEMENTATION
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "process.h"
 #include "intervals.h"
@@ -1659,9 +1660,9 @@ compact_small_strings ()
 
 
 DEFUN ("make-string", Fmake_string, Smake_string, 2, 2, 0,
-  "Return a newly created string of length LENGTH, with each element being INIT.\n\
-Both LENGTH and INIT must be numbers.")
-  (length, init)
+  /* Return a newly created string of length LENGTH, with each element being INIT.
+Both LENGTH and INIT must be numbers.  */
+       (length, init))
      Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -1703,9 +1704,9 @@ Both LENGTH and INIT must be numbers.")
 
 
 DEFUN ("make-bool-vector", Fmake_bool_vector, Smake_bool_vector, 2, 2, 0,
-  "Return a new bool-vector of length LENGTH, using INIT for as each element.\n\
-LENGTH must be a number.  INIT matters only in whether it is t or nil.")
-  (length, init)
+  /* Return a new bool-vector of length LENGTH, using INIT for as each element.
+LENGTH must be a number.  INIT matters only in whether it is t or nil.  */
+       (length, init))
      Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -2057,8 +2058,8 @@ free_cons (ptr)
 
 
 DEFUN ("cons", Fcons, Scons, 2, 2, 0,
-  "Create a new cons, give it CAR and CDR as components, and return it.")
-  (car, cdr)
+  /* Create a new cons, give it CAR and CDR as components, and return it.  */
+       (car, cdr))
      Lisp_Object car, cdr;
 {
   register Lisp_Object val;
@@ -2130,9 +2131,9 @@ list5 (arg1, arg2, arg3, arg4, arg5)
 
 
 DEFUN ("list", Flist, Slist, 0, MANY, 0,
-  "Return a newly created list with specified arguments as elements.\n\
-Any number of arguments, even zero arguments, are allowed.")
-  (nargs, args)
+  /* Return a newly created list with specified arguments as elements.
+Any number of arguments, even zero arguments, are allowed.  */
+       (nargs, args))
      int nargs;
      register Lisp_Object *args;
 {
@@ -2149,8 +2150,8 @@ Any number of arguments, even zero arguments, are allowed.")
 
 
 DEFUN ("make-list", Fmake_list, Smake_list, 2, 2, 0,
-  "Return a newly created list of length LENGTH, with each element being INIT.")
-  (length, init)
+  /* Return a newly created list of length LENGTH, with each element being INIT.  */
+       (length, init))
      register Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -2336,9 +2337,9 @@ allocate_other_vector (len)
 
 
 DEFUN ("make-vector", Fmake_vector, Smake_vector, 2, 2, 0,
-  "Return a newly created vector of length LENGTH, with each element being INIT.\n\
-See also the function `vector'.")
-  (length, init)
+  /* Return a newly created vector of length LENGTH, with each element being INIT.
+See also the function `vector'.  */
+       (length, init))
      register Lisp_Object length, init;
 {
   Lisp_Object vector;
@@ -2359,11 +2360,11 @@ See also the function `vector'.")
 
 
 DEFUN ("make-char-table", Fmake_char_table, Smake_char_table, 1, 2, 0,
-  "Return a newly created char-table, with purpose PURPOSE.\n\
-Each element is initialized to INIT, which defaults to nil.\n\
-PURPOSE should be a symbol which has a `char-table-extra-slots' property.\n\
-The property's value should be an integer between 0 and 10.")
-  (purpose, init)
+  /* Return a newly created char-table, with purpose PURPOSE.
+Each element is initialized to INIT, which defaults to nil.
+PURPOSE should be a symbol which has a `char-table-extra-slots' property.
+The property's value should be an integer between 0 and 10.  */
+       (purpose, init))
      register Lisp_Object purpose, init;
 {
   Lisp_Object vector;
@@ -2402,9 +2403,9 @@ make_sub_char_table (defalt)
 
 
 DEFUN ("vector", Fvector, Svector, 0, MANY, 0,
-  "Return a newly created vector with specified arguments as elements.\n\
-Any number of arguments, even zero arguments, are allowed.")
-  (nargs, args)
+  /* Return a newly created vector with specified arguments as elements.
+Any number of arguments, even zero arguments, are allowed.  */
+       (nargs, args))
      register int nargs;
      Lisp_Object *args;
 {
@@ -2422,12 +2423,12 @@ Any number of arguments, even zero arguments, are allowed.")
 
 
 DEFUN ("make-byte-code", Fmake_byte_code, Smake_byte_code, 4, MANY, 0,
-  "Create a byte-code object with specified arguments as elements.\n\
-The arguments should be the arglist, bytecode-string, constant vector,\n\
-stack size, (optional) doc string, and (optional) interactive spec.\n\
-The first four arguments are required; at most six have any\n\
-significance.")
-  (nargs, args)
+  /* Create a byte-code object with specified arguments as elements.
+The arguments should be the arglist, bytecode-string, constant vector,
+stack size, (optional) doc string, and (optional) interactive spec.
+The first four arguments are required; at most six have any
+significance.  */
+       (nargs, args))
      register int nargs;
      Lisp_Object *args;
 {
@@ -2510,9 +2511,9 @@ init_symbol ()
 
 
 DEFUN ("make-symbol", Fmake_symbol, Smake_symbol, 1, 1, 0,
-  "Return a newly allocated uninterned symbol whose name is NAME.\n\
-Its value and function definition are void, and its property list is nil.")
-  (name)
+  /* Return a newly allocated uninterned symbol whose name is NAME.
+Its value and function definition are void, and its property list is nil.  */
+       (name))
      Lisp_Object name;
 {
   register Lisp_Object val;
@@ -2628,8 +2629,8 @@ allocate_misc ()
 }
 
 DEFUN ("make-marker", Fmake_marker, Smake_marker, 0, 0, 0,
-  "Return a newly allocated marker which does not point at any place.")
-  ()
+  /* Return a newly allocated marker which does not point at any place.  */
+       ())
 {
   register Lisp_Object val;
   register struct Lisp_Marker *p;
@@ -3299,8 +3300,8 @@ static int max_live, max_zombies;
 static double avg_live;
 
 DEFUN ("gc-status", Fgc_status, Sgc_status, 0, 0, "",
-  "Show information about live and zombie objects.")
-     ()
+       /* Show information about live and zombie objects.  */
+       ())
 {
   Lisp_Object args[7];
   args[0] = build_string ("%d GCs, avg live/zombies = %.2f/%.2f (%f%%), max %d/%d");
@@ -3918,10 +3919,10 @@ make_pure_vector (len)
 
 
 DEFUN ("purecopy", Fpurecopy, Spurecopy, 1, 1, 0,
-  "Make a copy of OBJECT in pure storage.\n\
-Recursively copies contents of vectors and cons cells.\n\
-Does not copy symbols.  Copies strings without text properties.")
-  (obj)
+       /* Make a copy of OBJECT in pure storage.
+Recursively copies contents of vectors and cons cells.
+Does not copy symbols.  Copies strings without text properties.  */
+       (obj))
      register Lisp_Object obj;
 {
   if (NILP (Vpurify_flag))
@@ -4015,15 +4016,15 @@ inhibit_garbage_collection ()
 
 
 DEFUN ("garbage-collect", Fgarbage_collect, Sgarbage_collect, 0, 0, "",
-  "Reclaim storage for Lisp objects no longer needed.\n\
-Returns info on amount of space in use:\n\
- ((USED-CONSES . FREE-CONSES) (USED-SYMS . FREE-SYMS)\n\
-  (USED-MARKERS . FREE-MARKERS) USED-STRING-CHARS USED-VECTOR-SLOTS\n\
-  (USED-FLOATS . FREE-FLOATS) (USED-INTERVALS . FREE-INTERVALS)\n\
-  (USED-STRINGS . FREE-STRINGS))\n\
-Garbage collection happens automatically if you cons more than\n\
-`gc-cons-threshold' bytes of Lisp data since previous garbage collection.")
-  ()
+       /* Reclaim storage for Lisp objects no longer needed.
+Returns info on amount of space in use:
+ ((USED-CONSES . FREE-CONSES) (USED-SYMS . FREE-SYMS)
+  (USED-MARKERS . FREE-MARKERS) USED-STRING-CHARS USED-VECTOR-SLOTS
+  (USED-FLOATS . FREE-FLOATS) (USED-INTERVALS . FREE-INTERVALS)
+  (USED-STRINGS . FREE-STRINGS))
+Garbage collection happens automatically if you cons more than
+`gc-cons-threshold' bytes of Lisp data since previous garbage collection.  */
+       ())
 {
   register struct gcpro *tail;
   register struct specbinding *bind;
@@ -5317,10 +5318,10 @@ gc_sweep ()
 /* Debugging aids.  */
 
 DEFUN ("memory-limit", Fmemory_limit, Smemory_limit, 0, 0, 0,
-  "Return the address of the last byte Emacs has allocated, divided by 1024.\n\
-This may be helpful in debugging Emacs's memory usage.\n\
-We divide the value by 1024 to make sure it fits in a Lisp integer.")
-  ()
+  /* Return the address of the last byte Emacs has allocated, divided by 1024.
+This may be helpful in debugging Emacs's memory usage.
+We divide the value by 1024 to make sure it fits in a Lisp integer.  */
+       ())
 {
   Lisp_Object end;
 
@@ -5330,19 +5331,19 @@ We divide the value by 1024 to make sure it fits in a Lisp integer.")
 }
 
 DEFUN ("memory-use-counts", Fmemory_use_counts, Smemory_use_counts, 0, 0, 0,
-  "Return a list of counters that measure how much consing there has been.\n\
-Each of these counters increments for a certain kind of object.\n\
-The counters wrap around from the largest positive integer to zero.\n\
-Garbage collection does not decrease them.\n\
-The elements of the value are as follows:\n\
-  (CONSES FLOATS VECTOR-CELLS SYMBOLS STRING-CHARS MISCS INTERVALS STRINGS)\n\
-All are in units of 1 = one object consed\n\
-except for VECTOR-CELLS and STRING-CHARS, which count the total length of\n\
-objects consed.\n\
-MISCS include overlays, markers, and some internal types.\n\
-Frames, windows, buffers, and subprocesses count as vectors\n\
-  (but the contents of a buffer's text do not count here).")
-  ()
+  /* Return a list of counters that measure how much consing there has been.
+Each of these counters increments for a certain kind of object.
+The counters wrap around from the largest positive integer to zero.
+Garbage collection does not decrease them.
+The elements of the value are as follows:
+  (CONSES FLOATS VECTOR-CELLS SYMBOLS STRING-CHARS MISCS INTERVALS STRINGS)
+All are in units of 1 = one object consed
+except for VECTOR-CELLS and STRING-CHARS, which count the total length of
+objects consed.
+MISCS include overlays, markers, and some internal types.
+Frames, windows, buffers, and subprocesses count as vectors
+  (but the contents of a buffer's text do not count here).  */
+       ())
 {
   Lisp_Object consed[8];
 
@@ -5435,66 +5436,68 @@ init_alloc ()
 void
 syms_of_alloc ()
 {
-  DEFVAR_INT ("gc-cons-threshold", &gc_cons_threshold,
-    "*Number of bytes of consing between garbage collections.\n\
-Garbage collection can happen automatically once this many bytes have been\n\
-allocated since the last garbage collection.  All data types count.\n\n\
-Garbage collection happens automatically only when `eval' is called.\n\n\
-By binding this temporarily to a large number, you can effectively\n\
-prevent garbage collection during a part of the program.");
+  DEFVAR_INT ("gc-cons-threshold", &gc_cons_threshold
+    /* *Number of bytes of consing between garbage collections.
+Garbage collection can happen automatically once this many bytes have been
+allocated since the last garbage collection.  All data types count.
 
-  DEFVAR_INT ("pure-bytes-used", &pure_bytes_used,
-    "Number of bytes of sharable Lisp data allocated so far.");
+Garbage collection happens automatically only when `eval' is called.
 
-  DEFVAR_INT ("cons-cells-consed", &cons_cells_consed,
-    "Number of cons cells that have been consed so far.");
+By binding this temporarily to a large number, you can effectively
+prevent garbage collection during a part of the program.  */);
 
-  DEFVAR_INT ("floats-consed", &floats_consed,
-    "Number of floats that have been consed so far.");
+  DEFVAR_INT ("pure-bytes-used", &pure_bytes_used
+    /* Number of bytes of sharable Lisp data allocated so far.  */);
 
-  DEFVAR_INT ("vector-cells-consed", &vector_cells_consed,
-    "Number of vector cells that have been consed so far.");
+  DEFVAR_INT ("cons-cells-consed", &cons_cells_consed
+    /* Number of cons cells that have been consed so far.  */);
 
-  DEFVAR_INT ("symbols-consed", &symbols_consed,
-    "Number of symbols that have been consed so far.");
+  DEFVAR_INT ("floats-consed", &floats_consed
+    /* Number of floats that have been consed so far.  */);
 
-  DEFVAR_INT ("string-chars-consed", &string_chars_consed,
-    "Number of string characters that have been consed so far.");
+  DEFVAR_INT ("vector-cells-consed", &vector_cells_consed
+    /* Number of vector cells that have been consed so far.  */);
 
-  DEFVAR_INT ("misc-objects-consed", &misc_objects_consed,
-    "Number of miscellaneous objects that have been consed so far.");
+  DEFVAR_INT ("symbols-consed", &symbols_consed
+    /* Number of symbols that have been consed so far.  */);
 
-  DEFVAR_INT ("intervals-consed", &intervals_consed,
-    "Number of intervals that have been consed so far.");
+  DEFVAR_INT ("string-chars-consed", &string_chars_consed
+    /* Number of string characters that have been consed so far.  */);
 
-  DEFVAR_INT ("strings-consed", &strings_consed,
-    "Number of strings that have been consed so far.");
+  DEFVAR_INT ("misc-objects-consed", &misc_objects_consed
+    /* Number of miscellaneous objects that have been consed so far.  */);
 
-  DEFVAR_LISP ("purify-flag", &Vpurify_flag,
-    "Non-nil means loading Lisp code in order to dump an executable.\n\
-This means that certain objects should be allocated in shared (pure) space.");
+  DEFVAR_INT ("intervals-consed", &intervals_consed
+    /* Number of intervals that have been consed so far.  */);
 
-  DEFVAR_INT ("undo-limit", &undo_limit,
-    "Keep no more undo information once it exceeds this size.\n\
-This limit is applied when garbage collection happens.\n\
-The size is counted as the number of bytes occupied,\n\
-which includes both saved text and other data.");
+  DEFVAR_INT ("strings-consed", &strings_consed
+    /* Number of strings that have been consed so far.  */);
+
+  DEFVAR_LISP ("purify-flag", &Vpurify_flag
+    /* Non-nil means loading Lisp code in order to dump an executable.
+This means that certain objects should be allocated in shared (pure) space.  */);
+
+  DEFVAR_INT ("undo-limit", &undo_limit
+    /* Keep no more undo information once it exceeds this size.
+This limit is applied when garbage collection happens.
+The size is counted as the number of bytes occupied,
+which includes both saved text and other data.  */);
   undo_limit = 20000;
 
-  DEFVAR_INT ("undo-strong-limit", &undo_strong_limit,
-    "Don't keep more than this much size of undo information.\n\
-A command which pushes past this size is itself forgotten.\n\
-This limit is applied when garbage collection happens.\n\
-The size is counted as the number of bytes occupied,\n\
-which includes both saved text and other data.");
+  DEFVAR_INT ("undo-strong-limit", &undo_strong_limit
+    /* Don't keep more than this much size of undo information.
+A command which pushes past this size is itself forgotten.
+This limit is applied when garbage collection happens.
+The size is counted as the number of bytes occupied,
+which includes both saved text and other data.  */);
   undo_strong_limit = 30000;
 
-  DEFVAR_BOOL ("garbage-collection-messages", &garbage_collection_messages,
-    "Non-nil means display messages at start and end of garbage collection.");
+  DEFVAR_BOOL ("garbage-collection-messages", &garbage_collection_messages
+    /* Non-nil means display messages at start and end of garbage collection.  */);
   garbage_collection_messages = 0;
 
-  DEFVAR_LISP ("post-gc-hook", &Vpost_gc_hook,
-    "Hook run after garbage collection has finished.");
+  DEFVAR_LISP ("post-gc-hook", &Vpost_gc_hook
+    /* Hook run after garbage collection has finished.  */);
   Vpost_gc_hook = Qnil;
   Qpost_gc_hook = intern ("post-gc-hook");
   staticpro (&Qpost_gc_hook);
diff --git a/src/dispnew.c b/src/dispnew.c
index 0b91c69854c..191b437406e 100644
--- a/src/dispnew.c
+++ b/src/dispnew.c
@@ -19,6 +19,8 @@ along with GNU Emacs; see the file COPYING.  If not, write to
 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
+#define DOC_STRINGS_IN_COMMENTS
+
 #include <config.h>
 #include <signal.h>
 #include <stdio.h>
@@ -410,8 +412,8 @@ add_frame_display_history (f, paused_p)
 
 DEFUN ("dump-redisplay-history", Fdump_redisplay_history,
        Sdump_redisplay_history, 0, 0, "",
-   "Dump redisplay history to stderr.")
-     ()
+       /* Dump redisplay history to stderr.  */
+       ())
 {
   int i;
 
@@ -3305,8 +3307,8 @@ window_to_frame_hpos (w, hpos)
  **********************************************************************/
 
 DEFUN ("redraw-frame", Fredraw_frame, Sredraw_frame, 1, 1, 0,
-  "Clear frame FRAME and output again what is supposed to appear on it.")
-  (frame)
+       /* Clear frame FRAME and output again what is supposed to appear on it.  */
+       (frame))
      Lisp_Object frame;
 {
   struct frame *f;
@@ -3351,8 +3353,8 @@ redraw_frame (f)
 
 
 DEFUN ("redraw-display", Fredraw_display, Sredraw_display, 0, 0, "",
-  "Clear and redisplay all visible frames.")
-  ()
+       /* Clear and redisplay all visible frames.  */
+       ())
 {
   Lisp_Object tail, frame;
 
@@ -6040,10 +6042,10 @@ change_frame_size_1 (f, newheight, newwidth, pretend, delay, safe)
  ***********************************************************************/
 
 DEFUN ("open-termscript", Fopen_termscript, Sopen_termscript,
-  1, 1, "FOpen termscript file: ",
-  "Start writing all terminal output to FILE as well as the terminal.\n\
-FILE = nil means just close any termscript file currently open.")
-  (file)
+       1, 1, "FOpen termscript file: ",
+       /* Start writing all terminal output to FILE as well as the terminal.
+FILE = nil means just close any termscript file currently open.  */
+       (file))
      Lisp_Object file;
 {
   if (termscript != 0) fclose (termscript);
@@ -6061,10 +6063,10 @@ FILE = nil means just close any termscript file currently open.")
 
 
 DEFUN ("send-string-to-terminal", Fsend_string_to_terminal,
-  Ssend_string_to_terminal, 1, 1, 0,
-  "Send STRING to the terminal without alteration.\n\
-Control characters in STRING will have terminal-dependent effects.")
-  (string)
+       Ssend_string_to_terminal, 1, 1, 0,
+       /* Send STRING to the terminal without alteration.
+Control characters in STRING will have terminal-dependent effects.  */
+       (string))
      Lisp_Object string;
 {
   /* ??? Perhaps we should do something special for multibyte strings here.  */
@@ -6082,10 +6084,10 @@ Control characters in STRING will have terminal-dependent effects.")
 
 
 DEFUN ("ding", Fding, Sding, 0, 1, 0,
-  "Beep, or flash the screen.\n\
-Also, unless an argument is given,\n\
-terminate any keyboard macro currently executing.")
-  (arg)
+       /* Beep, or flash the screen.
+Also, unless an argument is given,
+terminate any keyboard macro currently executing.  */
+       (arg))
   Lisp_Object arg;
 {
   if (!NILP (arg))
@@ -6121,13 +6123,13 @@ bitch_at_user ()
  ***********************************************************************/
 
 DEFUN ("sleep-for", Fsleep_for, Ssleep_for, 1, 2, 0,
-  "Pause, without updating display, for SECONDS seconds.\n\
-SECONDS may be a floating-point value, meaning that you can wait for a\n\
-fraction of a second.  Optional second arg MILLISECONDS specifies an\n\
-additional wait period, in milliseconds; this may be useful if your\n\
-Emacs was built without floating point support.\n\
-\(Not all operating systems support waiting for a fraction of a second.)")
-  (seconds, milliseconds)
+       /* Pause, without updating display, for SECONDS seconds.
+SECONDS may be a floating-point value, meaning that you can wait for a
+fraction of a second.  Optional second arg MILLISECONDS specifies an
+additional wait period, in milliseconds; this may be useful if your
+Emacs was built without floating point support.
+\(Not all operating systems support waiting for a fraction of a second.  */
+       (seconds, milliseconds))
      Lisp_Object seconds, milliseconds;
 {
   int sec, usec;
@@ -6244,17 +6246,17 @@ sit_for (sec, usec, reading, display, initial_display)
 
 
 DEFUN ("sit-for", Fsit_for, Ssit_for, 1, 3, 0,
-  "Perform redisplay, then wait for SECONDS seconds or until input is available.\n\
-SECONDS may be a floating-point value, meaning that you can wait for a\n\
-fraction of a second.  Optional second arg MILLISECONDS specifies an\n\
-additional wait period, in milliseconds; this may be useful if your\n\
-Emacs was built without floating point support.\n\
-\(Not all operating systems support waiting for a fraction of a second.)\n\
-Optional third arg NODISP non-nil means don't redisplay, just wait for input.\n\
-Redisplay is preempted as always if input arrives, and does not happen\n\
-if input is available before it starts.\n\
-Value is t if waited the full time with no input arriving.")
-  (seconds, milliseconds, nodisp)
+  /* Perform redisplay, then wait for SECONDS seconds or until input is available.
+SECONDS may be a floating-point value, meaning that you can wait for a
+fraction of a second.  Optional second arg MILLISECONDS specifies an
+additional wait period, in milliseconds; this may be useful if your
+Emacs was built without floating point support.
+\(Not all operating systems support waiting for a fraction of a second.)
+Optional third arg NODISP non-nil means don't redisplay, just wait for input.
+Redisplay is preempted as always if input arrives, and does not happen
+if input is available before it starts.
+Value is t if waited the full time with no input arriving.  */
+       (seconds, milliseconds, nodisp))
      Lisp_Object seconds, milliseconds, nodisp;
 {
   int sec, usec;
@@ -6294,15 +6296,15 @@ static Lisp_Object frame_and_buffer_state;
 
 
 DEFUN ("frame-or-buffer-changed-p", Fframe_or_buffer_changed_p,
-  Sframe_or_buffer_changed_p, 0, 0, 0,
-  "Return non-nil if the frame and buffer state appears to have changed.\n\
-The state variable is an internal vector containing all frames and buffers,\n\
-aside from buffers whose names start with space,\n\
-along with the buffers' read-only and modified flags, which allows a fast\n\
-check to see whether the menu bars might need to be recomputed.\n\
-If this function returns non-nil, it updates the internal vector to reflect\n\
-the current state.\n")
-  ()
+       Sframe_or_buffer_changed_p, 0, 0, 0,
+  /* Return non-nil if the frame and buffer state appears to have changed.
+The state variable is an internal vector containing all frames and buffers,
+aside from buffers whose names start with space,
+along with the buffers' read-only and modified flags, which allows a fast
+check to see whether the menu bars might need to be recomputed.
+If this function returns non-nil, it updates the internal vector to reflect
+the current state.  */
+       ())
 {
   Lisp_Object tail, frame, buf;
   Lisp_Object *vecp;
@@ -6567,11 +6569,11 @@ For types not defined in VMS, use  define emacs_term \"TYPE\".\n\
 
 DEFUN ("internal-show-cursor", Finternal_show_cursor,
        Sinternal_show_cursor, 2, 2, 0,
-  "Set the cursor-visibility flag of WINDOW to SHOW.\n\
-WINDOW nil means use the selected window.  SHOW non-nil means\n\
-show a cursor in WINDOW in the next redisplay.  SHOW nil means\n\
-don't show a cursor.")
-  (window, show)
+       /* Set the cursor-visibility flag of WINDOW to SHOW.
+WINDOW nil means use the selected window.  SHOW non-nil means
+show a cursor in WINDOW in the next redisplay.  SHOW nil means
+don't show a cursor.  */
+       (window, show))
      Lisp_Object window, show;
 {
   /* Don't change cursor state while redisplaying.  This could confuse
@@ -6592,9 +6594,9 @@ don't show a cursor.")
 
 DEFUN ("internal-show-cursor-p", Finternal_show_cursor_p,
        Sinternal_show_cursor_p, 0, 1, 0,
-  "Value is non-nil if next redisplay will display a cursor in WINDOW.\n\
-WINDOW nil or omitted means report on the selected window.")
-  (window)
+   /* Value is non-nil if next redisplay will display a cursor in WINDOW.
+WINDOW nil or omitted means report on the selected window.  */
+       (window))
      Lisp_Object window;
 {
   struct window *w;
@@ -6639,53 +6641,53 @@ syms_of_display ()
   Qredisplay_dont_pause = intern ("redisplay-dont-pause");
   staticpro (&Qredisplay_dont_pause);
 
-  DEFVAR_INT ("baud-rate", &baud_rate,
-    "*The output baud rate of the terminal.\n\
-On most systems, changing this value will affect the amount of padding\n\
-and the other strategic decisions made during redisplay.");
+  DEFVAR_INT ("baud-rate", &baud_rate
+    /* *The output baud rate of the terminal.
+On most systems, changing this value will affect the amount of padding
+and the other strategic decisions made during redisplay.  */);
   
-  DEFVAR_BOOL ("inverse-video", &inverse_video,
-    "*Non-nil means invert the entire frame display.\n\
-This means everything is in inverse video which otherwise would not be.");
+  DEFVAR_BOOL ("inverse-video", &inverse_video
+    /* *Non-nil means invert the entire frame display.
+This means everything is in inverse video which otherwise would not be.  */);
   
-  DEFVAR_BOOL ("visible-bell", &visible_bell,
-    "*Non-nil means try to flash the frame to represent a bell.");
+  DEFVAR_BOOL ("visible-bell", &visible_bell
+    /* *Non-nil means try to flash the frame to represent a bell.  */);
   
-  DEFVAR_BOOL ("no-redraw-on-reenter", &no_redraw_on_reenter,
-    "*Non-nil means no need to redraw entire frame after suspending.\n\
-A non-nil value is useful if the terminal can automatically preserve\n\
-Emacs's frame display when you reenter Emacs.\n\
-It is up to you to set this variable if your terminal can do that.");
+  DEFVAR_BOOL ("no-redraw-on-reenter", &no_redraw_on_reenter
+    /* *Non-nil means no need to redraw entire frame after suspending.
+A non-nil value is useful if the terminal can automatically preserve
+Emacs's frame display when you reenter Emacs.
+It is up to you to set this variable if your terminal can do that.  */);
   
-  DEFVAR_LISP ("window-system", &Vwindow_system,
-    "A symbol naming the window-system under which Emacs is running\n\
-\(such as `x'), or nil if emacs is running on an ordinary terminal.");
+  DEFVAR_LISP ("window-system", &Vwindow_system
+    /* A symbol naming the window-system under which Emacs is running
+\(such as `x'), or nil if emacs is running on an ordinary terminal.  */);
   
-  DEFVAR_LISP ("window-system-version", &Vwindow_system_version,
-    "The version number of the window system in use.\n\
-For X windows, this is 10 or 11.");
+  DEFVAR_LISP ("window-system-version", &Vwindow_system_version
+    /* The version number of the window system in use.
+For X windows, this is 10 or 11.  */);
   
-  DEFVAR_BOOL ("cursor-in-echo-area", &cursor_in_echo_area,
-    "Non-nil means put cursor in minibuffer, at end of any message there.");
+  DEFVAR_BOOL ("cursor-in-echo-area", &cursor_in_echo_area
+    /* Non-nil means put cursor in minibuffer, at end of any message there.  */);
   
-  DEFVAR_LISP ("glyph-table", &Vglyph_table,
-    "Table defining how to output a glyph code to the frame.\n\
-If not nil, this is a vector indexed by glyph code to define the glyph.\n\
-Each element can be:\n\
- integer: a glyph code which this glyph is an alias for.\n\
- string: output this glyph using that string (not impl. in X windows).\n\
- nil: this glyph mod 524288 is the code of a character to output,\n\
-    and this glyph / 524288 is the face number (see `face-id') to use\n\
-    while outputting it.");
+  DEFVAR_LISP ("glyph-table", &Vglyph_table
+    /* Table defining how to output a glyph code to the frame.
+If not nil, this is a vector indexed by glyph code to define the glyph.
+Each element can be:
+ integer: a glyph code which this glyph is an alias for.
+ string: output this glyph using that string (not impl. in X windows).
+ nil: this glyph mod 524288 is the code of a character to output,
+    and this glyph / 524288 is the face number (see `face-id') to use
+    while outputting it.  */);
   Vglyph_table = Qnil;
 
-  DEFVAR_LISP ("standard-display-table", &Vstandard_display_table,
-    "Display table to use for buffers that specify none.\n\
-See `buffer-display-table' for more information.");
+  DEFVAR_LISP ("standard-display-table", &Vstandard_display_table
+    /* Display table to use for buffers that specify none.
+See `buffer-display-table' for more information.  */);
   Vstandard_display_table = Qnil;
 
-  DEFVAR_BOOL ("redisplay-dont-pause", &redisplay_dont_pause,
-    "*Non-nil means update isn't paused when input is detected.");
+  DEFVAR_BOOL ("redisplay-dont-pause", &redisplay_dont_pause
+    /* *Non-nil means update isn't paused when input is detected.  */);
   redisplay_dont_pause = 0;
 
   /* Initialize `window-system', unless init_display already decided it.  */
diff --git a/src/term.c b/src/term.c
index 9f281db0182..1ef1f2da929 100644
--- a/src/term.c
+++ b/src/term.c
@@ -27,6 +27,7 @@ Boston, MA 02111-1307, USA.  */
 #include <string.h>
 #include "termchar.h"
 #include "termopts.h"
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "charset.h"
 #include "coding.h"
@@ -2175,8 +2176,8 @@ turn_off_face (f, face_id)
 
 DEFUN ("tty-display-color-p", Ftty_display_color_p, Stty_display_color_p,
        0, 1, 0,
-  "Return non-nil if TTY can display colors on FRAME.")
-     (frame)
+       /* Return non-nil if TTY can display colors on FRAME.  */
+       (frame))
      Lisp_Object frame;
 {
   return TN_max_colors > 0 ? Qt : Qnil;
@@ -2607,18 +2608,18 @@ fatal (str, arg1, arg2)
 void
 syms_of_term ()
 {
-  DEFVAR_BOOL ("system-uses-terminfo", &system_uses_terminfo,
-    "Non-nil means the system uses terminfo rather than termcap.\n\
-This variable can be used by terminal emulator packages.");
+  DEFVAR_BOOL ("system-uses-terminfo", &system_uses_terminfo
+    /* Non-nil means the system uses terminfo rather than termcap.
+This variable can be used by terminal emulator packages.  */);
 #ifdef TERMINFO
   system_uses_terminfo = 1;
 #else
   system_uses_terminfo = 0;
 #endif
 
-  DEFVAR_LISP ("ring-bell-function", &Vring_bell_function,
-    "Non-nil means call this function to ring the bell.\n\
-The function should accept no arguments.");
+  DEFVAR_LISP ("ring-bell-function", &Vring_bell_function
+    /* Non-nil means call this function to ring the bell.
+The function should accept no arguments.  */);
   Vring_bell_function = Qnil;
 
   defsubr (&Stty_display_color_p);
diff --git a/src/xdisp.c b/src/xdisp.c
index 7c75ea2bc02..26de5ac5f33 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -169,6 +169,7 @@ Boston, MA 02111-1307, USA.  */
 
 #include <config.h>
 #include <stdio.h>
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "keyboard.h"
 #include "frame.h"
@@ -7793,8 +7794,8 @@ tool_bar_lines_needed (f)
 
 DEFUN ("tool-bar-lines-needed", Ftool_bar_lines_needed, Stool_bar_lines_needed,
        0, 1, 0,
-  "Return the number of lines occupied by the tool bar of FRAME.")
-  (frame)
+       /* Return the number of lines occupied by the tool bar of FRAME.  */
+       (frame))
      Lisp_Object frame;
 {
   struct frame *f;
@@ -12162,11 +12163,11 @@ dump_glyph_row (row, vpos, glyphs)
 
 DEFUN ("dump-glyph-matrix", Fdump_glyph_matrix,
        Sdump_glyph_matrix, 0, 1, "p",
-  "Dump the current matrix of the selected window to stderr.\n\
-Shows contents of glyph row structures.  With non-nil\n\
-parameter GLYPHS, dump glyphs as well.  If GLYPHS is 1 show\n\
-glyphs in short form, otherwise show glyphs in long form.")
-  (glyphs)
+       /* Dump the current matrix of the selected window to stderr.
+Shows contents of glyph row structures.  With non-nil
+parameter GLYPHS, dump glyphs as well.  If GLYPHS is 1 show
+glyphs in short form, otherwise show glyphs in long form.  */
+       (glyphs))
      Lisp_Object glyphs;
 {
   struct window *w = XWINDOW (selected_window);
@@ -12184,11 +12185,11 @@ glyphs in short form, otherwise show glyphs in long form.")
 
 
 DEFUN ("dump-glyph-row", Fdump_glyph_row, Sdump_glyph_row, 1, 2, "",
-  "Dump glyph row ROW to stderr.\n\
-GLYPH 0 means don't dump glyphs.\n\
-GLYPH 1 means dump glyphs in short form.\n\
-GLYPH > 1 or omitted means dump glyphs in long form.")
-  (row, glyphs)
+       /* Dump glyph row ROW to stderr.
+GLYPH 0 means don't dump glyphs.
+GLYPH 1 means dump glyphs in short form.
+GLYPH > 1 or omitted means dump glyphs in long form.  */
+       (row, glyphs))
      Lisp_Object row, glyphs;
 {
   struct glyph_matrix *matrix;
@@ -12206,11 +12207,11 @@ GLYPH > 1 or omitted means dump glyphs in long form.")
 
 
 DEFUN ("dump-tool-bar-row", Fdump_tool_bar_row, Sdump_tool_bar_row, 1, 2, "",
-  "Dump glyph row ROW of the tool-bar of the current frame to stderr.\n\
-GLYPH 0 means don't dump glyphs.\n\
-GLYPH 1 means dump glyphs in short form.\n\
-GLYPH > 1 or omitted means dump glyphs in long form.")
-  (row, glyphs)
+  /* Dump glyph row ROW of the tool-bar of the current frame to stderr.
+GLYPH 0 means don't dump glyphs.
+GLYPH 1 means dump glyphs in short form.
+GLYPH > 1 or omitted means dump glyphs in long form.  */
+       (row, glyphs))
      Lisp_Object row, glyphs;
 {
   struct frame *sf = SELECTED_FRAME ();
@@ -12227,9 +12228,9 @@ GLYPH > 1 or omitted means dump glyphs in long form.")
 
 
 DEFUN ("trace-redisplay", Ftrace_redisplay, Strace_redisplay, 0, 1, "P",
-  "Toggle tracing of redisplay.\n\
-With ARG, turn tracing on if and only if ARG is positive.")
-  (arg)
+       /* Toggle tracing of redisplay.
+With ARG, turn tracing on if and only if ARG is positive.  */
+       (arg))
      Lisp_Object arg;
 {
   if (NILP (arg))
@@ -12245,8 +12246,8 @@ With ARG, turn tracing on if and only if ARG is positive.")
 
 
 DEFUN ("trace-to-stderr", Ftrace_to_stderr, Strace_to_stderr, 1, MANY, "",
-   "Like `format', but print result to stderr.")
-   (nargs, args)
+       /* Like `format', but print result to stderr.  */
+       (nargs, args))
      int nargs;
      Lisp_Object *args;
 {
@@ -14703,101 +14704,101 @@ syms_of_xdisp ()
   Vmessages_buffer_name = build_string ("*Messages*");
   staticpro (&Vmessages_buffer_name);
   
-  DEFVAR_LISP ("show-trailing-whitespace", &Vshow_trailing_whitespace,
-    "Non-nil means highlight trailing whitespace.\n\
-The face used for trailing whitespace is `trailing-whitespace'.");
+  DEFVAR_LISP ("show-trailing-whitespace", &Vshow_trailing_whitespace
+    /* Non-nil means highlight trailing whitespace.
+The face used for trailing whitespace is `trailing-whitespace'.  */);
   Vshow_trailing_whitespace = Qnil;
 
-  DEFVAR_LISP ("inhibit-redisplay", &Vinhibit_redisplay,
-    "Non-nil means don't actually do any redisplay.\n\
-This is used for internal purposes.");
+  DEFVAR_LISP ("inhibit-redisplay", &Vinhibit_redisplay
+    /* Non-nil means don't actually do any redisplay.
+This is used for internal purposes.  */);
   Vinhibit_redisplay = Qnil;
 
-  DEFVAR_LISP ("global-mode-string", &Vglobal_mode_string,
-    "String (or mode line construct) included (normally) in `mode-line-format'.");
+  DEFVAR_LISP ("global-mode-string", &Vglobal_mode_string
+    /* String (or mode line construct) included (normally) in `mode-line-format'.  */);
   Vglobal_mode_string = Qnil;
 
-  DEFVAR_LISP ("overlay-arrow-position", &Voverlay_arrow_position,
-    "Marker for where to display an arrow on top of the buffer text.\n\
-This must be the beginning of a line in order to work.\n\
-See also `overlay-arrow-string'.");
+  DEFVAR_LISP ("overlay-arrow-position", &Voverlay_arrow_position
+    /* Marker for where to display an arrow on top of the buffer text.
+This must be the beginning of a line in order to work.
+See also `overlay-arrow-string'.  */);
   Voverlay_arrow_position = Qnil;
 
-  DEFVAR_LISP ("overlay-arrow-string", &Voverlay_arrow_string,
-    "String to display as an arrow.  See also `overlay-arrow-position'.");
+  DEFVAR_LISP ("overlay-arrow-string", &Voverlay_arrow_string
+    /* String to display as an arrow.  See also `overlay-arrow-position'.  */);
   Voverlay_arrow_string = Qnil;
 
-  DEFVAR_INT ("scroll-step", &scroll_step,
-    "*The number of lines to try scrolling a window by when point moves out.\n\
-If that fails to bring point back on frame, point is centered instead.\n\
-If this is zero, point is always centered after it moves off frame.\n\
-If you want scrolling to always be a line at a time, you should set\n\
-  `scroll-conservatively' to a large value rather than set this to 1.");
-
-  DEFVAR_INT ("scroll-conservatively", &scroll_conservatively,
-    "*Scroll up to this many lines, to bring point back on screen.\n\
-A value of zero means to scroll the text to center point vertically\n\
-in the window.");
+  DEFVAR_INT ("scroll-step", &scroll_step
+    /* *The number of lines to try scrolling a window by when point moves out.
+If that fails to bring point back on frame, point is centered instead.
+If this is zero, point is always centered after it moves off frame.
+If you want scrolling to always be a line at a time, you should set
+`scroll-conservatively' to a large value rather than set this to 1.  */);
+
+  DEFVAR_INT ("scroll-conservatively", &scroll_conservatively
+    /* *Scroll up to this many lines, to bring point back on screen.
+A value of zero means to scroll the text to center point vertically
+in the window.  */);
   scroll_conservatively = 0;
 
-  DEFVAR_INT ("scroll-margin", &scroll_margin,
-    "*Number of lines of margin at the top and bottom of a window.\n\
-Recenter the window whenever point gets within this many lines\n\
-of the top or bottom of the window.");
+  DEFVAR_INT ("scroll-margin", &scroll_margin
+    /* *Number of lines of margin at the top and bottom of a window.
+Recenter the window whenever point gets within this many lines
+of the top or bottom of the window.  */);
   scroll_margin = 0;
 
 #if GLYPH_DEBUG
-  DEFVAR_INT ("debug-end-pos", &debug_end_pos, "Don't ask");
+  DEFVAR_INT ("debug-end-pos", &debug_end_pos /* Don't ask.  */);
 #endif
 
   DEFVAR_BOOL ("truncate-partial-width-windows",
-               &truncate_partial_width_windows,
-    "*Non-nil means truncate lines in all windows less than full frame wide.");
+               &truncate_partial_width_windows
+    /* *Non-nil means truncate lines in all windows less than full frame wide.  */);
   truncate_partial_width_windows = 1;
 
-  DEFVAR_BOOL ("mode-line-inverse-video", &mode_line_inverse_video,
-    "nil means display the mode-line/header-line/menu-bar in the default face.\n\
-Any other value means to use the appropriate face, `mode-line',\n\
-`header-line', or `menu' respectively.\n\
-\n\
-This variable is deprecated; please change the above faces instead.");
+  DEFVAR_BOOL ("mode-line-inverse-video", &mode_line_inverse_video
+    /* nil means display the mode-line/header-line/menu-bar in the default face.
+Any other value means to use the appropriate face, `mode-line',
+`header-line', or `menu' respectively.
+
+This variable is deprecated; please change the above faces instead.  */);
   mode_line_inverse_video = 1;
 
-  DEFVAR_LISP ("line-number-display-limit", &Vline_number_display_limit,
-    "*Maximum buffer size for which line number should be displayed.\n\
-If the buffer is bigger than this, the line number does not appear\n\
-in the mode line.  A value of nil means no limit.");
+  DEFVAR_LISP ("line-number-display-limit", &Vline_number_display_limit
+    /* *Maximum buffer size for which line number should be displayed.
+If the buffer is bigger than this, the line number does not appear
+in the mode line.  A value of nil means no limit.  */);
   Vline_number_display_limit = Qnil;
 
   DEFVAR_INT ("line-number-display-limit-width",
-              &line_number_display_limit_width,
-    "*Maximum line width (in characters) for line number display.\n\
-If the average length of the lines near point is bigger than this, then the\n\
-line number may be omitted from the mode line.");
+              &line_number_display_limit_width
+    /* *Maximum line width (in characters) for line number display.
+If the average length of the lines near point is bigger than this, then the
+line number may be omitted from the mode line.  */);
   line_number_display_limit_width = 200;
 
-  DEFVAR_BOOL ("highlight-nonselected-windows", &highlight_nonselected_windows,
-    "*Non-nil means highlight region even in nonselected windows.");
+  DEFVAR_BOOL ("highlight-nonselected-windows", &highlight_nonselected_windows
+    /* *Non-nil means highlight region even in nonselected windows.  */);
   highlight_nonselected_windows = 0;
 
-  DEFVAR_BOOL ("multiple-frames", &multiple_frames,
-    "Non-nil if more than one frame is visible on this display.\n\
-Minibuffer-only frames don't count, but iconified frames do.\n\
-This variable is not guaranteed to be accurate except while processing\n\
-`frame-title-format' and `icon-title-format'.");
-
-  DEFVAR_LISP ("frame-title-format", &Vframe_title_format,
-    "Template for displaying the title bar of visible frames.\n\
-\(Assuming the window manager supports this feature.)\n\
-This variable has the same structure as `mode-line-format' (which see),\n\
-and is used only on frames for which no explicit name has been set\n\
-\(see `modify-frame-parameters').");
-  DEFVAR_LISP ("icon-title-format", &Vicon_title_format,
-    "Template for displaying the title bar of an iconified frame.\n\
-\(Assuming the window manager supports this feature.)\n\
-This variable has the same structure as `mode-line-format' (which see),\n\
-and is used only on frames for which no explicit name has been set\n\
-\(see `modify-frame-parameters').");
+  DEFVAR_BOOL ("multiple-frames", &multiple_frames
+    /* Non-nil if more than one frame is visible on this display.
+Minibuffer-only frames don't count, but iconified frames do.
+This variable is not guaranteed to be accurate except while processing
+`frame-title-format' and `icon-title-format'.  */);
+
+  DEFVAR_LISP ("frame-title-format", &Vframe_title_format
+    /* Template for displaying the title bar of visible frames.
+\(Assuming the window manager supports this feature.)
+This variable has the same structure as `mode-line-format' (which see),
+and is used only on frames for which no explicit name has been set
+\(see `modify-frame-parameters').  */);
+  DEFVAR_LISP ("icon-title-format", &Vicon_title_format
+    /* Template for displaying the title bar of an iconified frame.
+\(Assuming the window manager supports this feature.)
+This variable has the same structure as `mode-line-format' (which see),
+and is used only on frames for which no explicit name has been set
+\(see `modify-frame-parameters').  */);
   Vicon_title_format
     = Vframe_title_format
     = Fcons (intern ("multiple-frames"),
@@ -14809,113 +14810,113 @@ and is used only on frames for which no explicit name has been set\n\
                                                                Qnil)))),
                            Qnil)));
 
-  DEFVAR_LISP ("message-log-max", &Vmessage_log_max,
-    "Maximum number of lines to keep in the message log buffer.\n\
-If nil, disable message logging.  If t, log messages but don't truncate\n\
-the buffer when it becomes large.");
+  DEFVAR_LISP ("message-log-max", &Vmessage_log_max
+    /* Maximum number of lines to keep in the message log buffer.
+If nil, disable message logging.  If t, log messages but don't truncate
+the buffer when it becomes large.  */);
   Vmessage_log_max = make_number (50);
 
-  DEFVAR_LISP ("window-size-change-functions", &Vwindow_size_change_functions,
-    "Functions called before redisplay, if window sizes have changed.\n\
-The value should be a list of functions that take one argument.\n\
-Just before redisplay, for each frame, if any of its windows have changed\n\
-size since the last redisplay, or have been split or deleted,\n\
-all the functions in the list are called, with the frame as argument.");
+  DEFVAR_LISP ("window-size-change-functions", &Vwindow_size_change_functions
+    /* Functions called before redisplay, if window sizes have changed.
+The value should be a list of functions that take one argument.
+Just before redisplay, for each frame, if any of its windows have changed
+size since the last redisplay, or have been split or deleted,
+all the functions in the list are called, with the frame as argument.  */);
   Vwindow_size_change_functions = Qnil;
 
-  DEFVAR_LISP ("window-scroll-functions", &Vwindow_scroll_functions,
-    "List of Functions to call before redisplaying a window with scrolling.\n\
-Each function is called with two arguments, the window\n\
-and its new display-start position.  Note that the value of `window-end'\n\
-is not valid when these functions are called.");
+  DEFVAR_LISP ("window-scroll-functions", &Vwindow_scroll_functions
+    /* List of Functions to call before redisplaying a window with scrolling.
+Each function is called with two arguments, the window
+and its new display-start position.  Note that the value of `window-end'
+is not valid when these functions are called.  */);
   Vwindow_scroll_functions = Qnil;
   
-  DEFVAR_BOOL ("auto-resize-tool-bars", &auto_resize_tool_bars_p,
-    "*Non-nil means automatically resize tool-bars.\n\
-This increases a tool-bar's height if not all tool-bar items are visible.\n\
-It decreases a tool-bar's height when it would display blank lines\n\
-otherwise.");
+  DEFVAR_BOOL ("auto-resize-tool-bars", &auto_resize_tool_bars_p
+    /* *Non-nil means automatically resize tool-bars.
+This increases a tool-bar's height if not all tool-bar items are visible.
+It decreases a tool-bar's height when it would display blank lines
+otherwise.  */);
   auto_resize_tool_bars_p = 1;
   
-  DEFVAR_BOOL ("auto-raise-tool-bar-buttons", &auto_raise_tool_bar_buttons_p,
-    "*Non-nil means raise tool-bar buttons when the mouse moves over them.");
+  DEFVAR_BOOL ("auto-raise-tool-bar-buttons", &auto_raise_tool_bar_buttons_p
+    /* *Non-nil means raise tool-bar buttons when the mouse moves over them.  */);
   auto_raise_tool_bar_buttons_p = 1;
 
-  DEFVAR_LISP ("tool-bar-button-margin", &Vtool_bar_button_margin,
-    "*Margin around tool-bar buttons in pixels.\n\
-If an integer, use that for both horizontal and vertical margins.\n\
-Otherwise, value should be a pair of integers `(HORZ : VERT)' with\n\
-HORZ specifying the horizontal margin, and VERT specifying the\n\
-vertical margin.");
+  DEFVAR_LISP ("tool-bar-button-margin", &Vtool_bar_button_margin
+    /* *Margin around tool-bar buttons in pixels.
+If an integer, use that for both horizontal and vertical margins.
+Otherwise, value should be a pair of integers `(HORZ : VERT)' with
+HORZ specifying the horizontal margin, and VERT specifying the
+vertical margin.  */);
   Vtool_bar_button_margin = make_number (DEFAULT_TOOL_BAR_BUTTON_MARGIN);
 
-  DEFVAR_INT ("tool-bar-button-relief", &tool_bar_button_relief,
-    "Relief thickness of tool-bar buttons.");
+  DEFVAR_INT ("tool-bar-button-relief", &tool_bar_button_relief
+    /* Relief thickness of tool-bar buttons.  */);
   tool_bar_button_relief = DEFAULT_TOOL_BAR_BUTTON_RELIEF;
 
-  DEFVAR_LISP ("fontification-functions", &Vfontification_functions,
-    "List of functions to call to fontify regions of text.\n\
-Each function is called with one argument POS.  Functions must\n\
-fontify a region starting at POS in the current buffer, and give\n\
-fontified regions the property `fontified'.");
+  DEFVAR_LISP ("fontification-functions", &Vfontification_functions
+    /* List of functions to call to fontify regions of text.
+Each function is called with one argument POS.  Functions must
+fontify a region starting at POS in the current buffer, and give
+fontified regions the property `fontified'.  */);
   Vfontification_functions = Qnil;
   Fmake_variable_buffer_local (Qfontification_functions);
 
   DEFVAR_BOOL ("unibyte-display-via-language-environment",
-               &unibyte_display_via_language_environment,
-    "*Non-nil means display unibyte text according to language environment.\n\
-Specifically this means that unibyte non-ASCII characters\n\
-are displayed by converting them to the equivalent multibyte characters\n\
-according to the current language environment.  As a result, they are\n\
-displayed according to the current fontset.");
+               &unibyte_display_via_language_environment
+    /* *Non-nil means display unibyte text according to language environment.
+Specifically this means that unibyte non-ASCII characters
+are displayed by converting them to the equivalent multibyte characters
+according to the current language environment.  As a result, they are
+displayed according to the current fontset.  */);
   unibyte_display_via_language_environment = 0;
 
-  DEFVAR_LISP ("max-mini-window-height", &Vmax_mini_window_height,
-    "*Maximum height for resizing mini-windows.\n\
-If a float, it specifies a fraction of the mini-window frame's height.\n\
-If an integer, it specifies a number of lines.");
+  DEFVAR_LISP ("max-mini-window-height", &Vmax_mini_window_height
+    /* *Maximum height for resizing mini-windows.
+If a float, it specifies a fraction of the mini-window frame's height.
+If an integer, it specifies a number of lines.  */);
   Vmax_mini_window_height = make_float (0.25);
 
-  DEFVAR_LISP ("resize-mini-windows", &Vresize_mini_windows,
-    "*How to resize mini-windows.\n\
-A value of nil means don't automatically resize mini-windows.\n\
-A value of t means resize them to fit the text displayed in them.\n\
-A value of `grow-only', the default, means let mini-windows grow\n\
-only, until their display becomes empty, at which point the windows\n\
-go back to their normal size.");
+  DEFVAR_LISP ("resize-mini-windows", &Vresize_mini_windows
+    /* *How to resize mini-windows.
+A value of nil means don't automatically resize mini-windows.
+A value of t means resize them to fit the text displayed in them.
+A value of `grow-only', the default, means let mini-windows grow
+only, until their display becomes empty, at which point the windows
+go back to their normal size.  */);
   Vresize_mini_windows = Qgrow_only;
 
   DEFVAR_BOOL ("cursor-in-non-selected-windows",
-               &cursor_in_non_selected_windows,
-    "*Non-nil means display a hollow cursor in non-selected windows.\n\
-Nil means don't display a cursor there.");
+               &cursor_in_non_selected_windows
+    /* *Non-nil means display a hollow cursor in non-selected windows.
+Nil means don't display a cursor there.  */);
   cursor_in_non_selected_windows = 1;
   
-  DEFVAR_BOOL ("automatic-hscrolling", &automatic_hscrolling_p,
-    "*Non-nil means scroll the display automatically to make point visible.");
+  DEFVAR_BOOL ("automatic-hscrolling", &automatic_hscrolling_p
+    /* *Non-nil means scroll the display automatically to make point visible.  */);
   automatic_hscrolling_p = 1;
   
-  DEFVAR_LISP ("image-types", &Vimage_types,
-    "List of supported image types.\n\
-Each element of the list is a symbol for a supported image type.");
+  DEFVAR_LISP ("image-types", &Vimage_types
+    /* List of supported image types.
+Each element of the list is a symbol for a supported image type.  */);
   Vimage_types = Qnil;
   
-  DEFVAR_BOOL ("message-truncate-lines", &message_truncate_lines,
-    "If non-nil, messages are truncated instead of resizing the echo area.\n\
-Bind this around calls to `message' to let it take effect.");
+  DEFVAR_BOOL ("message-truncate-lines", &message_truncate_lines
+    /* If non-nil, messages are truncated instead of resizing the echo area.
+Bind this around calls to `message' to let it take effect.  */);
   message_truncate_lines = 0;
 
-  DEFVAR_LISP ("menu-bar-update-hook",  &Vmenu_bar_update_hook,
-    "Normal hook run for clicks on menu bar, before displaying a submenu.\n\
-Can be used to update submenus whose contents should vary.");
+  DEFVAR_LISP ("menu-bar-update-hook",  &Vmenu_bar_update_hook
+    /* Normal hook run for clicks on menu bar, before displaying a submenu.
+Can be used to update submenus whose contents should vary.  */);
   Vmenu_bar_update_hook = Qnil;
   
-  DEFVAR_BOOL ("inhibit-menubar-update", &inhibit_menubar_update,
-    "Non-nil means don't update menu bars.  Internal use only.");
+  DEFVAR_BOOL ("inhibit-menubar-update", &inhibit_menubar_update
+    /* Non-nil means don't update menu bars.  Internal use only.  */);
   inhibit_menubar_update = 0;
 
-  DEFVAR_BOOL ("inhibit-eval-during-redisplay", &inhibit_eval_during_redisplay,
-    "Non-nil means don't eval Lisp during redisplay.");
+  DEFVAR_BOOL ("inhibit-eval-during-redisplay", &inhibit_eval_during_redisplay
+    /* Non-nil means don't eval Lisp during redisplay.  */);
   inhibit_eval_during_redisplay = 0;
 }
 
diff --git a/src/xfaces.c b/src/xfaces.c
index 867dcb8315a..476908e5b15 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -194,6 +194,7 @@ Boston, MA 02111-1307, USA.  */
 #include <config.h>
 #include <sys/types.h>
 #include <sys/stat.h>
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "charset.h"
 #include "keyboard.h"
@@ -668,8 +669,8 @@ unregister_colors (pixels, n)
 
 
 DEFUN ("dump-colors", Fdump_colors, Sdump_colors, 0, 0, 0,
-  "Dump currently allocated colors and their reference counts to stderr.")
-  ()
+       /* Dump currently allocated colors to stderr.  */
+       ())
 {
   int i, n;
 
@@ -1016,9 +1017,9 @@ clear_face_cache (clear_fonts_p)
 
 
 DEFUN ("clear-face-cache", Fclear_face_cache, Sclear_face_cache, 0, 1, 0,
-  "Clear face caches on all frames.\n\
-Optional THOROUGHLY non-nil means try to free unused fonts, too.")
-  (thoroughly)
+       /* Clear face caches on all frames.
+Optional THOROUGHLY non-nil means try to free unused fonts, too.  */
+       (thoroughly))
      Lisp_Object thoroughly;
 {
   clear_face_cache (!NILP (thoroughly));
@@ -1097,13 +1098,13 @@ clear_font_table (dpyinfo)
 #ifdef HAVE_WINDOW_SYSTEM
 
 DEFUN ("bitmap-spec-p", Fbitmap_spec_p, Sbitmap_spec_p, 1, 1, 0,
-  "Value is non-nil if OBJECT is a valid bitmap specification.\n\
-A bitmap specification is either a string, a file name, or a list\n\
-(WIDTH HEIGHT DATA) where WIDTH is the pixel width of the bitmap,\n\
-HEIGHT is its height, and DATA is a string containing the bits of\n\
-the pixmap.  Bits are stored row by row, each row occupies\n\
-(WIDTH + 7)/8 bytes.")
-  (object)
+       /* Value is non-nil if OBJECT is a valid bitmap specification.
+A bitmap specification is either a string, a file name, or a list
+\(WIDTH HEIGHT DATA) where WIDTH is the pixel width of the bitmap,
+HEIGHT is its height, and DATA is a string containing the bits of
+the pixmap.  Bits are stored row by row, each row occupies
+\(WIDTH + 7)/8 bytes.  */
+       (object))
      Lisp_Object object;
 {
   int pixmap_p = 0;
@@ -1481,10 +1482,10 @@ face_color_supported_p (f, color_name, background_p)
 
 
 DEFUN ("color-gray-p", Fcolor_gray_p, Scolor_gray_p, 1, 2, 0,
-  "Return non-nil if COLOR is a shade of gray (or white or black).\n\
-FRAME specifies the frame and thus the display for interpreting COLOR.\n\
-If FRAME is nil or omitted, use the selected frame.")
-   (color, frame)
+       /* Return non-nil if COLOR is a shade of gray (or white or black).
+FRAME specifies the frame and thus the display for interpreting COLOR.
+If FRAME is nil or omitted, use the selected frame.  */
+       (color, frame))
      Lisp_Object color, frame;
 {
   struct frame *f;
@@ -1498,11 +1499,11 @@ If FRAME is nil or omitted, use the selected frame.")
 
 DEFUN ("color-supported-p", Fcolor_supported_p,
        Scolor_supported_p, 2, 3, 0,
-  "Return non-nil if COLOR can be displayed on FRAME.\n\
-BACKGROUND-P non-nil means COLOR is used as a background.\n\
-If FRAME is nil or omitted, use the selected frame.\n\
-COLOR must be a valid color name.")
-   (color, frame, background_p)
+       /* Return non-nil if COLOR can be displayed on FRAME.
+BACKGROUND-P non-nil means COLOR is used as a background.
+If FRAME is nil or omitted, use the selected frame.
+COLOR must be a valid color name.  */
+       (color, frame, background_p))
      Lisp_Object frame, color, background_p;
 {
   struct frame *f;
@@ -2691,22 +2692,22 @@ remove_duplicates (list)
 
 
 DEFUN ("x-family-fonts", Fx_family_fonts, Sx_family_fonts, 0, 2, 0,
-  "Return a list of available fonts of family FAMILY on FRAME.\n\
-If FAMILY is omitted or nil, list all families.\n\
-Otherwise, FAMILY must be a string, possibly containing wildcards\n\
-`?' and `*'.\n\
-If FRAME is omitted or nil, use the selected frame.\n\
-Each element of the result is a vector [FAMILY WIDTH POINT-SIZE WEIGHT\n\
-SLANT FIXED-P FULL REGISTRY-AND-ENCODING].\n\
-FAMILY is the font family name.  POINT-SIZE is the size of the\n\
-font in 1/10 pt.  WIDTH, WEIGHT, and SLANT are symbols describing the\n\
-width, weight and slant of the font.  These symbols are the same as for\n\
-face attributes.  FIXED-P is non-nil if the font is fixed-pitch.\n\
-FULL is the full name of the font, and REGISTRY-AND-ENCODING is a string\n\
-giving the registry and encoding of the font.\n\
-The result list is sorted according to the current setting of\n\
-the face font sort order.")
-  (family, frame)
+       /* Return a list of available fonts of family FAMILY on FRAME.
+If FAMILY is omitted or nil, list all families.
+Otherwise, FAMILY must be a string, possibly containing wildcards
+`?' and `*'.
+If FRAME is omitted or nil, use the selected frame.
+Each element of the result is a vector [FAMILY WIDTH POINT-SIZE WEIGHT
+SLANT FIXED-P FULL REGISTRY-AND-ENCODING].
+FAMILY is the font family name.  POINT-SIZE is the size of the
+font in 1/10 pt.  WIDTH, WEIGHT, and SLANT are symbols describing the
+width, weight and slant of the font.  These symbols are the same as for
+face attributes.  FIXED-P is non-nil if the font is fixed-pitch.
+FULL is the full name of the font, and REGISTRY-AND-ENCODING is a string
+giving the registry and encoding of the font.
+The result list is sorted according to the current setting of
+the face font sort order.  */
+       (family, frame))
      Lisp_Object family, frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -2751,12 +2752,12 @@ the face font sort order.")
 
 DEFUN ("x-font-family-list", Fx_font_family_list, Sx_font_family_list,
        0, 1, 0,
-  "Return a list of available font families on FRAME.\n\
-If FRAME is omitted or nil, use the selected frame.\n\
-Value is a list of conses (FAMILY . FIXED-P) where FAMILY\n\
-is a font family, and FIXED-P is non-nil if fonts of that family\n\
-are fixed-pitch.")
-  (frame)
+       /* Return a list of available font families on FRAME.
+If FRAME is omitted or nil, use the selected frame.
+Value is a list of conses (FAMILY . FIXED-P) where FAMILY
+is a font family, and FIXED-P is non-nil if fonts of that family
+are fixed-pitch.  */
+       (frame))
      Lisp_Object frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -2798,26 +2799,26 @@ are fixed-pitch.")
 
 
 DEFUN ("x-list-fonts", Fx_list_fonts, Sx_list_fonts, 1, 5, 0,
-  "Return a list of the names of available fonts matching PATTERN.\n\
-If optional arguments FACE and FRAME are specified, return only fonts\n\
-the same size as FACE on FRAME.\n\
-PATTERN is a string, perhaps with wildcard characters;\n\
-  the * character matches any substring, and\n\
-  the ? character matches any single character.\n\
-  PATTERN is case-insensitive.\n\
-FACE is a face name--a symbol.\n\
-\n\
-The return value is a list of strings, suitable as arguments to\n\
-set-face-font.\n\
-\n\
-Fonts Emacs can't use may or may not be excluded\n\
-even if they match PATTERN and FACE.\n\
-The optional fourth argument MAXIMUM sets a limit on how many\n\
-fonts to match.  The first MAXIMUM fonts are reported.\n\
-The optional fifth argument WIDTH, if specified, is a number of columns\n\
-occupied by a character of a font.  In that case, return only fonts\n\
-the WIDTH times as wide as FACE on FRAME.")
-  (pattern, face, frame, maximum, width)
+       /* Return a list of the names of available fonts matching PATTERN.
+If optional arguments FACE and FRAME are specified, return only fonts
+the same size as FACE on FRAME.
+PATTERN is a string, perhaps with wildcard characters;
+  the * character matches any substring, and
+  the ? character matches any single character.
+  PATTERN is case-insensitive.
+FACE is a face name--a symbol.
+
+The return value is a list of strings, suitable as arguments to
+set-face-font.
+
+Fonts Emacs can't use may or may not be excluded
+even if they match PATTERN and FACE.
+The optional fourth argument MAXIMUM sets a limit on how many
+fonts to match.  The first MAXIMUM fonts are reported.
+The optional fifth argument WIDTH, if specified, is a number of columns
+occupied by a character of a font.  In that case, return only fonts
+the WIDTH times as wide as FACE on FRAME.  */
+       (pattern, face, frame, maximum, width))
     Lisp_Object pattern, face, frame, maximum, width;
 {
   struct frame *f;
@@ -3623,12 +3624,12 @@ merge_face_vector_with_property (f, to, prop)
 
 DEFUN ("internal-make-lisp-face", Finternal_make_lisp_face,
        Sinternal_make_lisp_face, 1, 2, 0,
-  "Make FACE, a symbol, a Lisp face with all attributes nil.\n\
-If FACE was not known as a face before, create a new one.\n\
-If optional argument FRAME is specified, make a frame-local face\n\
-for that frame.  Otherwise operate on the global face definition.\n\
-Value is a vector of face attributes.")
-  (face, frame)
+       /* Make FACE, a symbol, a Lisp face with all attributes nil.
+If FACE was not known as a face before, create a new one.
+If optional argument FRAME is specified, make a frame-local face
+for that frame.  Otherwise operate on the global face definition.
+Value is a vector of face attributes.  */
+       (face, frame))
      Lisp_Object face, frame;
 {
   Lisp_Object global_lface, lface;
@@ -3701,11 +3702,11 @@ Value is a vector of face attributes.")
 
 DEFUN ("internal-lisp-face-p", Finternal_lisp_face_p,
        Sinternal_lisp_face_p, 1, 2, 0,
-  "Return non-nil if FACE names a face.\n\
-If optional second parameter FRAME is non-nil, check for the\n\
-existence of a frame-local face with name FACE on that frame.\n\
-Otherwise check for the existence of a global face.")
-  (face, frame)
+       /* Return non-nil if FACE names a face.
+If optional second parameter FRAME is non-nil, check for the
+existence of a frame-local face with name FACE on that frame.
+Otherwise check for the existence of a global face.  */
+       (face, frame))
      Lisp_Object face, frame;
 {
   Lisp_Object lface;
@@ -3724,14 +3725,14 @@ Otherwise check for the existence of a global face.")
 
 DEFUN ("internal-copy-lisp-face", Finternal_copy_lisp_face,
        Sinternal_copy_lisp_face, 4, 4, 0,
-  "Copy face FROM to TO.\n\
-If FRAME it t, copy the global face definition of FROM to the\n\
-global face definition of TO.  Otherwise, copy the frame-local\n\
-definition of FROM on FRAME to the frame-local definition of TO\n\
-on NEW-FRAME, or FRAME if NEW-FRAME is nil.\n\
-\n\
-Value is TO.")
-  (from, to, frame, new_frame)
+       /* Copy face FROM to TO.
+If FRAME it t, copy the global face definition of FROM to the
+global face definition of TO.  Otherwise, copy the frame-local
+definition of FROM on FRAME to the frame-local definition of TO
+on NEW-FRAME, or FRAME if NEW-FRAME is nil.
+
+Value is TO.  */
+       (from, to, frame, new_frame))
      Lisp_Object from, to, frame, new_frame;
 {
   Lisp_Object lface, copy;
@@ -3766,13 +3767,13 @@ Value is TO.")
 
 DEFUN ("internal-set-lisp-face-attribute", Finternal_set_lisp_face_attribute,
        Sinternal_set_lisp_face_attribute, 3, 4, 0,
-  "Set attribute ATTR of FACE to VALUE.\n\
-FRAME being a frame means change the face on that frame.\n\
-FRAME nil means change the face of the selected frame.\n\
-FRAME t means change the default for new frames.\n\
-FRAME 0 means change the face on all frames, and change the default\n\
-  for new frames.")
-  (face, attr, value, frame)
+       /* Set attribute ATTR of FACE to VALUE.
+FRAME being a frame means change the face on that frame.
+FRAME nil means change the face of the selected frame.
+FRAME t means change the default for new frames.
+FRAME 0 means change the face on all frames, and change the default
+  for new frames.  */
+       (face, attr, value, frame))
      Lisp_Object face, attr, value, frame;
 {
   Lisp_Object lface;
@@ -4310,8 +4311,9 @@ update_face_from_frame_parameter (f, param, new_value)
    doesn't take a frame argument.  */
 
 DEFUN ("internal-face-x-get-resource", Finternal_face_x_get_resource,
-       Sinternal_face_x_get_resource, 3, 3, 0, "")
-  (resource, class, frame)
+       Sinternal_face_x_get_resource, 3, 3, 0,
+       /* */
+       (resource, class, frame))
      Lisp_Object resource, class, frame;
 {
   Lisp_Object value = Qnil;
@@ -4362,8 +4364,9 @@ face_boolean_x_resource_value (value, signal_p)
 DEFUN ("internal-set-lisp-face-attribute-from-resource",
        Finternal_set_lisp_face_attribute_from_resource,
        Sinternal_set_lisp_face_attribute_from_resource,
-       3, 4, 0, "")
-  (face, attr, value, frame)
+       3, 4, 0,
+       /* */
+       (face, attr, value, frame))
      Lisp_Object face, attr, value, frame;
 {
   CHECK_SYMBOL (face, 0);
@@ -4492,13 +4495,13 @@ x_update_menu_appearance (f)
 DEFUN ("internal-get-lisp-face-attribute", Finternal_get_lisp_face_attribute,
        Sinternal_get_lisp_face_attribute,
        2, 3, 0,
-  "Return face attribute KEYWORD of face SYMBOL.\n\
-If SYMBOL does not name a valid Lisp face or KEYWORD isn't a valid\n\
-face attribute name, signal an error.\n\
-If the optional argument FRAME is given, report on face FACE in that\n\
-frame.  If FRAME is t, report on the defaults for face FACE (for new\n\
-frames).  If FRAME is omitted or nil, use the selected frame.")
-  (symbol, keyword, frame)
+       /* Return face attribute KEYWORD of face SYMBOL.
+If SYMBOL does not name a valid Lisp face or KEYWORD isn't a valid
+face attribute name, signal an error.
+If the optional argument FRAME is given, report on face FACE in that
+frame.  If FRAME is t, report on the defaults for face FACE (for new
+frames).  If FRAME is omitted or nil, use the selected frame.  */
+       (symbol, keyword, frame))
      Lisp_Object symbol, keyword, frame;
 {
   Lisp_Object lface, value = Qnil;
@@ -4557,9 +4560,9 @@ frames).  If FRAME is omitted or nil, use the selected frame.")
 DEFUN ("internal-lisp-face-attribute-values",
        Finternal_lisp_face_attribute_values,
        Sinternal_lisp_face_attribute_values, 1, 1, 0,
-  "Return a list of valid discrete values for face attribute ATTR.\n\
-Value is nil if ATTR doesn't have a discrete set of valid values.")
-  (attr)
+       /* Return a list of valid discrete values for face attribute ATTR.
+Value is nil if ATTR doesn't have a discrete set of valid values.  */
+       (attr))
      Lisp_Object attr;
 {
   Lisp_Object result = Qnil;
@@ -4609,9 +4612,9 @@ Value is nil if ATTR doesn't have a discrete set of valid values.")
 
 DEFUN ("internal-merge-in-global-face", Finternal_merge_in_global_face,
        Sinternal_merge_in_global_face, 2, 2, 0,
-  "Add attributes from frame-default definition of FACE to FACE on FRAME.\n\
-Default face attributes override any local face attributes.")
-  (face, frame)
+  /* Add attributes from frame-default definition of FACE to FACE on FRAME.
+Default face attributes override any local face attributes.  */
+       (face, frame))
      Lisp_Object face, frame;
 {
   int i;
@@ -4644,13 +4647,13 @@ Default face attributes override any local face attributes.")
    done in fontset.el.  */
 
 DEFUN ("face-font", Fface_font, Sface_font, 1, 2, 0,
-  "Return the font name of face FACE, or nil if it is unspecified.\n\
-If the optional argument FRAME is given, report on face FACE in that frame.\n\
-If FRAME is t, report on the defaults for face FACE (for new frames).\n\
-  The font default for a face is either nil, or a list\n\
-  of the form (bold), (italic) or (bold italic).\n\
-If FRAME is omitted or nil, use the selected frame.")
-  (face, frame)
+  /* Return the font name of face FACE, or nil if it is unspecified.
+If the optional argument FRAME is given, report on face FACE in that frame.
+If FRAME is t, report on the defaults for face FACE (for new frames).
+  The font default for a face is either nil, or a list
+  of the form (bold), (italic) or (bold italic).
+If FRAME is omitted or nil, use the selected frame.  */
+       (face, frame))
      Lisp_Object face, frame;
 {
   if (EQ (frame, Qt))
@@ -4728,11 +4731,11 @@ lface_equal_p (v1, v2)
 
 DEFUN ("internal-lisp-face-equal-p", Finternal_lisp_face_equal_p,
        Sinternal_lisp_face_equal_p, 2, 3, 0,
-  "True if FACE1 and FACE2 are equal.\n\
-If the optional argument FRAME is given, report on face FACE in that frame.\n\
-If FRAME is t, report on the defaults for face FACE (for new frames).\n\
-If FRAME is omitted or nil, use the selected frame.")
-  (face1, face2, frame)
+       /* True if FACE1 and FACE2 are equal.
+If the optional argument FRAME is given, report on face FACE in that frame.
+If FRAME is t, report on the defaults for face FACE (for new frames).
+If FRAME is omitted or nil, use the selected frame.  */
+       (face1, face2, frame))
      Lisp_Object face1, face2, frame;
 {
   int equal_p;
@@ -4758,11 +4761,11 @@ If FRAME is omitted or nil, use the selected frame.")
 
 DEFUN ("internal-lisp-face-empty-p", Finternal_lisp_face_empty_p,
        Sinternal_lisp_face_empty_p, 1, 2, 0,
-  "True if FACE has no attribute specified.\n\
-If the optional argument FRAME is given, report on face FACE in that frame.\n\
-If FRAME is t, report on the defaults for face FACE (for new frames).\n\
-If FRAME is omitted or nil, use the selected frame.")
-  (face, frame)
+       /* True if FACE has no attribute specified.
+If the optional argument FRAME is given, report on face FACE in that frame.
+If FRAME is t, report on the defaults for face FACE (for new frames).
+If FRAME is omitted or nil, use the selected frame.  */
+       (face, frame))
      Lisp_Object face, frame;
 {
   struct frame *f;
@@ -4789,9 +4792,9 @@ If FRAME is omitted or nil, use the selected frame.")
 
 DEFUN ("frame-face-alist", Fframe_face_alist, Sframe_face_alist,
        0, 1, 0,
-  "Return an alist of frame-local faces defined on FRAME.\n\
-For internal use only.")
-  (frame)
+       /* Return an alist of frame-local faces defined on FRAME.
+For internal use only.  */
+       (frame))
      Lisp_Object frame;
 {
   struct frame *f = frame_or_selected_frame (frame, 0);
@@ -5468,15 +5471,15 @@ lookup_derived_face (f, symbol, c, face_id)
 DEFUN ("internal-set-font-selection-order",
        Finternal_set_font_selection_order,
        Sinternal_set_font_selection_order, 1, 1, 0,
-  "Set font selection order for face font selection to ORDER.\n\
-ORDER must be a list of length 4 containing the symbols `:width',\n\
-`:height', `:weight', and `:slant'.  Face attributes appearing\n\
-first in ORDER are matched first, e.g. if `:height' appears before\n\
-`:weight' in ORDER, font selection first tries to find a font with\n\
-a suitable height, and then tries to match the font weight.\n\
-Value is ORDER.")
-  (order)
-       Lisp_Object order;
+       /* Set font selection order for face font selection to ORDER.
+ORDER must be a list of length 4 containing the symbols `:width',
+`:height', `:weight', and `:slant'.  Face attributes appearing
+first in ORDER are matched first, e.g. if `:height' appears before
+`:weight' in ORDER, font selection first tries to find a font with
+a suitable height, and then tries to match the font weight.
+Value is ORDER.  */
+       (order))
+     Lisp_Object order;
 {
   Lisp_Object list;
   int i;
@@ -5528,11 +5531,11 @@ Value is ORDER.")
 DEFUN ("internal-set-alternative-font-family-alist",
        Finternal_set_alternative_font_family_alist,
        Sinternal_set_alternative_font_family_alist, 1, 1, 0,
-  "Define alternative font families to try in face font selection.\n\
-ALIST is an alist of (FAMILY ALTERNATIVE1 ALTERNATIVE2 ...) entries.\n\
-Each ALTERNATIVE is tried in order if no fonts of font family FAMILY can\n\
-be found.  Value is ALIST.")
-  (alist)
+  /* Define alternative font families to try in face font selection.
+ALIST is an alist of (FAMILY ALTERNATIVE1 ALTERNATIVE2 ...) entries.
+Each ALTERNATIVE is tried in order if no fonts of font family FAMILY can
+be found.  Value is ALIST.  */
+       (alist))
      Lisp_Object alist;
 {
   CHECK_LIST (alist, 0);
@@ -5545,11 +5548,11 @@ be found.  Value is ALIST.")
 DEFUN ("internal-set-alternative-font-registry-alist",
        Finternal_set_alternative_font_registry_alist,
        Sinternal_set_alternative_font_registry_alist, 1, 1, 0,
-  "Define alternative font registries to try in face font selection.\n\
-ALIST is an alist of (REGISTRY ALTERNATIVE1 ALTERNATIVE2 ...) entries.\n\
-Each ALTERNATIVE is tried in order if no fonts of font registry REGISTRY can\n\
-be found.  Value is ALIST.")
-  (alist)
+  /* Define alternative font registries to try in face font selection.
+ALIST is an alist of (REGISTRY ALTERNATIVE1 ALTERNATIVE2 ...) entries.
+Each ALTERNATIVE is tried in order if no fonts of font registry REGISTRY can
+be found.  Value is ALIST.  */
+       (alist))
      Lisp_Object alist;
 {
   CHECK_LIST (alist, 0);
@@ -6656,13 +6659,13 @@ realize_tty_face (cache, attrs, c)
 DEFUN ("tty-suppress-bold-inverse-default-colors",
        Ftty_suppress_bold_inverse_default_colors,
        Stty_suppress_bold_inverse_default_colors, 1, 1, 0,
-  "Suppress/allow boldness of faces with inverse default colors.\n\
-SUPPRESS non-nil means suppress it.\n\
-This affects bold faces on TTYs whose foreground is the default background\n\
-color of the display and whose background is the default foreground color.\n\
-For such faces, the bold face attribute is ignored if this variable\n\
-is non-nil.")
-  (suppress)
+  /* Suppress/allow boldness of faces with inverse default colors.
+SUPPRESS non-nil means suppress it.
+This affects bold faces on TTYs whose foreground is the default background
+color of the display and whose background is the default foreground color.
+For such faces, the bold face attribute is ignored if this variable
+is non-nil.  */
+       (suppress))
      Lisp_Object suppress;
 {
   tty_suppress_bold_inverse_default_colors_p = !NILP (suppress);
@@ -6978,8 +6981,8 @@ dump_realized_face (face)
 }
 
 
-DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, "")
-   (n)
+DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, /* */
+       (n))
      Lisp_Object n;
 {
   if (NILP (n))
@@ -7013,8 +7016,8 @@ DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, "")
 
 
 DEFUN ("show-face-resources", Fshow_face_resources, Sshow_face_resources,
-       0, 0, 0, "")
-  ()
+       0, 0, 0, /* */
+       ())
 {
   fprintf (stderr, "number of colors = %d\n", ncolors_allocated);
   fprintf (stderr, "number of pixmaps = %d\n", npixmaps_allocated);
@@ -7206,40 +7209,41 @@ syms_of_xfaces ()
   defsubr (&Sdump_colors);
 #endif
 
-  DEFVAR_LISP ("font-list-limit", &Vfont_list_limit,
-    "*Limit for font matching.\n\
-If an integer > 0, font matching functions won't load more than\n\
-that number of fonts when searching for a matching font.");
+  DEFVAR_LISP ("font-list-limit", &Vfont_list_limit
+               /* *Limit for font matching.
+If an integer > 0, font matching functions won't load more than
+that number of fonts when searching for a matching font.  */);
   Vfont_list_limit = make_number (DEFAULT_FONT_LIST_LIMIT);
 
-  DEFVAR_LISP ("face-new-frame-defaults", &Vface_new_frame_defaults,
-    "List of global face definitions (for internal use only.)");
+  DEFVAR_LISP ("face-new-frame-defaults", &Vface_new_frame_defaults
+    /* List of global face definitions (for internal use only.)  */);
   Vface_new_frame_defaults = Qnil;
 
-  DEFVAR_LISP ("face-default-stipple", &Vface_default_stipple,
-    "*Default stipple pattern used on monochrome displays.\n\
-This stipple pattern is used on monochrome displays\n\
-instead of shades of gray for a face background color.\n\
-See `set-face-stipple' for possible values for this variable.");
+  DEFVAR_LISP ("face-default-stipple", &Vface_default_stipple
+    /* *Default stipple pattern used on monochrome displays.
+This stipple pattern is used on monochrome displays
+instead of shades of gray for a face background color.
+See `set-face-stipple' for possible values for this variable.  */);
   Vface_default_stipple = build_string ("gray3");
 
-  DEFVAR_LISP ("tty-defined-color-alist", &Vtty_defined_color_alist,
-   "An alist of defined terminal colors and their RGB values.");
+  DEFVAR_LISP ("tty-defined-color-alist", &Vtty_defined_color_alist
+   /* An alist of defined terminal colors and their RGB values.  */);
   Vtty_defined_color_alist = Qnil;
 
-  DEFVAR_LISP ("scalable-fonts-allowed", &Vscalable_fonts_allowed,
-    "Allowed scalable fonts.\n\
-A value of nil means don't allow any scalable fonts.\n\
-A value of t means allow any scalable font.\n\
-Otherwise, value must be a list of regular expressions.  A font may be\n\
-scaled if its name matches a regular expression in the list.\n\
-Note that if value is nil, a scalable font might still be used, if no\n\
-other font of the appropriate family and registry is available.");
+  DEFVAR_LISP ("scalable-fonts-allowed", &Vscalable_fonts_allowed
+               /* Allowed scalable fonts.
+A value of nil means don't allow any scalable fonts.
+A value of t means allow any scalable font.
+Otherwise, value must be a list of regular expressions.  A font may be
+scaled if its name matches a regular expression in the list.
+Note that if value is nil, a scalable font might still be used, if no
+other font of the appropriate family and registry is available.  */);
   Vscalable_fonts_allowed = Qnil;
 
-  DEFVAR_LISP ("face-ignored-fonts", &Vface_ignored_fonts,
-    "List of ignored fonts.\n\
-Each element is a regular expression that matches names of fonts to ignore.");
+  DEFVAR_LISP ("face-ignored-fonts", &Vface_ignored_fonts
+               /* List of ignored fonts.
+Each element is a regular expression that matches names of fonts to
+ignore.  */);
   Vface_ignored_fonts = Qnil;
 
 #ifdef HAVE_WINDOW_SYSTEM
diff --git a/src/xmenu.c b/src/xmenu.c
index e12099becf3..bf7bdbfd34e 100644
--- a/src/xmenu.c
+++ b/src/xmenu.c
@@ -37,6 +37,7 @@ Boston, MA 02111-1307, USA.  */
 #include <signal.h>
 
 #include <stdio.h>
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "termhooks.h"
 #include "keyboard.h"
@@ -655,39 +656,40 @@ list_of_items (pane)
 }
 
 DEFUN ("x-popup-menu", Fx_popup_menu, Sx_popup_menu, 2, 2, 0,
-  "Pop up a deck-of-cards menu and return user's selection.\n\
-POSITION is a position specification.  This is either a mouse button event\n\
-or a list ((XOFFSET YOFFSET) WINDOW)\n\
-where XOFFSET and YOFFSET are positions in pixels from the top left\n\
-corner of WINDOW's frame.  (WINDOW may be a frame object instead of a window.)\n\
-This controls the position of the center of the first line\n\
-in the first pane of the menu, not the top left of the menu as a whole.\n\
-If POSITION is t, it means to use the current mouse position.\n\
-\n\
-MENU is a specifier for a menu.  For the simplest case, MENU is a keymap.\n\
-The menu items come from key bindings that have a menu string as well as\n\
-a definition; actually, the \"definition\" in such a key binding looks like\n\
-\(STRING . REAL-DEFINITION).  To give the menu a title, put a string into\n\
-the keymap as a top-level element.\n\n\
-If REAL-DEFINITION is nil, that puts a nonselectable string in the menu.\n\
-Otherwise, REAL-DEFINITION should be a valid key binding definition.\n\
-\n\
-You can also use a list of keymaps as MENU.\n\
-  Then each keymap makes a separate pane.\n\
-When MENU is a keymap or a list of keymaps, the return value\n\
-is a list of events.\n\n\
-\n\
-Alternatively, you can specify a menu of multiple panes\n\
-  with a list of the form (TITLE PANE1 PANE2...),\n\
-where each pane is a list of form (TITLE ITEM1 ITEM2...).\n\
-Each ITEM is normally a cons cell (STRING . VALUE);\n\
-but a string can appear as an item--that makes a nonselectable line\n\
-in the menu.\n\
-With this form of menu, the return value is VALUE from the chosen item.\n\
-\n\
-If POSITION is nil, don't display the menu at all, just precalculate the\n\
-cached information about equivalent key sequences.")
-  (position, menu)
+  /* Pop up a deck-of-cards menu and return user's selection.
+POSITION is a position specification.  This is either a mouse button event
+or a list ((XOFFSET YOFFSET) WINDOW)
+where XOFFSET and YOFFSET are positions in pixels from the top left
+corner of WINDOW's frame.  (WINDOW may be a frame object instead of a window.)
+This controls the position of the center of the first line
+in the first pane of the menu, not the top left of the menu as a whole.
+If POSITION is t, it means to use the current mouse position.
+
+MENU is a specifier for a menu.  For the simplest case, MENU is a keymap.
+The menu items come from key bindings that have a menu string as well as
+a definition; actually, the "definition" in such a key binding looks like
+\(STRING . REAL-DEFINITION).  To give the menu a title, put a string into
+the keymap as a top-level element.
+
+If REAL-DEFINITION is nil, that puts a nonselectable string in the menu.
+Otherwise, REAL-DEFINITION should be a valid key binding definition.
+
+You can also use a list of keymaps as MENU.
+  Then each keymap makes a separate pane.
+When MENU is a keymap or a list of keymaps, the return value
+is a list of events.
+
+Alternatively, you can specify a menu of multiple panes
+  with a list of the form (TITLE PANE1 PANE2...),
+where each pane is a list of form (TITLE ITEM1 ITEM2...).
+Each ITEM is normally a cons cell (STRING . VALUE);
+but a string can appear as an item--that makes a nonselectable line
+in the menu.
+With this form of menu, the return value is VALUE from the chosen item.
+
+If POSITION is nil, don't display the menu at all, just precalculate the
+cached information about equivalent key sequences.  */
+       (position, menu))
      Lisp_Object position, menu;
 {
   Lisp_Object keymap, tem;
@@ -879,21 +881,22 @@ cached information about equivalent key sequences.")
 #ifdef HAVE_MENUS
 
 DEFUN ("x-popup-dialog", Fx_popup_dialog, Sx_popup_dialog, 2, 2, 0,
-  "Pop up a dialog box and return user's selection.\n\
-POSITION specifies which frame to use.\n\
-This is normally a mouse button event or a window or frame.\n\
-If POSITION is t, it means to use the frame the mouse is on.\n\
-The dialog box appears in the middle of the specified frame.\n\
-\n\
-CONTENTS specifies the alternatives to display in the dialog box.\n\
-It is a list of the form (TITLE ITEM1 ITEM2...).\n\
-Each ITEM is a cons cell (STRING . VALUE).\n\
-The return value is VALUE from the chosen item.\n\n\
-An ITEM may also be just a string--that makes a nonselectable item.\n\
-An ITEM may also be nil--that means to put all preceding items\n\
-on the left of the dialog box and all following items on the right.\n\
-\(By default, approximately half appear on each side.)")
-  (position, contents)
+  /* Pop up a dialog box and return user's selection.
+POSITION specifies which frame to use.
+This is normally a mouse button event or a window or frame.
+If POSITION is t, it means to use the frame the mouse is on.
+The dialog box appears in the middle of the specified frame.
+
+CONTENTS specifies the alternatives to display in the dialog box.
+It is a list of the form (TITLE ITEM1 ITEM2...).
+Each ITEM is a cons cell (STRING . VALUE).
+The return value is VALUE from the chosen item.
+
+An ITEM may also be just a string--that makes a nonselectable item.
+An ITEM may also be nil--that means to put all preceding items
+on the left of the dialog box and all following items on the right.
+\(By default, approximately half appear on each side.)  */
+       (position, contents))
      Lisp_Object position, contents;
 {
   struct frame * f = NULL;
@@ -2846,9 +2849,9 @@ syms_of_xmenu ()
   Qdebug_on_next_call = intern ("debug-on-next-call");
   staticpro (&Qdebug_on_next_call);
 
-  DEFVAR_LISP ("menu-updating-frame", &Vmenu_updating_frame,
-    "Frame for which we are updating a menu.\n\
-The enable predicate for a menu command should check this variable.");
+  DEFVAR_LISP ("menu-updating-frame", &Vmenu_updating_frame
+    /* Frame for which we are updating a menu.
+The enable predicate for a menu command should check this variable.  */);
   Vmenu_updating_frame = Qnil;
 
 #ifdef USE_X_TOOLKIT
diff --git a/src/xterm.c b/src/xterm.c
index caf9695cf11..2dd0cd01b89 100644
--- a/src/xterm.c
+++ b/src/xterm.c
@@ -32,6 +32,7 @@ Boston, MA 02111-1307, USA.  */
 
 #ifdef HAVE_X_WINDOWS
 
+#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "blockinput.h"
 
@@ -14790,24 +14791,24 @@ syms_of_xterm ()
   staticpro (&previous_help_echo);
   help_echo_pos = -1;
 
-  DEFVAR_BOOL ("x-stretch-cursor", &x_stretch_cursor_p,
-    "*Non-nil means draw block cursor as wide as the glyph under it.\n\
-For example, if a block cursor is over a tab, it will be drawn as\n\
-wide as that tab on the display.");
+  DEFVAR_BOOL ("x-stretch-cursor", &x_stretch_cursor_p
+    /* *Non-nil means draw block cursor as wide as the glyph under it.
+For example, if a block cursor is over a tab, it will be drawn as
+wide as that tab on the display.  */);
   x_stretch_cursor_p = 0;
 
   DEFVAR_BOOL ("x-use-underline-position-properties",
-               &x_use_underline_position_properties,
-     "*Non-nil means make use of UNDERLINE_POSITION font properties.\n\
-Nil means ignore them.  If you encounter fonts with bogus\n\
-UNDERLINE_POSITION font properties, for example 7x13 on XFree prior\n\
-to 4.1, set this to nil.");
+               &x_use_underline_position_properties
+     /* *Non-nil means make use of UNDERLINE_POSITION font properties.
+Nil means ignore them.  If you encounter fonts with bogus
+UNDERLINE_POSITION font properties, for example 7x13 on XFree prior
+to 4.1, set this to nil.  */);
   x_use_underline_position_properties = 1;
 
-  DEFVAR_LISP ("x-toolkit-scroll-bars", &Vx_toolkit_scroll_bars,
-    "What X toolkit scroll bars Emacs uses.\n\
-A value of nil means Emacs doesn't use X toolkit scroll bars.\n\
-Otherwise, value is a symbol describing the X toolkit.");
+  DEFVAR_LISP ("x-toolkit-scroll-bars", &Vx_toolkit_scroll_bars
+    /* What X toolkit scroll bars Emacs uses.
+A value of nil means Emacs doesn't use X toolkit scroll bars.
+Otherwise, value is a symbol describing the X toolkit.  */);
 #ifdef USE_TOOLKIT_SCROLL_BARS
 #ifdef USE_MOTIF
   Vx_toolkit_scroll_bars = intern ("motif");