commit 928bf6440ded35d65e6a5a1bf3fc930188dc2e5f
parent dc444559dc4c767d7489c203d7a9afa28b77e209
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 28 Jul 2023 16:52:19 +0200
Translate scdoc man page into mdoc'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.
Diffstat:
| M | Makefile | | | 3 | +++ |
| D | doc/mrumtl | | | 28 | ---------------------------- |
| D | doc/mrumtl.5.scd | | | 108 | ------------------------------------------------------------------------------- |
| A | mrumtl.5 | | | 104 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
4 files changed, 107 insertions(+), 136 deletions(-)
diff --git a/Makefile b/Makefile
@@ -80,6 +80,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" mrumtl.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include" src/mrumtl.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/mrumtl" COPYING README.md
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" mrumtl.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -87,6 +88,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/mrumtl/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/mrumtl/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/mrumtl.h"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/mrumtl.5"
################################################################################
# Miscellaneous targets
@@ -101,6 +103,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
+ mandoc -Tlint -Wall mrumtl.5
################################################################################
# Tests
diff --git a/doc/mrumtl b/doc/mrumtl
@@ -1,28 +0,0 @@
-<mrumtl> ::= <BRDF-list-wlen>
- | <BRDF-list-band>
-
-<BRDF-list-wlen> ::= wavelengths <wavelengths-count>
- <BRDF-wlen>
- [ <BRDF-wlen> ... ]
-
-<BRDF-list-band> ::= bands <bands-count>
- <BRDF-band>
- [ <BRDF-band> ... ]
-
-<wavelengths-count> ::= INTEGER
-<bands-count> ::= INTEGER
-
-<BRDF-wlen> ::= <wavelength> <BRDF>
-
-<BRDF-band> ::= <band-bound-min> <band-bound-max> <BRDF>
-<bound-bound-min> ::= <wavelength>
-<bound-bound-max> ::= <wavelength>
-
-<wavelength> ::= DOUBLE # in nanometer
-
-<BRDF> ::= <BRDF-lambertian>
- | <BRDF-specular>
-
-<BRDF-lambertian> ::= lambertian <reflectivity>
-<BRDF-specular> ::= specular <reflectivity>
-<reflectivity> ::= DOUBLE
diff --git a/doc/mrumtl.5.scd b/doc/mrumtl.5.scd
@@ -1,108 +0,0 @@
-mrumtl(5)
-
-; Copyright (C) 2020-2023 |Méso|Star> (contact@meso-star.com)
-;
-; 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
-
-mrumtl - ModRadUrb MaTeriaL file format
-
-# DESCRIPTION
-
-*mrumtl* is a text file format that describes a Bidirectional Reflectance
-Distribution Function (BRDF) 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
-
-```
-<mrumtl> ::= <per-wlen-BRDF>
- | <per-band-BRDF>
-
----
-
-<per-wlen-BRDF> ::= wavelengths <wavelengths-count>
- <wlen-BRDF>
- [ <wlen-BRDF> ... ]
-
-<wlen-BRDF> ::= <wavelength> <BRDF>
-<wavelengths-count> ::= INTEGER
-<wavelength> ::= REAL # in nanometer
-
----
-
-<per-band-BRDF> ::= bands <bands-count>
- <band-BRDF>
- [ <band-BRDF> ... ]
-
-<band-BRDF> ::= <wavelength-min> <wavelength-max> <BRDF>
-
-<bands-count> ::= INTEGER
-<wavelength-min> ::= REAL # Inclusive bound in nanometers
-<wavelength-max> ::= REAL # Inclusive bound in nanometers
-
----
-
-<BRDF> ::= <BRDF-lambertian>
- | <BRDF-specular>
-
-<BRDF-lambertian> ::= lambertian <reflectivity>
-<BRDF-specular> ::= specular <reflectivity>
-<reflectivity> ::= REAL # In [0, 1]
-```
-
-# EXAMPLES
-
-Describe a material with only two bands: one for the visible part of the
-spectrum and one for the long waves. In both cases use a diffuse reflectivity:
-
-```
-bands 2
-380 780 lambertian 0.9 # Visible part
-1000 100000 lambertian 0.1 # Infrared
-```
-
-Setup a material for a list of 17 wavelengths. This material is diffuse in
-short waves and specular in long waves:
-
-```
-wavelengths 17
-
-# Short waves
-430 lambertian 5.2e-2
-450 lambertian 6.2e-2
-500 lambertian 6.5e-002
-600 lambertian 0.165
-750 lambertian 0.175
-
-# Long waves
-1100 specular 0.1
-1300 specular 0.17
-1400 specular 0.1
-2000 specular 0.1
-2100 specular 0.4
-2300 specular 0.18
-2500 specular 0.9
-2600 specular 0.95
-2900 specular 0.4
-3000 specular 0.3
-4000 specular 0.0
-100000 specular 0.0
-```
diff --git a/mrumtl.5 b/mrumtl.5
@@ -0,0 +1,104 @@
+.\" Copyright (C) 2020, 2023 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" 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 July 28, 2023
+.Dt MRUMTL 5
+.Os
+.Sh NAME
+.Nm mrumtl
+.Nd ModRadUrb MaTeriaL file format
+.Sh DESCRIPTION
+.Nm
+is a text file format that describes a Bidirectional Reflectance
+Distribution Function
+.Pq BRDF
+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-BRDF) (::=) ()
+.It Ao Va mrumtl Ac Ta ::= Ta Ao Va per-wlen-BRDF Ac | Ao Va per-band-BRDF Ac
+.It \ Ta Ta
+.It Ao Va per-wlen-BRDF Ac Ta ::= Ta Li wavelength Ao Va #wavelengths Ac
+.It Ta Ta Ao Va wlen-BRDF Ac
+.It Ta Ta Va ...
+.It Ao Va wlen-BRDF Ac Ta ::= Ta Ao Va wavelength Ac Ao Va BRDF Ac
+.It Ao Va #wavelength Ac Ta ::= Ta Ao Va integer Ac
+.It Ao Va wavelength Ac Ta ::= Ta Ao Va real Ac
+# In nanometer
+.It \ Ta Ta
+.It Ao Va per-band-BRDF Ac Ta ::= Ta Li bands Ao Va #bands Ac
+.It Ta Ta Ao Va band-BRDF Ac
+.It Ta Ta Va ...
+.It Ao Va #bands Ac Ta ::= Ta Ao Va integer Ac
+.It Ao Va band-BRDF Ac Ta ::= Ta
+.Aq Va wavelength-min
+.Aq Va wavelength-max
+.Aq Va BRDF
+.It Ao Va wavelength-min Ac Ta ::= Ta Ao Va real Ac
+# Inclusive bound in nm
+.It Ao Va wavelength-max Ac Ta ::= Ta Ao Va real Ac
+# Inclusive bound in nm
+.It \ Ta Ta
+.It Ao Va BRDF Ac Ta ::= Ta
+.Aq Va BRDF-lambertian
+|
+.Aq Va BRDF-specular
+.It Ao Va BRDF-lambertian Ac Ta ::= Ta Li lambertian Ao Va reflectivity Ac
+.It Ao Va BRDF-specular Ac Ta ::= Ta Li specular Ao Va reflectivity Ac
+.It Ao Va reflectivity Ac Ta ::= Ta Ao Va real Ac
+# In [0, 1]
+.El
+.Sh EXAMPLES
+Describe a material with only two bands: one for the visible part of the
+spectrum and one for the long waves.
+In both cases use a diffuse reflectivity:
+.Bd -literal -offset indent
+bands 2
+380 780 lambertian 0.9 # Visible part
+1000 100000 lambertian 0.1 # Infrared
+.Ed
+.Pp
+Setup a material for a list of 17 wavelengths.
+This material is diffuse in short waves and specular in long waves:
+.Bd -literal -offset indent
+wavelengths 17
+
+# Short waves
+430 lambertian 5.2e-2
+450 lambertian 6.2e-2
+500 lambertian 6.5e-002
+600 lambertian 0.165
+750 lambertian 0.175
+
+# Long waves
+1100 specular 0.1
+1300 specular 0.17
+1400 specular 0.1
+2000 specular 0.1
+2100 specular 0.4
+2300 specular 0.18
+2500 specular 0.9
+2600 specular 0.95
+2900 specular 0.4
+3000 specular 0.3
+4000 specular 0.0
+100000 specular 0.0
+.Ed
