patch to fill `Parent documentation...' in Customize, plus two related suggestions

* patch to fill `Parent documentation...' in Customize, plus two related suggestions
@ 2007-12-28 19:04 Drew Adams
  2007-12-28 22:47 ` Robert J. Chassell
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Drew Adams @ 2007-12-28 19:04 UTC (permalink / raw)
  To: Emacs-Devel

[-- Attachment #1: Type: text/plain, Size: 3057 bytes --]

1. You can use :link in defgroup to provide links to documentation of the
group. This list of doc links is not filled in the Customize buffer, which
can lead to a long line. That, in turn, can throw off window-fitting and
frame-fitting code, for example, making a Customize frame wider than it
needs to be.

The attached patch fills the line "Parent documentation: ...". It indents
all filled lines except the first by two chars, so the result is like this:

Parent documentation: Doc-Part1, Doc-Part2, Description, Download,
  Related Libraries, and Send Bug Report.

This could perhaps be generalized to fill such lists of links wherever they
appear in Customize, but I have not done that.

2. I don't see why the lists of links `Parent groups:' and `Parent
documentation:' are called that. It seems to me they should be called simply
`Groups:' and `Documentation:'.

For example, if you customize option `foo', which is in groups `group1' and
`group2', then these two link lists refer to the groups that contain `foo'
and to their documentation, not to the parents of those groups. And an
option, such as `foo', has no parents, so it has no parent groups or parent
documentation.

The label `Parent groups' could make sense only when you are visiting a
Customize buffer for a group, not for an option or a face. And even then,
`Documentation' makes more sense than `Parent documentation', it seems to
me.

And when you are visiting a Customize buffer for a group, you don't even see
these labels! Instead, you see `Go to parent group:' and, for the doc links,
`See also '. So, in the only place where "parent" might reasonably be used,
it is not used anyway.

In addition, just as commas are used to separate the doc links, so should
they be used to separate the group links. Currently, only spaces separate
the group links.

3. You'll notice in the above example (#1) that the links do not really need
to be for documentation. Because :link can use `url-link', it can be a link
to anything, not necessarily documentation. I would argue that the Elisp
manual description of :link should not speak only of documentation. It
should simply say what :link really does, but it can mention documentation
as a use-case.

In fact, I'd suggest that the Elisp doc for :link even include an example of
using :link to provide a send-bug-report action, first, because it's useful
and should be encouraged, and second, because it points out that :link is
completely general. Here is such an example - it also shows how to make it a
little more difficult for a Web spider to recognize an email address in a
library file.

  :link `(url-link :tag "Send Bug Report"
          ,(concat "mailto:" "jane.doe" "@" "someplace"
                   ".org?subject=foo.el bug: \
&body=Describe bug here, starting with `emacs -q'.  \
Don't forget to mention your Emacs and Foo library versions."))

Note: In the attached patch, I have not changed anything wrt #2 or #3,
figuring that there might be some discussion of what is best. The patch only
fills the doc-links list (#1).

[-- Attachment #2: cus-edit-2007-12-28.patch --]
[-- Type: application/octet-stream, Size: 1773 bytes --]

*** cus-edit-CVS-2007-12-28.el	Fri Dec 28 09:23:48 2007
--- cus-edit-patched-2007-12-28.el	Fri Dec 28 09:52:52 2007
***************
*** 2267,2273 ****
  	(buttons (widget-get widget :buttons))
  	(start (point))
  	(parents nil))
!     (insert (or initial-string "Parent groups:"))
      (mapatoms (lambda (symbol)
  		(when (member (list name type) (get symbol 'custom-group))
  		  (insert " ")
--- 2267,2273 ----
  	(buttons (widget-get widget :buttons))
  	(start (point))
  	(parents nil))
!     (insert (or initial-string "\nParent groups:"))
      (mapatoms (lambda (symbol)
  		(when (member (list name type) (get symbol 'custom-group))
  		  (insert " ")
***************
*** 2286,2291 ****
--- 2286,2293 ----
  					 (get (car parents) 'custom-links))))
                  (many (> (length links) 2)))
             (when links
+              (let ((pt (point))
+                    (left-margin (+ left-margin 2)))
                 (insert "\nParent documentation: ")
                 (while links
                   (push (widget-create-child-and-convert
***************
*** 2302,2308 ****
                            (insert ", and ")
                          (insert " and ")))
                       (t
!                       (insert ", ")))))))
      (if parents
          (insert "\n")
        (delete-region start (point)))
--- 2304,2312 ----
                              (insert ", and ")
                            (insert " and ")))
                         (t
!                         (insert ", "))))
!                (fill-region-as-paragraph pt (point))
!                (delete-to-left-margin (1+ pt) (+ pt 2))))))
      (if parents
          (insert "\n")
        (delete-region start (point)))

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

^ permalink raw reply	[flat|nested] 7+ messages in thread