Re: icon-title-format vs. frame-title-format (Bug#61496)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 5 May 2023 12:40:37 +0200
> From: Tobias Bading <tbading@web.de>
> 
> Oh god, what have I done? XD
> [...]
> What were we talking about again?
> Right, that frame-title-format doc string… XD
> I didn’t intend to start a mega-thread about terminology. If Emacs doc
> strings had see-also sections I would have simply asked to please put a
> “See also: icon-title-format” into frame-title-format’s doc string.
> I’m happy with the added (setq icon-title-format t) in my ~/.emacs, which
> made Emacs 29 behave like Emacs 26.3. I just thought a little hint in the
> doc string might help other people who upgrade their Emacs like me and
> wonder about those changing window titles.

Something to consider when you post a message about some minor (in
this case, really minuscule) issue.  There's a lesson to be learned
here, I think.

Bottom line: from my POV, there's nothing wrong with our doc strings.
icon-title-format has a reference to frame-title-format, and there's a
reason for that.  There's no reason for the reverse reference, so we
don't have it.

Blindly adding a "see also" for every possible subject under the sun
is not something we do, and should not do.  References should be
instrumental, focused, and to the point, otherwise they are just a
distraction and a cause for user frustration.

The manual, OTOH, shows a broader picture, and thus describes both of
them, and provides some context which allows the reader to understand
the logic behind having both.  The right way of using the Emacs
documentation is to start with doc strings (perhaps via apropos
commands), then look in the manual if the issue is still not clear or
if there's a need for deeper, more comprehensive understanding of the
issue and its aspects.

Expecting the doc strings to answer all the questions and include all
the references to all the possible tangents is impractical.