Skip to content

Eliminate PDF doc build margin problem - #4883

Merged
bdbaddog merged 1 commit into
SCons:masterfrom
mwichmann:doc/title-margins
Jul 26, 2026
Merged

Eliminate PDF doc build margin problem#4883
bdbaddog merged 1 commit into
SCons:masterfrom
mwichmann:doc/title-margins

Conversation

@mwichmann

@mwichmann mwichmann commented Jul 26, 2026

Copy link
Copy Markdown
Collaborator

This is an AI analysis of errors reported by Apache fop. The error looks like this (same for margin-right ):

[ERROR] FOUserAgent - Invalid property value encountered in margin-left="": org.apache.fop.fo.expr.PropertyException: file:/home/mats/github/scons/build/doc/user/scons-user.fo:3:6: No conversion defined ; property:'margin-left' (See position 147:8)

Some builds of fop report the error as SEVERE rather than ERROR.

The problem was identified as:

A. When $fop.extensions != 0, the <xsl:value-of> inside <xsl:attribute> elements produces whitespace-padded content that FOP can't parse as valid length values.
B. When $fop.extensions = 0, the <xsl:attribute> elements with empty content produce empty strings.

The solution is to use <xsl:choose> blocks that always produce valid length values:

  • When $fop.extensions != 0: use 0pt (simple, valid FOP length)
  • When $fop.extensions = 0: use the original dynamic variable values

To summarize the two-part fix across all four scons_title.xsl files:

  1. (1 pair per file): Removed the redundant xsl:attribute elements from scons-titlepage-first that conflicted with the literal margin-left="0mm" margin-right="0mm"
  2. (11 blocks per file): Replaced the broken content-mode xsl:attribute blocks that produced empty strings or malformed concat() values:

Note: we only build doc/man and doc/user, but the same fixes were applied to the two unused documents for consistency.

Note: three of the files had the old-style copyright header (with unexpanded __COPYRIGHT__ in them), changed to the short one that was already in use in the User Guide copy of the titlepage file.

Signed-off-by: Mats Wichmann mats@linux.com
Assisted-by: OpenCode 1.18.5 driving Qwen 3.8

Contributor Checklist:

  • I have created a new test or updated the unit tests to cover the new/changed functionality.
  • I have updated CHANGES.txt and RELEASE.txt (and read the README.rst).
  • I have updated the appropriate documentation

This is an AI analysis of errors reported by Apache fop.  The error
looks like this (same for margin-right - line-breaks mine):

[ERROR] FOUserAgent - Invalid property value encountered in margin-left="":
org.apache.fop.fo.expr.PropertyException:
file:/home/mats/github/scons/build/doc/user/scons-user.fo:3:6:
No conversion defined ; property:'margin-left' (See position 147:8)

Some builds of fop report the error as SEVERE rather than ERROR.

The problem was identified as:

A. When `$fop.extensions != 0`, the `<xsl:value-of>` inside
   `<xsl:attribute>` elements produces whitespace-padded content that
   FOP can't parse as valid length values

B. When `$fop.extensions = 0`, the `<xsl:attribute>` elements with empty
   content produce empty strings

The solution is to use `<xsl:choose>` blocks that always produce
valid length values:
- When `$fop.extensions != 0`: use `0pt` (simple, valid FOP length)
- When `$fop.extensions = 0`: use the original dynamic variable values

To summarize the two-part fix across all four `scons_title.xsl` files:

1. (1 pair per file): Removed the redundant `xsl:attribute` elements
   from `scons-titlepage-first` that conflicted with the literal
   `margin-left="0mm" margin-right="0mm"`

2. (11 blocks per file, already applied): Replaced the broken
   content-mode `xsl:attribute` blocks that produced empty strings or
   malformed `concat()` values:

Note: we only build doc/man and doc/user, but the same fixes were
applied to the two unused documents for consistency.

Signed-off-by: Mats Wichmann <mats@linux.com>
Assisted-by: OpenCode 1.18.5 driving Qwen 3.8
@mwichmann
mwichmann force-pushed the doc/title-margins branch from d91a5de to 4267508 Compare July 26, 2026 15:34
@bdbaddog
bdbaddog merged commit e10fa2b into SCons:master Jul 26, 2026
8 of 11 checks passed
@mwichmann mwichmann added this to 4.11 Jul 26, 2026
@github-project-automation github-project-automation Bot moved this to Done in 4.11 Jul 26, 2026
@mwichmann mwichmann added this to the 4.11.0 milestone Jul 26, 2026
@mwichmann
mwichmann deleted the doc/title-margins branch July 27, 2026 00:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants