commit 250fb252c3fc095f2f77b92bd1ab9496481ab8b6
parent 00cf8fdf22024693ed1dc6c614f32849145ea22e
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 5 Sep 2023 14:50:56 +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
COPYRIGHT and LICENSE sections have been removed from the les2htcp
manual as they are not part of conventional Linux manuals (mandoc
doesn't mention them at all). Note that we're thinking of adding an
AUTHORS section. This is documented in mandoc, but is not recommended in
Linux manual page writing conventions due to, among other things,
maintenance weaknesses. Authors are already registered in source
control, so there is no particular advantage in adding a specific manual
section.
Diffstat:
| M | Makefile | | | 6 | ++++++ |
| D | doc/htcp.5.scd | | | 98 | ------------------------------------------------------------------------------- |
| D | doc/les2htcp.1.scd | | | 131 | ------------------------------------------------------------------------------- |
| A | htcp.5 | | | 112 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | les2htcp.1 | | | 164 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
5 files changed, 282 insertions(+), 229 deletions(-)
diff --git a/Makefile b/Makefile
@@ -109,6 +109,8 @@ install: build_library build_program pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" htcp.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/high_tune" src/htcp.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/htcp" COPYING README.md
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man1" les2htcp.1
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" htcp.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/bin/les2htcp"
@@ -117,6 +119,8 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/htcp/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/htcp/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/high_tune/htcp.h"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/les2htcp.1"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/htcp.5"
################################################################################
# Miscellaneous targets
@@ -134,6 +138,8 @@ lint:
shellcheck -o all src/dump_netcdf_data.sh
shellcheck -o all src/dump_netcdf_desc.sh
shellcheck -o all src/test_htcp_load_from_file.sh
+ mandoc -Tlint -Wall les2htcp.1
+ mandoc -Tlint -Wall htcp.5
################################################################################
# Tests
diff --git a/doc/htcp.5.scd b/doc/htcp.5.scd
@@ -1,98 +0,0 @@
-htcp(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
-
-htcp - High-Tune: Cloud Properties file format
-
-# DESCRIPTION
-
-*htcp* is a binary file format that describes properties on liquid water
-content in suspension within clouds. The *les2htcp*(1) command can be used to
-generate a *htcp* file from cloud properties saved in a NetCDF file format.
-
-The cloud properties are actually spatio temporal double precision floating
-point data, structured in a 4D grid whose definition and spatial origin is
-given by the _<definition>_ and the _<lower-pos>_ fields. The size of a grid
-cell along the X and Y dimension is constant while the size along the Z axis
-can be irregular. Is such case, the _<is-Z-irregular>_ header flag is set to 1
-and the sizes of the cells in Z are explicitly listed in _<voxel-size>_. Note
-that in *htcp*, the spatial dimensions are defined in meters, i.e. values
-listed in _<lower-pos>_ and _<voxel-size>_ are meters.
-
-For a given property, the list of its spatio temporal data are linearly listed
-along the X, Y, Z and time dimension, in that order. The address where its
-first data is stored is aligned on the value defined by the file header field
-_<pagesize>_; several bytes of padding can be thus added priorly to a property
-in order to ensure that its first data is correctly aligned.
-
-Available cloud properties are:
-
-- _<RVT>_: water vapor mixing ratio in kg of water per m^3 of dry air.
-- _<RCT>_: liquid water in suspension mixing ratio in kg of water per m^3 of dry
- air.
-- _<PABST>_: pressure in Pascal.
-- _<T>_: temperature in Kelvin.
-
-# BINARY FILE FORMAT
-
-Data are encoded with respect to the little endian bytes ordering, i.e. least
-significant bytes are stored first.
-
-```
-<htcp> ::= <header>
- <definition>
- <lower-pos>
- <voxel-size>
- <padding>
- <RVT>
- <padding>
- <RCT>
- <padding>
- <PABST>
- <padding>
- <T>
- <padding>
-
-<header> ::= <pagesize> <is-Z-irregular>
-<definition> ::= <X> <Y> <Z> <time> # Spatial and temporal definition
-<lower-pos> ::= DOUBLE DOUBLE DOUBLE # Spatial origin of the grid
-<voxel-size> ::= DOUBLE DOUBLE # Size of a cell in X and Y
- DOUBLE [ DOUBLE ... ] # Size of the cells in Z
-
-<pagesize> ::= INT64
-<is-Z-irregular>
- ::= INT8
-
-<X> ::= INT32
-<Y> ::= INT32
-<Z> ::= INT32
-<time> ::= INT32
-
-<RVT> ::= DOUBLE [ DOUBLE ... ] # Water vapor mixing ratio
-<RCT> ::= DOUBLE [ DOUBLE ... ] # Liquid water in suspension mixing ratio
-<PABST> ::= DOUBLE [ DOUBLE ... ] # Pressure
-<T> ::= DOUBLE [ DOUBLE ... ] # Temperature
-
-<padding> ::= [ BYTE ... ]
-```
-
-# SEE ALSO
-
-*les2htcp*(1)
diff --git a/doc/les2htcp.1.scd b/doc/les2htcp.1.scd
@@ -1,131 +0,0 @@
-les2htcp(1)
-
-; 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
-
-les2htcp - convert cloud properties from NetCDF to htcp(5) file format
-
-# SYNOPSIS
-
-les2htcp [_option_] ... -i _NetCDF_
-
-# DESCRIPTION
-*les2htcp* generates a *htcp*(5) file from cloud properties stores in a NetCDF
-file [1]. Expected variables in the submitted NetCDF file are:
-
-- _W_E_direction_ *and* _S_N_direction_: one dimensional list of position of the
- center of each cell along the West-East and South-North horizontal axis,
- respectively. This should be a homogeneous mesh: each cell should have the
- same width along each axis. The unit is assumed to be the meter but it can
- be adjusted by the *-m* option.
-- _VLEV_ *or* _vertical_levels_: position of the center of each cell along the
- vertical axis. The vertical mesh can possibly be inhomogeneous: each cell
- can have different vertical extent. At least one of this variable must be
- defined. Note that _VLEV_ is a four dimensional variable while
- _vertical_levels_ is assumed to be one dimensional. In all cases, *les2htcp*
- assumes that the vertical columns are the same for each cell along the
- West-East and South-North axis. The unit is assumed to be the meter but it
- can be adjusted by the *-m* option.
-- _RVT_: water vapor mixing ratio in each grid cell; in kg of water per kg of
- air.
-- _RCT_: liquid water (in suspension) mixing ratio in each grid cell; in kg of
- water per kg of dry air.
-- _PABST_: pressure in each grid cell in Pascal.
-- _THT_: potential temperature in each grid cell in Kelvin.
-
-# OPTIONS
-
-*-c*
- Advanced checks on the validity of the submitted _NetCDF_ file with respect
- to the *les2htcp* prerequisites on the NetCDF data. Note that this option
- can increase significantly the conversion time.
-
-*-f*
- Force overwrite of the _output_ file.
-
-*-h*
- List short help and exit.
-
-*-i* _NetCDF_
- NetCDF file to convert.
-
-*-m* _float-to-meter_
- Scale factor from floating point unit to meters. By default it is set to 1.
-
-*-o* _output_
- Destination file where the *htcp*(5) file is written. If not defined, the
- results are written to standard output.
-
-*-p* _page-size_
- Targeted page size in bytes; must be a power of 2. The size of the converted
- NetCDF data and their starting address into the *htcp*(5) file are aligned
- according to _page-size_. By default, _page-size_ is 4096 bytes.
-
-*-q*
- Write nothing to _output_. Might be used in conjunction of the *-c* option
- to only check the submitted _NetCDF_.
-
-*-v*
- Display version information and exit.
-
-# EXAMPLES
-
-Convert the _clouds.nc_ NetCDF file. Write the resulting *htcp*(5) file in
-_cloud.htcp_ excepted if the file already exists; in this case an error is
-notified, the program stops and the _cloud.htcp_ file remains unchanged:
-
-```
-les2htcp -i clouds.nc -o clouds.htcp
-```
-
-Convert the _clouds_km.nc_ file to *htcp*(5) file format. Use the *-f* option
-to write the output file _clouds.htcp_ even though it already exists. The
-_clouds_km.nc_ file to convert has its spatial unit in kilo-meters while the
-*htcp*(5) file format assumes meters: use the *-m* _1000_ option to map
-kilo-meters to meters:
-
-```
-les2htcp -i clouds_km.nc -m 1000 -o clouds.htcp
-```
-
-Check that the submitted _clouds.nc_ file is valid regarding the
-*les2htcp* constraints. Use the *-q* option to disable the generation of
-output data:
-
-```
-les2htcp -c -i clouds.nc -q
-```
-
-# COPYRIGHT
-
-Copyright © 2018, 2020 |Méso|Star> <contact@meso-star.com>++
-Copyright © 2018 Centre National de la Recherche Scientifique++
-Copyright © 2018 Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>
-
-# LICENSE
-
-*les2htcp* is free software released under the GPLv3+ license: GNU GPL version
-3 or later <https://gnu.org/licenses/gpl.html>. You are free to change and
-redistribute it. There is NO WARRANTY, to the extent permitted by law.
-
-# SEE ALSO
-
-. Network Common Data Form - <https://www.unidata.ucar.edu/software/netcdf/>
-
-*htcp*(5)
diff --git a/htcp.5 b/htcp.5
@@ -0,0 +1,112 @@
+.\" 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 4, 2023
+.Dt HTCP 5
+.Os
+.Sh NAME
+.Nm htcp
+.Nd High-Tune: Cloud Properties
+.Sh DESCRIPTION
+.Nm
+is a binary file format for storing the properties of liquid water content
+suspended in clouds.
+Cloud properties are double-precision spatio-temporal floating-point values,
+structured in a 4D grid whose definition and origin are stored in the
+.Va definition
+and
+.Va lower-pos
+fields.
+The size of a grid cell can be irregular.
+In such case, the
+.Va is-Z-irregular
+flag is set to 1 and the sizes of the cells in Z are explicitly listed in
+.Va voxel-size
+.Pq in meters .
+The size of a grid cell along the X and Y axes is constant, whereas the size
+along the Z axis may be irregular.
+In this case, the
+.Va is-Z-irregular
+flag is set to 1 and the Z cell size is explicitly indicated in
+.Va voxel-size
+.Pq in meters .
+.Pp
+For each property, the list of its data is enumerated linearly along the X, Y,
+Z and time dimensions, in that order.
+The address where its first data is stored is aligned with the value defined by
+the
+.Va pagesize
+field; several padding bytes can therefore be added before a property to ensure
+data alignment.
+Padding bytes are also added at the end of the file to align its overall size
+with the size of a page.
+.Pp
+The stored cloud properties are as follows:
+.Bl -dash -offset indent -compact
+.It
+.Va RVT :
+water vapor mixing ratio in kg of water per m^3 of dry air.
+.It
+.Va RCT :
+liquid water in suspension mixing ratio in kg of water per m^3 of dry air.
+.It
+.Va PABST :
+pressure in Pascal.
+.It
+.Va T :
+temperature in Kelvin.
+.El
+.Pp
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+.Pp
+The file format is as follows:
+.Bl -column (is-Z-irregular) (::=) ()
+.It Ao Va htcp Ac Ta ::= Ta Ao Va pagesize Ac Ao Va is-Z-irregular Ac
+.It Ta Ta Aq Va definition
+.It Ta Ta Aq Va lower-pos
+.It Ta Ta Aq Va voxel-size
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va RVT
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va RCT
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va PABST
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va T
+.It Ta Ta Aq Va padding
+.It \ Ta Ta
+.It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t
+.It Ao Va is-Z-irregular Ac Ta ::= Ta Vt int8_t
+.It \ Ta Ta
+.It Ao Va definition Ac Ta ::= Ta Ao Va X Ac Ao Va Y Ac Ao Va Z Ac Ao Va time Ac
+.It Ao Va lower-pos Ac Ta ::= Ta Vt double double double
+# In m
+.It Ao Va voxel-size Ac Ta ::= Ta Vt double double double ...
+# In m
+.It Ao Va X Ac Ta ::= Ta Vt uint32_t
+.It Ao Va Y Ac Ta ::= Ta Vt uint32_t
+.It Ao Va Z Ac Ta ::= Ta Vt uint32_t
+.It Ao Va time Ac Ta ::= Ta Vt uint32_t
+.It \ Ta Ta
+.It Ao Va RVT Ac Ta ::= Ta Vt double ...
+.It Ao Va RCT Ac Ta ::= Ta Vt double ...
+.It Ao Va PABST Ac Ta ::= Ta Vt double ...
+.It Ao Va T Ac Ta ::= Ta Vt double ...
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+.El
+.Sh SEE ALSO
+.Xr les2htcp 1
diff --git a/les2htcp.1 b/les2htcp.1
@@ -0,0 +1,164 @@
+.\" 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 5, 2023
+.Dt LES2HTCP 1
+.Os
+.Sh NAME
+.Nm les2htcp
+.Nd convert cloud properties from NetCDF to
+.Xr htcp 5
+.Sh SYNOPSIS
+.Nm
+.Op Fl cfhqv
+.Op Fl m Ar float_to_meter
+.Op Fl o Ar output
+.Op Fl p Ar pagesize
+.Fl i Ar netcdf
+.Sh DESCRIPTION
+.Nm
+generates a
+.Xr htcp 5
+file from cloud properties stored in a NetCDF file\ [1].
+The variables expected in the submitted NetCDF file are:
+.Bl -dash -offset indent
+.It
+.Va W_E_direction
+and
+.Va S_N_direction :
+one-dimensional list of the position at the center of each cell along the
+west-east and south-north horizontal axis, respectively.
+The mesh must be homogeneous: each cell must have the same width along each
+axis.
+The unit is assumed to be meters, but this can be adjusted via
+the
+.Fl m
+option.
+.It
+.Va VLEV
+or
+.Va vertical_levels :
+position at the center of each cell along the vertical axis.
+The vertical mesh can be inhomogeneous, i.e. each cell can have a different
+vertical extent.
+At least one of these variables must be defined.
+Note that
+.Va VLEV
+is a four-dimensional variable, whereas
+.Va vertical_levels
+is assumed to be one-dimensional.
+In all cases
+.Nm
+assumes that the vertical columns are
+the same for each cell along the west-east and south-north axes.
+The unit is assumed to be meters, but this can be adjusted via the
+.Fl m
+option.
+.It
+.Va RCT :
+mixing ratio of liquid suspended water in each grid cell; in kg of water per kg
+of dry air.
+.It
+.Va PABST :
+pressure in each grid cell in Pascal.
+.It
+.Va THT :
+potential temperature in each grid cell in Kelvin.
+.El
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl c
+Advanced checks of the validity of the input
+.Ar netcdf
+file against
+.Nm
+prerequisites on NetCDF data.
+Note that this option can significantly increase conversion time.
+.It Fl f
+Forces overwriting of
+.Ar output
+file.
+.It Fl h
+Display short help.
+.It Fl i Ar netcdf
+NetCDF file to convert.
+.It Fl m Ar float_to_meter
+Scale factor to be applied to floating-point number
+.Li 1.0 to convert it to meters. By default, it is set to
+.Li 1 .
+.It Fl o Ar output
+Output file.
+If not defined, data is written to standard output.
+.It Fl p Ar pagesize
+Page size in bytes on which htcp data will be aligned.
+It must be a power of 2 and greater than or equal to the size of a system page,
+which is the default value
+.Pq see Xr sysconf 3 .
+.It Fl q
+Writes nothing to the output.
+Can be used in conjunction with the
+.Fl c
+option to check only the validity of the input NetCDF.
+.It Fl v
+Display the version number and exit.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Convert the NetCDF
+.Pa clouds.nc
+file.
+The resulting
+.Xr htcp 5
+file is stored in the
+.Pa cloud.htcp
+file unless it already exists; in this case, an error is notified, the program
+stops and the
+.Pa cloud.htcp
+file remains unchanged:
+.Pp
+.Dl les2htcp -i clouds.nc -o clouds.htcp
+.Pp
+Converts NetCDF file
+.Pa clouds_km.nc
+to
+.Xr htcp 5
+format.
+Use the
+.Fl f
+option to write the output file
+.Pa clouds.htcp
+even if it already exists.
+The input file to be converted has its spatial unit in kilo-meters, whereas the
+htcp file format assumes meters; use the
+.Fl m Ar 1000
+option to perform the conversion:
+.Pp
+.Dl les2htcp -i clouds_km.nc -m 1000 -o clouds.htcp
+.Pp
+Check that the NetCDF file
+.Pa clouds.nc
+is a valid input file for
+.Nm .
+Use the
+.Fl q
+option to disable file conversion:
+.Pp
+.Dl les2htcp -c -i clouds.nc -q
+.Sh SEE ALSO
+.Xr sysconf 3 ,
+.Xr htcp 5
