From: "Drew Adams" <drew.adams@oracle.com>
To: "'Alan Mackenzie'" <acm@muc.de>
Cc: 'Eli Zaretskii' <eliz@gnu.org>,
emacs-devel@gnu.org, aidalgol@no8wireless.co.nz,
'Tassilo Horn' <tsdh@gnu.org>
Subject: RE: Fontless Info
Date: Tue, 19 Feb 2013 20:02:56 -0800 [thread overview]
Message-ID: <BFEE3B939DAD4DFCBABF42BE85EA4EA4@us.oracle.com> (raw)
In-Reply-To: <20130219232347.GC4377@acm.acm>
> > Our help system sends the user on a wild goose chase here.
> > S?he has no hope of reorientation and finding a way out
> > of the swamp. You can't get there from here.
>
> I agree with you, here. However, that info, "font-core.el"
> needs to be in the C-h f somewhere, since that is where the
> macro invocation is that generated
> `global-font-lock-mode-check-buffers'. But information is
> missing, more precisely, that that defun was generated by
> the macro define-globalized-minor-mode.
Yes, that's the info missing. More precisely, that that function is created in
the process of defining globalized minor mode whatever.
At least it is good that the link takes you to the right place. That in itself
is a strong hint that maybe the `define-globalized-mode' also creates this
function.
> May I suggest, even request, that you specify what the
> information from C-h f should look like,
See previous - say that it is defined as part of the process of defining the
mode. And say what its relation is to the mode: it is a helper function that
does...
The description of what the function does, including how it is related to the
particular mode, could be added to the doc generated doc string.
But the `C-h f' info that introduces that doc, and which describes the location
of the definition, should mention that it is defined in the process of defining
the mode by `define-globalized-minor-mode.
Or some such. The point is to add both: (a) some orientation info on where to
find the definition (i.e., the fact that it gets defined as part of the mode
definition) and (b) info about the relation of the generated function to the
mode - what it does for the mode etc.
> and perhaps even extend the infrastructure to implement it.
Someone else will need to do that, I'm afraid.
> > Emacs seems to be little-by-little losing its character of being
> > self-documenting, by the use more and more of macros that
> > generate functions without doc. And by the use more and more
> > of `defstruct' without providing doc for accessor etc.
> > functions. Dommage.
>
> > At the very least..., the doc for `define-globalized-minor-mode'
> > should mention the objects that it creates, such as function
> > `MODE-check-buffers'.
>
> This is partly done, in that a doc string for the global minor mode
> function is generated, even if not for the helper functions.
Yes, but that generated mode doc string does not mention the helper functions.
The doc string for the mode should mention its associated functions, just like
the doc for a defstruct should mention its helper functions.
And the doc for each helper function should mention what it helps, and how.
This is part of describing what it's for, what it does.
> > > Since the voodoo of easy-mmode is beyond me, I'll let
> > > others fix this.
>
> > Hear, hear. "Easy", indeed. Easy for those defining
> > things, perhaps. Hard on Emacs users. Dommage.
>
> Shame indeed, but not beyond repair.
That's good to hear.
next prev parent reply other threads:[~2013-02-20 4:02 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-02-19 8:01 Fontless Info Aidan Gauland
2013-02-19 10:16 ` Tassilo Horn
2013-02-19 15:00 ` Drew Adams
2013-02-19 16:33 ` Eli Zaretskii
2013-02-19 16:20 ` Eli Zaretskii
2013-02-19 17:58 ` Drew Adams
2013-02-19 18:48 ` Drew Adams
2013-02-19 20:53 ` Eli Zaretskii
2013-02-19 21:05 ` Drew Adams
2013-02-19 21:21 ` Eli Zaretskii
2013-02-19 21:25 ` Drew Adams
2013-02-20 11:08 ` Michael Heerdegen
2013-02-19 21:14 ` Drew Adams
2013-02-19 23:23 ` Alan Mackenzie
2013-02-20 4:02 ` Drew Adams [this message]
2013-02-19 23:10 ` Alan Mackenzie
2013-02-20 10:58 ` Alan Mackenzie
2013-02-23 4:58 ` Dmitry Gutov
2013-02-24 18:08 ` Alan Mackenzie
2013-02-26 5:43 ` Dmitry Gutov
2013-02-19 16:58 ` Glenn Morris
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=BFEE3B939DAD4DFCBABF42BE85EA4EA4@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=acm@muc.de \
--cc=aidalgol@no8wireless.co.nz \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=tsdh@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.