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

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 05 Sep 2025 11:43:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
79278: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=79278
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual
From: Eli Zaretskii <[email-masked]>
To: Roi Martin <[email-masked]>
Cc: [email-masked]
Date: Fri, 05 Sep 2025 14:41:50 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Roi Martin <[email-masked]>
> Cc: [email-masked]
> Date: Fri, 05 Sep 2025 13:34:37 +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?
> 
> Hi Eli,
> 
> On August 23th, almost 2 weeks ago, we asked in help-gnu-emacs.  It
> seems to me that the participation level (2 people replied) does not
> justify a new section in the manual.
> 
> Also, the main concern expressed by Jean Louis, which is lack of details
> and examples, should be covered by the links we already provide in the
> doc strings.
> 
> So, if you agree, feel free to close this issue.

Agreed and closed.

Subject: [PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual
From: Roi Martin <[email-masked]>
To: [email-masked]
Date: Wed, 20 Aug 2025 11:41:00 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Tags: patch

This patch adds a new section about semantic linefeeds to the Emacs user
manual.  This allows us to link the doc string of
`fill-region-as-paragraph-semlf' to the new Info node.  Now everything
related to semantic linefeeds is self-contained and we don't have to
rely on external URLs which are not official references.

        Roi

>From fd5ca29d054afcd51269b541bc30bd07bc64685e 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.
---
 doc/emacs/text.texi    | 99 ++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS               |  2 +-
 lisp/textmodes/fill.el |  4 +-
 3 files changed, 102 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index d8a7e0fc25e2..84715470b7da 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -674,6 +674,105 @@ 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 paragraph at or after point using semantic linefeeds.
+@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.
+
+@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.
+
+  Semantic linefeeds are usually used with markup languages that are not
+sensitive to newlines when exported to a different format (e.g. Org,
+Texinfo, Markdown).
+
+  Let's say that we have the following paragraph in an Org document:
+
+@example
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor.  Incididunt ut labore et dolore magna aliqua.  Ut enim ad minim
+veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+commodo consequat.
+@end example
+
+  After filling the paragraph using semantic linefeeds, the result is:
+
+@example
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor.
+Incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
+ut aliquip ex ea commodo consequat.
+@end example
+
+  However, when exported, in both cases the result is:
+
+@example
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor.  Incididunt ut labore et dolore magna aliqua.  Ut enim ad minim
+veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+commodo consequat.
+@end example
+
+  So, what are the benefits?
+
+  One benefit is that semantic linefeeds are ``diff friendly''.  For
+example,
+
+@example
+-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+-tempor.  Incididunt ut labore et dolore magna aliqua.  Ut enim ad minim
+-veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+-commodo consequat.
++Lorem ipsum dolor sit amet, XXXXX consectetur adipiscing elit, sed do
++eiusmod tempor.  Incididunt ut labore et dolore magna aliqua.  Ut enim
++ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
++aliquip ex ea commodo consequat.
+@end example
+
+  Versus,
+
+@example
+-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+-tempor.
++Lorem ipsum dolor sit amet, XXXXX consectetur adipiscing elit, sed do
++eiusmod tempor.
+ Incididunt ut labore et dolore magna aliqua.
+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
+ ut aliquip ex ea commodo consequat.
+@end example
+
+  Semantic linefeeds make easier to spot that the word @samp{XXXXX} was
+added in the first line.
+
+  Also, they are convenient during code reviews.  Shorter diffs and
+separating ideas with newlines allow to be more accurate when adding
+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