commit e2842f22bc1deb694aac773eb199954e61f9ada3
parent 177fcc9099dab15613e5324d8cf5841d36166861
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 18 May 2026 17:28:03 +0200
Translate schiff-output man page from man to mdoc macros
The content has also been updated. In particular, the grammar section is
no longer a separate part of the file format description. The two are
now closely integrated to make the documentation easier to read.
An history section has also been added. It provides background on the
context in which the schiff project was developed.
Diffstat:
2 files changed, 290 insertions(+), 179 deletions(-)
diff --git a/Makefile b/Makefile
@@ -114,6 +114,7 @@ lint: doc/schiff.1
shellcheck -o all src/test_schiff_sphere.sh
mandoc -Tlint -Wwarning doc/schiff.1
mandoc -Tlint -Wwarning doc/schiff-geometry.5
+ mandoc -Tlint -Wwarning doc/schiff-output.5
################################################################################
# Test
diff --git a/doc/schiff-output.5 b/doc/schiff-output.5
@@ -1,183 +1,293 @@
-.\" Copying and distribution of this file, with or without modification,
-.\" are permitted in any medium without royalty provided the copyright
-.\" notice and this notice are preserved. This file is offered as-is,
-.\" without any warranty.
-.TH SCHIFF-OUTPUT 5
-.SH NAME
-schiff\-output \- format of
-.BR schiff (1)
-results.
-.SH DESCRIPTION
+.\" Copyright (C) 2015, 2016, 2026 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2026 Clermont Auvergne INP
+.\" Copyright (C) 2026 Institut Mines Télécom Albi-Carmaux
+.\" Copyright (C) 2017, 2019-2021, 2026 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2026 Université de Lorraine
+.\" Copyright (C) 2026 Université de Toulouse
+.\"
+.\" 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/>.
+.Dd May 18, 2026
+.Dt SCHIFF-OUTPUT 5
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm schiff-output
+.Nd schiff's results format
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
The output result of the
-.BR schiff (1)
-program is a collection of ASCII floating point data. Each set of floating
-point values are separated by an empty line. The first set is a list of per
-wavelength cross\-sections. Each line stores the estimated cross\-section for a
-wavelength submitted by the \fB\-w\fR option of
-.BR schiff (1).
-It is formatted as "W E e A a S s P p" with "W" the wavelength in vacuum
-(expressed in microns), "E", "A" and "S" the estimation of the extinction,
-absorption and scattering cross\-sections, respectively, in square microns per
-particle, and "P" the estimated average projected area of the soft particles
-expressed in square microns per particle. The "e", "a", "s" and "p" values are
-the standard error of the aforementioned estimations.
-.PP
-Following the list of cross\-sections comes the list of phase function
-descriptors. Each descriptor is a line that gives informations on the
-[[inverse] cumulative] phase functions. It is formatted as "W theta-l Ws Ws-SE
-Wc Wc-SE n nangles nangles\-inv" with "W" the wavelength in vacuum (expressed in
-microns) of the inverse cumulative phase function, "theta-l" the scattering
-angle in radians from which the phase function was analytically computed, "Ws"
-and "Wc" the values of the differential cross\-section and its cumulative at
-"theta-l", "n" the parameter of the model used to analytically evaluate the
-phase function for large scattering angles (i.e. angles greater than "theta-l"),
-"nangles" the number of scattering angles (\fB\-a\fR option of
-.BR schiff (1))
-and "nangles\-inv" the number of inverse cumulative phase function values
-(\fB\-A\fR option of
-.BR schiff (1)).
-The "Ws-SE" and "Wc-SE" values are the standard error of the "Ws" and "Wc"
-estimations, respectively.
-.PP
-Then there is the list of phase functions, each stored as a list of lines
-formatted as "A E SE" where "E" is the expected value of the phase function for
-the input scattering angle "A" in radians, and "SE" its standard error. The
-number of scattering angles is controlled by the \fB\-a\fR option of
-.BR schiff (1).
-.PP
-After the phase functions come the cumulative phase functions that follow the
-format of the phase functions, i.e. each cumulative phase function is a list a
-lines \- one per scattering angle \- that defines the input scattering angle in
-radians, followed by the expected value and the standard error of its cumulative
-phase function.
-.PP
-Finally, there is the inverse cumulative phase functions. Each of these
-functions lists a set of N probabilities in [0, 1] and its corresponding
-scattering angles in [0, PI]. The number of entries of the inverse cumulative
-phase functions is controlled by the \fB\-A\fR option of
-.BR schiff (1).
-Assuming a set of N angles, the i^th angle (i in [0, N\-1]) is the angle whose
-probability is i/(N\-1).
-.PP
-Note that the cross sections, the phase function descriptors, the phase
-functions, their cumulative and their inverse cumulative are all sorted in
-ascending order with respect to their associated wavelength.
-.SH GRAMMAR
-The following grammar formally describes the
-.BR schiff (1)
-output format.
-The output values are ASCII data formatted line by line. By convention, in the
-following grammar the line data are listed between quote marks. The grammar may
-use new lines for formatting constraints, but data are actually on the same
-line while a closed quote mark is not defined.
-.PP
-.RS 4
-.nf
-<schiff\-output> ::= <cross\-sections>
- EMPTY\-LINE
- <phase\-function\-descriptor>
- EMPTY\-LINE
- <phase\-functions>
- EMPTY-LINE
- <cumulative\-phase\-functions>
- EMPTY\-LINE
- <inverse\-cumulative\-phase\-functions>
- EMPTY\-LINE
-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-
-<cross\-sections> ::= "WAVELENGTH <extinction> <absorption>
- <scattering> <area>"
- [ <cross\-sections> ]
-
-<extinction> ::= ESTIMATION STANDARD\-ERROR
-<absorption> ::= ESTIMATION STANDARD\-ERROR
-<scattering> ::= ESTIMATION STANDARD\-ERROR
-<area> ::= ESTIMATION STANDARD\-ERROR
-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-
-<phase\-functions\-descriptors>
- ::= "WAVELENGTH THETA <PF(THETA)> <CDF(THETA)>
- N #ANGLES #INVCUM"
- [ <phase\-functions\-descriptors> ]
-
-<CDF(THETA)> ::= ESTIMATION STANDARD\-ERROR
-<PF(THETA)> ::= ESTIMATION STANDARD\-ERROR
-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-
-<phase\-functions> ::= <function\-entries>
- [ EMPTY-LINE
- <phase\-functions> ]
-
-<cumulative\-phase\-functions>
- ::= <function\-entries>
- [ EMPTY-LINE
- <cumulative\-phase\-functions> ]
-
-<function\-entries> ::= ANGLE ESTIMATION STANDARD-ERROR
- [ <phase\-function\-entries> ]
-
-<inverse\-cumulative\-phase\-functions>
- ::= <inverse\-function\-entries>
- [ EMPTY-LINE
- <inverse\-cumulative\-phase\-functions> ]
-
-<inverse\-function\-entries>
- ::= PROBABILITY ANGLE
- [ <inverse\-function\-entries> ]
-.fi
-.SH EXAMPLE
+.Xr schiff 1
+program is a collection of ASCII floating point data.
+Each set of floating point values are separated by an empty line.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va schiff-output Ac Ta ::= Ta Aq Va cross-sections
+.It Ta Ta EMPTY-LINE
+.It Ta Ta Aq Va phase-func-desc
+.It Ta Ta EMPTY-LINE
+.It Ta Ta Aq Va phase-func-list
+.It Ta Ta EMPTY-LINE
+.It Ta Ta Aq Va cumul-phase-func-list
+.It Ta Ta EMPTY-LINE
+.It Ta Ta Aq Va invcumul-phase-func-list
+.It Ta Ta EMPTY-LINE
+.El
+.\""""""""""""""""""""""""""""""""""
+.Ss Cross sections
+The first set is a list of per wavelength cross-sections.
+Each line stores the estimated cross-section for a wavelength submitted
+by the
+.Fl w
+option of
+.Xr schiff 1 .
+.Pp
+Its grammar is as follows:
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va cross-sections Ac Ta ::= Ta
+.Aq Va wavelength
+.Aq Va extinction
+\e
+.It Ta Ta
+.Aq Va absorption
+.Aq Va scattering
+.Aq Va area
+.It Ta Ta ...
+.It \ Ta Ta
+.It Ao Va extinction Ac Ta ::= Ta Aq Va estimation
+.It Ao Va absorption Ac Ta ::= Ta Aq Va estimation
+.It Ao Va scattering Ac Ta ::= Ta Aq Va estimation
+.It Ao Va area Ac Ta ::= Ta Aq Va estimation
+.It \ Ta Ta
+.It Ao Va estimation Ac Ta ::= Ta
+.Aq Va mean-value
+.Aq Va standard-error
+.It \ Ta Ta
+.It Ao Va wavelength Ac Ta ::= Ta Vt real
+.It Ao Va mean-value Ac Ta ::= Ta Vt real
+.It Ao Va standard-error Ac Ta ::= Ta Vt real
+.El
+.Pp
+A line is a set of 9 reals: a
+.Ql wavelength
+in vacuum
+.Pq in microns ,
+followed by the estimations
+.Pq i.e., the mean values and standard errors
+of the
+.Ql extinction ,
+.Ql absorption
+and
+.Ql scattering
+cross-sections in square microns per particle, and finally the
+estimation of the projected
+.Ql area
+of the soft particles, also in square microns per particle.
+.\""""""""""""""""""""""""""""""""""
+.Ss Phase function descriptor
+Following the list of cross-sections comes the list of phase function
+descriptors.
+Each descriptor is a line that gives informations on the
+.Bq Bo inverse- Bc Ns cumulative
+phase functions.
+.Pp
+Its grammar is as follows:
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va phase-funcs-desc Ac Ta ::= Ta
+.Aq Va wavelength
+.Aq Va theta
+\e
+.It Ta Ta
+.Aq Va pf Ns Pq theta
+.Aq Va cdf Ns Pq theta
+\e
+.It Ta Ta
+.Aq Va n
+.Aq Va nangles
+.Aq Va nangles-inv
+.It Ta Ta ...
+.It \ Ta Ta
+.It Ao Va pf Ns Po theta Pc Ac Ta ::= Ta Aq Va estimation
+.It Ao Va cdf Ns Po theta Pc Ac Ta ::= Ta Aq Va estimation
+.El
+.Pp
+The first value of a descriptor is the wavelength in vacuum
+.Pq in microns
+of the inverse cumulative phase function.
+It is followed by
+.Ql theta
+that is the scattering angle in radians from which the phase function was
+analytically computed.
+Then come the estimation of the differential cross-section
+.Ql pf Ns Pq theta
+and its cumulative
+.Ql cdf Ns Pq theta
+at the angle
+.Ql theta .
+.Ql n
+is the parameter of the model used to analytically evaluate the phase
+function for large scattering angles
+.Pq i.e. angles greater than Ql theta .
+The last 2 values,
+.Ql nangles
+and
+.Ql nangles-inv ,
+are integers that correspond to the number of scattering angles
+.Pq option Fl a No of Xr schiff 1
+and the number of inverse cumulative phase function values
+.Pq option Fl A No of Xr schiff 1 .
+.\""""""""""""""""""""""""""""""""""
+.Ss List of phase functions
+The list of phase functions contains as many phase functions as there
+are wavelengths associated with the result
+.Pq option Fl w No of Xr schiff 1 .
+They are sorted in ascending order by their associated wavelengths.
+The phase functions are separated from one another by a blank line.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va phase-func-list Ac Ta ::= Ta \& \& Aq Va phase-func
+.It Ta Ta [\& EMPTY-LINE
+.It Ta Ta \& \& Ao Va phase-func Ac \& ] ...
+.El
+.Pp
+A phase function is a list of lines starting with a scattering angle in
+radians, followed by an estimate of the phase function's value - that
+is, its mean value and standard error.
+The number of scattering angles, and thus the number of lines describing
+the phase function, is controlled by the
+.Fl a
+option of
+.Xr schiff 1 .
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va phase-func Ac Ta ::= Ta
+.Aq Va angle
+.Aq Va estimation
+.It Ta Ta ...
+.It Ao Va angle Ac Ta ::= Ta Vt real No # \&In [0,PI]
+.El
+.\""""""""""""""""""""""""""""""""""
+.Ss List of cumulative phase functions
+The list of cumulative phase functions is formatted in the same way as
+the list of phase functions, that is, it contains as many functions as
+there are wavelengths associated with the result
+.Pq option Fl w No of Xr schiff 1 ,
+sorted in ascending order of wavelength, and separated by a blank line.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va cumul-phase-func-list Ac Ta ::= Ta \& \& Aq Va cumul-phase-func
+.It Ta Ta [\& EMPTY-LINE
+.It Ta Ta \& \& Ao Va cumul-phase-func Ac \& ] ...
+.El
+.Pp
+Similarly, a cumulative phase function follows the same data structure
+as a phase function, namely as many lines as there are scattering angles
+.Pq see the Fl a No option of Xr schiff 1 ,
+where each line begins with the value of the scattering angle in radians
+followed by the estimate of the cumulative phase function, namely its
+mean value and standard error.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va cumul-phase-func Ac Ta ::= Ta
+.Aq Va angle
+.Aq Va estimation
+.It Ta Ta ...
+.El
+.\""""""""""""""""""""""""""""""""""
+.Ss List of inverse cumulative phase function
+The last data set consists of a list of inverse cumulative phase
+functions which, like the previous function lists, contains as many
+entries as there are wavelengths used in the calculation
+.Pq option Fl w No of Xr schiff 1 .
+The functions in this list are sorted in ascending order of these
+wavelengths, and separated by a blank line.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va invcumul-phase-func-list Ac Ta ::= Ta
+.No \& \& Aq Va invcumul-phase-func
+.It Ta Ta [\& EMPTY-LINE
+.It Ta Ta \& \& Ao Va invcumul-phase-func Ac \& ] ...
+.El
+.Pp
+Each function corresponds to a list of lines, the number of which equals
+the number of scattering angles used to discretize the function
+.Pq option Fl A No in Xr schiff 1 .
+Each line of an inverse cumulative phase function contains two values:
+the scattering angle in radians
+.Pq in Bq 0,PI
+and its probability, which is equal to i/(N-1) for the i^th angle
+.Pq i in Bq 0,N-1 ,
+where N is the number of angles used to discretize the function.
+.Bl -column (invcumul-phase-func-list) (::=) ()
+.It Ao Va invcumul-phase-func Ac Ta ::= Ta
+.Aq Va angle
+.Aq Va proba
+.It Ta Ta ...
+.It \ Ta Ta
+.It Ao Va proba Ac Ta ::= Ta Vt real No # \&In [0,1]
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
The following output is emitted by the
-.BR schiff (1)
+.Xr schiff 1
program invoked on the wavelengths 0.3 and 0.6 micron.
Note that actually,
-.BR schiff (1)
-does not write comments, i.e. text preceeded by the "#" character. However
-comments are added in order to help in understanding the data layout.
-.RS 4
-.PP
-.nf
-0.3 10.61 0.20 9.51e-3 2.37e-4 10.6 0.20 5.25 0.10 \fB# X\-sections\fR
-0.6 11.15 0.25 4.76e-3 1.19e-4 11.1 0.25 5.25 0.10 \fB# X\-sections\fR
-0.3 0.18 1.37 17.6 7.74 0.73 0.80 1000 2000 \fB# descriptor\fR
-0.6 0.26 9.81 5.26 7.65 0.48 2.90 1000 2000 \fB# descriptor\fR
-0 520.23 64.2971 \fB# Phase function (0.3 micron)\fR
-0.00314474 474.315 50.6471
- ...
-3.13845 0.0196258 0
-3.14159 0.0196259 0
-.PP
-0 150.183 25.4822 \fB# Phase function (0.6 micron)\fR
-0.00314474 145.969 23.7955
- ...
-3.13845 0.00262338 0
-3.14159 0.00262338 0
-.PP
-0 0 0 \fB# Cumulative (0.3 micron)\fR
-0.00314474 0.0154297 0.00177366
- ...
-3.13845 0.999999 0
-3.14159 1 0
-.PP
-0 0 0 \fB# Cumulative (0.6 micron)\fR
-0.00314474 0.00460001 0.000765182
- ...
-3.13845 1 0
-3.14159 1 0
-.PP
-0 0 \fB# Inverse cumulative (0.3 micron)\fR
-0.00050025 0.000101956
- ...
-0.9995 3.05143
-1 3.14159
-.PP
-0 0 \fB# Inverse cumulative (0.6 micron)\fR
-0.00050025 0.00034199
- ...
-0.9995 2.89409
-1 3.14159
-.fi
-.SH SEE ALSO
-.BR schiff (1)
+.Xr schiff 1
+does not write comments, i.e. text preceeded by the hash character
+.Pq # .
+The comments here are intended to help in the understanding of the data
+structure.
+.Bl -column -offset Ds
+.It 0.3 10.61 0.20 9.51e-3 2.37e-4 10.6 0.20 5.25 0.10 Em # X-sections
+.It 0.6 11.15 0.25 4.76e-3 1.19e-4 11.1 0.25 5.25 0.10 Em # X-sections
+.It 0.3 0.18 1.37 17.6 7.74 0.73 0.80 1000 2000 Em # descriptor
+.It 0.6 0.26 9.81 5.26 7.65 0.48 2.90 1000 2000 Em # descriptor
+.It 0 520.23 64.2971 Em # Phase function (0.3 micron)
+.It 0.00314474 474.315 50.6471
+.It ...
+.It 3.13845 0.0196258 0
+.It 3.14159 0.0196259 0
+.It \&
+.It 0 150.183 25.4822 Em # Phase function (0.6 micron)
+.It 0.00314474 145.969 23.7955
+.It ...
+.It 3.13845 0.00262338 0
+.It 3.14159 0.00262338 0
+.It \&
+.It 0 0 0 Em # Cumulative (0.3 micron)
+.It 0.00314474 0.0154297 0.00177366
+.It ...
+.It 3.13845 0.999999 0
+.It 3.14159 1 0
+.It \&
+.It 0 0 0 Em # Cumulative (0.6 micron)
+.It 0.00314474 0.00460001 0.000765182
+.It ...
+.It 3.13845 1 0
+.It 3.14159 1 0
+.It \&
+.It 0 0 Em # Inverse cumulative (0.3 micron)
+.It 0.00050025 0.000101956
+.It ...
+.It 0.9995 3.05143
+.It 1 3.14159
+.It \&
+.It 0 0 Em # Inverse cumulative (0.6 micron)
+.It 0.00050025 0.00034199
+.It ...
+.It 0.9995 2.89409
+.It 1 3.14159
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr schiff 1
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh HISTORY
+.Nm
+has been developed as part of
+.Li ANR-11-IDEX-0002-02
+ALGUE project.
