Update Scribus and AsciiDoc docs for 2026-04-05

Author: github-actions[bot]

adoc/bwipp-options.adoc

@@ -141,6 +141,15 @@ image:data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi
 
 === Symbol Dimensions
 
+By default, symbols are rendered in normalised units: 1 point per narrow
+bar for linear barcodes and 2 points per module for most 2D symbologies.
+Bar heights default to 1 inch. These values produce pixel-locked output
+when rendered at 72 DPI, ensuring crisp bitmaps without anti-aliasing
+artefacts. For other resolutions, <<_gridfit,gridfit>> can snap modules
+to device pixel boundaries. For output that conforms to application
+specifications such as the GS1 Symbol Specification Tables, use
+<<_physspec,physspec>> mode.
+
 ==== height
 
 Height of longest bar, in inches.
@@ -180,6 +189,162 @@ Encoder: code93
 
 image:data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB3aWR0aD0iMTkwIiBoZWlnaHQ9Ijc0IiB2aWV3Qm94PSIwIDAgMTkwIDc0Ij4KPHJlY3QgeD0iLTE5IiB5PSItNy40IiB3aWR0aD0iMjI4IiBoZWlnaHQ9Ijg4LjgiIGZpbGw9InJnYigxMDAlLCAxMDAlLCAxMDAlKSIgZmlsbC1vcGFjaXR5PSIxIi8+CjxwYXRoIGZpbGwtcnVsZT0ibm9uemVybyIgZmlsbD0icmdiKDEwMCUsIDEwMCUsIDEwMCUpIiBmaWxsLW9wYWNpdHk9IjEiIGQ9Ik0gMC44MzU5MzggNzMgTCAxODkuMTY0MDYyIDczIEwgMTg5LjE2NDA2MiAxIEwgMC44MzU5MzggMSBaIE0gMC44MzU5MzggNzMgIi8+CjxwYXRoIGZpbGwtcnVsZT0ibm9uemVybyIgZmlsbD0icmdiKDAlLCAwJSwgMCUpIiBmaWxsLW9wYWNpdHk9IjEiIGQ9Ik0gMjMuMTY3OTY5IDEgTCAyNS4wODIwMzEgMSBMIDI1LjA4MjAzMSA3MyBMIDIzLjE2Nzk2OSA3MyBaIE0gMjcuNjY3OTY5IDEgTCAyOS41ODIwMzEgMSBMIDI5LjU4MjAzMSA3MyBMIDI3LjY2Nzk2OSA3MyBaIE0gMzIuMTY3OTY5IDEgTCA0MC44MzIwMzEgMSBMIDQwLjgzMjAzMSA3MyBMIDMyLjE2Nzk2OSA3MyBaIE0gNDMuNDE3OTY5IDEgTCA0Ny41ODIwMzEgMSBMIDQ3LjU4MjAzMSA3MyBMIDQzLjQxNzk2OSA3MyBaIE0gNTAuMTY3OTY5IDEgTCA1Mi4wODIwMzEgMSBMIDUyLjA4MjAzMSA3MyBMIDUwLjE2Nzk2OSA3MyBaIE0gNTYuOTE3OTY5IDEgTCA2MS4wODIwMzEgMSBMIDYxLjA4MjAzMSA3MyBMIDU2LjkxNzk2OSA3MyBaIE0gNjMuNjY3OTY5IDEgTCA2Ny44MzIwMzEgMSBMIDY3LjgzMjAzMSA3MyBMIDYzLjY2Nzk2OSA3MyBaIE0gNzIuNjY3OTY5IDEgTCA3NC41ODIwMzEgMSBMIDc0LjU4MjAzMSA3MyBMIDcyLjY2Nzk2OSA3MyBaIE0gNzkuNDE3OTY5IDEgTCA4MS4zMzIwMzEgMSBMIDgxLjMzMjAzMSA3MyBMIDc5LjQxNzk2OSA3MyBaIE0gODMuOTE3OTY5IDEgTCA4OC4wODIwMzEgMSBMIDg4LjA4MjAzMSA3MyBMIDgzLjkxNzk2OSA3MyBaIE0gOTAuNjY3OTY5IDEgTCA5NC44MzIwMzEgMSBMIDk0LjgzMjAzMSA3MyBMIDkwLjY2Nzk2OSA3MyBaIE0gOTkuNjY3OTY5IDEgTCAxMDEuNTgyMDMxIDEgTCAxMDEuNTgyMDMxIDczIEwgOTkuNjY3OTY5IDczIFogTSAxMDQuMTY3OTY5IDEgTCAxMDguMzMyMDMxIDEgTCAxMDguMzMyMDMxIDczIEwgMTA0LjE2Nzk2OSA3MyBaIE0gMTEwLjkxNzk2OSAxIEwgMTE1LjA4MjAzMSAxIEwgMTE1LjA4MjAzMSA3MyBMIDExMC45MTc5NjkgNzMgWiBNIDExOS45MTc5NjkgMSBMIDEyMS44MzIwMzEgMSBMIDEyMS44MzIwMzEgNzMgTCAxMTkuOTE3OTY5IDczIFogTSAxMjQuNDE3OTY5IDEgTCAxMjYuMzMyMDMxIDEgTCAxMjYuMzMyMDMxIDczIEwgMTI0LjQxNzk2OSA3MyBaIE0gMTMxLjE2Nzk2OSAxIEwgMTM1LjMzMjAzMSAxIEwgMTM1LjMzMjAzMSA3MyBMIDEzMS4xNjc5NjkgNzMgWiBNIDEzNy45MTc5NjkgMSBMIDE0Mi4wODIwMzEgMSBMIDE0Mi4wODIwMzEgNzMgTCAxMzcuOTE3OTY5IDczIFogTSAxNDQuNjY3OTY5IDEgTCAxNDYuNTgyMDMxIDEgTCAxNDYuNTgyMDMxIDczIEwgMTQ0LjY2Nzk2OSA3MyBaIE0gMTQ5LjE2Nzk2OSAxIEwgMTUxLjA4MjAzMSAxIEwgMTUxLjA4MjAzMSA3MyBMIDE0OS4xNjc5NjkgNzMgWiBNIDE1My42Njc5NjkgMSBMIDE2Mi4zMzIwMzEgMSBMIDE2Mi4zMzIwMzEgNzMgTCAxNTMuNjY3OTY5IDczIFogTSAxNjQuOTE3OTY5IDEgTCAxNjYuODMyMDMxIDEgTCAxNjYuODMyMDMxIDczIEwgMTY0LjkxNzk2OSA3MyBaIE0gMTY0LjkxNzk2OSAxICIvPgo8L3N2Zz4K[image]
 
+==== physspec
+
+Enable physical specification mode. The symbol is rendered at the
+correct physical dimensions for the symbology, based on the nominal
+X-dimension and height from the symbology's specification or selected
+Application Specification Table (AST).
+
+===== Notes
+
+* When enabled, the output is dimensioned in millimetres according to
+the symbology's specification.
+* Use *mag* to scale the symbol by a magnification factor relative to
+nominal.
+* Use *xdim* or *hdim* to directly specify physical dimensions in mm,
+overriding the nominal values.
+* Inkspread is adjusted to maintain a fixed physical reduction
+regardless of magnification.
+* Not compatible with *width*.
+* The output is resolution-independent (EPS/PDF compatible) unless
+<<_gridfit,gridfit>> is also enabled.
+
+===== Example
+
+An EAN-13 at 100% specification dimensions:
+
+....
+Data:    9520123456788
+Options: includetext physspec
+Encoder: ean13
+....
+
+An EAN-13 at 150% magnification:
+
+....
+Data:    9520123456788
+Options: includetext physspec mag=1.5
+Encoder: ean13
+....
+
+==== propspec
+
+Enable proportional specification mode. Adjusts bar heights to match the
+specification's height-to-width ratio without changing the physical
+scale.
+
+===== Notes
+
+* Useful for bitmap output at the normalised scale where correct
+height-to-width proportions are desired without physical scaling.
+* Requires the symbology to have both *xnom* and *hnom* defined (via AST
+or user override).
+* Linear barcodes only.
+
+===== Example
+
+....
+Data:    9520123456788
+Options: includetext propspec
+Encoder: ean13
+....
+
+==== mag
+
+Magnification factor for physical specification mode. Scales the symbol
+relative to its nominal specification dimensions. Default: `+1.0+`
+(100%).
+
+===== Notes
+
+* Only meaningful with *physspec*.
+* Mutually exclusive with *xdim* and *hdim*.
+
+===== Example
+
+A QR Code at twice the nominal X-dimension:
+
+....
+Data:    Hello
+Options: physspec mag=2.0 xnom=0.330
+Encoder: qrcode
+....
+
+==== xdim
+
+Directly specify the X-dimension (narrow bar width or module size) in
+millimetres. Overrides the nominal value from the AST.
+
+===== Notes
+
+* Only meaningful with *physspec*.
+* Mutually exclusive with *mag*.
+* If neither *xdim* nor *xnom* is available, an error is raised.
+
+===== Example
+
+....
+Data:    9520123456788
+Options: includetext physspec xdim=0.400
+Encoder: ean13
+....
+
+==== hdim
+
+Directly specify the bar height in millimetres. Overrides the nominal
+height from the AST. Linear barcodes only.
+
+===== Notes
+
+* Only meaningful with *physspec*.
+* Mutually exclusive with *mag*.
+
+==== xnom
+
+Override the nominal X-dimension in millimetres. Normally provided by
+the Application Specification Table (AST), but can be set by the user.
+
+==== hnom
+
+Override the nominal bar height in millimetres. Normally provided by the
+AST. Linear barcodes only.
+
+==== xmin
+
+Override the minimum allowed X-dimension in millimetres. Normally
+provided by the AST.
+
+==== xmax
+
+Override the maximum allowed X-dimension in millimetres. Normally
+provided by the AST.
+
+==== ast
+
+Select an Application Specification Table profile. The default profile
+(`+default+`) provides the symbology's own specification values. Named
+profiles (e.g., `+gs1.sst1+` through `+gs1.sst13+`) provide
+GS1-application-specific values.
+
+===== Notes
+
+* GS1 Symbol Specification Tables (SSTs) define X-dimension bounds and
+nominal heights for specific application contexts such as retail POS,
+general distribution, healthcare, and logistics.
+* See the GS1 General Specifications, Section 5.12.3 for the full list
+of SSTs.
+
+===== Example
+
+An EAN-13 at GS1 SST 2 (general distribution) specification:
+
+....
+Data:    9520123456788
+Options: includetext physspec ast=gs1.sst2
+Encoder: ean13
+....
+
 ==== gridfit
 
 When enabled, the renderer snaps symbol elements to device pixel
@@ -195,7 +360,17 @@ performance.
 ** Symbologies with fractional bar widths (e.g. postal codes,
 Pharmacode).
 ** Linear barcodes with a non-integer *barratio*.
-* The device resolution is probed Unless *gridfit* is provided.
+* The device resolution is probed automatically. If the user provides
+*griddpi* then this value is used directly without hardware probing,
+which also enables gridfit to operate on devices that would otherwise be
+skipped (e.g. nullpage).
+* When combined with <<_physspec,physspec>>:
+** The effective X-dimension after snapping is validated against
+<<_xmin,xmin>> and <<_xmax,xmax>> bounds.
+** If rounding to the nearest whole pixel produces an X-dimension
+outside the specification bounds, the alternate rounding direction
+(ceiling or floor) is tried automatically.
+** If neither direction produces an in-spec result, an error is raised.
 
 ===== Example
 
@@ -240,6 +415,9 @@ hexagons to compensate for inkspread, in points.
 ===== Notes
 
 * Negative values will increase the bar width.
+* When <<_physspec,physspec>> is enabled, inkspread is automatically
+adjusted so that the physical reduction (in mm) remains constant
+regardless of magnification.
 
 ===== Example