From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS17314 8.43.84.0/22 X-Spam-Status: No, score=-4.3 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id B37BB1F8C6 for ; Thu, 5 Aug 2021 07:40:24 +0000 (UTC) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 7A3FD385E449 for ; Thu, 5 Aug 2021 07:40:23 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7A3FD385E449 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1628149223; bh=a5sKO+a/Ukhqy1AT2qm8a6mK3NKhxvA+xd2GRNCn9rc=; h=Date:To:Subject:References:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=sf7cXCFQSd/JqYB7nKKh+HAP9WlSJuxS/9p3tyzjwEF5AFB+4rrM/v0uhDfyKBbX+ jxjr/LoTjgc+nd31Mdo59m2smtCrNdptHcEsGF1IGOlWO9ovQty9KTzK/kmsewbzJw rGFWDjNLx0XIJoUTlJsrZDnGo/pyihirk018VOgU= Received: from mail-pj1-x102e.google.com (mail-pj1-x102e.google.com [IPv6:2607:f8b0:4864:20::102e]) by sourceware.org (Postfix) with ESMTPS id 8FA323988418 for ; Thu, 5 Aug 2021 07:38:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8FA323988418 Received: by mail-pj1-x102e.google.com with SMTP id t7-20020a17090a5d87b029017807007f23so9587587pji.5 for ; Thu, 05 Aug 2021 00:38:58 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=a5sKO+a/Ukhqy1AT2qm8a6mK3NKhxvA+xd2GRNCn9rc=; b=KAXNEJtTFUxECZht9VAR8Kqrpcv8QlCYjzoOvLCZ21nlChOtHBIK3Pt7ErcSVYSGoj vZxzY+AQ4PzINvRmwDbjAxULngg/numXQ1WtoN1gNtZEUULDKbPu7HqxTElNZd1i0XC8 si/bb9yImmLyfFClUtPWSVsqks7nhbPAynO6iiUGKYSVEqKBVS7885WClulrFBU8zreD 4Fc7teH4SMVa7lICB1DFlnegj6KiV7zRvUjrg5hS9XwU+EHeXgVWZRStI6EAeWmZb4ym +eMecH0L4tIJWuUOX3fU2fc8iHwK4Fw1hkNwRSgn0fKySuxs3oNoXernquaGrSjOALw2 N0kA== X-Gm-Message-State: AOAM531H43u6FsnyQVah535qdnCgORgRp49VvNJhOLDbWW9GLEcdILRr 9i4WiJRTlQWYaRktB+ZQ1aQ= X-Google-Smtp-Source: ABdhPJyNsmclinunchTfNsG7QFchc54tX1GlxauPSaR4/MFFVxUaLIyFebrdOTwr1mfNqdt8N8E8hA== X-Received: by 2002:a17:902:b10f:b029:12b:c1d9:1ed2 with SMTP id q15-20020a170902b10fb029012bc1d91ed2mr2845777plr.85.1628149137745; Thu, 05 Aug 2021 00:38:57 -0700 (PDT) Received: from localhost.localdomain ([1.144.147.165]) by smtp.gmail.com with ESMTPSA id k5sm5418839pfi.55.2021.08.05.00.38.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 05 Aug 2021 00:38:57 -0700 (PDT) Date: Thu, 5 Aug 2021 17:38:52 +1000 To: "Alejandro Colomar (man-pages)" Subject: Re: [patch] nscd.conf.5: describe reloading, clarifications Message-ID: <20210805073851.e2n33a3d4hkmhbpa@localhost.localdomain> References: <02da5334-1635-8aa9-c4e6-deb0161a848d@gmail.com> <01329467-8747-ec5a-6f92-a5466ed64eed@gmail.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="lcltfg73op53t762" Content-Disposition: inline In-Reply-To: <01329467-8747-ec5a-6f92-a5466ed64eed@gmail.com> User-Agent: NeoMutt/20180716 X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , From: "G. Branden Robinson via Libc-alpha" Reply-To: "G. Branden Robinson" Cc: "libc-alpha@sourceware.org" , Greg Banks , Michael Kerrisk , "linux-man@vger.kernel.org" Errors-To: libc-alpha-bounces+e=80x24.org@sourceware.org Sender: "Libc-alpha" --lcltfg73op53t762 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Hi Alex, At 2021-08-05T08:58:33+0200, Alejandro Colomar (man-pages) wrote: [...] > > > >> +.PP > > >=20 > > > That's not correct.=C2=A0 Did you copy that from another place?=C2=A0= If so, > > > please tell me because I should fix it. > >=20 > > No, it's a habit left over from the last time I contributed to this > > project (in 2008).=C2=A0 It seems the rules have changed. > >=20 > > > We use that between paragraphs, but not before the first one nor > > > after the last one. > >=20 > > Ok, sure, but in that case the description of .PP in man(7) is wrong > >=20 > > =C2=A0 =C2=A0 =C2=A0 =C2=A0.PP =C2=A0 =C2=A0 =C2=A0Begin a new paragra= ph and reset prevailing indent. >=20 > That's something that I had pending to address from Branden. That > page is a mix of things that should go into man-pages(7), > groff_man_style(7), and groff_man(7), and then man(7) should be > removed and replaced by a link page to groff_man(7). I should emphasize that the foregoing is something I _proposed_ for discussion. I don't have any reason to suspect that it is something that has wide buy-in yet. I'm particularly interested in Michael's opinion. > For now, You can read groff_man(7) (provided by the groff package), > which tells us that .SH already does what .PP does (start a clean > paragraph) (and it does more things, of course). The thing is that if > you add .PP after .SH you will have a blank line (and this an exercise > of my mental groff, which I hope doesn't fail me this time), Sorry to disappoint you. :-O A PP (or LP, or P) call immediately after a SH call[1] will not add vertical space because the SH macro definition puts *roff into what is called "no-space mode"; vertical spacing is suppressed until turned back on manually, or glyphs[2] are sent to the output. > and it would be a bit weird to have a blank line after the section > title. Yes--as style advice I think this is quite sound and solidly precedented. To develop your *roff intuition, I suggest using groff as a REPL. Yes, it can be done! For instance, while composing this mail, even though I am familiar with the man(7) package sources, I attempted to protect myself from the embarrassment of making an incorrect claim by testing my knowledge with this short shell session[3]. $ nroff -man =2ETH foo 1 =2ESH Name =2EPP Foobar. foo(1) General Commands Manual foo= (1) Name Foobar. foo= (1) This quickly verified to me that I was right about no-space mode. I so strongly advocate this method of familiarizing oneself with *roff that I recently added a section about it to groff(1). Using groff as a REPL Those with a programmer=E2=80=99s bent may be pleased to know that = they can use groff in a read-evaluate-print loop (REPL). Doing so can be handy to verify one=E2=80=99s understanding of the formatter=E2= =80=99s behav=E2=80=90 ior and/or the syntax it accepts. Turning on all warnings with -ww can aid this goal. $ groff -ww -Tutf8 \# This is a comment. Let's define a register. .nr a 1 \# Do integer arithmetic with operators evaluated left-to-right. .nr b \n[a]+5/2 \# Let's get the result on the standard error stream. .tm \n[b] 3 \# Now we'll define a string. .ds name Leslie\" This is another form of comment. .nr b (\n[a] + (7/2)) \# Center the next two text input lines. .ce 2 Hi, \*[name]. Your secret number is \n[b]. \# We will see that the division rounded toward zero. It is \# Here's an if-else control structure. .ie (\n[b] % 2) odd. .el even. \# This trick sets the page length to the current vertical \# position, so that blank lines don't spew when we're done. .pl \n[nl]u Hi, Leslie. Your secret number is 4. It is even. The above example gets into many *roff concepts that man page authors typically need not worry about. Nevertheless the technique works with macro packages, too, as shown earlier. Macro packages often need to be initialized. man(7) is no exception. If you do not call man's "TH" as the first macro in the input, it will be unhappy. That is why I had the ".TH foo 1" line.[4] Regards, Branden [1] with arguments, technically--most people do not use the other legal form of calling SH input trap, which accepts input in the next line [2] or drawing commands, but that's mostly irrelevant to man pages [3] Full disclosure: my command input fibs above. I actually used, not "nroff", but a shell alias of mine called "tgu", which runs a bleeding edge groff from a working tree, since I'm a groff developer. After alias expansion, what I ran was ./build/test-groff -b -ww -Tutf8 but that's not very useful to people who don't have a shell window that lives in a built groff working tree. [4] A real man page would supply additional information to the macro. --lcltfg73op53t762 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmELlYIACgkQ0Z6cfXEm bc546xAAojkWrWl3l8Z/W5nkokKjj5Dxbjx0Rjte2xIVinsQibIz6Y5E8smjr3K4 NsowviqiMFIgy3HoMTOs6itJRFUP2teV6rYSnM8agli3CtEBbZMSJ3B4ODrAEScz UFK/B8nllAXXUEzQbnKrM+EXZO9usqRe7kzZxzW981fGCvFi8Sos9Y7umx87BfsB H5Tag+qaR3ZPT8NPPsNQJiB+ql6P0kWz/9+b6ExicA1sy+le3ZsO2lADHzHFrLHD TvWDncYufmyfSPSOZY0cYT9piB44qM/srtzWE+pF+od0bCCtnEWxSIieraoUpyBu CZu8ZbbfIyYvAG6DEMKBcPhlMYdIDTotZzEMww0rRd7WGNx2HSuEyFR5n8ujZRoa +rdo39bShPigcsIgMZi3mLM0fGFCbhn6X8p6DxuZXb2J/fmpTvs0StZuffWKo9/C cT46EHxar5+7sK1QFeaiYAvb+Dbx7wiF535IHv244h6auq4eFBWJ1LTTiexXVPKR hQ0hgDUxl+RaCfCgvylw360PJAGcc2sh7YJzk0xy8xppQ3B+iMtmJYTiFdCmC9xX Il5OjmkNNLAGfjHPIm3Q9ROXwXkUrgwUNKfDgOmT7b+Nz3wF1wzKxvTnJJyc3bCS rHK4HypQr2Y7WYUfZn0Qrax7SLSj6KqjjvEeKSX/TEa7kXVrOmk= =pWrX -----END PGP SIGNATURE----- --lcltfg73op53t762--