Re: [PATCH] Proposal: Improvements to PDF stylesheet and table column widths

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(at)gmail(dot)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