commit 19d4f0f6d329078dfd74e5ee0d3e48b7c384f7be
parent 7d41b6c42c46e3bd1a4bd59ee66cf841501b0679
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 24 Mar 2025 14:54:16 +0100
Update the man page
Use verbatim formatting for grammar and examples. This makes formatting
easier, but removes any possibility of stylization: only plain ASCII
text is allowed. As a result, verbatim grammar entries are placed in
single quotation marks where they were formatted in bold.
The grammar has been simplified by removing the optional comment at the
end of each line. Although this is not strictly accurate, given that a
comment can indeed be added at the end of a line, the change
nevertheless makes the grammar much lighter to read, and the example
shows that a comment can indeed be added at the end of a line. If that's
not enough, someone could explain it in the introductory text to the
grammar.
The grammar text is formatted so as not to exceed 80 columns. This
ensures that its formatting is compatible with a legacy terminal or,
more generally, with line-width constraints, for example when HTML
formatting is intended. Some grammar rules have therefore been renamed
to make them more compact, trying to ensure that they remain
sufficiently explicit with regard to what they represent.
Add the StL reference to the “See also” section.
Finally, automate the generation of the man page when the install target
is invoked.
Diffstat:
2 files changed, 145 insertions(+), 99 deletions(-)
diff --git a/Makefile b/Makefile
@@ -84,6 +84,9 @@ pkg:
-e 's#@SSTL_VERSION@#$(SSTL_VERSION)#g'\
sphin.pc.in > sphin.pc
+star-phor-input.5: doc/star-phor-input.scd
+ scdoc < doc/star-phor-input.scd > $@
+
sphin-local.pc: sphin.pc.in
sed -e '1d'\
-e 's#^includedir=.*#includedir=./src/#'\
@@ -93,7 +96,7 @@ sphin-local.pc: sphin.pc.in
-e 's#@SSTL_VERSION@#$(SSTL_VERSION)#g'\
sphin.pc.in > $@
-install: library pkg
+install: library pkg star-phor-input.5
install() { mode="$$1"; prefix="$$2"; shift 2; \
mkdir -p "$${prefix}"; \
cp "$$@" "$${prefix}"; \
@@ -102,6 +105,7 @@ install: library pkg
install 755 "$(DESTDIR)$(LIBPREFIX)" $(LIBNAME); \
install 644 "$(DESTDIR)$(LIBPREFIX)/pkgconfig" sphin.pc; \
install 644 "$(DESTDIR)$(INCPREFIX)/star" src/sphin.h; \
+ install 644 "$(DESTDIR)$(MANPREFIX)/man5" star-phor-input.5; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input" COPYING; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input" README.md
@@ -109,6 +113,7 @@ uninstall:
rm -f "$(DESTDIR)$(LIBPREFIX)/$(LIBNAME)"
rm -f "$(DESTDIR)$(LIBPREFIX)/pkgconfig/sphin.pc"
rm -f "$(DESTDIR)$(INCPREFIX)/star/sphin.h"
+ rm -f "$(DESTDIR)$(MANPREFIX)/man5/star-phor-input.5"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input/README.md"
diff --git a/doc/star-phor-input.scd b/doc/star-phor-input.scd
@@ -1,6 +1,31 @@
-star-phor-input(5)
+star-phor-input(5) "UNIX"
+
+; Copyright (C) 2024-2025 Centre National de la Recherche Scientifique
+; Copyright (C) 2024-2025 Clermont Auvergne INP
+; Copyright (C) 2024-2025 INSA Lyon
+; Copyright (C) 2024-2025 Institut Mines Télécom Albi-Carmaux
+; Copyright (C) 2024-2025 Institut National Polytechnique de Toulouse
+; Copyright (C) 2024-2025 |Méso|Star> (contact@meso-star.com)
+; Copyright (C) 2024-2025 PhotonLyX (info@photonlyx.com)
+; Copyright (C) 2024-2025 Université de Lorraine
+; Copyright (C) 2024-2025 Université Paul Sabatier
+; Copyright (C) 2024-2025 Université Toulouse - Jean Jaurès
+;
+; This program is free software: you can redistribute it and/or modify
+; it under the terms of the GNU General Public License as published by
+; the Free Software Foundation, either version 3 of the License, or
+; (at your option) any later version.
+;
+; This program is distributed in the hope that it will be useful,
+; but WITHOUT ANY WARRANTY; without even the implied warranty of
+; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+; GNU General Public License for more details.
+;
+; You should have received a copy of the GNU General Public License
+; along with this program. If not, see <http://www.gnu.org/licenses/>.
# NAME
+
star-phor-input - photoreactive system description files
# DESCRIPTION
@@ -11,121 +36,137 @@ either geometrical characteristics or physical properties. The only supported
geometrical data format is the triangular mesh stored in STL files. The geometry
(or the set of geometries) associated with a volume must form a closed enclosure
to ensure that every part of the system domain consists of a single medium with
-consistent properties.++
-++
+consistent properties.
+
Properties are specified either as a single-line entry or as a multi-line block,
-where each line corresponds to a distinct property.++
-++
+where each line corresponds to a distinct property.
+
Single line properties are declared using the key: value syntax. No additional
content other than comments is allowed after the value. Both the key and the
-value must appear on the same line.++
-++
+value must appear on the same line.
+
The star-phor-input format does not enforce a specific order for property
declarations. However, when encountering a keyword that does not belong to the
current parsing scope, the parser will move up one hierarchy level.
Consequently, all properties within the same scope must be declared together
within the same block; otherwise, an exception will be raised and the parsing
-will be stopped.++
-++
+will be stopped.
+
Indentation of any type is not mandatory for lower hierarchy blocks. Keywords in
the format file must be separated by at least one tab or space. If multiple
tabs, spaces, or combinations of both are used, they will be ignored.
+
# GRAMMAR
+
Please note that in the following lines, the percent symbol (%) is used to
introduce a comment in the file format description. It should not be taken into
-account when writing these files, nor should anything that comes after it.++
-++
-The file format describing a photoreactive system is as follows:++
-++
-<photoreactive-system> ::= <element> | <comment>++
- ...++
-<element> ::= <volume> | <surface>++
-++
-<volume> ::= *volume*: <string> [<comment>]++
- <ka> [<comment>]++
- <geometry> [<comment>]++
- [<geometry>] [<comment>]++
- ...++
- [<sensor>]++
-++
-<surface> ::= *surface*: <string> [<comment>]++
- <brdf> [<comment>]++
- <geometry> [<comment>]++
- [<geometry>] [<comment>]++
- ...++
- [<sensor>]++
- [<surface-source>]++
-++
-<geometry> ::= *geometry:* <geometry-side> <geometry-filename>++
-<geometry-side> ::= *FRONT* | *BACK*++
-<geometry-filename> ::= path % STL files only; spaces not allowed ++
-++
-<sensor> ::= *sensor:* [<comment>]++
- *response_function:* real++
-++
-<ka> ::= *ka:* real <ka-unit> % ka > 0++
-<ka-unit> ::= *cm^-1* | *1/cm* | *mm^-1* | *1/mm* | *m^-1* | *1/m*++
-++
-<brdf> ::= *brdf:* <brdf-type> <reflectivity>++
-<brdf-type> ::= *LAMBERT* | *SPECULAR*++
-<reflectivity> ::= real % In [0, 1]++
-++
-<surface-source> ::= *source:* [<comment>]++
- *flux_density:* <flux-density-value> <flux-density-unit>++
- *direction:* <direction-distribution>++
-++
-<flux-density-value> ::= real % Flux density value > 0++
-<flux-density-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*++
-++
-<direction-distribution> ::= <lambert> | <collim> | <cos_pow_n>++
-<lambert> ::= *LAMBERT*++
-<collim> ::= *COLLIM* *NORMAL* | <direction>++
-<cos_pow_n> ::= *COS_POW_N* <collimation-degree>++
-<collimation-degree> ::= real % Collimation degree > 0++
-++
-<direction> ::= *[*real, real, real*]*++
-<comment> ::= *#* string
+account when writing these files, nor should anything that comes after it.
+
+Text enclosed in single quotation marks (') must be included in the entry as is,
+with the exception of single quotation marks.
+
+The file format describing a photoreactive system is as follows:
+
+```
+<photoreactive-system> ::= <element> | <comment>
+ ...
+<element> ::= <volume> | <surface>
+
+<volume> ::= 'volume:' <name>
+ [<volume-props> ...]
+<volume-props> ::= <ka>
+ | <geometry>
+ | <sensor>
+
+<surface> ::= 'surface:' <name>
+ [<surface-props> ...]
+<surface-props> ::= <brdf>
+ | <geometry>
+ | <sensor>
+ | <surface-source>
+
+<geometry> ::= 'geometry:' <side> <geom-file>
+<side> ::= 'FRONT' | 'BACK'
+<geom-file> ::= path % STL files only
+ % Spaces not allowed
+
+<sensor> ::= 'sensor:'
+ 'response_function:' real
+
+<ka> ::= 'ka:' real <ka-unit> % ka > 0
+<ka-unit> ::= 'cm^-1'
+ | '1/cm'
+ | 'mm^-1'
+ | '1/mm'
+ | 'm^-1'
+ | '1/m'
+
+<brdf> ::= 'brdf:' <brdf-type> <reflectivity>
+<brdf-type> ::= 'LAMBERT' | 'SPECULAR'
+<reflectivity> ::= real % In [0, 1]
+
+<surface-source> ::= 'source:'
+ 'flux_density:' <flux-val> <flux-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'
+
+<direction-distrib> ::= <lambert> | <collim> | <cos_pow_n>
+<lambert> ::= 'LAMBERT'
+<collim> ::= 'COLLIM' 'NORMAL' | <direction>
+<cos_pow_n> ::= 'COS_POW_N' <collimation-degree>
+<collimation-degree> ::= real % Collimation degree > 0
+
+<direction> ::= '['real',' real',' real']'
+<comment> ::= '#' string
+<name> ::= '"'string'"'
+```
+
# EXAMPLES
The example below describes a simple photoreactive system composed of a cube, in
which absorption takes place. Tube walls have diffuse reflectivity. A LED panel
emits light with a defined flux density, and a surface base reflects light with
-specular reflectivity.++
-++
- # Keyword name++
- volume: "reaction volume"++
- geometry: FRONT cube.stl++
- ka: 1 m^-1 # lineic absorption coefficient++
- sensor:++
- response_function: 1++
- ++
- # Keyword name++
- surface: "tube walls"++
- geometry: BACK cube.stl++
- brdf: LAMBERT 0.1++
- ++
- # Keyword name++
- surface: "led panel"++
- geometry: FRONT led_panel.stl mm++
- brdf: LAMBERT 0++
- source:++
- flux_density: 200e-6 mol/m^2/s++
- direction: COLLIM NORMAL++
- ++
- # Keyword name++
- surface: "reflecting base"++
- geometry: FRONT base.stl++
- brdf: SPECULAR 0.9++
-++
+specular reflectivity.
+
+```
+# Keyword name
+volume: "reaction volume"
+ geometry: FRONT cube.stl
+ ka: 1 m^-1 # lineic absorption coefficient
+ sensor:
+ response_function: 1
+
+# Keyword name
+surface: "tube walls"
+ geometry: BACK cube.stl
+ brdf: LAMBERT 0.1
+
+# Keyword name
+surface: "led panel"
+ geometry: FRONT led_panel.stl mm
+ brdf: LAMBERT 0
+ source:
+ flux_density: 200e-6 mol/m^2/s
+ direction: COLLIM NORMAL
+
+# Keyword name
+surface: "reflecting base"
+ geometry: FRONT base.stl
+ brdf: SPECULAR 0.9
+```
+
# SEE ALSO
+Marshall Burns, _The StL Format: Standard Data Format for Fabbers_,
+https://www.fabbers.com/tech/STL_Format, 1993.
