Thread

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

Adjust some table column widths in PDF
- 05f506a5158e 19 (unreleased) landed
Improve PDF documentation margins
- 37e06ba6e82b 19 (unreleased) landed

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

Noboru Saito <noborusai@gmail.com> — 2025-05-08T07:18:25Z

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

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

Noboru Saito <noborusai@gmail.com> — 2025-05-29T23:06:39Z

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

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

Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com> — 2025-05-30T04:26:47Z

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

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

Noboru Saito <noborusai@gmail.com> — 2025-05-30T05:27:04Z

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

>
> 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
>

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

Florents Tselai <florents.tselai@gmail.com> — 2025-06-01T09:27:05Z

> 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.

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

Noboru Saito <noborusai@gmail.com> — 2025-06-04T05:37:04Z

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>:
>
>
>
> > 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.
>

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

Peter Eisentraut <peter@eisentraut.org> — 2025-06-05T09:15:55Z

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.

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

Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com> — 2025-06-09T07:17:12Z

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

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

Noboru Saito <noborusai@gmail.com> — 2025-06-10T23:39:10Z

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

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

Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com> — 2025-06-11T04:48:09Z

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

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

Noboru Saito <noborusai@gmail.com> — 2025-06-11T23:49:11Z

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.

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

Tatsuo Ishii <ishii@postgresql.org> — 2025-06-12T03:52:13Z

> 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

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

Noboru Saito <noborusai@gmail.com> — 2025-06-12T06:13:12Z

 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
```

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

Tatsuo Ishii <ishii@postgresql.org> — 2025-06-12T09:34:34Z

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

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

Tatsuo Ishii <ishii@postgresql.org> — 2025-06-26T05:57:51Z

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

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

Hayato Kuroda (Fujitsu) <kuroda.hayato@fujitsu.com> — 2025-06-26T06:01:11Z

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

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

Tatsuo Ishii <ishii@postgresql.org> — 2025-06-26T06:47:00Z

Dear Kuroda-san,

> Dear Ishii-san,
> 
> Actually Saito-san has already been registered [1]. And cfbot said OK.
> 
> [1]: https://commitfest.postgresql.org/patch/5775/

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

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

Peter Eisentraut <peter@eisentraut.org> — 2025-08-13T13:54:20Z

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.
>>
>> [1]: https://commitfest.postgresql.org/patch/5775/
> 
> Thank you for pointing it out. Also I see Peter has been already
> registered as a committer. Great.

committed

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

Peter Eisentraut <peter@eisentraut.org> — 2025-08-13T15:50:10Z

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.

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

Peter Eisentraut <peter@eisentraut.org> — 2025-08-13T16:00:29Z

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.

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

Noboru Saito <noborusai@gmail.com> — 2025-08-14T22:20:53Z

> > 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.

Thank you for your review and for committing the changes.

I checked the patch for the `functions-pg-control-recovery` table, and
you are right—the patch was incorrect.
Thank you for catching this.

Noboru Saito

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

Noboru Saito <noborusai@gmail.com> — 2025-08-14T23:25:28Z

Thank you for reviewing the patch.

> > 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.

For the change to margin-left, I have attached a screenshot for comparison.
(pdf-table-margin.png)

Currently, when the Function/Operator content is too long, it wraps like this:

```
Function/Operator
             Description
function(....) ->
             Function continued...
             Description
```

With the margin-left change, it will look like this:

```
Function/Operator
              Description
function(....) ->
function continued...
             Description
```

This way, the continuation of the function/operator starts from the
same position as the first line,
making it easier to distinguish from the Description.

> > 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.

Regarding the background color for code blocks , the HTML version of
the documentation already
uses a background color for code blocks, and I think this makes them
easier to read.

If the current color feels too strong, perhaps we could use a lighter
shade to reduce the
 emphasis while still improving readability.

To demonstrate this, I have created a patch (`0004-pdf-shade.patch`)
that adjusts the shading
for code blocks in the PDF output.
I have also attached a comparison image (`pdf-shade.png`) to
illustrate the effect.

Please let me know your thoughts or if you have any suggestions for
further adjustments.