Emacs inventing system documentation

Emacs inventing system documentation

[Reuben Thomas]

I'm using Emacs 21.3.1, and have noticed that from time to time, when I
use M-x man foo RET to get a man page, the man page is displayed along
with a message "foo man page made up". I don't want Emacs inventing man
pages! I'd rather it just displayed the man page I have installed, or gave
an error if it didn't exist.

I must admit that up to now I haven't noticed any differences between the
pages made up by Emacs and those I get from using the "man" command, but I
haven't checked the details. What if Emacs guesses wrongly about some
arcane corner of bash variable expansion? I could end up wasting hours
trying to track down a bug in a script (and even perhaps waste developers'
time by mistakenly reporting a bug in bash) when the real problem is
Emacs's unwilligness or inability to just look at the real man pages.

Is this just a configuration problem? I think I have my MANPATH and so-on
correctly set up. Looking through apropos I notice:

Man-default-man-entry
  Function: Make a guess at a default manual entry.

I'm guessing this function is being run when it shouldn't be.

-- 
http://www.mupsych.org/~rrt/ | impossible, a.  worth doing

Re: Emacs inventing system documentation

[Kevin Rodgers]

Reuben Thomas wrote:

> I'm using Emacs 21.3.1, and have noticed that from time to time, when I
> use M-x man foo RET to get a man page, the man page is displayed along
> with a message "foo man page made up". I don't want Emacs inventing man
> pages! I'd rather it just displayed the man page I have installed, or gave
> an error if it didn't exist.


(Are you joking?  There's no smiley in your message, so I guess you're not.)


That message is displayed by the Man-fontify-manpage function, whose doc
string says:

| Convert overstriking and underlining to the correct fonts.
| Same for the ANSI bold and normal escape sequences.


"Make up" is used here in the publishing sense: converting markup into
presentation.

-- 
Kevin Rodgers

Re: Emacs inventing system documentation

[LEE Sau Dan]

>>>>> "Reuben" == Reuben Thomas <rrt@sc3d.org> writes:

    Reuben> I'm using Emacs 21.3.1, and have noticed that from time to
    Reuben> time, when I use M-x man foo RET to get a man page, the
    Reuben> man page is displayed along with a message "foo man page
    Reuben> made up". I don't want Emacs inventing man pages! I'd
    Reuben> rather it just displayed the man page I have installed, or
    Reuben> gave an error if it didn't exist.

Emacs  doesn't invent the  man page.   M-x man  simply runs  the 'man'
command on your system, grabs its output, and then add the formatting.
If you  don't have a  man page for  command 'foo', Emacs will  give an
error.


    Reuben> I must admit that up to now I haven't noticed any
    Reuben> differences between the pages made up by Emacs and those I
    Reuben> get from using the "man" command, 

Because Emacs runs 'man' to get the page contents.


    Reuben> but I haven't checked the details. 

You should have done so before going out and shouting.


    Reuben> What if Emacs guesses wrongly about some arcane corner of
    Reuben> bash variable expansion? I could end up wasting hours
    Reuben> trying to track down a bug in a script (and even perhaps
    Reuben> waste developers' time by mistakenly reporting a bug in
    Reuben> bash) when the real problem is Emacs's unwilligness or
    Reuben> inability to just look at the real man pages.

The real  problem is your unwillingness  or inability to  just look at
Emac's "man"  buffers and  compare them with  the so called  "real man
pages".


    Reuben> Is this just a configuration problem? 

A configuration in you mind, then.


    Reuben> I think I have my MANPATH and so-on correctly set
    Reuben> up. Looking through apropos I notice:

    Reuben> Man-default-man-entry Function: Make a guess at a default
    Reuben> manual entry.

Read further:

        Make a guess at a default manual entry.
        This guess is based on the text surrounding the cursor.


Now, you  tell me what this  last sentence means,  according to *YOUR*
understand.


    Reuben> I'm guessing this function is being run when it shouldn't
    Reuben> be.

You're making an even worse guess than Emacs.


-- 
Lee Sau Dan                     李守敦(Big5)                    ~{@nJX6X~}(HZ) 

E-mail: danlee@informatik.uni-freiburg.de
Home page: http://www.informatik.uni-freiburg.de/~danlee

Re: Emacs inventing system documentation

[Richard Stallman]

I thought Reuben's message was meant as a humorous
way to report that the term "made up" was not clear.
So I will change it to "formatted for display".

Re: Emacs inventing system documentation

[LEE Sau Dan]

>>>>> "Kevin" == Kevin Rodgers <ihs_4664@yahoo.com> writes:

    Kevin> "Make up" is used here in the publishing sense: converting
    Kevin> markup into presentation.

Or in the cosmetics sense.  :)


-- 
Lee Sau Dan                     李守敦(Big5)                    ~{@nJX6X~}(HZ) 

E-mail: danlee@informatik.uni-freiburg.de
Home page: http://www.informatik.uni-freiburg.de/~danlee

Re: Emacs inventing system documentation

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> I thought Reuben's message was meant as a humorous
> way to report that the term "made up" was not clear.
> So I will change it to "formatted for display".

Oh please don't.  That sounds really too nitpicky.  Just use
"formatted" without any addition if you must.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs inventing system documentation

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> I thought Reuben's message was meant as a humorous
> way to report that the term "made up" was not clear.
> So I will change it to "formatted for display".

The second message in the same function could be changed as well.  The
following patch also fixes one bug (using `frame-width' instead of
`window-width' causes too long lines when window is split
horizontally), and sets `outline-regexp'.

2004-02-18  Juri Linkov  <juri@jurta.org>

	* man.el (Man-fontify-manpage): Clean up message.
	(Man-mode): Set outline-regexp.
	(Man-getpage-in-background): Use window-width instead of
	frame-width.

	* woman.el (woman-decode-region): Use window-width instead of
	frame-width.

Index: emacs/lisp/man.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/man.el,v
retrieving revision 1.131
diff -c -r1.131 man.el
*** emacs/lisp/man.el	24 Jan 2004 21:52:12 -0000	1.131
--- emacs/lisp/man.el	18 Feb 2004 23:43:34 -0000
***************
*** 679,685 ****
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (frame-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
--- 679,685 ----
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (window-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
***************
*** 757,763 ****
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: making up the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
--- 757,763 ----
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: formatting the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
***************
*** 971,976 ****
--- 971,977 ----
    (auto-fill-mode -1)
    (use-local-map Man-mode-map)
    (set-syntax-table man-mode-syntax-table)
+   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
    (Man-build-page-list)
    (Man-strip-page-headers)
    (Man-unindent)
Index: emacs/lisp/woman.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/woman.el,v
retrieving revision 1.18
diff -c -r1.18 woman.el
*** emacs/lisp/woman.el	22 Sep 2003 15:15:26 -0000	1.18
--- emacs/lisp/woman.el	18 Feb 2004 23:43:37 -0000
***************
*** 2204,2210 ****
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (frame-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)
--- 2204,2210 ----
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (window-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)

-- 
http://www.jurta.org/emacs/

Re: Emacs inventing system documentation

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Thu, 18 Feb 2004 23:02:03 +0200
> 
> The following patch also fixes one bug (using `frame-width' instead of
> `window-width' causes too long lines when window is split
> horizontally), and sets `outline-regexp'.

Does that code run before or after Emacs pops up the window where it
displays the formatted man page?  If it runs before the window is
created, it might not be correct to take the value of COLUMNS from
whatever random window you happen to be in at that time.

Re: Emacs inventing system documentation

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Thu, 18 Feb 2004 23:02:03 +0200
>> 
>> The following patch also fixes one bug (using `frame-width' instead of
>> `window-width' causes too long lines when window is split
>> horizontally), and sets `outline-regexp'.
>
> Does that code run before or after Emacs pops up the window where it
> displays the formatted man page?  If it runs before the window is
> created, it might not be correct to take the value of COLUMNS from
> whatever random window you happen to be in at that time.

This code runs before the man page is formatted and displayed, and
we don't know where the page will actually be displayed, so both
frame-width and window-width are incorrect.  But still window-width
is better than frame-width, because it produces more correct results
in one situation and don't make it worse in another.

When window is split horizontally and window configuration is not
changed before the man page window is displayed (by all notify methods
except `newframe' and `bully'), then the result is more correct than
current, where frame-window always causes too wide man pages for
horizontally split windows.

When window is not split or split vertically the result will be
the same as now, because in this case frame-width = window-width.

But for better customization I added a new defcustom Man-column-width
to be able to define desired column width explicitly.  And new
value of woman-fill-frame is added in the woman.el to select
between frame width, window width and column width.

Btw, in the following patch I also added imenu-generic-expression for
Man-mode (it don't call make-local-variable for imenu-generic-expression
because its make-variable-buffer-local is autoloaded from imenu.el)
and added outline-level with the constant first level for all headings.

Index: emacs/lisp/man.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/man.el,v
retrieving revision 1.132
diff -c -r1.132 man.el
*** emacs/lisp/man.el	16 Feb 2004 18:20:31 -0000	1.132
--- emacs/lisp/man.el	20 Feb 2004 00:08:41 -0000
***************
*** 175,180 ****
--- 175,186 ----
  		(const polite) (const quiet) (const meek))
    :group 'man)
  
+ (defcustom Man-column-width 0
+   "*Column width for formatted text.  If value is 0 then either
+ frame width or window width is used."
+   :type 'integer
+   :group 'man)
+ 
  (defcustom Man-frame-parameters nil
    "*Frame parameter list for creating a new frame for a manual page."
    :type 'sexp
***************
*** 679,685 ****
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (frame-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
--- 685,700 ----
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS"
!                       (number-to-string
!                        (cond
!                         ((and (integerp Man-column-width)
!                               (> Man-column-width 0))
!                          Man-column-width)
!                         ((memq Man-notify-method '(newframe bully))
!                          (frame-width))
!                         (t
!                          (window-width)))))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
***************
*** 757,763 ****
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: making up the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
--- 772,778 ----
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: formatting the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
***************
*** 976,981 ****
--- 991,999 ----
    (auto-fill-mode -1)
    (use-local-map Man-mode-map)
    (set-syntax-table man-mode-syntax-table)
+   (setq imenu-generic-expression (list (list nil Man-heading-regexp 0)))
+   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
+   (set (make-local-variable 'outline-level) (lambda () 1))
    (Man-build-page-list)
    (Man-strip-page-headers)
    (Man-unindent)
Index: emacs/lisp/woman.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/woman.el,v
retrieving revision 1.18
diff -c -r1.18 woman.el
*** emacs/lisp/woman.el	22 Sep 2003 15:15:26 -0000	1.18
--- emacs/lisp/woman.el	20 Feb 2004 00:08:45 -0000
***************
*** 807,814 ****
  
  (defcustom woman-fill-frame nil
    ;; Based loosely on a suggestion by Theodore Jump:
!   "*If non-nil then most of the frame width is used."
!   :type 'boolean
    :group 'woman-formatting)
  
  (defcustom woman-default-indent 5
--- 807,818 ----
  
  (defcustom woman-fill-frame nil
    ;; Based loosely on a suggestion by Theodore Jump:
!   "*If nil then `woman-fill-column' is used.
! If non-nil and not `window-width' then most of the frame width is used.
! If value is `window-width' then most of the window width is used."
!   :type '(choice (const :tag "Column" nil)
!                  (const :tag "Window width" window-width)
!                  (other :tag "Frame width" t))
    :group 'woman-formatting)
  
  (defcustom woman-default-indent 5
***************
*** 2204,2210 ****
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (frame-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)
--- 2208,2218 ----
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column
!               (- (if (eq woman-fill-frame 'window-width)
!                      (window-width)
!                    (frame-width))
!                  woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)

-- 
http://www.jurta.org/emacs/

Re: Emacs inventing system documentation

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Fri, 19 Feb 2004 23:57:22 +0200
> 
> This code runs before the man page is formatted and displayed, and
> we don't know where the page will actually be displayed, so both
> frame-width and window-width are incorrect.  But still window-width
> is better than frame-width, because it produces more correct results
> in one situation and don't make it worse in another.

``More correct'' might not be good enough: it could be better for the
situations you tried, but we cannot guarantee it is always better.
That's why it is IMHO wrong to use incorrect methods.

So I think we should come up with a different approach, one that
guarantees that the screen width passed to `man' is the correct one.
Could you please try to think about such a different solution?