commit 79054702ca9982fd2ab718a2f917e4726df8c1cf
parent 04fc6e940e71212626127f68503f70da3a225ed2
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 13 Nov 2018 15:20:13 +0100
Write the htcp man page
Diffstat:
3 files changed, 187 insertions(+), 0 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -58,6 +58,7 @@ endif()
################################################################################
# Sub projects
################################################################################
+add_subdirectory(doc)
add_subdirectory(htcp)
add_subdirectory(les2htcp)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -0,0 +1,82 @@
+# Copyright (C) 2018 CNRS, Université Paul Sabatier, |Meso|Star>
+#
+# 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/>.
+
+set(HTCP_DOC_DIR ${PROJECT_SOURCE_DIR}/../doc)
+
+################################################################################
+# Look for the a2x program
+################################################################################
+find_program(A2X NAMES a2x a2x.py)
+if(NOT A2X)
+ message(WARNING
+ "The `a2x' program is missing. "
+ "The htrdr man pages cannot be generated.")
+ return()
+endif()
+
+################################################################################
+# Copy doc files
+################################################################################
+set(MAN_NAMES htcp.5)
+
+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(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)
+
+ add_custom_command(
+ OUTPUT ${_man}
+ COMMAND ${A2X} ${A2X_OPTS} ${_txt}
+ DEPENDS man-copy ${_txt}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Build ROFF man page ${_man}"
+ VERBATIM)
+ list(APPEND MAN_FILES ${_man})
+
+ string(REGEX MATCH "^.*.5$" _man5 ${_man})
+ string(REGEX MATCH "^.*.1$" _man1 ${_man})
+ if(_man1)
+ list(APPEND MAN1_FILES ${_man1})
+ elseif(_man5)
+ list(APPEND MAN5_FILES ${_man5})
+ else()
+ message(FATAL_ERROR "Unexpected man type")
+ endif()
+endforeach()
+add_custom_target(man-roff ALL DEPENDS ${MAN_FILES})
+
+install(FILES ${MAN1_FILES} DESTINATION share/man/man1)
+install(FILES ${MAN5_FILES} DESTINATION share/man/man5)
+
diff --git a/doc/htcp.5.txt b/doc/htcp.5.txt
@@ -0,0 +1,104 @@
+// Copyright (C) 2018 CNRS, Université Paul Sabatier, |Meso|Star>
+//
+// 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 resulting of a Large Eddy
+Simulation and saved in a Meso-NH like NetCDF file format [1].
+
+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 cell sizes of each cell in Z are explicitly listed in _<voxel-size>_.
+
+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>_: potential 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 ... ] # Potential temperature
+
+<padding> ::= [ BYTE ... ]
+-------
+
+NOTES
+-----
+1. Meso-NH - <http://mesonh.aero.obs-mip.fr/mesonh54/Welcome>
+
+SEE ALSO
+--------
+*les2htcp*(1)
