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

From: Roi Martin <[email-masked]>
Date: Wed, 20 Aug 2025 16:05:54 +0200

Eli Zaretskii <[email-masked]> writes:

> Thanks, but I'm not sure this feature is important enough to have it
> described in so many words in the user manual.

I agree this is a minor feature, which is why I added the documentation
into a subsubsection.  However, I'd like to provide users with
information about what is the meaning of "semantic linefeeds" and how to
use them in Emacs.

I believe that having information about `fill-paragraph-semlf',
`fill-region-as-paragraph-semlf' and `fill-region-as-paragraph-function'
side by side makes it easier to understand the different ways in which
users can use the feature.

I also agree that the first version was too verbose.  What do you think
of this new version?

        Roi

>From 258bfa33b5a7c81c02d1f6d82ae83be15f50b553 Mon Sep 17 00:00:00 2001
From: Roi Martin <[email-masked]>
Date: Wed, 20 Aug 2025 11:12:16 +0200
Subject: [PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual

* doc/emacs/text.texi (Fill Commands): Add subsection "Semantic Linefeed
Filling".
* etc/NEWS: Indicate that all relevant manuals in doc/ have been
updated.
* lisp/textmodes/fill.el (fill-region-as-paragraph-semlf): Link to Info
node from doc string.  (Bug#79278)
---
 doc/emacs/text.texi    | 44 ++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS               |  2 +-
 lisp/textmodes/fill.el |  4 ++--
 3 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index d8a7e0fc25e2..c7b6d3ad4f48 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -674,6 +674,50 @@ Fill Commands
 using the Display fill column indicator mode (@pxref{Displaying
 Boundaries, display-fill-column-indicator}).
 
+@menu
+* Semantic Linefeed Filling::  Paragraph filling using semantic linefeeds.
+@end menu
+
+@node Semantic Linefeed Filling
+@subsubsection Semantic Linefeed Filling
+@cindex semantic linefeed filling
+@cindex semantic linefeeds
+@cindex semlf
+
+@table @kbd
+@item M-x fill-paragraph-semlf
+Fill current paragraph using semantic linefeeds.
+@item M-x fill-region-as-paragraph-semlf
+Fill the region using semantic linefeeds, considering it as one
+paragraph.
+@end table
+
+  The term @dfn{semantic linefeeds} or @dfn{semantic line breaks} refers
+to a set of conventions for using insensitive vertical whitespace to
+structure prose along semantic boundaries.  For instance, inserting a
+newline after every sentence.  They are usually used with markup
+languages that are not sensitive to newlines when exported to a
+different format (e.g. Org, Texinfo, Markdown).
+
+@findex fill-paragraph-semlf
+  The command @kbd{M-x fill-paragraph-semlf} fills a paragraph of text
+using semantic linefeeds, whereby a newline is inserted after every
+sentence.
+
+@findex fill-region-as-paragraph-semlf
+  The command @code{fill-region-as-paragraph-semlf} fills a region of
+text using semantic linefeeds as if the region were a single paragraph.
+Users can set the variable @code{fill-region-as-paragraph-function} to
+the value @code{fill-region-as-paragraph-semlf} to enable functions like
+@kbd{M-q} (@code{fill-paragraph}) and @code{fill-region} to fill text
+using semantic linefeeds.
+
+  One benefit of using semantic linefeeds is that they are
+``diff-friendly'', making it easy to spot which specific sentences have
+been modified in a diff.  They are also convenient during code reviews:
+shorter diffs and the separation of ideas with newlines make it easier
+to add accurate comments.
+
 @node Fill Prefix
 @subsection The Fill Prefix
 
diff --git a/etc/NEWS b/etc/NEWS
index ebf03b53e123..05c10827a6fa 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -697,7 +697,7 @@ activate the mark if it is not already active.
 The default value is t, which retains the old behavior.
 This variable has no effect when Transient Mark mode is off.
 
----
++++
 ** New commands for filling text using semantic linefeeds.
 The new command 'fill-paragraph-semlf' fills a paragraph of text using
 "semantic linefeeds", whereby a newline is inserted after every
diff --git a/lisp/textmodes/fill.el b/lisp/textmodes/fill.el
index 4ab639497ec9..df3794aad616 100644
--- a/lisp/textmodes/fill.el
+++ b/lisp/textmodes/fill.el
@@ -1645,8 +1645,8 @@ fill-region-as-paragraph-semlf
 override how functions like `fill-paragraph' and `fill-region' fill
 text.
 
-For more details about semantic linefeeds, see `https://sembr.org/' and
-`https://rhodesmill.org/brandon/2012/one-sentence-per-line/'."
+For more details about semantic linefeeds, see Info node `(emacs)
+Semantic Linefeed Filling'."
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (region-beginning)
-- 
2.50.1