commit 255630c92abeb14131a03ca8f523d5a0a73d488b
parent 584937f0225fc530efc591a0c7e53773563cdcd8
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 15 Sep 2023 12:09:25 +0200
Translate scdoc man pages into mandoc's roff macros
Unlike writing manuals with man's roff macros, and even more so with
scdoc, mdoc macros take care of layout, font handling and all the other
typesetting details which, by construction, guarantee the consistency of
all manuals without leaving the responsibility to the individual author.
This also facilitates translation into other formats and documentation
tools. These are the main reasons for writing manual pages with mdoc
macros.
Note that the referenced htrdr-planeto man page has not been installed
in mandoc's default search path, so mandoc issues a warning and returns
1 when checking file conformity. This generates an error at the Makefile
invocation when invoking the lint target. We correct this problem by
accepting all mandoc return codes less than or equal to 1, which
corresponds to "at least one violation of the base system convention or
style suggestion has occurred, but no warning or error" (extract from
the mandoc manual "EXIT STATUS").
Diffstat:
| M | Makefile | | | 6 | +++--- |
| D | doc/rnsf.5.scd | | | 138 | ------------------------------------------------------------------------------- |
| A | rnsf.5 | | | 148 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 151 insertions(+), 141 deletions(-)
diff --git a/Makefile b/Makefile
@@ -87,7 +87,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" rnsf.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/rad-net" src/rnsf.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/rnsf" COPYING README.md
-# @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rnsf.5
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rnsf.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -95,7 +95,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnsf/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnsf/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/rad-net/rnsf.h"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnsf.5"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnsf.5"
################################################################################
# Miscellaneous targets
@@ -110,7 +110,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
-# mandoc -Tlint -Wall rnsf.5 || [ $$? -le 1 ]
+ mandoc -Tlint -Wall rnsf.5 || [ $$? -le 1 ]
################################################################################
# Tests
diff --git a/doc/rnsf.5.scd b/doc/rnsf.5.scd
@@ -1,138 +0,0 @@
-rnsf(5)
-
-; Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
-; Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
-; Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
-; Copyright (C) 2022, 2023 |Méso|Star>(contact@meso-star.com)
-; Copyright (C) 2022, 2023 Observatoire de Paris
-; Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
-; Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
-; Copyright (C) 2022, 2023 Université Paul Sabatier
-;
-; 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
-
-rnsf - Rad-Net Scattering Functions file format
-
-# DESCRIPTION
-
-*rnsf* is a text file format that describes a phase function whose type and
-parameters can vary spectrally. Its data are described for a set of wavelengths
-or spectral bands that must be listed in ascending order.
-
-Characters behind the hash mark (#) are considered comments and are therefore
-ignored, as well as empty lines, i.e. lines without any characters or composed
-only of spaces and tabs.
-
-# GRAMMAR
-
-```
-<rnsf> ::= <per-wlen-phase-func>
- | <per-band-pĥase-func>
-
----
-
-<per-wlen-phase-func> ::= wavelengths <wavelengths-count>
- <wlen-phase-func>
- [ <wlen-phase-func> ... ]
-
-<wlen-phase-func> ::= <wavelength> <phase-func>
-<wavelengths-count> ::= INTEGER
-<wavelength> ::= REAL # In nanometers
-
----
-
-<per-band-phase-func> ::= bands <bands-count>
- <band-phase-func>
- [ <band-phase-func ... ]
-
-<wlen-band-func> ::= <wavelength-min> <wavelength-max> <phase-func>
-
-<bands-count> ::= INTEGER
-<wavelength-min> ::= REAL # Inclusive bound in nanometers
-<wavelength-max> ::= REAL # Inlcusive bound in nanometers
-
----
-
-<phase-func> ::= <phase-func-HG>
- | <phase-func-discrete>
-
-<phase-func-HG> ::= HG <asymmetric-param>
-<asymmetric-param> ::= REAL # in [-1, 1]
-
-<phase-func-discrete> ::= discrete <angles-count>
- 0 <value>
- [ <per-angle-value> ... ] # In ascending order wrt the angle
- 3.14159 <value>
-<per-angle-value> ::= <theta> <value>
-<theta> ::= REAL # In radian
-<value> ::= REAL # Not necessarily normalized
-
-```
-
-# EXAMPLES
-
-Spectrally varying phase function on two spectral bands: a band for the visible
-part of the spectrum for which a Henyey & Greenstein phase function is used, and
-a band for long waves with a discretized phase function on 4 angles:
-
-```
-bands 2
-
-# Visible part
-380 780 HG 0
-
-# Inrared
-1000 100000 discrete 4
- 0 0.079577
- 0.78 0.079577
- 2.35 0.079577
- 3.14159 0.079577
-```
-
-Setup a phase function for a set of 10 wavelengths. Use a discrete phase
-function for short waves and Henyey & Greenstein for long waves:
-
-```
-wavelengths 10
-
-# Short waves
-430 discrete 8
- 0 0.02
- 0.23 0.04
- 0.5 0.07
- 0.7 0.15
- 1.54 1.23
- 1.8 0.02
- 2 1.23
- 3.14159 0.79
-450 discrete 2
- 0 0.5
- 3.14159 0.796
-750 discrete 4
- 0 0.079577
- 0.78 0.079577
- 2.35 0.079577
- 3.14159 0.079577
-
-# Long waves
-1100 HG -0.1
-1300 HG 0.57
-1400 HG 0.4
-2100 HG 0.3
-2500 HG -0.9
-2900 HG -0.4
-100000 HG 0.0
-```
diff --git a/rnsf.5 b/rnsf.5
@@ -0,0 +1,148 @@
+.\" Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
+.\" Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
+.\" Copyright (C) 2022, 2023 |Méso|Star>(contact@meso-star.com)
+.\" Copyright (C) 2022, 2023 Observatoire de Paris
+.\" Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
+.\" Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
+.\" Copyright (C) 2022, 2023 Université Paul Sabatier
+.\"
+.\" 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 September 15, 2023
+.Dt RNSF 5
+.Os
+.Sh NAME
+.Nm rnsf
+.Nd Rad-Net Scattering Functions file format
+.Sh DESCRIPTION
+.Nm
+is a text file format that describes a phase function whose type and parameters
+can vary spectrally.
+Its data are described for a set of wavelengths or spectral bands that must be
+listed in ascending order.
+.Pp
+Characters behind the hash mark
+.Pq Li #
+are considered comments and are therefore ignored, as well as empty lines,
+i.e. lines without any characters or composed only of spaces and tabs.
+.Pp
+The file format is as follows:
+.Bl -column (per-band-phase-func) (::=) ()
+.It Aq Va rnsf Ta ::= Ta Ao Va per-wlen-phase-func Ac |
+.Ao Va per-band-phase-func Ac
+.It \ Ta Ta
+.It Aq Va per-wlen-phase-func Ta ::= Ta
+.Li wavelengths
+.Aq Va wavelengths-count
+.It Ta Ta Aq Va wlen-phase-func
+.It Ta Ta Va ...
+.It Aq Va wlen-phase-func Ta ::= Ta Ao Va wavelength Ac Ao Va phase-func Ac
+.It Aq Va wavelengths-count Ta ::= Ta Va integer
+.It Aq Va wavelength Ta ::= Ta Va real
+# In nanometers
+.It \ Ta Ta
+.It Aq Va per-band-phase-func Ta ::= Ta
+.Li bands
+.Aq Va bands-count
+.It Ta Ta Aq Va band-phase-func
+.It Ta Ta Va ...
+.It Aq Va band-phase-func Ta ::= Ta
+.Aq Va length-min
+.Aq Va length-max
+.Aq Va phase-func
+.It Aq Va bands-count Ta ::= Ta Va integer
+.It Aq Va length-min Ta ::= Ta Va real
+# Inclusive bound in nanometers
+.It Aq Va length-max Ta ::= Ta Va real
+# Inclusive bound in nanometers
+.It \ Ta Ta
+.It Aq Va phase-func Ta ::= Ta Ao Va phase-func-HG Ac |
+.Ao Va phase-func-discrete Ac
+.It \ Ta Ta
+.It Aq Va phase-func-HG Ta ::= Ta Li HG Aq Va asymmetric-param
+.It Aq Va asymmetric-param Ta ::= Ta Va real
+# In
+.Bq -1, 1
+.It \ Ta Ta
+.It Aq Va phase-func-discrete Ta ::= Ta Li discrete Aq Va angles-count
+.It Ta Ta Li 0 Aq Va value
+.It Ta Ta Op Ao Va pair Ac Va ...
+# Ascending angles
+.It Ta Ta Li 3.14159 Aq Va value
+.It Aq Va angles-count Ta ::= Ta Va integer
+# Must be >= 2
+.It Aq Va pair Ta ::= Ta Ao Va theta Ac Ao Va value Ac
+.It Aq Va theta Ta ::= Ta Va real
+# In radians
+.It Aq Va value Ta ::= Ta Va real
+# Not necessarily normalized
+.El
+.Sh EXAMPLES
+Spectrally varying phase function on two spectral bands: a band for the visible
+part of the spectrum for which a Henyey & Greenstein phase function is used,
+and a band for long waves with a discretized phase function on 4 angles:
+.Bd -literal -offset Ds
+bands 2
+
+# Visible part
+380 780 HG 0
+
+# Inrared
+1000 100000 discrete 4
+ 0 0.079577
+ 0.78 0.079577
+ 2.35 0.079577
+ 3.14159 0.079577
+.Ed
+.Pp
+Phase function for a set of 10 wavelengths.
+Use a discrete phase function for short waves and Henyey & Greenstein for long
+waves:
+.Bd -literal -offset Ds
+wavelengths 10
+
+# Short waves
+430 discrete 8
+ 0 0.02
+ 0.23 0.04
+ 0.5 0.07
+ 0.7 0.15
+ 1.54 1.23
+ 1.8 0.02
+ 2 1.23
+ 3.14159 0.79
+450 discrete 2
+ 0 0.5
+ 3.14159 0.796
+750 discrete 4
+ 0 0.079577
+ 0.78 0.079577
+ 2.35 0.079577
+ 3.14159 0.079577
+
+# Long waves
+1100 HG -0.1
+1300 HG 0.57
+1400 HG 0.4
+2100 HG 0.3
+2500 HG -0.9
+2900 HG -0.4
+100000 HG 0.0
+.Ed
+.Sh HISTORY
+The
+.Nm
+format was first developed for the
+.Xr htrdr-planeto 1
+program.
