Small edits for lispref/os.texi

* doc/lispref/os.texi (Startup Summary): Copyedits.  Fix startup screen logic.
(Init File): Copyedits.
(Command-Line Arguments): Copyedits.  Do not mention argv alias.

* lisp/startup.el (normal-top-level, command-line, command-line-1):
Give them doc strings.

4 files changed, 71 insertions, 52 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5477da38abe..ce532c27f4d 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-03-26  Glenn Morris  <rgm@gnu.org>
+
+        * os.texi (Startup Summary): Copyedits.  Fix startup screen logic.
+        (Init File): Copyedits.
+        (Command-Line Arguments): Copyedits.  Do not mention argv alias.
+
 2012-03-25  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (Fringes): Note that fringes are shown on graphical
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 2563bc57aef..2571c7b2539 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -110,8 +110,8 @@ compiled into the Emacs executable when it was built.
 It runs the normal hook @code{before-init-hook}.
 
 @item
-If appropriate (e.g., not in batch mode or started as a daemon), it
-creates a graphical frame.
+If appropriate, it creates a graphical frame.  This is not done if the
+options @samp{--batch} or @samp{--daemon} were specified.
 
 @item
 It initializes the initial frame's faces, and sets up the menu bar
@@ -195,7 +195,7 @@ It now exits if the option @code{--batch} was specified.
 
 @item
 If @code{initial-buffer-choice} is a string, it visits the file with
-that name.  Furthermore, if the @samp{*scratch*} buffer exists and is
+that name.  If the @samp{*scratch*} buffer exists and is
 empty, it inserts @code{initial-scratch-message} into that buffer.
 
 @c To make things nice and confusing, the next three items can be
@@ -221,9 +221,9 @@ It runs @code{window-setup-hook}.  @xref{Window Systems}.
 @item
 It displays the @dfn{startup screen}, which is a special buffer that
 contains information about copyleft and basic Emacs usage.  This is
-not done if @code{initial-buffer-choice} or
-@code{inhibit-startup-screen} are @code{nil}, nor if the
-@samp{--no-splash} or @samp{-Q} command-line options were specified.
+not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice}
+are non-@code{nil}, or if the @samp{--no-splash} or @samp{-Q} command-line
+options were specified.
 
 @c End of command-line-1.
 
@@ -267,15 +267,14 @@ aliases for this variable.
 @end defopt
 
 @defopt initial-buffer-choice
-This variable, if non-@code{nil}, determines a file or buffer for
-Emacs to display after starting up, instead of the startup screen.
+If non-@code{nil}, this variable is a string that specifies a file or
+directory for Emacs to display after starting up, instead of the
+startup screen.
 @ignore
 @c I do not think this should be mentioned.  AFAICS it is just a dodge
 @c around inhibit-startup-screen not being settable on a site-wide basis.
 If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. 
 @end ignore
-If its value is a string, that specifies the name of a file for Emacs to
-visit.
 @end defopt
 
 @defopt inhibit-startup-echo-area-message
@@ -365,11 +364,12 @@ Lisp library named @file{default.el}.  Emacs finds this file through
 the standard search path for libraries (@pxref{How Programs Do
 Loading}).  The Emacs distribution does not come with this file; it is
 intended for local customizations.  If the default init file exists,
-it is loaded whenever you start Emacs, except in batch mode or if
-@samp{-q} (or @samp{-Q}) is specified.  But your own personal init
+it is loaded whenever you start Emacs.  But your own personal init
 file, if any, is loaded first; if it sets @code{inhibit-default-init}
 to a non-@code{nil} value, then Emacs does not subsequently load the
-@file{default.el} file.
+@file{default.el} file.  In batch mode, or if you specify @samp{-q}
+(or @samp{-Q}), Emacs loads neither your personal init file nor
+the default init file.
 
   Another file for site-customization is @file{site-start.el}.  Emacs
 loads this @emph{before} the user's init file.  You can inhibit the
@@ -380,6 +380,7 @@ This variable specifies the site-customization file to load before the
 user's init file.  Its normal value is @code{"site-start"}.  The only
 way you can change it with real effect is to do so before dumping
 Emacs.
+@c So why even mention it here.  I imagine it is almost never changed.
 @end defopt
 
   @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
@@ -387,28 +388,27 @@ examples of how to make various commonly desired customizations in your
 @file{.emacs} file.
 
 @defopt inhibit-default-init
-This variable prevents Emacs from loading the default initialization
-library file for your session of Emacs.  If its value is non-@code{nil},
-then the default library is not loaded.  The default value is
-@code{nil}.
+If this variable is non-@code{nil}, it prevents Emacs from loading the
+default initialization library file.  The default value is @code{nil}.
 @end defopt
 
 @defvar before-init-hook
 This normal hook is run, once, just before loading all the init files
-(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+(@file{site-start.el}, your init file, and @file{default.el}).
 (The only way to change it with real effect is before dumping Emacs.)
 @end defvar
 
 @defvar after-init-hook
 This normal hook is run, once, just after loading all the init files
-(the user's init file, @file{default.el}, and/or @file{site-start.el}),
-before loading the terminal-specific library and processing the
-command-line action arguments.
+(@file{site-start.el}, your init file, and @file{default.el}),
+before loading the terminal-specific library (if started on a text
+terminal) and processing the command-line action arguments.
 @end defvar
 
 @defvar emacs-startup-hook
 This normal hook is run, once, just after handling the command line
-arguments, just before @code{term-setup-hook}.
+arguments, just before @code{term-setup-hook}.  In batch mode, Emacs
+does not run either of these hooks.
 @end defvar
 
 @defvar user-init-file
@@ -419,7 +419,7 @@ the value refers to the corresponding source file.
 
 @defvar user-emacs-directory
 This variable holds the name of the @file{.emacs.d} directory.  It is
-ordinarily @file{~/.emacs.d}, but differs on some platforms.
+@file{~/.emacs.d} on all platforms but MS-DOS.
 @end defvar
 
 @node Terminal-Specific
@@ -442,12 +442,12 @@ set or add to @code{input-decode-map} if the Termcap or Terminfo entry
 does not specify all the terminal's function keys.  @xref{Terminal
 Input}.
 
-  When the name of the terminal type contains a hyphen, and no library
+  When the name of the terminal type contains a hyphen or underscore, and no library
 is found whose name is identical to the terminal's name, Emacs strips
-from the terminal's name the last hyphen and everything that follows
+from the terminal's name the last hyphen or underscore and everything that follows
 it, and tries again.  This process is repeated until Emacs finds a
-matching library, or until there are no more hyphens in the name
-(i.g.@: there is no terminal-specific library).  For example, if the
+matching library, or until there are no more hyphens or underscores in the name
+(i.e.@: there is no terminal-specific library).  For example, if the
 terminal name is @samp{xterm-256color} and there is no
 @file{term/xterm-256color.el} library, Emacs tries to load
 @file{term/xterm.el}.  If necessary, the terminal library can evaluate
@@ -460,10 +460,10 @@ experimenting with your own peculiar customizations.
 
   You can also arrange to override some of the actions of the
 terminal-specific library by setting the variable
-@code{term-setup-hook}.  This is a normal hook which Emacs runs using
-@code{run-hooks} at the end of Emacs initialization, after loading both
-your init file and any terminal-specific libraries.  You can
-use this variable to define initializations for terminals that do not
+@code{term-setup-hook}.  This is a normal hook that Emacs runs
+at the end its initialization, after loading both
+your init file and any terminal-specific libraries.  You could
+use this hook to define initializations for terminals that do not
 have their own libraries.  @xref{Hooks}.
 
 @defvar term-file-prefix
@@ -478,11 +478,9 @@ terminal-specific initialization file as follows:
 @noindent
 You may set the @code{term-file-prefix} variable to @code{nil} in your
 init file if you do not wish to load the
-terminal-initialization file.  To do this, put the following in
-your init file: @code{(setq term-file-prefix nil)}.
+terminal-initialization file.
 
-On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
-uses @samp{internal} as the terminal type.
+On MS-DOS, Emacs sets the @code{TERM} environment variable to @samp{internal}.
 @end defvar
 
 @defvar term-setup-hook
@@ -492,28 +490,27 @@ terminal-specific Lisp file.
 
 You can use @code{term-setup-hook} to override the definitions made by a
 terminal-specific file.
-@end defvar
 
-  See @code{window-setup-hook} in @ref{Window Systems}, for a related
-feature.
+For a related feature, @pxref{Window Systems, window-setup-hook}.
+@end defvar
 
 @node Command-Line Arguments
 @subsection Command-Line Arguments
 @cindex command-line arguments
 
   You can use command-line arguments to request various actions when
-you start Emacs.  Command-line arguments should not be commonly used,
-since the recommended way of using Emacs is to start it just once,
-after logging in, and do all editing in the same Emacs session
-(@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}); nonetheless,
-they can be useful when invoking Emacs from session scripts or
-debugging Emacs itself.  This section describes how Emacs processes
-command-line arguments.
+you start Emacs.  Note that the recommended way of using Emacs is to
+start it just once, after logging in, and then do all editing in the same
+Emacs session (@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}).
+For this reason, you might not use command-line arguments very often;
+nonetheless, they can be useful when invoking Emacs from session
+scripts or debugging Emacs.  This section describes how Emacs
+processes command-line arguments.
 
 @defun command-line
 This function parses the command line that Emacs was called with,
-processes it, loads the user's init file and displays the
-startup messages.
+processes it, and (amongst other things) loads the user's init file and
+displays the startup messages.
 @end defun
 
 @defvar command-line-processed
@@ -529,9 +526,9 @@ to process its new command-line arguments.
 @cindex switches on command line
 @cindex options on command line
 @cindex command-line options
-The value of this variable is an alist of user-defined command-line
-options and associated handler functions.  This variable exists so you
-can add elements to it.
+This variable is an alist of user-defined command-line options and
+associated handler functions.  By default it is empty, but you can
+add elements if you wish.
 
 A @dfn{command-line option} is an argument on the command line, which
 has the form:
@@ -571,7 +568,9 @@ to Emacs.
 @defvar command-line-args-left
 @vindex argv
 The value of this variable is the list of command-line arguments that
-have not yet been processed.  @code{argv} is an alias for this.
+have not yet been processed.
+@c Don't mention this, since it is a "bad name for a dynamically bound variable"
+@c @code{argv} is an alias for this.
 @end defvar
 
 @defvar command-line-functions
@@ -592,7 +591,7 @@ should return a non-@code{nil} value to say it has dealt with that
 argument.  If it has also dealt with some of the following arguments, it
 can indicate that by deleting them from @code{command-line-args-left}.
 
-If all of these functions return @code{nil}, then the argument is used
+If all of these functions return @code{nil}, then the argument is treated
 as a file name to visit.
 @end defvar
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5a0c33da3c8..0903c2c2fd5 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2012-03-26  Glenn Morris  <rgm@gnu.org>
+
+        * startup.el (normal-top-level, command-line, command-line-1):
+        Give them doc strings.
+
 2012-03-25  Eli Zaretskii  <eliz@gnu.org>
 
         * makefile.w32-in (install): Use $(DIRNAME)_same-dir.tst instead
diff --git a/lisp/startup.el b/lisp/startup.el
index 41056f3907e..57d7a74e5ec 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -65,6 +65,8 @@ once you are familiar with the contents of the startup screen."
 
 (defvar startup-screen-inhibit-startup-screen nil)
 
+;; FIXME? Why does this get such weirdly extreme treatment, when the
+;; more important inhibit-startup-screen does not.
 (defcustom inhibit-startup-echo-area-message nil
   "Non-nil inhibits the initial startup echo area message.
 Setting this variable takes effect
@@ -464,6 +466,10 @@ DIRS are relative."
       (setcdr tail (append (mapcar 'expand-file-name dirs) (cdr tail))))))
 
 (defun normal-top-level ()
+  "Emacs calls this function when it first starts up.
+It sets `command-line-processed', processes the command-line,
+reads the initialization files, etc.
+It is the default value of the variable `top-level'."
   (if command-line-processed
       (message "Back to top level.")
     (setq command-line-processed t)
@@ -701,6 +707,8 @@ opening the first frame (e.g. open a connection to an X server).")
 (defvar server-process)
 
 (defun command-line ()
+  "A subroutine of `normal-top-level'.
+Amongst another things, it parses the command-line arguments."
   (setq before-init-time (current-time)
         after-init-time nil
         command-line-default-directory default-directory)
@@ -2076,6 +2084,7 @@ A fancy display is used on graphic displays, normal otherwise."
 (defalias 'display-splash-screen 'display-startup-screen)
 
 (defun command-line-1 (args-left)
+  "A subroutine of `command-line'."
   (display-startup-echo-area-message)
   (when (and pure-space-overflow
              (not noninteractive))