[PATCH] Proposal: Improvements to PDF stylesheet and table column widths
Hi PostgreSQL Hackers,
I am a member of the PostgreSQL Japanese translation team, and I have been
working on improving the formatting and readability of the PostgreSQL
documentation in PDF format. This email contains two patches that I would
like to propose for consideration. These changes aim to enhance the layout
and usability of the generated PDFs, and I have included the resulting PDFs
for review.
---
### Patch 1: Improvements to `stylesheet-fo.xsl`
The first patch focuses on improving the PDF stylesheet (`stylesheet-fo.xsl`).
The key changes are as follows:
1. **Added `body.start.indent` and `body.end.indent` parameters**:
- Both are set to `0` to maximize the display width, which is particularly
important for tables.
2. **Adjusted `nongraphical.admonition.properties`**:
- Ensures that elements like "Note" and "Hint" are centered properly, as
they previously appeared misaligned to the right.
3. **Replaced `text-indent` with `margin-left` for `func_signature` and
`column_definition`**:
- The previous `text-indent: -3.5em` only affected the first line, causing
inconsistent formatting for multi-line code blocks. Changing this to
`margin-left: 0em` ensures consistent alignment across all lines.
4. **Introduced `shade.verbatim.style`**:
- Added a shaded background for code blocks to improve visual distinction.
This includes a border, padding, and a light gray background color
(`#EFEFEF`).
- Adjusted padding to reduce excessive spacing above code blocks.
These changes are intended to improve the overall usability and aesthetics
of the generated PDF documentation. However, I understand that some of these
changes, such as the shaded background for code blocks, may be subjective.
I welcome feedback and suggestions for further adjustments.
---
### Patch 2: Adjustments to table column widths
Building on the first patch, the second patch adjusts the column widths of
various tables in the documentation to take advantage of the increased
display width. The changes include:
1. **Added `<colspec>` elements to tables**:
- Adjusted column widths using `<colspec>` to ensure a better balance
between columns.
- For most tables, the first column (`col1`) is set to `1*` and the second
column (`col2`) is set to `3*`. This provides a proportional layout that
works well with the wider table display.
2. **Files affected**:
- `datatype.sgml`
- `func.sgml`
- `storage.sgml`
3. **PDF Results**:
- The resulting PDFs (`datatype.pdf`, `functions.pdf`, and `storage.pdf`)
are attached for review. These demonstrate the improved table layouts
with the adjusted column widths.
While I believe these changes improve the readability of the tables, I
understand that table layouts can be subjective and may require further
refinement. I am open to feedback and alternative suggestions.
---
### Attached Files
1. `improve-stylesheet-fo.diff`: Patch for `stylesheet-fo.xsl`.
2. `improve-pdf-table.diff`: Patch for `datatype.sgml`, `func.sgml`, and
`storage.sgml`.
3. `datatype.pdf`: Resulting PDF for `datatype.sgml`.
4. `functions.pdf`: Resulting PDF for `func.sgml`.
5. `storage.pdf`: Resulting PDF for `storage.sgml`.
---
Best regards,
Noboru Saito
Attachments:
improve-stylesheet-fo.difftext/x-patch; charset=US-ASCII; name=improve-stylesheet-fo.diffDownload
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index e7916a6a883..e8d9237ae51 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -32,6 +32,8 @@ an "Unresolved ID reference found" warning during PDF builds.
<xsl:param name="use.extensions" select="1"></xsl:param>
<xsl:param name="variablelist.as.blocks" select="1"></xsl:param>
<xsl:param name="orderedlist.label.width">1.5em</xsl:param>
+<xsl:param name="body.start.indent">0</xsl:param>
+<xsl:param name="body.end.indent">0</xsl:param>
<xsl:attribute-set name="monospace.verbatim.properties"
use-attribute-sets="verbatim.properties monospace.properties">
@@ -46,6 +48,8 @@ an "Unresolved ID reference found" warning during PDF builds.
<xsl:attribute name="padding-end">12pt</xsl:attribute>
<xsl:attribute name="padding-top">6pt</xsl:attribute>
<xsl:attribute name="padding-bottom">6pt</xsl:attribute>
+ <xsl:attribute name="margin-left">0.25in</xsl:attribute>
+ <xsl:attribute name="margin-right">0.25in</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="admonition.title.properties">
@@ -98,7 +102,7 @@ an "Unresolved ID reference found" warning during PDF builds.
<xsl:template match="entry[@role='func_table_entry']/para">
<fo:block margin-left="4em" text-align="left">
<xsl:if test="self::para[@role='func_signature']">
- <xsl:attribute name="text-indent">-3.5em</xsl:attribute>
+ <xsl:attribute name="margin-left">0em</xsl:attribute>
</xsl:if>
<xsl:apply-templates/>
</fo:block>
@@ -108,12 +112,23 @@ an "Unresolved ID reference found" warning during PDF builds.
<xsl:template match="entry[@role='catalog_table_entry']/para">
<fo:block margin-left="4em" text-align="left">
<xsl:if test="self::para[@role='column_definition']">
- <xsl:attribute name="text-indent">-3.5em</xsl:attribute>
+ <xsl:attribute name="margin-left">0em</xsl:attribute>
</xsl:if>
<xsl:apply-templates/>
</fo:block>
</xsl:template>
+<xsl:param name="shade.verbatim">1</xsl:param>
+<xsl:attribute-set name="shade.verbatim.style">
+ <xsl:attribute name="border">1pt solid black</xsl:attribute>
+ <xsl:attribute name="margin-left">0</xsl:attribute>
+ <xsl:attribute name="margin-right">0</xsl:attribute>
+ <xsl:attribute name="background-color">#EFEFEF</xsl:attribute>
+ <xsl:attribute name="padding">5pt</xsl:attribute>
+ <xsl:attribute name="padding-bottom">10pt</xsl:attribute>
+ <xsl:attribute name="padding-top">0pt</xsl:attribute>
+</xsl:attribute-set>
+
<!-- overrides stylesheet-common.xsl -->
<!-- FOP needs us to be explicit about the font to use for right arrow -->
<xsl:template match="returnvalue">
improve-pdf-table.difftext/x-patch; charset=US-ASCII; name=improve-pdf-table.diffDownload
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 09309ba0390..42e428dd8a5 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2054,8 +2054,6 @@ MINUTE TO SECOND
<table id="datatype-datetime-time-table">
<title>Time Input</title>
<tgroup cols="2">
- <colspec colname="col1" colwidth="3*"/>
- <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>Example</entry>
@@ -5234,8 +5232,8 @@ WHERE ...
<table id="datatype-pseudotypes-table">
<title>Pseudo-Types</title>
<tgroup cols="2">
- <colspec colname="col1" colwidth="2*"/>
- <colspec colname="col2" colwidth="3*"/>
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>Name</entry>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 27ec46105f4..d57a0ae52a7 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6561,6 +6561,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Atoms</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Atom</entry>
@@ -6643,6 +6645,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Quantifiers</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Quantifier</entry>
@@ -6747,6 +6751,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Constraints</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Constraint</entry>
@@ -6985,6 +6991,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Character-Entry Escapes</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Escape</entry>
@@ -7126,6 +7134,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Class-Shorthand Escapes</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Escape</entry>
@@ -7185,6 +7195,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Constraint Escapes</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Escape</entry>
@@ -7241,6 +7253,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>Regular Expression Back References</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Escape</entry>
@@ -7322,6 +7336,8 @@ regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<title>ARE Embedded-Option Letters</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Option</entry>
@@ -8130,6 +8146,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
<table id="functions-formatting-datetime-table">
<title>Template Patterns for Date/Time Formatting</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Pattern</entry>
@@ -8723,6 +8741,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
<table id="functions-formatting-numeric-table">
<title>Template Patterns for Numeric Formatting</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Pattern</entry>
@@ -26927,6 +26947,8 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
<table id="functions-info-index-column-props">
<title>Index Column Properties</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row><entry>Name</entry><entry>Description</entry></row>
</thead>
@@ -26986,6 +27008,8 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
<table id="functions-info-index-props">
<title>Index Properties</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row><entry>Name</entry><entry>Description</entry></row>
</thead>
@@ -27019,6 +27043,8 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
<table id="functions-info-indexam-props">
<title>Index Access Method Properties</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row><entry>Name</entry><entry>Description</entry></row>
</thead>
@@ -27058,6 +27084,8 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
<table id="functions-pg-settings-flags">
<title>GUC Flags</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row><entry>Flag</entry><entry>Description</entry></row>
</thead>
@@ -27701,6 +27729,8 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres}
<table id="functions-pg-snapshot-parts">
<title>Snapshot Components</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Name</entry>
@@ -28263,6 +28293,8 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres}
<table id="functions-pg-control-recovery">
<title><function>pg_control_recovery</function> Output Columns</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="3*"/>
<thead>
<row>
<entry>Column Name</entry>
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 61250799ec0..02ddfda834a 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -39,6 +39,8 @@ these required items, the cluster configuration files
<table tocentry="1" id="pgdata-contents-table">
<title>Contents of <varname>PGDATA</varname></title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>
@@ -743,6 +745,8 @@ There are five parts to each page.
<title>Overall Page Layout</title>
<titleabbrev>Page Layout</titleabbrev>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>
datatype.pdfapplication/pdf; name=datatype.pdfDownload
%PDF-1.4
%����
1 0 obj
<<
/Title (PostgreSQL 18beta1 Documentation)
/Author (The PostgreSQL Global Development Group)
/Creator (DocBook XSL Stylesheets with Apache FOP)
/Producer (Apache FOP Version 2.8)
/CreationDate (D:20250508150541+09'00')
>>
endobj
2 0 obj
<<
/N 3
/Length 3 0 R
/Filter /FlateDecode
>>
stream
x���gPTY��{�
�M���I��$�$A��@w�i��AQdpFI� ���AFQ��((��N#��2�"**K�������U[�g��x��sO�s��[����1������M��:�1��C� H�( �JN���� �!���c ����s����>��qy�v�y����%��. ����lN2k�w�r4;�-��
8=%1 �{�i��W�-��o�!��o\�V��k��� ���Z�kL�0+�� �t�j�
+���|iA/�o3���`?�(��O���f+�y�S/T�����7����o��r�L@���r��`� Q�WN� �= t����8@W) ��X���o9��� ����<P@S`l�#p^�����A��t�v�PJ�!P
�@#hm�,��p���(� |0
^��,C��H�� UH2����y@�P0EA\(���@EPT
�C��O�y�
t�A���'� F�D���j���maw��G�Ip���+��4� _�o��0~/"