Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtp (Exim 4.84_2)
	(envelope-from
 <pgsql-docs-owner+M9613=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
	id 1e5x5W-0008J2-Ah
	for pgsql-docs@arkaria.postgresql.org; Sat, 21 Oct 2017 16:57:30 +0000
Received: from localhost ([127.0.0.1] helo=postgresql.org)
	by malur.postgresql.org with smtp (Exim 4.84_2)
	(envelope-from
 <pgsql-docs-owner+M9613=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
	id 1e5x5V-0005Rn-PL
	for pgsql-docs@arkaria.postgresql.org; Sat, 21 Oct 2017 16:57:29 +0000
Received: from makus.postgresql.org ([2001:4800:1501:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <peter.eisentraut@2ndquadrant.com>)
	id 1e5x58-0004m9-6e
	for pgsql-docs@postgresql.org; Sat, 21 Oct 2017 16:57:06 +0000
Received: from out4-smtp.messagingengine.com ([66.111.4.28])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <peter.eisentraut@2ndquadrant.com>)
	id 1e5x54-0006c9-No
	for pgsql-docs@postgresql.org; Sat, 21 Oct 2017 16:57:04 +0000
Received: from compute7.internal (compute7.nyi.internal [10.202.2.47])
	by mailout.nyi.internal (Postfix) with ESMTP id 7938F206B8
	for <pgsql-docs@postgresql.org>; Sat, 21 Oct 2017 12:57:01 -0400 (EDT)
Received: from frontend2 ([10.202.2.161])
  by compute7.internal (MEProxy); Sat, 21 Oct 2017 12:57:01 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=
	messagingengine.com; h=content-transfer-encoding:content-type
	:date:from:message-id:mime-version:subject:to:x-me-sender
	:x-me-sender:x-sasl-enc; s=fm1; bh=P0TJQ/AjC+Bet0E2mgjiIB2hukYwH
	U2q2cUxJPUIot4=; b=AWPya1oV5XV0PRZEM6TIODiGTHruIq8RB6cDjalFtDCI6
	8+w6wbdX/EgfQR7h0JJNt6cSp+h1nrerkrndwNUunEkeE2Ft7PiyTwD3dnseeeUy
	RfnnqC3j6iLmhCxIgB1py+UmlnQZk6I5HmwZzuPNyMnThagPrtN4rlrW+Hh7lWXe
	MdHLObKe69pEvXcRispQOuJAzHkeFoTaHpkq5xSXA/QS/ktFupsoJOPKDrJgbnby
	4AXpx6urN6Wle9aEGLZZZWDjJ0nS2YSBx/ajd8PvMqivL3FHJi5OjLoWo9LyBQqB
	WECt8weTQEYRoLZd/4H+ZQq+n6hf9KZpHOYFVIvfg==
X-ME-Sender: <xms:XXzrWfURN55CiFSDCwCvOVCVN-xoJzmLu1HmvirE-ej1vtlKoQB8sQ>
Received: from april.local (c-73-13-66-39.hsd1.pa.comcast.net [73.13.66.39])
	by mail.messagingengine.com (Postfix) with ESMTPA id 3CF262484B
	for <pgsql-docs@postgresql.org>; Sat, 21 Oct 2017 12:57:01 -0400 (EDT)
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Subject: backpatching documentation after conversion to XML
To: pgsql-docs <pgsql-docs@postgresql.org>
Organization: 2ndQuadrant
Message-ID: <609dc528-6eab-522d-5b7d-842bd83159e5@2ndquadrant.com>
Date: Sat, 21 Oct 2017 12:57:00 -0400
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:52.0)
 Gecko/20100101 Thunderbird/52.4.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 8bit
List-Archive: <http://archives.postgresql.org/pgsql-docs>
List-Help: <mailto:majordomo@postgresql.org?body=help>
List-ID: <pgsql-docs.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@postgresql.org>
List-Post: <mailto:pgsql-docs@postgresql.org>
List-Subscribe: <mailto:majordomo@postgresql.org?body=sub%20pgsql-docs>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
X-Mailing-List: pgsql-docs
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

In a nearby message, Tom pointed out that the ongoing conversion of the
documentation sources from SGML to XML could/will cause problems when
backpatching.  The changes made so far would merely cause merge
conflicts but there is an additional issue to consider that can cause
compatibility problems.

When we finally convert the sources from SGML to XML, we will have to
change empty tags such as

    <xref linkend="foo">

to XML syntax

    <xref linkend="foo"/>

(like HTML versus XHTML).  The problem is that if you backpatch that
literally into an SGML source, it will be interpreted as

    <xref linkend="foo">>

(i.e., an additional character will appear in the output) without an
indication of an error.

One workaround (other than being careful) would be to write

    <xref linkend="foo"></xref>

and maintain that style until the last SGML-based version goes EOL.

Another workaround would be to backpatch a check that greps for
something like '[^<]/>' in *.sgml and errors on that.

(AFAICT, this is the last major issue impacting the conversion, so when
we have resolved this, this can go ahead.)

Thoughts?

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs