git.notmuchmail.org Git - notmuch/blob - test/corpora/indexing/PATCH-1-2-system_data_types.7-srcfix.txt:2,S

   1 From mboxrd@z Thu Jan  1 00:00:00 1970
   2 Return-Path: <SRS0=/pzd=DH=vger.kernel.org=linux-man-owner@kernel.org>
   3 X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
   4         aws-us-west-2-korg-lkml-1.web.codeaurora.org
   5 X-Spam-Level:
   6 X-Spam-Status: No, score=-8.3 required=3.0 tests=BAYES_00,DKIM_SIGNED,
   7         DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
   8         HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,
   9         SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_1 autolearn=ham autolearn_force=no
  10         version=3.4.0
  11 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
  12         by smtp.lore.kernel.org (Postfix) with ESMTP id AFE3FC4727E
  13         for <linux-man@archiver.kernel.org>; Wed, 30 Sep 2020 10:12:21 +0000 (UTC)
  14 Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
  15         by mail.kernel.org (Postfix) with ESMTP id 4E0D62074A
  16         for <linux-man@archiver.kernel.org>; Wed, 30 Sep 2020 10:12:21 +0000 (UTC)
  17 Authentication-Results: mail.kernel.org;
  18         dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Osm9Pn67"
  19 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
  20         id S1725823AbgI3KMU (ORCPT <rfc822;linux-man@archiver.kernel.org>);
  21         Wed, 30 Sep 2020 06:12:20 -0400
  22 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50038 "EHLO
  23         lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
  24         with ESMTP id S1725779AbgI3KMU (ORCPT
  25         <rfc822;linux-man@vger.kernel.org>); Wed, 30 Sep 2020 06:12:20 -0400
  26 Received: from mail-pf1-x443.google.com (mail-pf1-x443.google.com [IPv6:2607:f8b0:4864:20::443])
  27         by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5026DC061755
  28         for <linux-man@vger.kernel.org>; Wed, 30 Sep 2020 03:12:20 -0700 (PDT)
  29 Received: by mail-pf1-x443.google.com with SMTP id b124so832681pfg.13
  30         for <linux-man@vger.kernel.org>; Wed, 30 Sep 2020 03:12:20 -0700 (PDT)
  31 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
  32         d=gmail.com; s=20161025;
  33         h=date:from:to:cc:subject:message-id:references:mime-version
  34          :content-disposition:in-reply-to:user-agent;
  35         bh=qR1FJVXOhU6/g+m4SoSco3vMtV+CNvRvNyXS1xuG+T4=;
  36         b=Osm9Pn67G380QiA1ORltntJShSHlKg/KZZfKV8ebvfEXJw9893EO0N6J6GDR+zkmHi
  37          TOQuIe7x9y95Pipm54rWWEW33U3gwoXRHsPc2Kivm6L8Ixb+f0T0rMPKw/FOkL8OGo9t
  38          WmmSvnlErAXHqBq9aRAJJsf2bSlDgdAyYY1Qe6PSq2hKi2rg+sOy1Vaj4RqZ6jTK/DWY
  39          tX28Ql0XS3kKWp0Lc8MNsSP+SXlcdwHQYll5LeReAg1oi++hICgWphuMmo3OH+2B1WtO
  40          hMH7VuUONqbuE1aLoZ6PyyUlCeN1soJd8bKY0cmY0TKCsw0Jvkuh/XzYDVNi6wOSM6Ez
  41          okpA==
  42 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
  43         d=1e100.net; s=20161025;
  44         h=x-gm-message-state:date:from:to:cc:subject:message-id:references
  45          :mime-version:content-disposition:in-reply-to:user-agent;
  46         bh=qR1FJVXOhU6/g+m4SoSco3vMtV+CNvRvNyXS1xuG+T4=;
  47         b=TJU+duGLhruSES/5sJy4y1wfcltfokDpA58edkSUJyasvsooUo67VNtOB3ZK49iHm5
  48          C/cjy0ExxTECB0aM6p+B1jcePdWoPUaVBY9bVd/Q5DNhm4KhTO8ON96gB43d2rLWLOiK
  49          /Y1vCu+MwOpY0JQTojbC140s/JYccR/KPapTmbUkRzrpmeoYqw8CbBPV60rQxYCn9GUu
  50          FeCXJY5q9OfaYW1viQZoBL5n1IMMpJDVa61Q8gZ33b3wRCvQv/x1eZCsVlYpjcqf7Umc
  51          /Amx3i27cxvo8pSvvwiTzrlJHJv0Gkytz13i7s+zW+XKzZRyzy3yirtU2DFTGat6FeMn
  52          H8Ig==
  53 X-Gm-Message-State: AOAM530Yon7xNOW6kiuy6bVpbpwbzR/9pldRB49OtZaSAHAZg7Gyf7qE
  54         JXgAH20rZzYlwqOZyeZCeAwtWh09PeI=
  55 X-Google-Smtp-Source: ABdhPJxzyZAVDBtMwQ5+dUqVg37y/LgZByrSaTxvhS6wnx6sJuG8ROItw0CwDAg939XUVADeje/nZQ==
  56 X-Received: by 2002:a63:c547:: with SMTP id g7mr1563654pgd.234.1601460739764;
  57         Wed, 30 Sep 2020 03:12:19 -0700 (PDT)
  58 Received: from localhost.localdomain ([1.129.172.177])
  59         by smtp.gmail.com with ESMTPSA id k14sm1804437pjd.45.2020.09.30.03.12.17
  60         (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
  61         Wed, 30 Sep 2020 03:12:19 -0700 (PDT)
  62 Date:   Wed, 30 Sep 2020 20:12:15 +1000
  63 From:   "G. Branden Robinson" <g.branden.robinson@gmail.com>
  64 To:     "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
  65 Cc:     Jakub Wilk <jwilk@jwilk.net>, linux-man@vger.kernel.org
  66 Subject: Re: [PATCH 1/2] system_data_types.7: srcfix
  67 Message-ID: <20200930101213.2m2pt3jrspvcrxfx@localhost.localdomain>
  68 References: <20200925080330.184303-1-colomar.6.4.3@gmail.com>
  69  <20200927061015.4obt73pdhyh7wecu@localhost.localdomain>
  70  <20200928132959.x4koforqnzohxh5u@jwilk.net>
  71  <9b8303fe-969e-c9f0-e3cd-0590b342d5bf@gmail.com>
  72 MIME-Version: 1.0
  73 Content-Type: multipart/signed; micalg=pgp-sha256;
  74         protocol="application/pgp-signature"; boundary="jg2hlfugxpumieke"
  75 Content-Disposition: inline
  76 In-Reply-To: <9b8303fe-969e-c9f0-e3cd-0590b342d5bf@gmail.com>
  77 User-Agent: NeoMutt/20180716
  78 Precedence: bulk
  79 List-ID: <linux-man.vger.kernel.org>
  80 X-Mailing-List: linux-man@vger.kernel.org
  81
  82
  83 --jg2hlfugxpumieke
  84 Content-Type: multipart/mixed; boundary="wl6i3r6gpq7ibouc"
  85 Content-Disposition: inline
  86
  87
  88 --wl6i3r6gpq7ibouc
  89 Content-Type: text/plain; charset=us-ascii
  90 Content-Disposition: inline
  91 Content-Transfer-Encoding: quoted-printable
  92
  93 Hi Jakub and Michael,
  94
  95 At 2020-09-29T14:13:26+0200, Michael Kerrisk (man-pages) wrote:
  96 > On 9/28/20 3:29 PM, Jakub Wilk wrote:
  97 > > Hi Branden!
  98 > >=20
  99 > > In groff_man_style(7) you wrote:
 100 > >> Unused macro arguments are more often simply omitted, or good style
 101 > >> suggests that a more appropriate macro be chosen, that earlier
 102 > >> arguments are more important than later ones, or that arguments
 103 > >> have identical significance such that skipping any is superfluous.
 104 > >=20
 105 > > After 15 minutes of gawking at this sentence, I still don't
 106 > > understand what are you trying to say here. The sentence should be
 107 > > either thoroughly rephrased or removed.
 108 >=20
 109 > I must say that I too found it hard to parse. I presume, Branden,
 110 > that you mean:
 111 >=20
 112 > [[
 113 > Unused macro arguments are more often simply omitted, or good style=20
 114 > suggests
 115 > EITHER (1)=20
 116 > that a more appropriate macro be chosen,=20
 117 > (2)
 118 > that earlier arguments are more important than later ones, or
 119 > (3)
 120 > that arguments have=20
 121 > identical significance such that skipping any is superfluous.
 122 > ]]
 123
 124 You got it.  But it was too much work.
 125
 126 > But it takes a few scans to work that out. Perhaps break this into
 127 > smaller pieces, or add some explicit structuring elements to the
 128 > sentence?
 129
 130 I was trying to be comprehensive with respect to several anti-patterns I
 131 had in mind.  However, using the anti-patterns concretely is premature
 132 at that point in the page.  So I both expanded and relocated the
 133 material.
 134
 135 I'm attaching what I've just committed to groff git.
 136
 137 Further feedback is welcome, of course; revision of documentation is a
 138 process that is never completed, only abandoned.  And I haven't given up
 139 yet.  :)
 140
 141 Thank you both for your reviews.
 142
 143 Regards,
 144 Branden
 145
 146 --wl6i3r6gpq7ibouc
 147 Content-Type: text/x-diff; charset=us-ascii
 148 Content-Disposition: attachment; filename="excise_standardese.diff"
 149 Content-Transfer-Encoding: quoted-printable
 150
 151 commit dd2c4cf05a659ae7127e342924668ff0fa0deaa1
 152 Author: G. Branden Robinson <g.branden.robinson@gmail.com>
 153 Date:   Wed Sep 30 19:56:38 2020 +1000
 154
 155     groff_man_style(7): Clarify empty macro arguments.
 156    =20
 157     Rewrite some ersatz standardese I had managed to concoct regarding why
 158     empty macro arguments are usually not needed.  Put an expanded
 159     discussion, with anti-patterns and remedies, in section "Notes", with
 160     forward reference from subsection "Macro reference preliminaries".
 161    =20
 162     Thanks to Jakub Wilk and Michael Kerrisk for the critique.
 163
 164 diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
 165 index c62d97ba..b96cbaf4 100644
 166 --- a/tmac/groff_man.7.man.in
 167 +++ b/tmac/groff_man.7.man.in
 168 @@ -281,23 +281,8 @@ but the
 169  package is designed such that this should seldom be necessary.
 170  _ifstyle()dnl
 171  .
 172 -Unused macro arguments are more often simply omitted,
 173 -.\" antipattern: '.TP ""' (just '.TP' will do)
 174 -or good style suggests that a more appropriate macro be chosen,
 175 -.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
 176 -that earlier arguments are more important than later ones,
 177 -.\" antipattern: '.TH foo 1 "" "foo "1.2.3"' (don't skip the date!)
 178 -.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
 179 -or that arguments have identical significance such that skipping any is
 180 -superfluous.
 181 -.\" antipattern: '.B one two "" three' (pointless)
 182 -.\"   Technically, the above has a side-effect of additional space
 183 -.\"   between "two" and "three", but there are much more obvious ways of
 184 -.\"   getting it if desired.
 185 -.\"     .B "one two  three"
 186 -.\"     .B one "two " three
 187 -.\"     .B one two " three"
 188 -.\"     .B one two\~ three
 189 +See section \(lqNotes\(rq below for examples of cases where better
 190 +alternatives to empty arguments in macro calls are available.
 191  _endif()dnl
 192  .
 193  Most macro arguments are strings that will be output as text;
 194 @@ -3235,6 +3220,63 @@ Some tips on troubleshooting your man pages follow.
 195  .
 196  .
 197  .TP
 198 +\(bu Do I ever need to use an empty macro argument ("")?
 199 +Probably not.
 200 +.
 201 +When this seems necessary,
 202 +often a shorter or clearer alternative is available.
 203 +.
 204 +.\" antipattern: '.TP ""' (just '.TP' will do)
 205 +.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
 206 +.\" antipattern: '.TH foo 1 "" "foo 1.2.3"' (don't skip the date!)
 207 +.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
 208 +.\" antipattern: '.B one two "" three' (pointless)
 209 +.\"   Technically, the above has a side-effect of additional space
 210 +.\"   between "two" and "three", but there are much more obvious ways of
 211 +.\"   getting it if desired.
 212 +.\"     .B "one two  three"
 213 +.\"     .B one "two " three
 214 +.\"     .B one two " three"
 215 +.\"     .B one two\~ three
 216 +.TS
 217 +c c
 218 +lfCB lfCB.
 219 +Instead of.\|.\.       .\|.\|.do this.
 220 +_
 221 +\&.TP \(dq\(dq .TP
 222 +\&.BI \(dq\(dq italic-text bold-text   .IB italic-text bold-text
 223 +\&.TH foo 1 \(dq\(dq \(dqfoo 1.2.3\(dq .TH foo 1 \
 224 +\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 1.2.3\(dq
 225 +\&.IP \(dq\(dq 4n      .TP 4n
 226 +\&.B one two \(dq\(dq three    .B one two three
 227 +.TE
 228 +.
 229 +.
 230 +.IP
 231 +In the title heading
 232 +.RB ( .TH ),
 233 +the date of the page's last revision is more important than packaging
 234 +information;
 235 +it should not be omitted.
 236 +.
 237 +Ideally,
 238 +a page maintainer will keep both up to date.
 239 +.
 240 +.
 241 +.IP
 242 +In the last example,
 243 +the empty argument does have a subtly different effect than its
 244 +suggested replacement;
 245 +the empty argument becomes an additional space character\(embut it is a
 246 +regular breaking space,
 247 +so it can be discarded at the end of an output line.
 248 +.
 249 +It is better not to be subtle,
 250 +particularly with space,
 251 +which can be overlooked in source and rendered forms.
 252 +.
 253 +.
 254 +.TP
 255  .RB \(bu " .RS" " doesn't indent relative to my indented paragraph"
 256  The
 257  .B .RS
 258
 259 --wl6i3r6gpq7ibouc--
 260
 261 --jg2hlfugxpumieke
 262 Content-Type: application/pgp-signature; name="signature.asc"
 263
 264 -----BEGIN PGP SIGNATURE-----
 265
 266 iQIzBAEBCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAl90WfUACgkQ0Z6cfXEm
 267 bc5raQ/9GhXG/5U7McaEEu+aW1IgaTYTMbsMpew5u3tBlj3/IenGzsy8wDO912BD
 268 aHPSedYoc485k1Vh/Kowyx569RhyIXiMtH7uINCEtheMSUNgITNFqXo8mhaqVMlU
 269 3JoV12btQddOIqHnGX6c5V9Z38KXFmVctD6CxjLaWGLp/Bu9tSKwSaHOOmtUYyOv
 270 fYpMzr0amd4z9f+O8PPnToqBhwUitEvis1ZHYU6gIj8VwOjD0gNsWjA9HR3uC3c9
 271 GK/R5przMANrNejzSgofm0/yAL6a61WhqhYEtzLUYu2NFnsyNJWzITNsNnoxzgQ5
 272 liKL0Onmw0YWjOo4Z9Zht9Iyd6JhJxW0uRwlpFhE6UlCkFHK8nbv3NbHT2xlx/po
 273 rxY5jDC3Ap3+mdYHY8k5o8vFd4QOXc2bSTuDRZoWtFZQsjnl4Fpkqks1W54Txq4y
 274 o3Vu9aOPx//Jfi8sDc/qD/mFnyUu+AMFWjIj8UxQN4HmbrbXg/DEczRfP68DjOiX
 275 ssy/0Rmm/H1cu7oBMoSss63mpk/NvPTSzzCR+VhU4PHQ7rxSZYS105tzkBVfe37e
 276 hSS00rQVWe2YnI1KkfJHFjzveHiPXf+IxC0Z4PpJuLhl+pIZ/FgxJ5yEkX0XVUIy
 277 aYRzKI3JaJktYl6WvulKSBPzQxIyOgrqVkZW4lv/uTh64pE6E5w=
 278 =oeam
 279 -----END PGP SIGNATURE-----
 280
 281 --jg2hlfugxpumieke--
 282