Subject: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual

From: Eli Zaretskii <[email-masked]>
Date: Sat, 23 Aug 2025 17:13:38 +0300

> From: Roi Martin <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 23 Aug 2025 15:29:50 +0200
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> > I'd like first to see if this is used widely enough to warrant being
> > mentioned in the manual.  How about asking on help-gnu-emacs or via
> > Reddit?
> 
> What would you ask specifically?

"Who uses this?: sounds like a good starting point.

> Also, given that the feature is already in core, what are the criteria
> for deciding what goes in the manual and what does not?

It's a judgment call.  Features that are minor and rarely used are not
in the manual.

> This specific
> feature provides user-facing commands and variables, where should I
> document the details?  Only in the corresponding doc strings?

Yes.  Emacs has commands to search the doc strings, so not everything
must be in the manual.

> What about users who are not aware of the concept?

How would they find it in the manual, if they are not aware of the
concept?  No one reads the manual start to end, because it is huge.

> I'm just asking to have a better understanding that I can apply to
> future patches.

I understand.

> In any case, my main goal is for the information about the feature to be
> self-contained.  I don't want to depend on external URLs, which can
> change or stop working (actually, one of the referenced sites was down
> recently).  Can I use the doc string of `fill-region-as-paragraph-semlf'
> for that?

Yes, you can.  But there's nothing wrong in principle in pointing to
external URLs, when we implement features whose definition is external
to Emacs.  If the URL becomes invalid, we will update it when we know
it became invalid.