Re: Documenting buffer display

[martin rudalics <rudalics@gmx.at>]

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

I could put the last two sections into the "Tips and Conventions"
chapter.  Or do we have another place where to put tutorial-like text?

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

My basic idea was to put the description proper into the first three,
four sections and leave the last two, three sections to those puzzled
by the technical level used in the decription.

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

That's why I chose the present style: The first three, four sections
address the main audience, the people who search for the right tools.
These sections try to be concise and use cross references to lead the
reader right to the tool in question.

The remaining sections are by design not intended for finding tools.
People are supposed to read these sections when they are confused by
the technicality of the previous sections.  The examples are
intentionally not concise - code like

      (display-buffer
       (get-buffer-create "*foo*")
       '((display-buffer-below-selected display-buffer-at-bottom)))

has been written for being evaluated in place so to not confuse
already confused people more by telling them how to create *foo*
first.  I repetitively employ calls of 'display-buffer' and
'customize-set-variable' to emphasize the distinction between how
programmers are supposed to use actions and how users are supposed to
customize them.  So occasionally text in these sections is repetitive.

But asking again: How else would you address a complaint like

   Telling someone that they must instead use
   `display-buffer' ACTION hoops to accomplish
   the same thing leads them down the garden path,
   on a wild goose chase, over the river & through
   the woods, and around Robin Hood's barn.  IMO.

if not with the help of an example where every single step can be
executed right in place and the effect of that step seen right away?

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

I disagree in this particular case.  Readers in a hurry will have
found the necessary information already in the preceding sections.  If
they didn't, we have to fix that in those sections.  Only if they did
but they are still uncertain about how to put their findings into
practice they would go on with the remaining sections.

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

Well, Alan's impression was that

   The doc string of display-buffer is a bit of a heavy read at this time
   of night.

and I'm currently contemplating to remove the description of action
alist entries from it.  'display-buffer' is a function that delegates
its work to action functions (Drew's garden path) and guides the
latter with the help of action alists which have now their separate
entry in the Elisp manual.  The "further down" in the garden path an
information is found, the more Drew will complain.  The "further up"
everybody else will complain.

A couple of weeks ago Drew complained that the doc-string of
'pop-to-buffer-same-window' misses any information about how it
handles dedicated windows.  So you amended the doc-string as follows:

   Unlike `pop-to-buffer', this function prefers using the selected
   window over popping up a new window or frame.  Specifically, if
   the selected window is neither a minibuffer window (as reported
   by `window-minibuffer-p'), nor is dedicated to another buffer
   (see `window-dedicated-p'), BUFFER will be displayed in the
   currently selected window; otherwise it will be displayed in
   another window.

While this would be appropriate for 'switch-to-buffer-other-window' it
may be wrong for 'pop-to-buffer-same-window' as soon as the user has
customized 'display-buffer-alist'.  We can't avoid the garden path of
'display-buffer' here and elsewhere.

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

I see what you mean and it's obvious that the text I wrote takes the
opposite direction.  It tries to segregate the tips from the technical
description rather than to combine them.  The intention was that
experienced readers should be allowed to read the technical sections
without having to study the tips at the same time (or at all).
Confused readers OTOH should be carefully guided to read on, as time
permits.

martin