Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kOiyn-00072t-90 for pgsql-hackers@arkaria.postgresql.org; Sat, 03 Oct 2020 14:57:45 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1kOiym-0007LR-4Y for pgsql-hackers@arkaria.postgresql.org; Sat, 03 Oct 2020 14:57:44 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kOiyl-0007LJ-2C for pgsql-hackers@lists.postgresql.org; Sat, 03 Oct 2020 14:57:43 +0000 Received: from wforward1-smtp.messagingengine.com ([64.147.123.30]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kOiyi-0003p8-3m for pgsql-hackers@postgresql.org; Sat, 03 Oct 2020 14:57:41 +0000 Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailforward.west.internal (Postfix) with ESMTP id 8DF431106; Sat, 3 Oct 2020 10:57:37 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Sat, 03 Oct 2020 10:57:37 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=BGyL2FL+WHnQBt5uSDVIsw8fZ7ZwHQLrmpxl52xgJ vE=; b=YgjNB7pvl4zpnppBfJ7ouTHaF2kmdqW9qSMolRupCuWhc6x+3oX89ZdMS 1gAg+eibO57ib7fCylkxdhOykuBFiGMr+QcscmEJjRlpf3CxUzjus38mx58Pgtva XEo3UOB5+m1SfOQi0tbm03nzzEXaRX+zrCspyiH0cc88qlaw00MwG8pL/uNqjdS7 BUaRoKb2RzVQOqdmTN3L8VB5tqB2bE6rv1+l8gfbLKOmLkQ6K9K3xpfvupy49z6t ArdhBBI+TYPZzvpxbdW8y67T8kcj90+URaEwJ7sWqkcsRpl7NpoUWvqz8BcLrdNj airHJxDfNo9RdGWo9IqU5b1X1Kfww== X-ME-Sender:

X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedujedrfeekgdekudcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefuhffvfhhokffffgggjggtgfesthejredttdefjeenucfhrhhomheprfgvthgv rhcugfhishgvnhhtrhgruhhtuceophgvthgvrhdrvghishgvnhhtrhgruhhtsedvnhguqh hurggurhgrnhhtrdgtohhmqeenucggtffrrghtthgvrhhnpedtheefgfdvudffudefvdej fedukeegudevjeevhfduudekuefhvdevueejfedvteenucffohhmrghinhepvdhnughquh grughrrghnthdrtghomhenucfkphepkeejrddujeejrdeigedrudeludenucevlhhushht vghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehpvghtvghrrdgvihhsvg hnthhrrghuthesvdhnughquhgrughrrghnthdrtghomh X-ME-Proxy:

Received: from april.pezone.net (p57b140bf.dip0.t-ipconnect.de [87.177.64.191]) by mail.messagingengine.com (Postfix) with ESMTPA id 310D53064610; Sat, 3 Oct 2020 10:57:36 -0400 (EDT) Subject: Re: vs formatting in the docs From: Peter Eisentraut To: =?UTF-8?Q?Dagfinn_Ilmari_Manns=c3=a5ker?= , Alvaro Herrera References: <20200621153038.GA2296@alvherre.pgsql> <87lfkgnypi.fsf@wibble.ilmari.org> <631ac57a-e4aa-a3a7-2b0d-0a84974c2205@2ndquadrant.com> Cc: PostgreSQL Hackers Organization: 2ndQuadrant Message-ID: Date: Sat, 3 Oct 2020 16:57:34 +0200 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk On 2020-09-25 07:38, Peter Eisentraut wrote: > So, based on that, I think the patch proposed here is not the right one, > and we should instead be marking up the link sources appropriately. I have committed a fix for this: Improve vs. formatting in the documentation SQL commands are generally marked up as , except when a link to a reference page is used using . But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting in the on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the inside the ; the DTD doesn't allow this. DocBook 5 would allow the to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the s to plus . This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain . In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see ") the xref is kept. Let me know if I missed something or further changes are needed. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services