[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+17-2
improve-pdf-table.difftext/x-patch; charset=US-ASCII; name=improve-pdf-table.diffDownload+38-4
datatype.pdfapplication/pdf; name=datatype.pdfDownload+1-1
functions.pdfapplication/pdf; name=functions.pdfDownload+7-9
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>:
Show quoted text
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]https://git-scm.com/docs/git-format-patch.
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
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.
2025年5月30日(金) 13:26 Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com>:
Show quoted text
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.
Hi,
Thank you very much for your feedback.
From my own testing, I believe that setting the indentation to zero does not
introduce any issues in the generated PDFs. If I had to mention a possible
side effect, it might be that admonition blocks become a bit more visually
prominent on the right side of the page.
To address this, I thought it could be helpful to add left and right margins
to nongraphical.admonition.properties so that admonitions are more centered.
I am attaching two files for your reference:
- 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)
Please let me know if you have any thoughts or further suggestions.
Best regards,
Noboru Saito
2025年6月1日(日) 18:27 Florents Tselai <florents.tselai@gmail.com>:
Show quoted text
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]https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Email 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 prefer the 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>:
Show quoted text
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.25inThis 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
Attachments:
0001-setting-both-body.start.indent-and-body.end.indent-t.patchtext/x-patch; charset=US-ASCII; name=0001-setting-both-body.start.indent-and-body.end.indent-t.patchDownload+2-1
0002-set-margin-left-and-margin-right-to-0.25in.patchtext/x-patch; charset=US-ASCII; name=0002-set-margin-left-and-margin-right-to-0.25in.patchDownload+2-1
postgres-A4.pdfapplication/pdf; name=postgres-A4.pdfDownload+13-13
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.25inI 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]https://wiki.postgresql.org/wiki/Mailing_Lists:
```
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]https://www.slideshare.net/slideshow/postgresql-community-development-deim2024-nttdata/266677773#24.
[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
```
Attachments:
postgres-US.pdfapplication/pdf; name=postgres-US.pdfDownload+6-8
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]https://commitfest.postgresql.org/patch/5775/. And cfbot said OK.
[1]: https://commitfest.postgresql.org/patch/5775/
Best regards,
Hayato Kuroda
FUJITSU LIMITED
Dear Kuroda-san,
Dear Ishii-san,
Actually Saito-san has already been registered [1]. And cfbot said OK.
Thank you for pointing it out. Also I see Peter has been already
registered as a committer. Great.
Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp
On 26.06.25 08:47, Tatsuo Ishii wrote:
Dear Kuroda-san,
Dear Ishii-san,
Actually Saito-san has already been registered [1]. And cfbot said OK.
Thank you for pointing it out. Also I see Peter has been already
registered as a committer. Great.
committed
On 08.05.25 09:18, Noboru Saito wrote:
### 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.
I have committed this, except the change in table
functions-pg-control-recovery, which didn't seem right.
On 08.05.25 09:18, Noboru Saito wrote:
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.
I think I found what this is meant to change, but it's not clear why one
is better than the other. I think you would need to provide some
concrete examples with screenshots perhaps that people could look at.
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.
I'm not a fan of this change. The boxes break the flow of the text.
I think it's ok to put boxes and shading around elements that are not in
the flow of the text, like the warning boxes, are perhaps tables or
formal examples. But not verbatim text that is part of the main text.