From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: YE via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#56870: [PATCH] Re: bug#56870: company-dabbrev variable documentation Date: Thu, 04 Aug 2022 19:06:36 +0300 Message-ID: References: Reply-To: YE 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="1590"; mail-complaints-to="usenet@ciao.gmane.io" Cc: yet@ego.team, uzibalqa@proton.me, larsi@gnus.org, 56870@debbugs.gnu.org To: Matt Armstrong Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Aug 04 18:12:05 2022 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 1oJdS9-0000GW-Dn for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 04 Aug 2022 18:12:05 +0200 Original-Received: from localhost ([::1]:60596 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJdS8-0004ym-FO for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 04 Aug 2022 12:12:04 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34448) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJdNG-0006Qj-CZ for bug-gnu-emacs@gnu.org; Thu, 04 Aug 2022 12:07:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36475) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJdNG-0005br-12 for bug-gnu-emacs@gnu.org; Thu, 04 Aug 2022 12:07:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJdNF-0000Ch-O4 for bug-gnu-emacs@gnu.org; Thu, 04 Aug 2022 12:07:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: YE Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 Aug 2022 16:07:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56870 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 56870-submit@debbugs.gnu.org id=B56870.1659629203760 (code B ref 56870); Thu, 04 Aug 2022 16:07:01 +0000 Original-Received: (at 56870) by debbugs.gnu.org; 4 Aug 2022 16:06:43 +0000 Original-Received: from localhost ([127.0.0.1]:54457 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJdMx-0000CC-8z for submit@debbugs.gnu.org; Thu, 04 Aug 2022 12:06:43 -0400 Original-Received: from out0.migadu.com ([94.23.1.103]:59168) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJdMu-0000C2-Kr for 56870@debbugs.gnu.org; Thu, 04 Aug 2022 12:06:42 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ego.team; s=key1; t=1659629198; h=from:from:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to; bh=anNGSR2Pw/FWyF2CrbgfbaOZdwHNTSKviJH+K5oa5y8=; b=Ty3UN75AKhKL264OxLmXGY+nuHBJRDSQ7E9yewXDL3yaE3XpetyghyAd8uyemLNeYWQPLZ WxBte3/kQKY/c5k7B1AphMjxBR5IZ5AwRWkqLRxhiFL7WTpvDo58wRq6TtliQPr4Q4ftmK uoC6nv/Fdf/7SuXa/ZzQr2lRCdQg8QA= In-Reply-To: <87sfmd2mqk.fsf@rfc20.org> (message from Matt Armstrong on Wed, 03 Aug 2022 11:41:39 -0700) X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: ego.team 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" X-ACL-Warn: , YE Xref: news.gmane.io gmane.emacs.bugs:238763 Archived-At: --=-=-= Content-Type: text/plain My take on the 'Init File' docs improvement is attached. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Expand-Init-File-documentation-in-Emacs-manual.patch Content-Description: Expand Init File docs >From d83fd0b706e60e321be695ab7d00ef7d1746258d Mon Sep 17 00:00:00 2001 From: YugaEgo Date: Thu, 4 Aug 2022 18:45:49 +0300 Subject: [PATCH] Expand Init File documentation in Emacs manual * doc/emacs/custom.texi (Init Syntax): Add 'Other Lisp symbols' item. Expand 'True' and 'False' items docs. Add indexes. (Init Examples): Mention doc strings convention for symbols. (Bug#56870) --- doc/emacs/custom.texi | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 6ed43bcb79..e9b65b66ce 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2442,13 +2442,31 @@ Init Syntax keys which send non-@acronym{ASCII} characters. @item True: -@code{t} stands for ``true''. +@cindex @code{t} +@cindex true +@cindex boolean +The special symbol @code{t} stands for ``true''. @xref{Constant +Variables,,, elisp, The Emacs Lisp Reference Manual}. @item False: -@code{nil} stands for ``false''. +@cindex @code{nil} +@cindex false +@cindex boolean +The special symbol @code{nil} stands for ``false''. @xref{Constant +Variables,,, elisp, The Emacs Lisp Reference Manual}). + +@item Other Lisp symbols: +@cindex Lisp symbol syntax +@cindex symbol syntax +Write a single-quote (@code{'}) followed by the symbol name +(@pxref{Symbols,,, elisp, The Emacs Lisp Reference Manual}). Note +that documentation strings refer to symbols by their names only, +without the single-quote (@pxref{Documentation Tips,,, elisp, The +Emacs Lisp Reference Manual}). @item Other Lisp objects: @cindex Lisp object syntax +@cindex object syntax Write a single-quote (@code{'}) followed by the Lisp object you want. @end table @@ -2515,7 +2533,9 @@ Init Examples Note that @code{text-mode} is used because it is the command for entering Text mode. The single-quote before it makes the symbol a constant; otherwise, @code{text-mode} would be treated as a variable -name. +name. By convention, documentation strings refer to symbol arguments +by their names, without the single-quote (@pxref{Documentation Tips,,, +elisp, The Emacs Lisp Reference Manual}). @need 1500 @item -- 2.34.1 --=-=-=--