From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eshel Yaron via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual Date: Mon, 02 Oct 2023 10:21:58 +0200 Message-ID: Reply-To: Eshel Yaron Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30166"; mail-complaints-to="usenet@ciao.gmane.io" To: 66303@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Oct 02 10:23:31 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qnEDC-0007OE-2B for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 02 Oct 2023 10:23:30 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qnECW-0001fR-Jj; Mon, 02 Oct 2023 04:22:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnECU-0001e1-KF for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:46 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qnECT-0005Xo-Vt for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:46 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qnECk-00034b-Ce for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:23:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 02 Oct 2023 08:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 66303 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.169623495211769 (code B ref -1); Mon, 02 Oct 2023 08:23:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 2 Oct 2023 08:22:32 +0000 Original-Received: from localhost ([127.0.0.1]:35941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECG-00033k-1n for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:32 -0400 Original-Received: from lists.gnu.org ([2001:470:142::17]:33352) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qnECE-00033W-Ib for submit@debbugs.gnu.org; Mon, 02 Oct 2023 04:22:31 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnEBr-0001We-2q for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:07 -0400 Original-Received: from mail.eshelyaron.com ([107.175.124.16] helo=eshelyaron.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qnEBl-0005Sq-PG for bug-gnu-emacs@gnu.org; Mon, 02 Oct 2023 04:22:06 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1696234920; bh=ZiIwSRrmqebEVpc0lMtff52kOKAOrYSFA9vUm+mtIgI=; h=From:To:Subject:Date:From; b=kOMDGHWjySf58bxUyD2FaU+yWPimWXqBr76VdZyEmOQWOWXVDAPl5EYecuXqPQjZP 7xeN5Vsd1plnNyxbmaCcYLjtxQ4YA9Jg9NXv4jv/DCNpV0cAi9BfPb/fzUnjDtj8CY nrHD6Jga+BY30LY+U88dWvIOVCRAZ0l6FgdljnBycYEG6zxss52bRgdUBN0t/DF9gW 2qa6YCiMwmCZ4iBoQOmFMDqynmjqSyifoPxTQFkqCRfR/o3OD2pUC2M6ilJYtwwUcD LBboalRJ7iw97d1G+Ft28znWMUqYsN3m1Dqmc0wPLanQSYdAb2W0nntBw+pEJWboK4 npR4OgvyatIYA== X-Hashcash: 1:20:231002:bug-gnu-emacs@gnu.org::09bnJvPqIqQRObOp:Nu/ Received-SPF: pass client-ip=107.175.124.16; envelope-from=me@eshelyaron.com; helo=eshelyaron.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FORGED_SPF_HELO=0.799, SPF_HELO_PASS=-0.001, T_SPF_TEMPERROR=0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:271657 Archived-At: --=-=-= Content-Type: text/plain Tags: patch Hi, This is a request for documenting `M-x align` in the Emacs manual, along with a suggested draft for such documentation. Best, Eshel --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Document-M-x-align-in-the-Emacs-manual.patch >From 20fa3ea348617350fa8a437fad75aa9e9a9a620f Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 2 Oct 2023 10:02:46 +0200 Subject: [PATCH] Document 'M-x align' in the Emacs manual * doc/emacs/align.texi: New file. * doc/emacs/emacs.texi: Include it and update menu. --- doc/emacs/align.texi | 70 ++++++++++++++++++++++++++++++++++++++++++++ doc/emacs/emacs.texi | 2 ++ 2 files changed, 72 insertions(+) create mode 100644 doc/emacs/align.texi diff --git a/doc/emacs/align.texi b/doc/emacs/align.texi new file mode 100644 index 00000000000..c7e48890695 --- /dev/null +++ b/doc/emacs/align.texi @@ -0,0 +1,70 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2023 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Alignment +@chapter Alignment +@cindex alignment + + @dfn{Alignment} is the process of adjusting whitespace in a sequence +of lines such that in all lines certain parts begin at the same +column. This is usually done to enhance readability of a piece of +text or code. The classic example is aligning a series of assignments +in C-like programming languages: + +@example +int a = 1; +short foo = 2; +double blah = 4; +@end example + +Is commonly aligned to: + +@example +int a = 1; +short foo = 2; +double blah = 4; +@end example + +@findex align + You can use the command @kbd{M-x align} to align lines in the +current region. This command knows about common alignment patterns +across many markup and programming languages. It encodes these +patterns as a set of @dfn{alignment rules}, that say how to align +different kinds of text in different contexts. + +@kbd{M-x align} splits the region into a series of @dfn{sections}, +usually sequences of non-blank lines, and aligns each section +according to a matching alignment rule by expanding or contracting +stretches of whitespace. If you call this command with a prefix +argument (@kbd{C-u M-x align}), it enables more alignment rules that +are often useful but may sometimes be too intrusive. For example, in +a Lisp buffer with the following form: + +@lisp +(set-face-attribute 'mode-line-inactive nil + :box nil + :background nil + :underline "black") +@end lisp + +Typing (@kbd{C-u M-x align}) yields: + +@lisp +(set-face-attribute 'mode-line-inactive nil + :box nil + :background nil + :underline "black") +@end lisp + +@vindex align-indent-before-aligning + If the user option @code{align-indent-before-aligning} is +non-@code{nil}, Emacs indents the region before aligning it with +@kbd{M-x align}. @xref{Indentation}. + +@vindex align-to-tab-stop + The user option @code{align-to-tab-stop} says whether aligned parts +should start at a tab stop (@pxref{Tab Stops}). If this option is +@code{nil}, @kbd{M-x align} uses just enough whitespace for alignment, +disregarding tab stops. If this is a non-@code{nil} symbol, @kbd{M-x +align} checks the value of that symbol, and if this value is +non-@code{nil}, @kbd{M-x align} aligns to tab stops. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 7a21eb49e24..c4ed9a6ae93 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -178,6 +178,7 @@ Top Advanced Features * Modes:: Major and minor modes alter Emacs's basic behavior. * Indentation:: Editing the white space at the beginnings of lines. +* Alignment:: Making common parts of lines start at the same column. * Text:: Commands and modes for editing human languages. * Programs:: Commands and modes for editing programs. * Building:: Compiling, running and debugging programs. @@ -1616,6 +1617,7 @@ Intro @include mule.texi @include modes.texi @include indent.texi +@include align.texi @include text.texi @c Includes fortran-xtra. @include programs.texi -- 2.42.0 --=-=-=--