commit 473baa188a9ac9f40ea4935760b37f5b61fc3bb2
parent fcb41f4ea7b072718c08c5ab37ed436a2628fd25
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 8 Jul 2022 11:50:56 +0200
Use scdoc rather than asciidoc to write the man page
Diffstat:
4 files changed, 114 insertions(+), 122 deletions(-)
diff --git a/README.md b/README.md
@@ -8,7 +8,9 @@ and provide a library to load these data.
The `mrumtl` library is compatible GNU/Linux 64-bits. It relies on the
[CMake](http://www.cmake.org) and the
[RCMake](https://gitlab.com/vaplv/rcmake/) packages to build. They also depend
-on the [RSys](https://gitlab.com/vaplv/rsys/) library.
+on the [RSys](https://gitlab.com/vaplv/rsys/) library. It optionally depends
+on [scdoc](https://sr.ht/~sircmpwn/scdoc/) which, if available, is used to
+generate the man page of the file format.
To build the library, first ensure that CMake is installed on your system. Then
install the RCMake package as well as the aforementioned prerequisites. Finally
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -95,18 +95,16 @@ endif()
################################################################################
# Man pages
###############################################################################
-find_program(A2X NAMES a2x a2x.py)
-if(NOT A2X)
+find_program(SCDOC NAMES scdoc)
+if(NOT SCDOC)
message(WARNING
- "The `a2x' program is missing. "
+ "The `scdoc' program is missing. "
"The mrumtl man page cannot be generated.")
else()
- set(_src ${PROJECT_SOURCE_DIR}/../doc/mrumtl.5.txt)
- set(_txt ${CMAKE_CURRENT_BINARY_DIR}/mrumtl.5.txt)
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/mrumtl.5.scd)
add_custom_command(
OUTPUT mrumtl.5
- COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_txt}
- COMMAND ${A2X} -dmanpage -fmanpage ${_txt}
+ COMMAND ${SCDOC} < ${_src} > mrumtl.5
DEPENDS ${_src}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Buid ROFF man page mrumtl.5"
@@ -115,6 +113,7 @@ else()
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mrumtl.5 DESTINATION share/man/man5)
endif()
+
################################################################################
# Define output & install directories
################################################################################
diff --git a/doc/mrumtl.5.scd b/doc/mrumtl.5.scd
@@ -0,0 +1,105 @@
+mrumtl(5)
+
+; Copyright (C) 2020, 2021, 2022 |Meso|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
+
+A *mrumtl* file defines a spectral varying Bidirectional Reflectance
+Distribution Function (BRDF). Both the parameters and the type of the function
+can vary over the spectrum. These data can be defined for a list of
+wavelengths or for a set a spectral bands. In both cases, the wavelengths or
+the band boundaries are given in nanometers and must be listed in ascending
+orders. In addition the spectral bands must not overlapped.
+
+Characters behind the hash mark (#) are considered as comments and are thus
+ignored. Empty lines, i.e. lines without any characters or composed only of
+spaces and tabulations, are simply skipped.
+
+# GRAMMAR
+
+```
+<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> ::= REAL # in nanometer
+
+<BRDF> ::= <BRDF-lambertian>
+ | <BRDF-specular>
+
+<BRDF-lambertian> ::= lambertian <reflectivity>
+<BRDF-specular> ::= specular <reflectivity>
+<reflectivity> ::= REAL
+```
+
+# 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/doc/mrumtl.5.txt b/doc/mrumtl.5.txt
@@ -1,114 +0,0 @@
-// Copyright (C) 2020 |Meso|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/>.
-:toc:
-
-mrumtl(5)
-=========
-
-NAME
-----
-mrumtl - ModRadUrb MaTeriaL file format
-
-DESCRIPTION
------------
-
-A *mrumtl* file defines a spectral varying Bidirectional Reflectance
-Distribution Function (BRDF). Both the parameters and the type of the function
-can vary over the spectrum. These data can be defined for a list of
-wavelengths or for a set a spectral bands. In both cases, the wavelengths or
-the band boundaries are given in nanometers and must be listed in ascending
-orders. In addition the spectral bands must not overlapped.
-
-Characters behind the hash mark (#) are considered as comments and are thus
-ignored. Empty lines, i.e. lines without any characters or composed only of
-spaces and tabulations, are simply skipped.
-
-GRAMMAR
--------
-
-[verse]
--------
-<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
--------
-
-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:
-
-[verse]
--------
-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:
-
-[verse]
--------
-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
--------
-
