Re: master 72b1379f079: Increase `emacs-lisp-docstring-fill-column` to 72

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> of which criticism is met by an ultimatum to either complete a
> task that stands little chance of success (designing and securing the
> universal adoption of a new doc string format),

It seems like you think I didn't mean what I said, or in other words
that I wasn't replying honestly.  That's not the case.

IIUC, the problem you seem to be concerned about is that Emacs doesn't
wrap docstrings on narrow displays (mobile phones).  We seem to agree
that this is not currently supported.

The claim that wrapping docstrings to 65 characters in any way solves
that problem is just wrong.  It is the same as ignoring the problem,
perhaps simply because it happened to work on the one screen we bothered
to test with (using some font and font size, letter spacing, etc.).

I described the only solution I see, which is a new docstring format.
Designing a new docstring format is obviously not a small task, but it
would have many important benefits.

It's quite a big blemish that for an editor that prides itself on its
high quality documentation to have such a limited markup for docstrings.
Our docstring format does have one important upside: its relative
simplicity.  But IME it's only simple for the simple cases.  It was
probably not too bad at some point in the past, but the world in 2024
looks very different, and users expect more.

The markup itself is more like a bunch of cobbled together hacks that
have amassed organically over years than a proper markup language.
It doesn't only lack important features like word wrapping, but also:

  - bold, italic, etc.
  - lists (numbers and bullets)
  - variable width text
  - tables
  - semantically marking arguments
  - proper hyperlinks
  - an actually good way to markup keybindings and commands
  - maybe dividers and subheaders
  - etc.

This project has the potential to make our help system better for users
and developers, more consistent, easier to navigate, and so on and so
forth.  I think it's a very worthy endeavor.

> In truth, there has been _nothing_ to suggest that the
> width of doc strings has inconvenienced our users in any manner,

Increasing the fill column for docstrings will not inconvenience users
more than the current default does.

Also, knowing Emacs, the overwhelming majority of docstrings are likely
to continue being wrapped to 65 characters for years to come.  I expect
that we will have a new docstring format long before they are all
rewrapped.