Re: lispref gmake info build Error 2 on 11/29/2004 CVS pull

[Luc Teirlinck]

Richard Stallman wrote:

   The bootstrap mechanism should be fixed so that errors in generating
   an Info file don't prevent bootstrapping from finishing.

I am not sure about that.  It would mean that the user might wind up
without some important manuals.  Also, right now, errors in
bootstrapping (with the exception of the one we are talking about) are
usually fixed in a matter of hours, because a maintainer notices or a
user files a bug report.  If an error in the manual only causes some
error messages to be printed, that flash unread across the screen,
like all those tons of other error messages, serious non-deliberate
errors in the manual may remain unnoticed.

There are plenty of known problems with the Elisp and Emacs manuals
that still need to be fixed and that are more serious than the fact
that those two variables are not yet documented.  Why is remembering
those two problems both so unusually difficult and so unusually
important that it is worth disabling building the Elisp manual until
they are fixed?  There are other ways to catalogue and remember what
one still has to do than to cause errors.

If they are so important, why do we not fix them right now?  What
about the following three patches?  It would be good if somebody
really familiar with the frame parameter and variable `line-spacing'
could double check whether the description is 100 percent accurate.
(If not, then the docstring is unclear.)  Even if there would still be
some problems with the patches why do we not comment out these error
producing xrefs, so that people can bootstrap without problems again.
It should not take all eternity to get those two variables documented
properly.  (I believe that the patches below do just that.)

===File ~/man-frames.texi-diff==============================
*** frames.texi 26 Nov 2004 13:39:13 -0600      1.66
--- frames.texi 30 Nov 2004 18:01:53 -0600      
***************
*** 760,773 ****
  argument is positive.  This command applies to all frames, including
  frames yet to be created.  Customize the option @code{scroll-bar-mode}
  to control the use of scroll bars at startup.  You can use it to specify
! that they are placed at the right of windows if you prefer that.  You
! can use the X resource @samp{verticalScrollBars} to control the initial
! setting of Scroll Bar mode similarly.  @xref{Resources}.
  
  @findex toggle-scroll-bar
    To enable or disable scroll bars for just the selected frame, use the
  command @kbd{M-x toggle-scroll-bar}.
  
  @vindex scroll-bar-width
  @cindex width of the scroll bar
    You can control the scroll bar width by changing the value of the
--- 760,781 ----
  argument is positive.  This command applies to all frames, including
  frames yet to be created.  Customize the option @code{scroll-bar-mode}
  to control the use of scroll bars at startup.  You can use it to specify
! that they are placed at the right of windows if you prefer that: the
! possible values are @code{left}, @code{right} and @code{nil} for no
! scroll bar.  You can use the X resource @samp{verticalScrollBars} to
! control the initial setting of Scroll Bar mode similarly.
! @xref{Resources}.
  
  @findex toggle-scroll-bar
    To enable or disable scroll bars for just the selected frame, use the
  command @kbd{M-x toggle-scroll-bar}.
  
+   You can also enable or disable scroll bars for a particular buffer,
+ by setting the variable @code{vertical-scroll-bar}.  This variable
+ automatically becomes buffer-local when set.  The possible values are
+ @code{left}, @code{right}, @code{t}, which means to use the
+ frame's default, and @code{nil} for no scroll bar.
+ 
  @vindex scroll-bar-width
  @cindex width of the scroll bar
    You can control the scroll bar width by changing the value of the
============================================================

===File ~/lispref-frames.texi-diff==========================
*** frames.texi 16 Nov 2004 08:37:08 -0600      1.80
--- frames.texi 30 Nov 2004 17:48:01 -0600      
***************
*** 586,594 ****
  that makes colors darker.  A screen gamma value of 1.5 may give good
  results for LCD color displays.
  
- @item line-spacing
- Additional space put below text lines, in pixels (a positive integer)
- 
  @item wait-for-wm
  If address@hidden, tell Xt to wait for the window manager to confirm
  geometry changes.  Some window managers, including versions of Fvwm2
--- 586,591 ----
***************
*** 603,610 ****
--- 600,623 ----
  application's window.  (It is not certain this will be implemented; try
  it and see if it works.)
  @end ignore
+ 
+ @item line-spacing
+ See the description of the variable @code{line-spacing} below.
  @end table
  
+ @defvar line-spacing
+ @anchor{Definition of line-spacing}
+ Additional space to put below text lines when displaying a buffer.
+ Usually, the value is a positive integer, in which case it specifies
+ the space in pixels.  The value can also be a floating point number,
+ in which case it specifies the space as a multiple of the default
+ frame line height.
+ 
+ This is often set as a frame parameter (see above).  However, if it is
+ set in any other way, it automatically becomes buffer local.  Remember
+ that buffer-local bindings take precedence over frame-local bindings.
+ @end defvar
+  
  @defvar blink-cursor-alist
  This variable specifies how to blink the cursor.  Each element has the
  form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
============================================================

===File ~/locals.texi-diff==================================
*** locals.texi 27 Nov 2004 13:59:31 -0600      1.17
--- locals.texi 30 Nov 2004 18:05:46 -0600      
***************
*** 132,139 ****
  @xref{Display Margins}.
  
  @item line-spacing
! @c Cause an error so we will fix this.
! @xref{Yet to be written}.
  
  @item local-abbrev-table
  @xref{Abbrevs}.
--- 132,138 ----
  @xref{Display Margins}.
  
  @item line-spacing
! @xref{Definition of line-spacing}.
  
  @item local-abbrev-table
  @xref{Abbrevs}.
***************
*** 199,205 ****
  @xref{Mode Line Variables}.
  
  @item vertical-scroll-bar
! @xref{Yet to be written}.
  @end table
  
  @ignore
--- 198,204 ----
  @xref{Mode Line Variables}.
  
  @item vertical-scroll-bar
! @xref{Scroll Bars,,, emacs, The Gnu Emacs Manual}.
  @end table
  
  @ignore
============================================================