From 5545b69ae65f27ba1f4ceaf24486e98c186e9412 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 4 May 2020 16:16:42 -0400
Subject: [PATCH] Doc: improve PDF presentation of some tables by adjusting
 column widths.

The PDF toolchain defaults to laying out all columns of a table with
equal widths, in contrast to the HTML rendering which automatically
varies the column widths to fit the data.  In many places, this
results in very badly laid-out tables, with lots of useless whitespace
in some places and text that overruns its cell in other places.

For tables that have reasonably static content, we can improve
matters by adding <colspec> entries to hand-assign the column widths.
This commit does that for a few of the tables that were worst off;
it eliminates close to 200 "contents ... exceed the available area"
warnings in an A4 PDF build.

I also forced align="left" in these tables, overriding the PDF
toolchain's default which is evidently "justify".  (The HTML toolchain
seems to default to that already.)  Anyplace where things are tight
enough that we need to worry about this, forced justification tends to
look truly awful.
---
 doc/src/sgml/charset.sgml               | 16 +++++++++++++++-
 doc/src/sgml/errcodes.sgml              |  4 ++--
 doc/src/sgml/features.sgml              |  8 ++++++++
 doc/src/sgml/generate-keywords-table.pl |  5 +++++
 4 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index b6023fa459..04e71f17d3 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -95,6 +95,8 @@ initdb --locale=sv_SE
 
     <informaltable>
      <tgroup cols="2">
+      <colspec colname="col1" align="left" colwidth="1*"/>
+      <colspec colname="col2" align="left" colwidth="3*"/>
       <tbody>
        <row>
         <entry><envar>LC_COLLATE</envar></entry>
@@ -993,6 +995,13 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
      <table id="charset-table">
       <title><productname>PostgreSQL</productname> Character Sets</title>
       <tgroup cols="7">
+       <colspec colname="col1" align="left" colwidth="3*"/>
+       <colspec colname="col2" align="left" colwidth="2*"/>
+       <colspec colname="col3" align="left" colwidth="2*"/>
+       <colspec colname="col4" align="left" colwidth="1.25*"/>
+       <colspec colname="col5" align="left" colwidth="1*"/>
+       <colspec colname="col6" align="left" colwidth="1*"/>
+       <colspec colname="col7" align="left" colwidth="2*"/>
        <thead>
         <row>
          <entry>Name</entry>
@@ -1004,7 +1013,7 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
           The Bytes/Char field is populated by looking at the values returned
           by pg_wchar_table.mblen function for each encoding.
          -->
-         <entry>Bytes/Char</entry>
+         <entry>Bytes/&zwsp;Char</entry>
          <entry>Aliases</entry>
         </row>
        </thead>
@@ -1635,6 +1644,8 @@ RESET client_encoding;
     <table id="multibyte-translation-table">
      <title>Built-in Client/Server Character Set Conversions</title>
      <tgroup cols="2">
+      <colspec colname="col1" align="left" colwidth="1*"/>
+      <colspec colname="col2" align="left" colwidth="3*"/>
       <thead>
        <row>
         <entry>Server Character Set</entry>
@@ -1933,6 +1944,9 @@ RESET client_encoding;
     <table id="builtin-conversions-table">
      <title>All Built-in Character Set Conversions</title>
      <tgroup cols="3">
+      <colspec colname="col1" align="left" colwidth="2*"/>
+      <colspec colname="col2" align="left" colwidth="1*"/>
+      <colspec colname="col3" align="left" colwidth="1*"/>
       <thead>
        <row>
         <entry>Conversion Name
diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index 6fd16f643e..f0ef050033 100644
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -66,8 +66,8 @@
  <title><productname>PostgreSQL</productname> Error Codes</title>
 
  <tgroup cols="2">
-  <colspec colnum="1" colname="errorcode"/>
-  <colspec colnum="2" colname="condname"/>
+  <colspec colnum="1" colname="errorcode" align="left" colwidth="1*"/>
+  <colspec colnum="2" colname="condname" align="left" colwidth="8*"/>
   <spanspec namest="errorcode" nameend="condname" spanname="span12"/>
 
   <thead>
diff --git a/doc/src/sgml/features.sgml b/doc/src/sgml/features.sgml
index b4596a9eb2..330481ff6a 100644
--- a/doc/src/sgml/features.sgml
+++ b/doc/src/sgml/features.sgml
@@ -111,6 +111,10 @@
    <para>
     <informaltable>
      <tgroup cols="4">
+      <colspec colname="col1" align="left" colwidth="1.5*"/>
+      <colspec colname="col2" align="left" colwidth="1*"/>
+      <colspec colname="col3" align="left" colwidth="7*"/>
+      <colspec colname="col4" align="left" colwidth="3*"/>
       <thead>
        <row>
         <entry>Identifier</entry>
@@ -138,6 +142,10 @@
 
     <informaltable>
      <tgroup cols="4">
+      <colspec colname="col1" align="left" colwidth="1.5*"/>
+      <colspec colname="col2" align="left" colwidth="1*"/>
+      <colspec colname="col3" align="left" colwidth="7*"/>
+      <colspec colname="col4" align="left" colwidth="3*"/>
       <thead>
        <row>
         <entry>Identifier</entry>
diff --git a/doc/src/sgml/generate-keywords-table.pl b/doc/src/sgml/generate-keywords-table.pl
index 086a158e79..a975b058d8 100644
--- a/doc/src/sgml/generate-keywords-table.pl
+++ b/doc/src/sgml/generate-keywords-table.pl
@@ -56,6 +56,11 @@ print <<END;
  <title><acronym>SQL</acronym> Key Words</title>
 
  <tgroup cols="5">
+  <colspec colname="col1" align="left" colwidth="5*"/>
+  <colspec colname="col2" align="left" colwidth="3*"/>
+  <colspec colname="col3" align="left" colwidth="2*"/>
+  <colspec colname="col4" align="left" colwidth="2*"/>
+  <colspec colname="col5" align="left" colwidth="2*"/>
   <thead>
    <row>
     <entry>Key Word</entry>