Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hpaGV-0001ay-BX for pgsql-docs@arkaria.postgresql.org; Mon, 22 Jul 2019 15:30:15 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1hpaGU-00066n-3q for pgsql-docs@arkaria.postgresql.org; Mon, 22 Jul 2019 15:30:14 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hpaGT-00066Z-Ga for pgsql-docs@lists.postgresql.org; Mon, 22 Jul 2019 15:30:13 +0000 Received: from meldrar.postgresql.org ([2a02:c0:301:0:ffff::31]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hpaGR-0000pf-Ap for pgsql-docs@lists.postgresql.org; Mon, 22 Jul 2019 15:30:13 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=postgresql.org; s=20171124; h=Content-Type:In-Reply-To:MIME-Version:Date: Message-ID:From:References:Cc:To:Subject:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=4uq7jCNjQQaumJ7IQmWZAQ57ijsPyrHgDd46tXZQ3x4=; b=vCkct1J33VqS6spRgVGiNQ/luh 5DqVS3nsY2V8kigVOTnP6I8ldMzzIROvNO5vLtdFQRQnOMaetSAhKAC2sHiVsigEvcPplf4e1MdOc n6mQh7O9IKQoh3J8u9d9mZ+bCuXa7YqVPnHXhxgBQwTylkIedzTa5yW/PTM7NU8QVmrjRn4wPkABa 41LqOCkNFN8cBWSNyo4vZF6CdvDoqkIQAhpaqPV1STvDonaqF8McipSBRK8xnzlEwEk6Fr8kLrBRR 6BqrbDmWt56UNHT3lEUZBtuybm1Erv7CZWQFfpmTf01iJSwqmV6o3kGPBVJMhE60Hww3kVErFMga6 7xRRp/WA==; Received: from [63.118.15.50] (helo=Ph33r-Retina.local) by meldrar.postgresql.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hpaGN-0005BY-TM; Mon, 22 Jul 2019 15:30:10 +0000 Subject: Re: Formatting of warning about using ident To: Tom Lane , Peter Eisentraut Cc: Daniel Gustafsson , pgsql-docs@lists.postgresql.org References: <05d9e235-118f-2dbc-95c3-e1a51c19dad1@2ndquadrant.com> <23574.1563804571@sss.pgh.pa.us> From: "Jonathan S. Katz" Openpgp: preference=signencrypt Autocrypt: addr=jkatz@postgresql.org; keydata= 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 FmEC Message-ID: Date: Mon, 22 Jul 2019 11:30:01 -0400 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 MIME-Version: 1.0 In-Reply-To: <23574.1563804571@sss.pgh.pa.us> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="d7p7ZUgVPzjOeBJg6KL37jbL6JuBo6Z80" X-Host-Lookup-Failed: Reverse DNS lookup failed for 63.118.15.50 (failed) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --d7p7ZUgVPzjOeBJg6KL37jbL6JuBo6Z80 Content-Type: multipart/mixed; boundary="NccSqcDo9mqrNBnywjWj0NM42OlC9aSA1"; protected-headers="v1" From: "Jonathan S. Katz" To: Tom Lane , Peter Eisentraut Cc: Daniel Gustafsson , pgsql-docs@lists.postgresql.org Message-ID: Subject: Re: Formatting of warning about using ident References: <05d9e235-118f-2dbc-95c3-e1a51c19dad1@2ndquadrant.com> <23574.1563804571@sss.pgh.pa.us> In-Reply-To: <23574.1563804571@sss.pgh.pa.us> --NccSqcDo9mqrNBnywjWj0NM42OlC9aSA1 Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable On 7/22/19 10:09 AM, Tom Lane wrote: > Peter Eisentraut writes: >> In general, I would argue in favor of fewer "note", "warning", etc. >> Some documentation pages are now just a sequence of "note"s and little= >> proper text. If the normal text properly explains a topic and its pro= s >> and cons, then we don't need all that extra decoration and it makes th= e >> text easier to read. >=20 > +1. With the way these things are rendered in the current HTML output,= > they are so visually distracting that they ought to be reserved for > absolutely critical info. I almost feel that we should ban > entirely, because the rendering is completely disproportional to the > meaning. Based on the example of auth-ident.html, removing "note" seems to make sense. It just seems like it's a part of the regular documentation. However, perhaps the reason people feel the need to highlight such things is that they want to ensure the reader catches an important point, particularly as one is often reading the documentation quickly to find the piece of info they're looking for (speaking from personal experience). That said, looking through some other pages, the "notes" feel like they're other "asides" to add more detail around a particular point, or calling out a specific fact. It seems like they could be inlined as part of the regular documentation. Something like a "warning" should be visually distracting...it's a warning that the user could end up in a dangerous situation with their data, so they should heed it. > (Or, maybe, somebody could tinker with the stylesheets?) I think lessening the use of "note" would help. It would require some rewriting in places it's being used. That way, if we need something that's truly a "warning" we won't feel as hesitant to add it to the docs.= Thanks, Jonathan --NccSqcDo9mqrNBnywjWj0NM42OlC9aSA1-- --d7p7ZUgVPzjOeBJg6KL37jbL6JuBo6Z80 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl011nkACgkQ8QSccp8c ZSc7Xw//XCcvZt9hiU4lka4IudjBgqmgKrQnwBo3lRNpU+FLj2aE3bXblJFH2q0u T7NhmYd6493uecCVbxbqjquQxdFoQCbjV0fKTkni4KTQ4Z/xe/Qj0c+OmmEvdbaR aTn3RosSso48BWQYTlGotnfROAhbTCbkN3EmVbJxsql0XWsNw7YFGY0RWyV6Zis3 1OXAy2hnRtHo97YwawGekMN+v2LtCg/rBt7chhr5TjjFwNmqMLgsod76KkeHwbAK eUz0pnmx5sLjt6LCcsyetioa0iIeYcielB/YoRR3w/OcKHy/abvq3wP3X38fGaIu 4D0TYWIVt8656nx+QsgUiGvx5Vx4WbJYuPmAPVvPpq8QcHI5BcNY7TypIKAqExCM 1wSyHqGwLvQVb2sQA4X7aSYm3Vc3FdwHuaIBf9wNXm4kFetDb3xz4ZGfuId+VylF nLksyIBV2QbCWEBEUjk6aT9Ns0INdJQK9BY6U0AVQ6Q5B0tg96Vz0MQt1pLTb1DD LUZdIZT6qdwmZGskuEp9/QZm9qqRytrh7TKbwJWpGhcjPNTKax7NR7hwGkATT07u XFA4kG2aajEY1JRv3KrKR0+mSQA/xMn0aGkqsnO8vUtfWMP6RKV5tyblUwaF3Kg+ h2SkfuR62LJH1XDhhwiWkrgaoANC5L8Aq7lpcY2t6ngCrZFv1WY= =t9zA -----END PGP SIGNATURE----- --d7p7ZUgVPzjOeBJg6KL37jbL6JuBo6Z80--