changeset 40962:f66d09d1bb2f

Change doc-string comments to `new style'. [w/`doc:' keyword]. Doc fixes.

--- a/src/w32console.c	Mon Nov 12 23:49:56 2001 +0000
+++ b/src/w32console.c	Mon Nov 12 23:57:09 2001 +0000
@@ -420,11 +420,11 @@
 }
 
 DEFUN ("set-message-beep", Fset_message_beep, Sset_message_beep, 1, 1, 0,
-       "Set the sound generated when the bell is rung.\n\
-SOUND is 'asterisk, 'exclamation, 'hand, 'question, 'ok, or 'silent\n\
-to use the corresponding system sound for the bell.  The 'silent sound\n\
-prevents Emacs from making any sound at all.\n\
-SOUND is nil to use the normal beep.")
+       doc: /* Set the sound generated when the bell is rung.
+SOUND is 'asterisk, 'exclamation, 'hand, 'question, 'ok, or 'silent
+to use the corresponding system sound for the bell.  The 'silent sound
+prevents Emacs from making any sound at all.
+SOUND is nil to use the normal beep.  */)
      (sound)
      Lisp_Object sound;
 {
@@ -682,7 +682,7 @@
 }
 
 DEFUN ("set-screen-color", Fset_screen_color, Sset_screen_color, 2, 2, 0,
-       "Set screen colors.")
+       doc: /* Set screen colors.  */)
     (foreground, background)
     Lisp_Object foreground;
     Lisp_Object background;
@@ -694,7 +694,7 @@
 }
 
 DEFUN ("set-cursor-size", Fset_cursor_size, Sset_cursor_size, 1, 1, 0,
-       "Set cursor size.")
+       doc: /* Set cursor size.  */)
     (size)
     Lisp_Object size;
 {
@@ -728,11 +728,11 @@
 {
   DEFVAR_BOOL ("w32-use-full-screen-buffer",
                &w32_use_full_screen_buffer,
-  "Non-nil means make terminal frames use the full screen buffer dimensions.\n\
-This is desirable when running Emacs over telnet, and is the default.\n\
-A value of nil means use the current console window dimensions; this\n\
-may be preferrable when working directly at the console with a large\n\
-scroll-back buffer.");
+	       doc: /* Non-nil means make terminal frames use the full screen buffer dimensions.
+This is desirable when running Emacs over telnet, and is the default.
+A value of nil means use the current console window dimensions; this
+may be preferrable when working directly at the console with a large
+scroll-back buffer.  */);
   w32_use_full_screen_buffer = 1;
 
   defsubr (&Sset_screen_color);

--- a/src/w32menu.c	Mon Nov 12 23:49:56 2001 +0000
+++ b/src/w32menu.c	Mon Nov 12 23:57:09 2001 +0000
@@ -584,38 +584,37 @@
 }
 
 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.")
+       doc: /* 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;
 {
@@ -808,20 +807,21 @@
 #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.)")
+       doc: /* 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;
 {
@@ -2229,8 +2229,8 @@
   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.");
+	       doc: /* Frame for which we are updating a menu.
+The enable predicate for a menu command should check this variable.  */);
   Vmenu_updating_frame = Qnil;
 
   defsubr (&Sx_popup_menu);

--- a/src/w32proc.c	Mon Nov 12 23:49:56 2001 +0000
+++ b/src/w32proc.c	Mon Nov 12 23:57:09 2001 +0000
@@ -1646,14 +1646,14 @@
 extern Lisp_Object Vsystem_name;
 
 DEFUN ("w32-has-winsock", Fw32_has_winsock, Sw32_has_winsock, 0, 1, 0,
-  "Test for presence of the Windows socket library `winsock'.\n\
-Returns non-nil if winsock support is present, nil otherwise.\n\
-\n\
-If the optional argument LOAD-NOW is non-nil, the winsock library is\n\
-also loaded immediately if not already loaded.  If winsock is loaded,\n\
-the winsock local hostname is returned (since this may be different from\n\
-the value of `system-name' and should supplant it), otherwise t is\n\
-returned to indicate winsock support is present.")
+       doc: /* Test for presence of the Windows socket library `winsock'.
+Returns non-nil if winsock support is present, nil otherwise.
+
+If the optional argument LOAD-NOW is non-nil, the winsock library is
+also loaded immediately if not already loaded.  If winsock is loaded,
+the winsock local hostname is returned (since this may be different from
+the value of `system-name' and should supplant it), otherwise t is
+returned to indicate winsock support is present.  */)
   (load_now)
      Lisp_Object load_now;
 {
@@ -1682,10 +1682,10 @@
 
 DEFUN ("w32-unload-winsock", Fw32_unload_winsock, Sw32_unload_winsock,
        0, 0, 0,
-  "Unload the Windows socket library `winsock' if loaded.\n\
-This is provided to allow dial-up socket connections to be disconnected\n\
-when no longer needed.  Returns nil without unloading winsock if any\n\
-socket connections still exist.")
+       doc: /* Unload the Windows socket library `winsock' if loaded.
+This is provided to allow dial-up socket connections to be disconnected
+when no longer needed.  Returns nil without unloading winsock if any
+socket connections still exist.  */)
   ()
 {
   return term_winsock () ? Qt : Qnil;
@@ -1704,9 +1704,9 @@
   } while (0)
 
 DEFUN ("w32-short-file-name", Fw32_short_file_name, Sw32_short_file_name, 1, 1, 0,
-  "Return the short file name version (8.3) of the full path of FILENAME.\n\
-If FILENAME does not exist, return nil.\n\
-All path elements in FILENAME are converted to their short names.")
+       doc: /* Return the short file name version (8.3) of the full path of FILENAME.
+If FILENAME does not exist, return nil.
+All path elements in FILENAME are converted to their short names.  */)
      (filename)
      Lisp_Object filename;
 {
@@ -1729,9 +1729,9 @@
 
 DEFUN ("w32-long-file-name", Fw32_long_file_name, Sw32_long_file_name,
        1, 1, 0,
-  "Return the long file name version of the full path of FILENAME.\n\
-If FILENAME does not exist, return nil.\n\
-All path elements in FILENAME are converted to their long names.")
+       doc: /* Return the long file name version of the full path of FILENAME.
+If FILENAME does not exist, return nil.
+All path elements in FILENAME are converted to their long names.  */)
   (filename)
      Lisp_Object filename;
 {
@@ -1750,15 +1750,15 @@
   return build_string (longname);
 }
 
-DEFUN ("w32-set-process-priority", Fw32_set_process_priority, Sw32_set_process_priority,
-       2, 2, 0,
-  "Set the priority of PROCESS to PRIORITY.\n\
-If PROCESS is nil, the priority of Emacs is changed, otherwise the\n\
-priority of the process whose pid is PROCESS is changed.\n\
-PRIORITY should be one of the symbols high, normal, or low;\n\
-any other symbol will be interpreted as normal.\n\
-\n\
-If successful, the return value is t, otherwise nil.")
+DEFUN ("w32-set-process-priority", Fw32_set_process_priority,
+       Sw32_set_process_priority, 2, 2, 0,
+       doc: /* Set the priority of PROCESS to PRIORITY.
+If PROCESS is nil, the priority of Emacs is changed, otherwise the
+priority of the process whose pid is PROCESS is changed.
+PRIORITY should be one of the symbols high, normal, or low;
+any other symbol will be interpreted as normal.
+
+If successful, the return value is t, otherwise nil.  */)
   (process, priority)
      Lisp_Object process, priority;
 {
@@ -1804,19 +1804,20 @@
 }
 
 
-DEFUN ("w32-get-locale-info", Fw32_get_locale_info, Sw32_get_locale_info, 1, 2, 0,
-  "Return information about the Windows locale LCID.\n\
-By default, return a three letter locale code which encodes the default\n\
-language as the first two characters, and the country or regionial variant\n\
-as the third letter.  For example, ENU refers to `English (United States)',\n\
-while ENC means `English (Canadian)'.\n\
-\n\
-If the optional argument LONGFORM is t, the long form of the locale\n\
-name is returned, e.g. `English (United States)' instead; if LONGFORM\n\
-is a number, it is interpreted as an LCTYPE constant and the corresponding\n\
-locale information is returned.\n\
-\n\
-If LCID (a 16-bit number) is not a valid locale, the result is nil.")
+DEFUN ("w32-get-locale-info", Fw32_get_locale_info,
+       Sw32_get_locale_info, 1, 2, 0,
+       doc: /* Return information about the Windows locale LCID.
+By default, return a three letter locale code which encodes the default
+language as the first two characters, and the country or regionial variant
+as the third letter.  For example, ENU refers to `English (United States)',
+while ENC means `English (Canadian)'.
+
+If the optional argument LONGFORM is t, the long form of the locale
+name is returned, e.g. `English (United States)' instead; if LONGFORM
+is a number, it is interpreted as an LCTYPE constant and the corresponding
+locale information is returned.
+
+If LCID (a 16-bit number) is not a valid locale, the result is nil.  */)
      (lcid, longform)
      Lisp_Object lcid, longform;
 {
@@ -1859,10 +1860,11 @@
 }
 
 
-DEFUN ("w32-get-current-locale-id", Fw32_get_current_locale_id, Sw32_get_current_locale_id, 0, 0, 0,
-  "Return Windows locale id for current locale setting.\n\
-This is a numerical value; use `w32-get-locale-info' to convert to a\n\
-human-readable form.")
+DEFUN ("w32-get-current-locale-id", Fw32_get_current_locale_id,
+       Sw32_get_current_locale_id, 0, 0, 0,
+       doc: /* Return Windows locale id for current locale setting.
+This is a numerical value; use `w32-get-locale-info' to convert to a
+human-readable form.  */)
      ()
 {
   return make_number (GetThreadLocale ());
@@ -1896,10 +1898,11 @@
   return TRUE;
 }
 
-DEFUN ("w32-get-valid-locale-ids", Fw32_get_valid_locale_ids, Sw32_get_valid_locale_ids, 0, 0, 0,
-  "Return list of all valid Windows locale ids.\n\
-Each id is a numerical value; use `w32-get-locale-info' to convert to a\n\
-human-readable form.")
+DEFUN ("w32-get-valid-locale-ids", Fw32_get_valid_locale_ids,
+       Sw32_get_valid_locale_ids, 0, 0, 0,
+       doc: /* Return list of all valid Windows locale ids.
+Each id is a numerical value; use `w32-get-locale-info' to convert to a
+human-readable form.  */)
      ()
 {
   Vw32_valid_locale_ids = Qnil;
@@ -1912,11 +1915,11 @@
 
 
 DEFUN ("w32-get-default-locale-id", Fw32_get_default_locale_id, Sw32_get_default_locale_id, 0, 1, 0,
-  "Return Windows locale id for default locale setting.\n\
-By default, the system default locale setting is returned; if the optional\n\
-parameter USERP is non-nil, the user default locale setting is returned.\n\
-This is a numerical value; use `w32-get-locale-info' to convert to a\n\
-human-readable form.")
+       doc: /* Return Windows locale id for default locale setting.
+By default, the system default locale setting is returned; if the optional
+parameter USERP is non-nil, the user default locale setting is returned.
+This is a numerical value; use `w32-get-locale-info' to convert to a
+human-readable form.  */)
      (userp)
      Lisp_Object userp;
 {
@@ -1927,8 +1930,8 @@
 
   
 DEFUN ("w32-set-current-locale", Fw32_set_current_locale, Sw32_set_current_locale, 1, 1, 0,
-  "Make Windows locale LCID be the current locale setting for Emacs.\n\
-If successful, the new locale id is returned, otherwise nil.")
+       doc: /* Make Windows locale LCID be the current locale setting for Emacs.
+If successful, the new locale id is returned, otherwise nil.  */)
      (lcid)
      Lisp_Object lcid;
 {
@@ -1960,8 +1963,9 @@
   return TRUE;
 }
 
-DEFUN ("w32-get-valid-codepages", Fw32_get_valid_codepages, Sw32_get_valid_codepages, 0, 0, 0,
-  "Return list of all valid Windows codepages.")
+DEFUN ("w32-get-valid-codepages", Fw32_get_valid_codepages,
+       Sw32_get_valid_codepages, 0, 0, 0,
+       doc: /* Return list of all valid Windows codepages.  */)
      ()
 {
   Vw32_valid_codepages = Qnil;
@@ -1973,18 +1977,20 @@
 }
 
 
-DEFUN ("w32-get-console-codepage", Fw32_get_console_codepage, Sw32_get_console_codepage, 0, 0, 0,
-  "Return current Windows codepage for console input.")
+DEFUN ("w32-get-console-codepage", Fw32_get_console_codepage,
+       Sw32_get_console_codepage, 0, 0, 0,
+       doc: /* Return current Windows codepage for console input.  */)
      ()
 {
   return make_number (GetConsoleCP ());
 }
 
   
-DEFUN ("w32-set-console-codepage", Fw32_set_console_codepage, Sw32_set_console_codepage, 1, 1, 0,
-  "Make Windows codepage CP be the current codepage setting for Emacs.\n\
-The codepage setting affects keyboard input and display in tty mode.\n\
-If successful, the new CP is returned, otherwise nil.")
+DEFUN ("w32-set-console-codepage", Fw32_set_console_codepage,
+       Sw32_set_console_codepage, 1, 1, 0,
+       doc: /* Make Windows codepage CP be the current codepage setting for Emacs.
+The codepage setting affects keyboard input and display in tty mode.
+If successful, the new CP is returned, otherwise nil.  */)
      (cp)
      Lisp_Object cp;
 {
@@ -2000,18 +2006,20 @@
 }
 
 
-DEFUN ("w32-get-console-output-codepage", Fw32_get_console_output_codepage, Sw32_get_console_output_codepage, 0, 0, 0,
-  "Return current Windows codepage for console output.")
+DEFUN ("w32-get-console-output-codepage", Fw32_get_console_output_codepage,
+       Sw32_get_console_output_codepage, 0, 0, 0,
+       doc: /* Return current Windows codepage for console output.  */)
      ()
 {
   return make_number (GetConsoleOutputCP ());
 }
 
   
-DEFUN ("w32-set-console-output-codepage", Fw32_set_console_output_codepage, Sw32_set_console_output_codepage, 1, 1, 0,
-  "Make Windows codepage CP be the current codepage setting for Emacs.\n\
-The codepage setting affects keyboard input and display in tty mode.\n\
-If successful, the new CP is returned, otherwise nil.")
+DEFUN ("w32-set-console-output-codepage", Fw32_set_console_output_codepage,
+       Sw32_set_console_output_codepage, 1, 1, 0,
+       doc: /* Make Windows codepage CP be the current codepage setting for Emacs.
+The codepage setting affects keyboard input and display in tty mode.
+If successful, the new CP is returned, otherwise nil.  */)
      (cp)
      Lisp_Object cp;
 {
@@ -2027,9 +2035,10 @@
 }
 
 
-DEFUN ("w32-get-codepage-charset", Fw32_get_codepage_charset, Sw32_get_codepage_charset, 1, 1, 0,
-  "Return charset of codepage CP.\n\
-Returns nil if the codepage is not valid.")
+DEFUN ("w32-get-codepage-charset", Fw32_get_codepage_charset,
+       Sw32_get_codepage_charset, 1, 1, 0,
+       doc: /* Return charset of codepage CP.
+Returns nil if the codepage is not valid.  */)
      (cp)
      Lisp_Object cp;
 {
@@ -2047,9 +2056,10 @@
 }
 
 
-DEFUN ("w32-get-valid-keyboard-layouts", Fw32_get_valid_keyboard_layouts, Sw32_get_valid_keyboard_layouts, 0, 0, 0,
-  "Return list of Windows keyboard languages and layouts.\n\
-The return value is a list of pairs of language id and layout id.")
+DEFUN ("w32-get-valid-keyboard-layouts", Fw32_get_valid_keyboard_layouts,
+       Sw32_get_valid_keyboard_layouts, 0, 0, 0,
+       doc: /* Return list of Windows keyboard languages and layouts.
+The return value is a list of pairs of language id and layout id.  */)
      ()
 {
   int num_layouts = GetKeyboardLayoutList (0, NULL);
@@ -2072,9 +2082,10 @@
 }
 
 
-DEFUN ("w32-get-keyboard-layout", Fw32_get_keyboard_layout, Sw32_get_keyboard_layout, 0, 0, 0,
-  "Return current Windows keyboard language and layout.\n\
-The return value is the cons of the language id and the layout id.")
+DEFUN ("w32-get-keyboard-layout", Fw32_get_keyboard_layout,
+       Sw32_get_keyboard_layout, 0, 0, 0,
+       doc: /* Return current Windows keyboard language and layout.
+The return value is the cons of the language id and the layout id.  */)
      ()
 {
   DWORD kl = (DWORD) GetKeyboardLayout (dwWindowsThreadId);
@@ -2084,10 +2095,11 @@
 }
 
   
-DEFUN ("w32-set-keyboard-layout", Fw32_set_keyboard_layout, Sw32_set_keyboard_layout, 1, 1, 0,
-  "Make LAYOUT be the current keyboard layout for Emacs.\n\
-The keyboard layout setting affects interpretation of keyboard input.\n\
-If successful, the new layout id is returned, otherwise nil.")
+DEFUN ("w32-set-keyboard-layout", Fw32_set_keyboard_layout,
+       Sw32_set_keyboard_layout, 1, 1, 0,
+       doc: /* Make LAYOUT be the current keyboard layout for Emacs.
+The keyboard layout setting affects interpretation of keyboard input.
+If successful, the new layout id is returned, otherwise nil.  */)
      (layout)
      Lisp_Object layout;
 {
@@ -2150,75 +2162,75 @@
   defsubr (&Sw32_set_keyboard_layout);
 
   DEFVAR_LISP ("w32-quote-process-args", &Vw32_quote_process_args,
-    "Non-nil enables quoting of process arguments to ensure correct parsing.\n\
-Because Windows does not directly pass argv arrays to child processes,\n\
-programs have to reconstruct the argv array by parsing the command\n\
-line string.  For an argument to contain a space, it must be enclosed\n\
-in double quotes or it will be parsed as multiple arguments.\n\
-\n\
-If the value is a character, that character will be used to escape any\n\
-quote characters that appear, otherwise a suitable escape character\n\
-will be chosen based on the type of the program.");
+	       doc: /* Non-nil enables quoting of process arguments to ensure correct parsing.
+Because Windows does not directly pass argv arrays to child processes,
+programs have to reconstruct the argv array by parsing the command
+line string.  For an argument to contain a space, it must be enclosed
+in double quotes or it will be parsed as multiple arguments.
+
+If the value is a character, that character will be used to escape any
+quote characters that appear, otherwise a suitable escape character
+will be chosen based on the type of the program.  */);
   Vw32_quote_process_args = Qt;
 
   DEFVAR_LISP ("w32-start-process-show-window",
 	       &Vw32_start_process_show_window,
-    "When nil, new child processes hide their windows.\n\
-When non-nil, they show their window in the method of their choice.\n\
-This variable doesn't affect GUI applications, which will never be hidden.");
+	       doc: /* When nil, new child processes hide their windows.
+When non-nil, they show their window in the method of their choice.
+This variable doesn't affect GUI applications, which will never be hidden.  */);
   Vw32_start_process_show_window = Qnil;
 
   DEFVAR_LISP ("w32-start-process-share-console",
 	       &Vw32_start_process_share_console,
-    "When nil, new child processes are given a new console.\n\
-When non-nil, they share the Emacs console; this has the limitation of\n\
-allowing only only DOS subprocess to run at a time (whether started directly\n\
-or indirectly by Emacs), and preventing Emacs from cleanly terminating the\n\
-subprocess group, but may allow Emacs to interrupt a subprocess that doesn't\n\
-otherwise respond to interrupts from Emacs.");
+	       doc: /* When nil, new child processes are given a new console.
+When non-nil, they share the Emacs console; this has the limitation of
+allowing only only DOS subprocess to run at a time (whether started directly
+or indirectly by Emacs), and preventing Emacs from cleanly terminating the
+subprocess group, but may allow Emacs to interrupt a subprocess that doesn't
+otherwise respond to interrupts from Emacs.  */);
   Vw32_start_process_share_console = Qnil;
 
   DEFVAR_LISP ("w32-start-process-inherit-error-mode",
 	       &Vw32_start_process_inherit_error_mode,
-    "When nil, new child processes revert to the default error mode.\n\
-When non-nil, they inherit their error mode setting from Emacs, which stops\n\
-them blocking when trying to access unmounted drives etc.");
+	       doc: /* When nil, new child processes revert to the default error mode.
+When non-nil, they inherit their error mode setting from Emacs, which stops
+them blocking when trying to access unmounted drives etc.  */);
   Vw32_start_process_inherit_error_mode = Qt;
 
   DEFVAR_INT ("w32-pipe-read-delay", &Vw32_pipe_read_delay,
-    "Forced delay before reading subprocess output.\n\
-This is done to improve the buffering of subprocess output, by\n\
-avoiding the inefficiency of frequently reading small amounts of data.\n\
-\n\
-If positive, the value is the number of milliseconds to sleep before\n\
-reading the subprocess output.  If negative, the magnitude is the number\n\
-of time slices to wait (effectively boosting the priority of the child\n\
-process temporarily).  A value of zero disables waiting entirely.");
+	      doc: /* Forced delay before reading subprocess output.
+This is done to improve the buffering of subprocess output, by
+avoiding the inefficiency of frequently reading small amounts of data.
+
+If positive, the value is the number of milliseconds to sleep before
+reading the subprocess output.  If negative, the magnitude is the number
+of time slices to wait (effectively boosting the priority of the child
+process temporarily).  A value of zero disables waiting entirely.  */);
   Vw32_pipe_read_delay = 50;
 
   DEFVAR_LISP ("w32-downcase-file-names", &Vw32_downcase_file_names,
-    "Non-nil means convert all-upper case file names to lower case.\n\
-This applies when performing completions and file name expansion.\n\
-Note that the value of this setting also affects remote file names,\n\
-so you probably don't want to set to non-nil if you use case-sensitive\n\
-filesystems via ange-ftp."); 
+	       doc: /* Non-nil means convert all-upper case file names to lower case.
+This applies when performing completions and file name expansion.
+Note that the value of this setting also affects remote file names,
+so you probably don't want to set to non-nil if you use case-sensitive
+filesystems via ange-ftp.  */); 
   Vw32_downcase_file_names = Qnil;
 
 #if 0
   DEFVAR_LISP ("w32-generate-fake-inodes", &Vw32_generate_fake_inodes,
-    "Non-nil means attempt to fake realistic inode values.\n\
-This works by hashing the truename of files, and should detect \n\
-aliasing between long and short (8.3 DOS) names, but can have\n\
-false positives because of hash collisions.  Note that determing\n\
-the truename of a file can be slow.");
+	       doc: /* Non-nil means attempt to fake realistic inode values.
+This works by hashing the truename of files, and should detect
+aliasing between long and short (8.3 DOS) names, but can have
+false positives because of hash collisions.  Note that determing
+the truename of a file can be slow.  */);
   Vw32_generate_fake_inodes = Qnil;
 #endif
 
   DEFVAR_LISP ("w32-get-true-file-attributes", &Vw32_get_true_file_attributes,
-    "Non-nil means determine accurate link count in file-attributes.\n\
-This option slows down file-attributes noticeably, so is disabled by\n\
-default.  Note that it is only useful for files on NTFS volumes,\n\
-where hard links are supported.");
+	       doc: /* Non-nil means determine accurate link count in file-attributes.
+This option slows down file-attributes noticeably, so is disabled by
+default.  Note that it is only useful for files on NTFS volumes,
+where hard links are supported.  */);
   Vw32_get_true_file_attributes = Qnil;
 }
 /* end of ntproc.c */

--- a/src/w32select.c	Mon Nov 12 23:49:56 2001 +0000
+++ b/src/w32select.c	Mon Nov 12 23:57:09 2001 +0000
@@ -51,7 +51,7 @@
 
 #if 0
 DEFUN ("w32-open-clipboard", Fw32_open_clipboard, Sw32_open_clipboard, 0, 1, 0,
-       "This opens the clipboard with the given frame pointer.")
+       doc: /* This opens the clipboard with the given frame pointer.  */)
      (frame)
      Lisp_Object frame;
 {
@@ -69,8 +69,10 @@
   return (ok ? frame : Qnil);
 }
 
-DEFUN ("w32-empty-clipboard", Fw32_empty_clipboard, Sw32_empty_clipboard, 0, 0, 0,
-       "This empties the clipboard and assigns ownership to the window which opened the clipboard.")
+DEFUN ("w32-empty-clipboard", Fw32_empty_clipboard,
+       Sw32_empty_clipboard, 0, 0, 0,
+       doc: /* Empty the clipboard.
+Assigns ownership of the clipboard to the window which opened it.  */)
      ()
 {
   BOOL ok = FALSE;
@@ -84,8 +86,9 @@
   return (ok ? Qt : Qnil);
 }
 
-DEFUN ("w32-close-clipboard", Fw32_close_clipboard, Sw32_close_clipboard, 0, 0, 0,
-       "This closes the clipboard.")
+DEFUN ("w32-close-clipboard", Fw32_close_clipboard,
+       Sw32_close_clipboard, 0, 0, 0,
+       doc: /* Close the clipboard.  */)
      ()
 {
   BOOL ok = FALSE;
@@ -101,8 +104,9 @@
 
 #endif
 
-DEFUN ("w32-set-clipboard-data", Fw32_set_clipboard_data, Sw32_set_clipboard_data, 1, 2, 0,
-       "This sets the clipboard data to the given text.")
+DEFUN ("w32-set-clipboard-data", Fw32_set_clipboard_data,
+       Sw32_set_clipboard_data, 1, 2, 0,
+       doc: /* This sets the clipboard data to the given text.  */)
     (string, frame)
     Lisp_Object string, frame;
 {
@@ -248,8 +252,9 @@
   return (ok ? string : Qnil);
 }
 
-DEFUN ("w32-get-clipboard-data", Fw32_get_clipboard_data, Sw32_get_clipboard_data, 0, 1, 0,
-       "This gets the clipboard data in text format.")
+DEFUN ("w32-get-clipboard-data", Fw32_get_clipboard_data,
+       Sw32_get_clipboard_data, 0, 1, 0,
+       doc: /* This gets the clipboard data in text format.  */)
      (frame)
      Lisp_Object frame;
 {
@@ -394,13 +399,13 @@
 /* Support checking for a clipboard selection. */
 
 DEFUN ("x-selection-exists-p", Fx_selection_exists_p, Sx_selection_exists_p,
-  0, 1, 0,
-  "Whether there is an owner for the given X Selection.\n\
-The arg should be the name of the selection in question, typically one of\n\
-the symbols `PRIMARY', `SECONDARY', or `CLIPBOARD'.\n\
-\(Those are literal upper-case symbol names, since that's what X expects.)\n\
-For convenience, the symbol nil is the same as `PRIMARY',\n\
-and t is the same as `SECONDARY'.")
+       0, 1, 0,
+       doc: /* Whether there is an owner for the given X Selection.
+The arg should be the name of the selection in question, typically one of
+the symbols `PRIMARY', `SECONDARY', or `CLIPBOARD'.
+\(Those are literal upper-case symbol names, since that's what X expects.)
+For convenience, the symbol nil is the same as `PRIMARY',
+and t is the same as `SECONDARY'.  */)
   (selection)
      Lisp_Object selection;
 {
@@ -442,18 +447,17 @@
   defsubr (&Sx_selection_exists_p);
 
   DEFVAR_LISP ("selection-coding-system", &Vselection_coding_system,
-    "Coding system for communicating with other X clients.\n\
-When sending or receiving text via cut_buffer, selection, and clipboard,\n\
-the text is encoded or decoded by this coding system.\n\
-A default value is `compound-text'");
+	       doc: /* Coding system for communicating with other programs.
+When sending or receiving text via cut_buffer, selection, and clipboard,
+the text is encoded or decoded by this coding system.  */);
   Vselection_coding_system=intern ("iso-latin-1-dos");
 
   DEFVAR_LISP ("next-selection-coding-system", &Vnext_selection_coding_system,
-    "Coding system for the next communication with other X clients.\n\
-Usually, `selection-coding-system' is used for communicating with\n\
-other X clients.   But, if this variable is set, it is used for the\n\
-next communication only.   After the communication, this variable is\n\
-set to nil.");
+	       doc: /* Coding system for the next communication with other programs.
+Usually, `selection-coding-system' is used for communicating with
+other programs.   But, if this variable is set, it is used for the
+next communication only.   After the communication, this variable is
+set to nil.  */);
   Vnext_selection_coding_system = Qnil;
 
   QCLIPBOARD = intern ("CLIPBOARD");	staticpro (&QCLIPBOARD);

--- a/src/w32term.c	Mon Nov 12 23:49:56 2001 +0000
+++ b/src/w32term.c	Mon Nov 12 23:57:09 2001 +0000
@@ -10925,43 +10925,43 @@
 
   DEFVAR_INT ("w32-num-mouse-buttons",
 	      &Vw32_num_mouse_buttons,
-	      "Number of physical mouse buttons.");
+	      doc: /* Number of physical mouse buttons.  */);
   Vw32_num_mouse_buttons = Qnil;
 
   DEFVAR_LISP ("w32-swap-mouse-buttons",
 	      &Vw32_swap_mouse_buttons,
-	      "Swap the mapping of middle and right mouse buttons.\n\
-When nil, middle button is mouse-2 and right button is mouse-3.");
+	       doc: /* Swap the mapping of middle and right mouse buttons.
+When nil, middle button is mouse-2 and right button is mouse-3.  */);
   Vw32_swap_mouse_buttons = Qnil;
 
   DEFVAR_LISP ("w32-grab-focus-on-raise",
 	       &Vw32_grab_focus_on_raise,
-	       "Raised frame grabs input focus.\n\
-When t, `raise-frame' grabs input focus as well.  This fits well\n\
-with the normal Windows click-to-focus policy, but might not be\n\
-desirable when using a point-to-focus policy.");
+	       doc: /* Raised frame grabs input focus.
+When t, `raise-frame' grabs input focus as well.  This fits well
+with the normal Windows click-to-focus policy, but might not be
+desirable when using a point-to-focus policy.  */);
   Vw32_grab_focus_on_raise = Qt;
 
   DEFVAR_LISP ("w32-capslock-is-shiftlock",
 	       &Vw32_capslock_is_shiftlock,
-	       "Apply CapsLock state to non character input keys.\n\
-When nil, CapsLock only affects normal character input keys.");
+	       doc: /* Apply CapsLock state to non character input keys.
+When nil, CapsLock only affects normal character input keys.  */);
   Vw32_capslock_is_shiftlock = Qnil;
 
   DEFVAR_LISP ("w32-recognize-altgr",
 	       &Vw32_recognize_altgr,
-	       "Recognize right-alt and left-ctrl as AltGr.\n\
-When nil, the right-alt and left-ctrl key combination is\n\
-interpreted normally."); 
+	       doc: /* Recognize right-alt and left-ctrl as AltGr.
+When nil, the right-alt and left-ctrl key combination is
+interpreted normally.  */); 
   Vw32_recognize_altgr = Qt;
 
   DEFVAR_BOOL ("w32-enable-unicode-output",
                &w32_enable_unicode_output,
-               "Enable the use of Unicode for text output if non-nil.\n\
-Unicode output may prevent some third party applications for displaying\n\
-Far-East Languages on Windows 95/98 from working properly.\n\
-NT uses Unicode internally anyway, so this flag will probably have no\n\
-affect on NT machines.");
+               doc: /* Enable the use of Unicode for text output if non-nil.
+Unicode output may prevent some third party applications for displaying
+Far-East Languages on Windows 95/98 from working properly.
+NT uses Unicode internally anyway, so this flag will probably have no
+affect on NT machines.  */);
   w32_enable_unicode_output = 1;
 
   help_echo = Qnil;
@@ -10975,23 +10975,23 @@
   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.");
+	       doc: /* *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;
 
 #if 0 /* TODO: Setting underline position from font properties.  */
   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.");
+	       doc: /* *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;
 #endif
 
   DEFVAR_LISP ("x-toolkit-scroll-bars", &Vx_toolkit_scroll_bars,
-    "If not nil, Emacs uses toolkit scroll bars.");
+	       doc: /* If not nil, Emacs uses toolkit scroll bars.  */);
   Vx_toolkit_scroll_bars = Qt;
 
   staticpro (&last_mouse_motion_frame);