GNU bug report logs - #79278
[PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual

Previous Next

To reply to this bug, email your comments to 79278 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add section "Semantic Linefeed Filling" to Emacs user manual
Date: Wed, 20 Aug 2025 11:41:00 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Add-section-Semantic-Linefeed-Filling-to-Emacs-user-.patch (text/x-patch, attachment)]

Message #8 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Wed, 20 Aug 2025 14:20:46 +0300

> From: Roi Martin <jroi.martin <at> gmail.com>
> Date: Wed, 20 Aug 2025 11:41:00 +0200
> 
> 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.

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

What do others think?

Message #11 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Wed, 20 Aug 2025 16:05:54 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> 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

[0001-Add-section-Semantic-Linefeed-Filling-to-Emacs-user-.patch (text/x-patch, attachment)]

Message #14 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Sat, 23 Aug 2025 15:19:18 +0300

> From: Roi Martin <jroi.martin <at> gmail.com>
> Cc: 79278 <at> debbugs.gnu.org
> Date: Wed, 20 Aug 2025 16:05:54 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> 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?

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?

Message #17 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Sat, 23 Aug 2025 15:29:50 +0200

Eli Zaretskii <eliz <at> gnu.org> 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?

Also, given that the feature is already in core, what are the criteria
for deciding what goes in the manual and what does not?  This specific
feature provides user-facing commands and variables, where should I
document the details?  Only in the corresponding doc strings?  What
about users who are not aware of the concept?  This change in the manual
may allow them to learn about something that they could find useful and
Emacs implements.

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

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?

        Roi

Message #20 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Sat, 23 Aug 2025 17:13:38 +0300

> From: Roi Martin <jroi.martin <at> gmail.com>
> Cc: 79278 <at> debbugs.gnu.org
> Date: Sat, 23 Aug 2025 15:29:50 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> 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.

Message #23 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Sat, 23 Aug 2025 18:26:12 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> 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.

When reading about a related concept.  For instance, in this case, fill
commands.  It happens to me all the time.  You look for something
specific and when reading its documentation a related concept catches
your attention (e.g. a subsection).

        Roi

Message #26 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Sat, 23 Aug 2025 19:32:02 +0300

> From: Roi Martin <jroi.martin <at> gmail.com>
> Cc: 79278 <at> debbugs.gnu.org
> Date: Sat, 23 Aug 2025 18:26:12 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> 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.
> 
> When reading about a related concept.  For instance, in this case, fill
> commands.  It happens to me all the time.  You look for something
> specific and when reading its documentation a related concept catches
> your attention (e.g. a subsection).

The same is true with built-in documentation.  For example:

    M-x apropos-command RET fill RET

Message #29 received at 79278 <at> debbugs.gnu.org (full text, mbox):

From: Roi Martin <jroi.martin <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79278 <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Fri, 05 Sep 2025 13:34:37 +0200

Eli Zaretskii <eliz <at> gnu.org> 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.

Thanks!

        Roi

Message #34 received at 79278-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Roi Martin <jroi.martin <at> gmail.com>
Cc: 79278-done <at> debbugs.gnu.org
Subject: Re: bug#79278: [PATCH] Add section "Semantic Linefeed Filling" to
 Emacs user manual
Date: Fri, 05 Sep 2025 14:41:50 +0300

> From: Roi Martin <jroi.martin <at> gmail.com>
> Cc: 79278 <at> debbugs.gnu.org
> Date: Fri, 05 Sep 2025 13:34:37 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.