commit 472227db664ff50a7e45b0cd586ba2131b558e16
parent a74002361e8f0748da5741b48dd21276a181379d
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 27 Jan 2026 14:42:48 +0100
Update to the formatting of the star-phor-input manual page
Limit the width of literal text to ensure it displays correctly on
narrow media, such as certain HTML pages, standard PDF documents, good
old terminals, etc.
Diffstat:
1 file changed, 121 insertions(+), 108 deletions(-)
diff --git a/doc/star-phor-input.scd b/doc/star-phor-input.scd
@@ -78,113 +78,125 @@ description itself. In both cases, the # character and everything that follows
it on the same line must be ignored and should not be included in the actual
configuration file.
+Some lines end with a backslash (\\). This allows the description to continue on
+the next line for formatting purposes. However, this trick cannot be used in
+description files, and actual description lines must remain on a single line.
+
The syntax rules enabling the description of a photoreactor are as follows:
```
-<photoreactive-system> ::= <element> | <comment>
- ...
-
-<element> ::= <volume> | <surface>
-
-<volume> ::= 'volume:' <name>
- [<volume-props> ...]
-
-<volume-props> ::= <geometry>
- | <sensor>
- | <prop-rad>
-
-<surface> ::= 'surface:' <name>
- [<surface-props> ...]
-
-<surface-props> ::= <brdf>
- | <geometry>
- | <sensor>
- | <surface-source>
-
-<geometry> ::= 'geometry:' <side> <geom-file> [<geom-unit>]
-<side> ::= 'FRONT' | 'BACK'
-<geom-file> ::= path # STL files only
- # Spaces not allowed
-
-<geom-unit> ::= 'm' # if no unit is specified,
- | 'cm' # meter is assumed
- | 'mm'
- | 'km'
-
-<sensor> ::= 'sensor:'
- 'response_function:' real
-
-<prop-rad> ::= 'prop_rad:' <name> <prop-rad-type>
- <concentration>
- <cross-sections>
-<prop-rad-type> ::= 'SCATTERER'
-
-<concentration> ::= 'concentration:' real <concentration-unit> # conc > 0
-<concentration-unit> ::= 'kg/L'
- | 'kg.L^-1'
- | 'kg.m^-3'
- | 'kg/m^3'
- | 'mol/L'
- | 'mol.L^-1'
- | 'mol.m^-3'
- | 'mol/m^3'
- | 'part/L'
- | 'part.L^-1'
- | 'part.m^-3'
- | 'part/m^3'
-
-<cross-section> ::= 'cross_sections:'
- <abs-cross-sections>
-<abs-cross-sections> ::= 'abs_cross_sec:' <prop-file> <spec-unit> <cross-sec-unit>
-
-<spec-unit> ::= 'nm'
- | 'cm'
- | 'm'
- | 'cm^-1' # assumes wavenumber (1/wavelength) is used
- | '1/cm'
-
-<cross-sec-unit> ::= # should be compatible with concentration-unit
- | 'm^2/kg'
- | 'm^2.kg^-1'
- | 'm^2/mol'
- | 'm^2.mol^-1'
- | 'm^2/part'
- | 'm^2.part^-1'
-
-<refractive_index> ::= 'refractive_index:'
- ['n_real:' <prop-file>]
- ['n_imag:' <prop-file>]
-
-<brdf> ::= 'brdf:' <brdf-type> <reflectivity>
-<brdf-type> ::= 'LAMBERT' | 'SPECULAR'
-<reflectivity> ::= real # In [0, 1]
-
-<surface-source> ::= 'source:'
- 'flux_density:' <flux-val> <flux-unit> <prop-file> <spec-unit> <spec-pdf-unit>
- 'direction:' <direction-distrib>
-<flux-val> ::= real # Flux density value > 0
-<flux-unit> ::= 'mol/m^2/s'
- | 'mol.m^-2.s^-1'
- | 'umol/m^2/s'
- | 'umol.m^-2.s^-1'
- | 'mW/m^2'
- | 'mW.m^-2'
- | 'W/m^2'
- | 'W.m^-2'
- | 'J.m^-2.s^-1'
- | 'J/m^2/s'
-<spec-pdf-unit> ::= 'nm^-1'
-
-<direction-distrib> ::= <lambert> | <collim> | <cos_pow_n>
-<lambert> ::= 'LAMBERT'
-<collim> ::= 'COLLIM' 'NORMAL'
-<cos_pow_n> ::= 'COS_POW_N' <collimation-degree>
-<collimation-degree> ::= real # Collimation degree > 0
-
-<direction> ::= '['real',' real',' real']'
-<prop-file> ::= path # no spaces allowed
-<comment> ::= '#' string
-<name> ::= '"'string'"'
+<photoreactive-system> ::= <element> | <comment>
+ ...
+
+<element> ::= <volume> | <surface>
+
+<volume> ::= 'volume:' <name>
+ [<volume-props> ...]
+
+<volume-props> ::= <geometry>
+ | <sensor>
+ | <prop-rad>
+
+<surface> ::= 'surface:' <name>
+ [<surface-props> ...]
+
+<surface-props> ::= <brdf>
+ | <geometry>
+ | <sensor>
+ | <surface-source>
+
+<geometry> ::= geometry:' <side> \\
+ <geom-file> [<geom-unit>]
+<side> ::= 'FRONT' | 'BACK'
+<geom-file> ::= path # STL files only
+ # Spaces are not allowed
+
+<geom-unit> ::= 'm' # Default unit
+ | 'cm'
+ | 'mm'
+ | 'km'
+
+<sensor> ::= 'sensor:'
+ 'response_function:' real
+
+<prop-rad> ::= 'prop_rad:' <name> <prop-rad-type>
+ <concentration>
+ <cross-sections>
+<prop-rad-type> ::= 'SCATTERER'
+
+<concentration> ::= 'concentration:' real \\
+ <concentration-unit>
+<concentration-unit> ::= 'kg/L'
+ | 'kg.L^-1'
+ | 'kg.m^-3'
+ | 'kg/m^3'
+ | 'mol/L'
+ | 'mol.L^-1'
+ | 'mol.m^-3'
+ | 'mol/m^3'
+ | 'part/L'
+ | 'part.L^-1'
+ | 'part.m^-3'
+ | 'part/m^3'
+
+<cross-section> ::= 'cross_sections:'
+ <abs-cross-sections>
+<abs-cross-sections> ::= 'abs_cross_sec:' <prop-file> \\
+ <spec-unit> \\
+ <cross-sec-unit>
+
+<spec-unit> ::= 'nm'
+ | 'cm'
+ | 'm'
+ | 'cm^-1' # wavenumber (1/wavelength)
+ | '1/cm'
+
+<cross-sec-unit> ::= # must match the <concentration-unit>
+ | 'm^2/kg'
+ | 'm^2.kg^-1'
+ | 'm^2/mol'
+ | 'm^2.mol^-1'
+ | 'm^2/part'
+ | 'm^2.part^-1'
+
+<refractive_index> ::= 'refractive_index:'
+ ['n_real:' <prop-file>]
+ ['n_imag:' <prop-file>]
+
+<brdf> ::= 'brdf:' <brdf-type> <reflectivity>
+<brdf-type> ::= 'LAMBERT' | 'SPECULAR'
+<reflectivity> ::= real # In [0, 1]
+
+<surface-source> ::= 'source:'
+ 'flux_density:' <flux-val> \\
+ <flux-unit> \\
+ <prop-file> \\
+ <spec-unit> \\
+ <spec-pdf-unit>
+ 'direction:' <direction-distrib>
+<flux-val> ::= real # Flux density value > 0
+<flux-unit> ::= 'mol/m^2/s'
+ | 'mol.m^-2.s^-1'
+ | 'umol/m^2/s'
+ | 'umol.m^-2.s^-1'
+ | 'mW/m^2'
+ | 'mW.m^-2'
+ | 'W/m^2'
+ | 'W.m^-2'
+ | 'J.m^-2.s^-1'
+ | 'J/m^2/s'
+<spec-pdf-unit> ::= 'nm^-1'
+
+<direction-distrib> ::= <lambert> | <collim> | <cos_pow_n>
+<lambert> ::= 'LAMBERT'
+<collim> ::= 'COLLIM' 'NORMAL'
+<cos_pow_n> ::= 'COS_POW_N' <collimation-degree>
+<collimation-degree> ::= real # Collimation degree > 0
+
+<direction> ::= '['real',' real',' real']'
+<prop-file> ::= path # no spaces allowed
+<comment> ::= '#' string
+<name> ::= '"'string'"'
```
# EXAMPLES
@@ -219,8 +231,8 @@ surface: "led panel"
direction: COLLIM NORMAL
# A surface in which both sides have the same properties.
-# Note that this same syntax is not allowed when the surface is also a source.
-# Such case is treated in example 3.
+# Note that this same syntax is not allowed when the
+# surface is also a source. Such case is treated in example 3.
# Keyword name
surface: "reflecting base"
geometry: FRONT base.stl
@@ -269,8 +281,9 @@ volume: "reaction volume"
sensor:
response_function: 1
-# If both sides of a same geometry are emitting surfaces, they have to be
-# entered as separeted surfaces, even if the source properties are identical.
+# If both sides of a same geometry are emitting surfaces,
+# they have to be entered as separeted surfaces,
+# even if the source properties are identical.
# The front side of the source
# Keyword name
