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/