commit abebc2ca1691190d96cb0ae0a527cfc6d18f1cf8
parent 541e2763c1661b5bc7428bcd73477133c7de2eea
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 17 Oct 2022 15:27:37 +0200
Convert the man page sources from asciidoc to scdoc
Diffstat:
| M | README.md | | | 9 | ++++----- |
| M | cmake/doc/CMakeLists.txt | | | 47 | ++++++++++++----------------------------------- |
| A | doc/htcp.5.scd | | | 97 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | doc/htcp.5.txt | | | 101 | ------------------------------------------------------------------------------- |
| A | doc/les2htcp.1.scd | | | 130 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | doc/les2htcp.1.txt | | | 134 | ------------------------------------------------------------------------------- |
6 files changed, 243 insertions(+), 275 deletions(-)
diff --git a/README.md b/README.md
@@ -17,9 +17,8 @@ They rely on the [CMake](http://www.cmake.org) and the
on the [RSys](https://gitlab.com/vaplv/rsys/) library. Furthermore, the
`les2htcp` tool depends on the
[NetCDF](https://www.unidata.ucar.edu/software/netcdf/) C library.
-Both eventually depend on the [AsciiDoc](https://asciidoc.org/) suite of
-tools; if available, the man pages for the reference documentation will be
-generated.
+Both eventually depend on [scdoc](https://sr.ht/~sircmpwn/scdoc/)
+which, if available, is used to generate the man pages.
To build them, first ensure that CMake is installed on your system. Then
install the RCMake package as well as the aforementioned prerequisites. Finally
@@ -31,8 +30,8 @@ informations on CMake.
## Copyright notice
-Copyright (C) 2018, 2020, 2021 |Meso|Star> (<contact@meso-star.com>).
-Copyright (C) 2018 Centre National de la Recherche Scientifique (CNRS).
+Copyright (C) 2018, 2020, 2021 |Meso|Star> (<contact@meso-star.com>).
+Copyright (C) 2018 Centre National de la Recherche Scientifique (CNRS).
Copyright (C) 2018 Université Paul Sabatier (<contact-edstar@laplace.univ-tlse.fr>)
## License
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -19,49 +19,28 @@ set(HTCP_DOC_DIR ${PROJECT_SOURCE_DIR}/../doc)
################################################################################
# Look for the a2x program
################################################################################
-find_program(A2X NAMES a2x a2x.py)
-if(NOT A2X)
+find_program(SCDOC NAMES scdoc)
+if(NOT SCDOC)
message(WARNING
+ "The `scdoc' program is missing. "
"The `a2x' program is missing. "
- "The htcp man pages cannot be generated.")
+ "The High-Tune Cloud Properties man pages cannot be generated.")
return()
endif()
################################################################################
-# Copy doc files
-################################################################################
-set(MAN_NAMES htcp.5 les2htcp.1)
-
-set(MAN_FILES)
-foreach(_name IN LISTS MAN_NAMES)
- set(_src ${HTCP_DOC_DIR}/${_name}.txt)
- set(_dst ${CMAKE_CURRENT_BINARY_DIR}/${_name}.txt)
- add_custom_command(
- OUTPUT ${_dst}
- COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_dst}
- DEPENDS ${_src}
- COMMENT "Copy the asciidoc ${_src}"
- VERBATIM)
- list(APPEND MAN_FILES ${_dst})
-endforeach()
-add_custom_target(man-copy ALL DEPENDS ${MAN_FILES})
-
-################################################################################
# ROFF man pages
################################################################################
-set(A2X_OPTS -dmanpage -fmanpage)
-set(MAN_FILES)
+set(MAN_NAMES htcp.5 les2htcp.1)
set(MAN5_FILES)
set(MAN1_FILES)
-foreach(_name IN LISTS MAN_NAMES)
- set(_man ${CMAKE_CURRENT_BINARY_DIR}/${_name})
- set(_txt ${CMAKE_CURRENT_BINARY_DIR}/${_name}.txt)
+foreach(_man IN LISTS MAN_NAMES)
+ set(_src ${HTCP_DOC_DIR}/${_man}.scd)
add_custom_command(
OUTPUT ${_man}
- COMMAND ${A2X} ${A2X_OPTS} ${_txt}
- DEPENDS man-copy ${_txt}
- WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMAND ${SCDOC} < ${_src} > ${_man}
+ DEPENDS ${_src}
COMMENT "Build ROFF man page ${_man}"
VERBATIM)
list(APPEND MAN_FILES ${_man})
@@ -69,15 +48,13 @@ foreach(_name IN LISTS MAN_NAMES)
string(REGEX MATCH "^.*.5$" _man5 ${_man})
string(REGEX MATCH "^.*.1$" _man1 ${_man})
if(_man1)
- list(APPEND MAN1_FILES ${_man1})
+ list(APPEND MAN1_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_man1})
elseif(_man5)
- list(APPEND MAN5_FILES ${_man5})
+ list(APPEND MAN5_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_man5})
else()
message(FATAL_ERROR "Unexpected man type")
endif()
endforeach()
-add_custom_target(man-roff ALL DEPENDS ${MAN_FILES})
-
+add_custom_target(man-roff ALL DEPENDS ${MAN_NAMES})
install(FILES ${MAN1_FILES} DESTINATION share/man/man1)
install(FILES ${MAN5_FILES} DESTINATION share/man/man5)
-
diff --git a/doc/htcp.5.scd b/doc/htcp.5.scd
@@ -0,0 +1,97 @@
+htcp(5)
+
+; Copyright (C) 2018 CNRS, |Meso|Star>, 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/htcp.5.txt b/doc/htcp.5.txt
@@ -1,101 +0,0 @@
-// Copyright (C) 2018 CNRS, |Meso|Star>, 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/>.
-:toc:
-
-htcp(5)
-=======
-
-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.
-
-[verse]
--------
-<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
@@ -0,0 +1,130 @@
+les2htcp(1)
+
+; Copyright (C) 2018, 2020 |Meso|Star> (contact@meso-star.com)
+; Copyright (C) 2018 CNRS, 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 formats 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
+```
+
+# NOTES
+
+. Network Common Data Form - <https://www.unidata.ucar.edu/software/netcdf/>
+
+# COPYRIGHT
+
+Copyright © 2018, 2020 |Meso|Star> <contact@meso-star.com>.++
+Copyright © 2018 CNRS, Université Paul Sabatier
+<contact-edstar@laplace.univ-tlse.fr>.
+
+*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
+
+*htcp*(5)
diff --git a/doc/les2htcp.1.txt b/doc/les2htcp.1.txt
@@ -1,134 +0,0 @@
-// Copyright (C) 2018, 2020 |Meso|Star> (contact@meso-star.com)
-// Copyright (C) 2018 CNRS, 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/>.
-:toc:
-
-les2htcp(1)
-===========
-
-NAME
-----
-les2htcp - convert cloud properties from NetCDF to htcp(5) file format
-
-SYNOPSIS
---------
-[verse]
-*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
- dry 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 formats 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
-
-NOTES
------
-1. Network Common Data Form -
-<https://www.unidata.ucar.edu/software/netcdf/>
-
-COPYRIGHT
----------
-Copyright © 2018, 2020 |Meso|Star> <contact@meso-star.com>.
-Copyright © 2018 CNRS, Université Paul Sabatier
-<contact-edstar@laplace.univ-tlse.fr>.
-*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
---------
-*htcp*(5)
