RE: Fontless Info

["Drew Adams" <drew.adams@oracle.com>]

> > 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.