Thread: [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

Hi PostgreSQL Hackers,

Since my previous email included many changes and may have been
difficult to review, I would like to propose a much simpler change
this time.

I suggest setting both body.start.indent and body.end.indent to 0 in
stylesheet-fo.xsl as follows:

<xsl:param name="body.start.indent">0</xsl:param>
<xsl:param name="body.end.indent">0</xsl:param>

This change maximizes the usable width of each page in the generated
PDF documentation. As a result, the total number of pages is reduced
from 3095 to 2960, making the PDF more compact and easier to read.

For your reference, I have attached a screenshot  comparing the
current and proposed layouts.

I would appreciate any feedback on this small change.

Best regards,
Noboru Saito

2025年5月8日(木) 16:18 Noboru Saito <noborusai@gmail.com>:
>
> 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

Dear Saito-san,

> Since my previous email included many changes and may have been
> difficult to review, I would like to propose a much simpler change
> this time.

I feel this is a reasonable approach. If needed, you can create set of patches
and can discuss from 0001. See [1].

> I suggest setting both body.start.indent and body.end.indent to 0 in
> stylesheet-fo.xsl as follows:
> 
> <xsl:param name="body.start.indent">0</xsl:param>
> <xsl:param name="body.end.indent">0</xsl:param>
> 
> This change maximizes the usable width of each page in the generated
> PDF documentation. As a result, the total number of pages is reduced
> from 3095 to 2960, making the PDF more compact and easier to read.

Sounds great.

> For your reference, I have attached a screenshot  comparing the
> current and proposed layouts.

To confirm, generated pdf with current setting is left slide, and it would
become like right side, is it correct? I prefer right one.

[1]: https://git-scm.com/docs/git-format-patch

Best regards,
Hayato Kuroda
FUJITSU LIMITED

> On 30 May 2025, at 8:27 AM, Noboru Saito <noborusai@gmail.com> wrote:
>
> Thank you Kuroda-san.
>
>> To confirm, generated pdf with current setting is left slide, and it would
>> become like right side, is it correct? I prefer right one.
>
> Sorry for the lack of explanation.
> That's right, the version on the left is the previous version,
> and the version on the right has the patch applied.

Thanks for starting this thread; the documentation could use some love.

The patch applies cleanly for me and I can reproduce the screenshot shared above.
Indeed I prefer the new margins too; the existing layout wastes too much whitespace indeed.