pgsql: Get rid of parameterized marked sections in SGML

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: pgsql-committers(at)postgresql(dot)org
Subject: pgsql: Get rid of parameterized marked sections in SGML
Date: 2017-09-27 15:28:04
Message-ID: E1dxEFo-0006gS-DC@gemulon.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-committers

Get rid of parameterized marked sections in SGML

Previously, we created a variant of the installation instructions for
producing the plain-text INSTALL file by marking up certain parts of
installation.sgml using SGML parameterized marked sections. Marked
sections will not work anymore in XML, so before we can convert the
documentation to XML, we need a new approach.

DocBook provides a "profiling" feature that allows selecting content
based on attributes, which would work here. But it imposes a noticeable
overhead when building the full documentation and causes complications
when building some output formats, and given that we recently spent a
fair amount of effort optimizing the documentation build time, it seems
sad to have to accept that.

So as an alternative, (1) we create our own mini-profiling layer that
adjusts just the text we want, and (2) assemble the pieces of content
that we want in the INSTALL file using XInclude. That way, there is no
overhead when building the full documentation and most of the "ugly"
stuff in installation.sgml can be removed and dealt with out of line.

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/684cf76b83e9dc8aed12aeb9131d2208f61bd31f

Modified Files
--------------
doc/src/sgml/Makefile | 5 +-
doc/src/sgml/filelist.sgml | 9 --
doc/src/sgml/installation.sgml | 245 +++++------------------------------
doc/src/sgml/standalone-install.sgml | 28 ----
doc/src/sgml/standalone-install.xml | 167 ++++++++++++++++++++++++
doc/src/sgml/standalone-profile.xsl | 81 ++++++++++++
6 files changed, 280 insertions(+), 255 deletions(-)

Browse pgsql-committers by date

  From Date Subject
Next Message Peter Eisentraut 2017-09-27 15:51:49 pgsql: Improve vpath support in plperl build
Previous Message Alvaro Herrera 2017-09-27 13:11:10 Re: ALTER enums (was Re: [COMMITTERS] pgsql: doc: first draft of Postgres 10 release notes)