commit 928c1f325ea19c7a104bbc71ccfd8ceb565b91a2
parent 16e0221a3de817e960cc2ed8e98e9482e9084250
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 8 Sep 2023 09:02:28 +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.
During translation, minor content updates were made. In particular, the
STANDARDS section has been added to refer to the netcDF4/HDF5 format
specification. We've also added a HISTORY section to notify the
connection of the file format to the htrdr program. Note that the
referenced htrdr 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/htmie.5.scd | | | 54 | ------------------------------------------------------ |
| A | htmie.5 | | | 58 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 61 insertions(+), 57 deletions(-)
diff --git a/Makefile b/Makefile
@@ -86,7 +86,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" htmie.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/high_tune" src/htmie.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/htmie" COPYING README.md
-# @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" htmie.5
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" htmie.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -94,7 +94,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/htmie/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/htmie/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/high_tune/htmie.h"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htmie.5"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htmie.5"
################################################################################
# Miscellaneous targets
@@ -110,7 +110,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
shellcheck -o all src/dump_netcdf_data.sh
-# mandoc -Tlint -Wall htmie.5
+ mandoc -Tlint -Wall htmie.5 || [ $$? -le 1 ]
################################################################################
# Tests
diff --git a/doc/htmie.5.scd b/doc/htmie.5.scd
@@ -1,54 +0,0 @@
-htmie(5)
-
-; Copyright (C) 2018, 2020-2023 |Méso|Star> (contact@meso-star.com)
-; Copyright (C) 2018 Centre National de la Recherche Scientifique
-; Copyright (C) 2018 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
-
-htmie - High-Tune: Mie's data file format
-
-# DESCRIPTION
-
-*htmie* is the file format used by *htrdr*(1) to describe the optical
-properties of water droplets obtained by a Mie code. This format relies on the
-NetCDF data format [1]. To be a valid *htmie* file, the NetCDF file must
-define the following variables:
-
-*lambda*++
- One dimensional array of floating point data that lists the wavelengths
-in nanometers for which the subsequent data are defined.
-
-*macs*++
- One dimensional array of massic absorption cross-sections in kg of liquid
-water in suspension.
-
-*mscs*++
- One dimensional array of massic scattering cross-sections in kg of liquid
-water in suspension.
-
-*g*++
- One dimensional array of asymmetry parameters of the equivalent
-Henyey-Greenstein phase function.
-
-# NOTES
-
-. Network Common Data Form - <https://www.unidata.ucar.edu/software/netcdf/>
-
-# SEE ALSO
-
-*htrdr*(1)
-
diff --git a/htmie.5 b/htmie.5
@@ -0,0 +1,58 @@
+.\" Copyright (C) 2018, 2020-2023 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2018 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2018 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 8, 2023
+.Dt HTMIE 5
+.Os
+.Sh NAME
+.Nm htmie
+.Nd High-Tune: Mie
+.Sh DESCRIPTION
+.Nm
+is a netCDF file format for storing the optical properties of water droplets
+obtained by Mie scattering evaluation.
+A
+.Nm
+netCDF file must define the following variables:
+.Bl -hang
+.It Va lambda
+One-dimensional array of floating-point data that lists the wavelengths in
+nanometers for which the following data are defined.
+.It Va macs
+One dimensional array of massic absorption cross-sections in kg of liquid
+water in suspension.
+.It Va mscs
+One-dimensional table of mass diffusion cross-sections in kg of suspended
+liquid water.
+.It Va g
+One-dimensional table of asymmetry parameters of the Henyey-Greenstein
+equivalent phase function.
+.El
+.Sh SEE ALSO
+.Xr htrdr 1
+.Sh STANDARDS
+.Rs
+.%A Edward Hartnett
+.%D March 2011
+.%R ESDS-RFC-022v1
+.%T netCDF4/HDF5 File Format
+.Re
+.Sh HISTORY
+The
+.Nm
+format was first developed for the
+.Xr htrdr 1
+program.
