[Emacs-diffs] /srv/bzr/emacs/trunk r107678: Small edits for lispref/os.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107678
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2012-03-25 17:37:04 -0700
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/os.texi
  lisp/ChangeLog
  lisp/startup.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-25 07:58:59 +0000
+++ b/doc/lispref/ChangeLog     2012-03-26 00:37:04 +0000
@@ -1,3 +1,9 @@
+2012-03-26  Glenn Morris  <address@hidden>
+
+       * 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  <address@hidden>
 
        * display.texi (Fringes): Note that fringes are shown on graphical

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2012-03-20 07:44:03 +0000
+++ b/doc/lispref/os.texi       2012-03-26 00:37:04 +0000
@@ -110,8 +110,8 @@
 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 @@
 
 @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 @@
 @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
address@hidden are @code{nil}, nor if the
address@hidden or @samp{-Q} command-line options were specified.
+not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice}
+are address@hidden, or if the @samp{--no-splash} or @samp{-Q} command-line
+options were specified.
 
 @c End of command-line-1.
 
@@ -267,15 +267,14 @@
 @end defopt
 
 @defopt initial-buffer-choice
-This variable, if address@hidden, determines a file or buffer for
-Emacs to display after starting up, instead of the startup screen.
+If address@hidden, 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 @@
 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
address@hidden (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 address@hidden value, then Emacs does not subsequently load the
address@hidden file.
address@hidden 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 @@
 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.
address@hidden 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 @@
 @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 address@hidden,
-then the default library is not loaded.  The default value is
address@hidden
+If this variable is address@hidden, 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 @@
 
 @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.
address@hidden/.emacs.d} on all platforms but MS-DOS.
 @end defvar
 
 @node Terminal-Specific
@@ -442,12 +442,12 @@
 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 @@
 
   You can also arrange to override some of the actions of the
 terminal-specific library by setting the variable
address@hidden  This is a normal hook which Emacs runs using
address@hidden 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
address@hidden  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 @@
 @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 @@
 
 You can use @code{term-setup-hook} to override the definitions made by a
 terminal-specific file.
+
+For a related feature, @pxref{Window Systems, window-setup-hook}.
 @end defvar
 
-  See @code{window-setup-hook} in @ref{Window Systems}, for a related
-feature.
-
 @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 @@
 @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 @@
 @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.
address@hidden Don't mention this, since it is a "bad name for a dynamically 
bound variable"
address@hidden @code{argv} is an alias for this.
 @end defvar
 
 @defvar command-line-functions
@@ -592,7 +591,7 @@
 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
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-03-25 18:17:46 +0000
+++ b/lisp/ChangeLog    2012-03-26 00:37:04 +0000
@@ -1,3 +1,8 @@
+2012-03-26  Glenn Morris  <address@hidden>
+
+       * startup.el (normal-top-level, command-line, command-line-1):
+       Give them doc strings.
+
 2012-03-25  Eli Zaretskii  <address@hidden>
 
        * makefile.w32-in (install): Use $(DIRNAME)_same-dir.tst instead

=== modified file 'lisp/startup.el'
--- a/lisp/startup.el   2012-01-19 07:21:25 +0000
+++ b/lisp/startup.el   2012-03-26 00:37:04 +0000
@@ -65,6 +65,8 @@
 
 (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 @@
       (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 @@
 (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 @@
 (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))