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.

On 30.05.25 01:06, Noboru Saito wrote:
> 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.

I agree with this change.

I don't necessarily care about the page count change, but I just find 
the output easier to read without the indentation.

Dear Saito-san,

> - A patch that adds margins to admonition blocks.
> - An updated image where I have highlighted the space with a red
> border for clarity.
> 
> The image shows:
> - The original layout (top left)
> - Only indentation set to 0 (top right)
> - Indentation 0 plus admonition margins (bottom right)

To confirm, the top-right was generated with the previous patch, and bottom-right
was generated v2 patch, right? I prefer the bottom-right one.

BTW, I can suggest separating patches like:

0001 - setting both body.start.indent and body.end.indent to 0
0002 - set margin-left and margin-right to 0.25in

This approach makes us easier to understand and discuss, i.e., someone only loves
0001. They can be combined by committers when they push changes.
To create a series of patches, you can git format-patch command can be used.
Please refer [1] for more detail.


[1]: https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Email

Best regards,
Hayato Kuroda
FUJITSU LIMITED

Dear Kuroda-san,

Thank you for your feedback and suggestions.

> To confirm, the top-right was generated with the previous patch, and bottom-right was generated v2 patch, right? I
preferthe bottom-right one. 

Yes, your understanding is correct. The top-right image was generated
with the previous patch, and the bottom-right with the v2 patch.

Thank you also for your advice regarding splitting the patch into two parts:
- 0001: Set both body.start.indent and body.end.indent to 0
- 0002: Set margin-left and margin-right to 0.25in

I agree that separating the patches will make the review process easier.
I will prepare and send a patch series using `git format-patch` as you
suggested.

I have also attached a part of the PDF generated with both 0001 and
0002 applied for your reference.

Best regards,
Noboru Saito

2025年6月9日(月) 16:17 Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com>:
>
> Dear Saito-san,
>
> > - A patch that adds margins to admonition blocks.
> > - An updated image where I have highlighted the space with a red
> > border for clarity.
> >
> > The image shows:
> > - The original layout (top left)
> > - Only indentation set to 0 (top right)
> > - Indentation 0 plus admonition margins (bottom right)
>
> To confirm, the top-right was generated with the previous patch, and bottom-right
> was generated v2 patch, right? I prefer the bottom-right one.
>
> BTW, I can suggest separating patches like:
>
> 0001 - setting both body.start.indent and body.end.indent to 0
> 0002 - set margin-left and margin-right to 0.25in
>
> This approach makes us easier to understand and discuss, i.e., someone only loves
> 0001. They can be combined by committers when they push changes.
> To create a series of patches, you can git format-patch command can be used.
> Please refer [1] for more detail.
>
>
> [1]: https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Email
>
> Best regards,
> Hayato Kuroda
> FUJITSU LIMITED
>

Dear Saito-san,

> Yes, your understanding is correct. The top-right image was generated
> with the previous patch, and the bottom-right with the v2 patch.
> 
> Thank you also for your advice regarding splitting the patch into two parts:
> - 0001: Set both body.start.indent and body.end.indent to 0
> - 0002: Set margin-left and margin-right to 0.25in
> 
> I agree that separating the patches will make the review process easier.
> I will prepare and send a patch series using `git format-patch` as you
> suggested.
> 
> I have also attached a part of the PDF generated with both 0001 and
> 0002 applied for your reference.

The patch is cleanly created, and +1 for all contents.



Another general suggestion: Please avoid the top-post when you reply. According
to the wikipage [1]:

```
Finally, our community generally does not "top post" in response to mailing list threads (See Wikipedia:
Top Postingfor a definition of top posting, and Top Posting Deprecated for discussion of why we discourage it).
```

And a Japanese article written by Fujii-san is also helpful [2].

[1]: https://wiki.postgresql.org/wiki/Mailing_Lists
[2]: https://www.slideshare.net/slideshow/postgresql-community-development-deim2024-nttdata/266677773#24

Best regards,
Hayato Kuroda
FUJITSU LIMITED

Dear Kuroda-san,

2025年6月11日(水) 13:48 Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com>:
> > I have also attached a part of the PDF generated with both 0001 and
> > 0002 applied for your reference.
>
> The patch is cleanly created, and +1 for all contents.

Thank you very much for your review and for confirming the patch contents.

> Another general suggestion: Please avoid the top-post when you reply. According
> to the wikipage [1]:
>

Thank you, I stopped using the Gmail email client and started making mistakes.

> Dear Kuroda-san,
> 
> 2025年6月11日(水) 13:48 Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com>:
>> > I have also attached a part of the PDF generated with both 0001 and
>> > 0002 applied for your reference.
>>
>> The patch is cleanly created, and +1 for all contents.
> 
> Thank you very much for your review and for confirming the patch contents.
> 
>> Another general suggestion: Please avoid the top-post when you reply. According
>> to the wikipage [1]:
>>
> 
> Thank you, I stopped using the Gmail email client and started making mistakes.

I wonder how your patches apply to non A4 format (letter). Can you
please share the PDF file in letter format after patching?  Also I
would like to get comments from native English speakers. Are they
comfortable with the proposed changes?

Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

 Dear Ishii-san,

> I wonder how your patches apply to non A4 format (letter). Can you
> please share the PDF file in letter format after patching?

I had not mentioned the US letter format before, but the patch also
affects the US letter version.
I attach a PDF of the US letter version created with the following
command after applying the patch.

```
make "XSLTPROCFLAGS= --stringparam rootid functions" postgres-US.pdf
```

Dear Saito-san,

>  Dear Ishii-san,
> 
>> I wonder how your patches apply to non A4 format (letter). Can you
>> please share the PDF file in letter format after patching?
> 
> I had not mentioned the US letter format before, but the patch also
> affects the US letter version.
> I attach a PDF of the US letter version created with the following
> command after applying the patch.
> 
> ```
> make "XSLTPROCFLAGS= --stringparam rootid functions" postgres-US.pdf
> ```

The PDF file looks good to me.

Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

Dear Saito-san,

>>  Dear Ishii-san,
>> 
>>> I wonder how your patches apply to non A4 format (letter). Can you
>>> please share the PDF file in letter format after patching?
>> 
>> I had not mentioned the US letter format before, but the patch also
>> affects the US letter version.
>> I attach a PDF of the US letter version created with the following
>> command after applying the patch.
>> 
>> ```
>> make "XSLTPROCFLAGS= --stringparam rootid functions" postgres-US.pdf
>> ```
> 
> The PDF file looks good to me.

I think it's better to register the patch to CommitFest.

https://commitfest.postgresql.org/

Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

Dear Ishii-san,

Actually Saito-san has already been registered [1]. And cfbot said OK.

[1]: https://commitfest.postgresql.org/patch/5775/

Best regards,
Hayato Kuroda
FUJITSU LIMITED