Re: function doc string display

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > By convention, the first line of a doc string is supposed to be
  > > a summary.  It can't necessarily even hint at everything pertinent
  > > but it is supposed to provide a conceptual framework for what it does.

  > Historically, the one line could hold a very brief, headline‑style summary 
  > of what the command does adequately.  But, 65-70 characters is not enough 
  > to adequately describe many new commands, especially once you account for 
  > their expansion in behavior.

The reason for the first-line convention is practical: to make it easy
to show a compact list of many commands, using just one line for each,
including a brief description.  If we made these headline‑style
summaries longer, it would not achieve that purpose.

The way to make a short enough summary for a complex command is to
think more abstractly.  The details can go in the rest of the doc
string.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)