* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode,... @ 2011-01-04 21:34 Drew Adams 2011-01-04 23:03 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode, Drew Adams ` (2 more replies) 0 siblings, 3 replies; 7+ messages in thread From: Drew Adams @ 2011-01-04 21:34 UTC (permalink / raw) To: 7783 emacs -Q C-h i, choose Elisp Search for autoload. The first occurrence is `Autoload Type', in subsection `Programming Types'. The second occurrence is `Autoloading', in subsection `Kinds of Forms'. It is supposed to be a node on "Functions set up to load files containing their real definitions" ("their" is not super clear). So the main menu entry for `Autoloading' is that node. Continuing to search in the top-level menu we come to `Autoload' in subsection `Loading'. So we see that there are at least 3 nodes with very similar node names: `Autoload Type', `Autoloading', and `Autoload'. The first part of this bug is that the names should be more specific, referring to the topics of their relative subsections or some other specificity. Next, follow the menu link to node `Autoloading'. It is not, as the main menu said, a node that describes or explains "Functions set up to load files containing their real definitions". It is a node that is nearly vacuous of content. It simply gives some general blah-blah about autoloading and then sends you off to node `Autoload'. So the second part of this bug is to clean this up - either get rid of this node or DTRT wrt its purported topic (and rename it, since the name is too general for the topic). Following that link we finally get to node `Autoload', which is where autoloading is explained. There should be a top-level, main menu entry to this node, and not just a link buried in some subsection (let along 3 links in 3 subsections). Finally, in node `Autoload' we say that these constructs are handled by cookies: "Function-defining forms" include `define-skeleton', `define-derived-mode', `define-generic-mode' and `define-minor-mode' as well as `defun' and `defmacro'. What about `define-globalized-minor-mode'? If that is not handled similarly, then that is a code bug - it should be. If it is handled similarly by a cookie then it should be included in the doc list. Users should not need to consult the source code to try to determine what an autoload cookie before `define-globalized-minor-mode' will do. In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2011-01-03 on 3249CTO Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/imagesupport/include' Important settings: value of $LC_ALL: nil value of $LC_COLLATE: nil value of $LC_CTYPE: nil value of $LC_MESSAGES: nil value of $LC_MONETARY: nil value of $LC_NUMERIC: nil value of $LC_TIME: nil value of $LANG: ENU value of $XMODIFIERS: nil locale-coding-system: cp1252 default enable-multibyte-characters: t Major mode: Info Minor modes in effect: tooltip-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t blink-cursor-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t line-number-mode: t transient-mark-mode: t Recent input: C-h i <tab> <tab> <tab> <tab> <tab> <return> C-s a u t o l o a d C-s <return> <return> l <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <help-echo> <menu-bar> <help-menu> <send-emacs-bug-report> Recent messages: For information about GNU Emacs and the GNU system, type C-h C-a. Composing main Info directory...done Mark saved where search started Load-path shadows: c:/Emacs-24-2011-01-03/lisp/emacs-lisp/sregex hides c:/Emacs-24-2011-01-03/lisp/obsolete/sregex c:/Emacs-24-2011-01-03/lisp/pgg hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg c:/Emacs-24-2011-01-03/lisp/pgg-pgp5 hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-pgp5 c:/Emacs-24-2011-01-03/lisp/pgg-pgp hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-pgp c:/Emacs-24-2011-01-03/lisp/pgg-parse hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-parse c:/Emacs-24-2011-01-03/lisp/pgg-gpg hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-gpg c:/Emacs-24-2011-01-03/lisp/pgg-def hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-def Features: (shadow sort gnus-util mail-extr message rfc822 mml mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mailabbrev mail-utils gmm-utils mailheader emacsbug multi-isearch info easymenu dired regexp-opt tooltip ediff-hook vc-hooks lisp-float-type mwheel dos-w32 disp-table ls-lisp w32-win w32-vars tool-bar dnd fontset image fringe lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev button minibuffer faces cus-face files text-properties overlay md5 base64 format env code-pages mule custom widget hashtable-print-readable backquote make-network-process multi-tty emacs) ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,... 2011-01-04 21:34 bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Drew Adams @ 2011-01-04 23:03 ` Drew Adams 2011-01-05 16:52 ` Eli Zaretskii 2011-01-05 16:49 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Eli Zaretskii 2012-03-10 4:02 ` Chong Yidong 2 siblings, 1 reply; 7+ messages in thread From: Drew Adams @ 2011-01-04 23:03 UTC (permalink / raw) To: 7783 > What about `define-globalized-minor-mode'? If that is not handled > similarly, then that is a code bug - it should be. If it is handled > similarly by a cookie then it should be included in the doc > list. Users should not need to consult the source code to try to > determine what an autoload cookie before > `define-globalized-minor-mode' will do. Likewise `define-widget' and any others. In sum the list in the manual should be complete, so users need not guess what gets handled by an autoload cookie and what does not. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,... 2011-01-04 23:03 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode, Drew Adams @ 2011-01-05 16:52 ` Eli Zaretskii 2011-01-05 18:31 ` Drew Adams 0 siblings, 1 reply; 7+ messages in thread From: Eli Zaretskii @ 2011-01-05 16:52 UTC (permalink / raw) To: Drew Adams; +Cc: 7783 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Tue, 4 Jan 2011 15:03:07 -0800 > Cc: > > > What about `define-globalized-minor-mode'? If that is not handled > > similarly, then that is a code bug - it should be. If it is handled > > similarly by a cookie then it should be included in the doc > > list. Users should not need to consult the source code to try to > > determine what an autoload cookie before > > `define-globalized-minor-mode' will do. > > Likewise `define-widget' and any others. In sum the list in the manual should > be complete, so users need not guess what gets handled by an autoload cookie and > what does not. The text sounds as if the list is exhaustive, so the only issue is whether it is correct or not. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,... 2011-01-05 16:52 ` Eli Zaretskii @ 2011-01-05 18:31 ` Drew Adams 0 siblings, 0 replies; 7+ messages in thread From: Drew Adams @ 2011-01-05 18:31 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 7783 > > > What about `define-globalized-minor-mode'? If that is not handled > > > similarly, then that is a code bug - it should be. If it > > > is handled similarly by a cookie then it should be included in > > > the doc list. Users should not need to consult the source code > > > to try to determine what an autoload cookie before > > > `define-globalized-minor-mode' will do. > > > > Likewise `define-widget' and any others. In sum the list > > in the manual should be complete, so users need not guess what > > gets handled by an autoload cookie and what does not. > > The text sounds as if the list is exhaustive, so the only issue is > whether it is correct or not. Sounds as if...maybe...sort of...depending on the reader. I agree that that is suggested. But it would be clearer if we said explicitly that this is a complete list. But yes, my main concern is that the list be up-to-date (complete). ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode,... 2011-01-04 21:34 bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Drew Adams 2011-01-04 23:03 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode, Drew Adams @ 2011-01-05 16:49 ` Eli Zaretskii 2011-01-05 18:31 ` Drew Adams 2012-03-10 4:02 ` Chong Yidong 2 siblings, 1 reply; 7+ messages in thread From: Eli Zaretskii @ 2011-01-05 16:49 UTC (permalink / raw) To: Drew Adams; +Cc: 7783 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Tue, 4 Jan 2011 13:34:08 -0800 > Cc: > > C-h i, choose Elisp > > Search for autoload. The first occurrence is `Autoload Type', in > subsection `Programming Types'. > > The second occurrence is `Autoloading', in subsection `Kinds of Forms'. > It is supposed to be a node on "Functions set up to load files > containing their real definitions" ("their" is not super clear). > > So the main menu entry for `Autoloading' is that node. > > Continuing to search in the top-level menu we come to `Autoload' in > subsection `Loading'. I presume you searched with `s' or some such. If so, it is unclear why you are doing that, since `i' is so much more efficient (in this case it instantly gets you to the right spot). Using `s' should be Plan B, not the first attempt. (And if Plan B succeeds, a bug report about bad indexing should follow.) > So we see that there are at least 3 nodes with very similar node names: > `Autoload Type', `Autoloading', and `Autoload'. The first part of this > bug is that the names should be more specific, referring to the topics > of their relative subsections or some other specificity. "Autoload Type" sounds appropriate to me -- it is a subsection of "Lisp Data Types". "Autoloading" could be renamed as "Autoload Forms", since it's in the "Kinds of Forms" section, and quite a few of its siblings are named "SOME Forms". As for "Autoload", I'm not sure it's a good idea to rename it, since it describes the `autoload' facility itself. Suggestions for specific node/section names are welcome. > Next, follow the menu link to node `Autoloading'. It is not, as the > main menu said, a node that describes or explains "Functions set up to > load files containing their real definitions". It is a node that is > nearly vacuous of content. It simply gives some general blah-blah about > autoloading and then sends you off to node `Autoload'. So the second > part of this bug is to clean this up - either get rid of this node or > DTRT wrt its purported topic (and rename it, since the name is too > general for the topic). I see no problem with the current organization of the manual. Manuals are for human consumption, so they don't need to mention each feature in only one place. It is perfectly valid practice in manuals to mention shortly something that is only tangentially related to the current main topic, then refer the reader for details to where that something is described in full. In this case, it is in a separate node so that a reader who is not interested could go to the next node without descending through the menu. > Following that link we finally get to node `Autoload', which is where > autoloading is explained. There should be a top-level, main menu entry > to this node, and not just a link buried in some subsection (let along 3 > links in 3 subsections). I see no need for having this in the _main_ menu (it is, of course, present in the detailed menu, below, in the same node). It is impractical to have every single important concept in the main menu, and still produce a manual of a reasonably deep structure. Readers should use `i', not the main menu, to search for specific subjects, that's why we try to invest a significant effort in having good indexing. And in this case, it _is_ good, I think, because it lands you right on target. > Finally, in node `Autoload' we say that these constructs are handled by > cookies: > > "Function-defining forms" include `define-skeleton', > `define-derived-mode', `define-generic-mode' and `define-minor-mode' as > well as `defun' and `defmacro'. > > What about `define-globalized-minor-mode'? If that is not handled > similarly, then that is a code bug - it should be. If it is handled > similarly by a cookie then it should be included in the doc list. Users > should not need to consult the source code to try to determine what > an autoload cookie before `define-globalized-minor-mode' will do. I don't know anything about this part, sorry. Sounds like a separate issue, anyway. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode,... 2011-01-05 16:49 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Eli Zaretskii @ 2011-01-05 18:31 ` Drew Adams 0 siblings, 0 replies; 7+ messages in thread From: Drew Adams @ 2011-01-05 18:31 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 7783 > I presume you searched with `s' or some such. If so, it is unclear > why you are doing that, since `i' is so much more efficient (in this > case it instantly gets you to the right spot). Using `s' should be > Plan B, not the first attempt. (And if Plan B succeeds, a bug report > about bad indexing should follow.) Don't worry so much about why I'm doing that. I mentioned that only as part of the bug report recipe, for _you_ to find the menu links I wanted to discuss. I could have mentioned `m' instead. At first I in fact wrote "scroll down to..." in the recipe. The point was to have you see the context and find the occurrences easily. I use `i' always as my first resort, thank you. (FWIW, I use `C-s' if I need to search in Info these days. I use `s' only in older Emacs versions that do not support `C-s' across nodes.) > I see no problem with the current organization of the manual. Good for you. > > Finally, in node `Autoload' we say that these constructs > > are handled by cookies: > > > > "Function-defining forms" include `define-skeleton', > > `define-derived-mode', `define-generic-mode' and > > `define-minor-mode' as well as `defun' and `defmacro'. > > > > What about `define-globalized-minor-mode'? If that is not handled > > similarly, then that is a code bug - it should be. If it is handled > > similarly by a cookie then it should be included in the doc > > list. Users should not need to consult the source code to try > > to determine what an autoload cookie before > > `define-globalized-minor-mode' will do. > > I don't know anything about this part, sorry. Sounds like a separate > issue, anyway. Separate from what? This is the _reason_ for this bug report. The doc about autoloading does not tell you the latest list of constructs that are supported by autoload cookies. See the Subject line for this report. You say you know nothing about this; fine. Let's hope that someone does and will DTRT. Deciding whether to add an autoload cookie entails knowing how they are handled. You need to know what a cookie will do for a `defcustom' or a top-level sexp such as `(if...)'. That's why such things are documented. E.g., if `define-widget' is not handled specially (is treated essentially like `(if...)'), then a programmer needs to know that, so s?he does not bother (in most cases) to add an autoload cookie for `define-widget'. Only certain defining forms are handled specially by autoload cookies, and they are documented as such. But my impression is that the list might not be up-to-date. To be _completely_ clear it would help for the doc to either also say explicitly which of the defining forms are _not_ handled or else (better, and sufficient) state clearly that the list is complete (exhaustive). ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode,... 2011-01-04 21:34 bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Drew Adams 2011-01-04 23:03 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode, Drew Adams 2011-01-05 16:49 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Eli Zaretskii @ 2012-03-10 4:02 ` Chong Yidong 2 siblings, 0 replies; 7+ messages in thread From: Chong Yidong @ 2012-03-10 4:02 UTC (permalink / raw) To: 7783-done I've checked in a fix which states explicitly which forms are processed specially by the autoload facility. I agree with Eli that the current organization of the nodes is fine, so that's left alone. ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2012-03-10 4:02 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2011-01-04 21:34 bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Drew Adams 2011-01-04 23:03 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode, Drew Adams 2011-01-05 16:52 ` Eli Zaretskii 2011-01-05 18:31 ` Drew Adams 2011-01-05 16:49 ` bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode, Eli Zaretskii 2011-01-05 18:31 ` Drew Adams 2012-03-10 4:02 ` Chong Yidong
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.