Re: Documenting buffer display

[Eli Zaretskii]

> Date: Sat, 20 Oct 2018 20:02:22 +0200
> From: martin rudalics <address@hidden>
> CC: address@hidden
> 
>  > Please consider adding one or more @cindex entries here, so that
>  > readers could get here when they look for topics described in this
>  > section.  Similarly for each of the new subsections.
> 
> I haven't done any indexing yet.  Suggestions, like the ones you
> provide below, are highly welcome.

Will do as the time passes ;-)

>  > I suggest to rewrite this text in terms of what the reader might be
>  > looking for, or as a list of tasks related to the material in the
>  > section.  The way the text is written now, it is an overview of the
>  > topics covered by the section, without any explicit relation to what
>  > the reader may want to do or learn about.  Such "abstract" overviews
>  > are IME much less useful.
> 
> Fully agreed but I ran out of ideas here.  It would be a great help if
> you or anyone else came up with a rough sketch of what to do instead.

For that, I'd need to have a good understanding of the overall
structure of the material.  I don't have that now; I thought you, as
the author, did.  Failing that, we could postpone this issue to later,
it's relatively minor one.

>  >> +* Action Functions::        Support functions for buffer display.
>  >> +* Action Alists::           Alists for fine-tuning buffer display.
>  >
>  > I question the wisdom of removing "Display" from the names of these
>  > nodes.  "Action Functions" and "Action Alists" are IMO too general,
>  > and might clash with some other kind of "actions".
> 
> Agreed.  But IMO "display action function" is even worse because
> "display" has a very different connotation in Emacs.  So I can only
> propose "buffer display action function" or "display buffer action
> function" instead.  WDYT?

I'd go with "Buffer Display Actions" and "Buffer Display Functions".

>  >> address@hidden Action Functions
>  >> address@hidden Action Functions for Buffer Display
>  >
>  > I think @cindex entries here about "action functions" and "display
>  > action functions" are in order.
> 
> They are already indexed in Choosing Window thusly
> 
> @cindex display action
> @cindex action function, for @code{display-buffer}
> @cindex action alist, for @code{display-buffer}
> 
> so you suggest to move the indices to the corresponding sections?

Yes.  Index entries should be where the feature is described in the
most detailed way.  The other places should have cross-references to
that main description.

>  >>   The following basic action functions are defined in Emacs.  Each of
>  >
>  > "Action function" is a term introduced in this section, right?  If so,
>  > its first instance should be in @dfn, and this section should define
>  > the term.
> 
> They are defined in Choosing Window thusly
> 
> Here, @var{function} is either a function or a list of functions,
> which we refer to as @dfn{action functions}; @var{alist} is an
> association list, which we refer to as an @dfn{action alist}.
> 
> so you suggest to move the @dfns to the corresponding sections as well
> and leave only the cross references in Choosing Window?

Yes.

>  >> +to maintain compatibility with code that uses older options like
>  >> address@hidden, @code{pop-up-frames},
>  >> address@hidden, @code{same-window-buffer-names} and
>  >> address@hidden  Applications and users should refrain
>  >
>  > The text below this should have index entries for the obsolete
>  > variables you describe.
> 
> OK (they are not obsolete yet, BTW).

I know.  I meant something like

  @vindex address@hidden, replacement for}

>  > FWIW, I find such tutorial-like style
> 
> I initially wanted to call this section "A Tutorial for ...".

I'm not against tutorials; far from that.  I just think they should be
separate from Reference manuals.  Reference manuals can then point to
tutorials for examples.

But that doesn't mean a Reference manual can consider itself done by
providing a "lip service" in the form of such a tutorial reference.  A
good Reference manual should still describe the feature in a clear and
useful way.

Reference manual's main audience are people who already have some,
perhaps even good, idea about the feature, and need help in finding
exactly the right tools, out of those available, to do the jop at
hand.  Tutorials, by contrast, target newbies who have no clue:
walking those through a large enough set of well-explained examples
will bring them up to speed, so they could proceed to the Reference
manual.

> Readers in a hurry are not supposed to read that section.

I think it's a mistake to take that stand when writing a Reference
manual.

> On this list people have asked for examples quite often.  Roland
> Winkler:
> 
>    The current discussion of 'display-buffer-alist' in the elisp manual
>    appears rather technical, suited only for expert users.  On the
>    other hand, the variable is declared with defcustom, as if
>    individual users should customize it to their personal liking.
> 
> N. Jackson in the same thread:
> 
>    Perhaps `display-buffer-alist' is sufficient for the BBDB case. As
>    its documentation is a little unclear (while recursive code is okay,
>    recursive documentation is a little bit trying), it would be nice to
>    see an example of how this might be done.
> 
> Honestly, I have no idea how to do if not with the help of a detailed
> sequence of examples.

It's not easy, I will give you that.  But that doesn't mean we should
give up.

One thing to remember is that the manual is not the only place where
the documentation could live: there are doc strings as well.  Some of
the details might be better suited to doc strings.

> Maybe some of the tips and tricks I propose here will help Alan to
> avoid sleepless nights (and Stefan when quitting an edebug session
> will yet another time try to restore his window configuration on the
> wrong frame).

I didn't say those tips are useless, far from it.  I just ended up
having an impression that I've read a list of tips that I will have to
re-read again when I need to find something in it.  So I suggested to
think about some way of organizing them, so that similar and related
stuff is closer to one another.

Anyway, I don't want to discourage you by being my usual perfectionist
self.  I think it's great you are working on improving these docs, and
I think we are lucky to have you and your expertise on these matters.
So if you can take anything at all from my comments, I'm happy; the
rest can be improved later, if we find a how.

Thanks.