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
