commit 0993403b7f2bb7e5236e267aad93481dc742329f
parent 22bc0b5a0c75d8008d7ce5c3fcbb50f7017cef4c
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 30 Aug 2023 17:14:44 +0200
Translate scdoc man page into mdoc'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.
Diffstat:
| M | Makefile | | | 3 | +++ |
| A | atrtp.5 | | | 120 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | doc/atrtp.5.scd | | | 97 | ------------------------------------------------------------------------------- |
3 files changed, 123 insertions(+), 97 deletions(-)
diff --git a/Makefile b/Makefile
@@ -81,6 +81,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" atrtp.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include" src/atrtp.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/atrtp" COPYING README.md
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" atrtp.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -88,6 +89,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/atrtp/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/atrtp/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/atrtp.h"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/atrtp.5"
################################################################################
# Miscellaneous targets
@@ -102,6 +104,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
+ mandoc -Tlint -Wall atrtp.5
################################################################################
# Tests
diff --git a/atrtp.5 b/atrtp.5
@@ -0,0 +1,120 @@
+.\" Copyright (C) 2020-2023 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2020, 2021 Centre National de la Recherche Scientifique
+.\"
+.\" 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 August 30, 2023
+.Dt ATRTP 5
+.Os
+.Sh NAME
+.Nm atrtp
+.Nd AsToRia: Thermodynamic Properties
+.Sh DESCRIPTION
+.Nm
+is a binary file format to store a set of thermodynamic porperties for each
+node of a volumetric mesh representing a medium in combustion.
+An
+.Nm
+file begins by a header that describes the data layout followed by a list of
+per node properties.
+.Pp
+The header consist of 2 integers.
+The first integer is a power of two
+.Pq usually 4096
+that defines the size of the memory page in bytes
+.Pq Va pagesize
+on which the thermodynamic properties are aligned.
+By aligning data to
+.Va pagesize ,
+and depending on system requirements, memory mapping can be used to
+automatically load/unload pages on demand
+.Pq see Xr mmap 2 .
+The other integer stores the number of elements in the list.
+In the following, we'll call it
+.Va #nodes ,
+for "number of nodes", in reference to the mesh nodes to which these properties
+will be attached.
+.Pp
+Fill bytes follow the file header to align thermodynamic
+properties to
+.Va pagesize .
+Properties are then listed with 8 double-precision floating-point numbers per
+element (i.e. per node).
+The data per node are as follows:
+.Bl -dash -offset indent -compact
+.It
+The pressure in Pascal
+.It
+The temperature in Kelvin
+.It
+The molar fraction of H2O in mol(H2O)/mol(mixture)
+.It
+The molar fraction of CO2 in mol(CO2)/mol(mixture)
+.It
+The molar fraction of CO in mol(CO)/mol(mixture)
+.It
+The volumic fraction of soot in m^3(soot)/m^3
+.It
+The number of soot primary particules per agregate
+.It
+The soot primary particles diameter in nm
+.El
+.Pp
+Finally, fill bytes are added to align the overall file size to
+.Va pagesize .
+.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 (thermo-props) (::=) ()
+.It Ao Va atrtp Ac Ta ::= Ta Ao Va pagesize Ac Ao Va #nodes Ac
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va thermo-props
+.It Ta Ta Aq Va padding
+.It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t
+.It Ao Va #nodes Ac Ta ::= Ta Vt uint64_t
+.It \ Ta Ta
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+# Ensure alignment on
+.Va pagesize
+.It \ Ta Ta
+.It Ao Va thermo-props Ac Ta ::= Ta Ao Va thermo-prop Ac Va ...
+.It Ao Va thermo-prop Ac Ta ::= Ta Ao Va pressure Ac
+# In Pascal
+.It Ta Ta Ao Va temperature Ac
+.It Ta Ta Ao Va xH2O Ac # Molar fraction of H2O
+.It Ta Ta Ao Va xCO2 Ac # Molar fraction of CO2
+.It Ta Ta Ao Va xCO Ac # Molar fraction of CO
+.It Ta Ta Ao Va vf-soot Ac # Volumic fraction of soot
+.It Ta Ta Ao Va np-soot Ac # Soot particles per agregate
+.It Ta Ta Ao Va dp-soot Ac # Soot particles diameter
+.It \ Ta Ta
+.It Ao Va pressure Ac Ta ::= Ta Vt double
+# In Pascal
+.It Ao Va temperature Ac Ta ::= Ta Vt double
+# In Kelvin
+.It Ao Va xH2O Ac Ta ::= Ta Vt double
+# In mol(H2O)/mol(mixture)
+.It Ao Va xCO2 Ac Ta ::= Ta Vt double
+# In mol(CO2)/mol(mixture)
+.It Ao Va xCO Ac Ta ::= Ta Vt double
+# In mol(CO)/mol(mixture)
+.It Ao Va vf-soot Ac Ta ::= Ta Vt double
+# In m^3(soot)/m^3
+.It Ao Va np-soot Ac Ta ::= Ta Vt double
+.It Ao Va dp-soot Ac Ta ::= Ta Vt double
+# In nm
+.El
+.Sh SEE ALSO
+.Xr mmap 2
diff --git a/doc/atrtp.5.scd b/doc/atrtp.5.scd
@@ -1,97 +0,0 @@
-atrtp(5)
-
-; Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
-; Copyright (C) 2020, 2021 CNRS
-;
-; 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
-
-atrtp - AsToRia: Thermodynamic Properties
-
-# DESCRIPTION
-
-*atrtp* is a binary file format to store a set of thermodynamic porperties for
-each node a volumetric mesh representing a medium in combustion. An *atrtp*
-file begins by a header that describes the data layout followed by a list of
-per node properties.
-
-The header is made up of 2 64-bit integers. The first integer is a power of
-two (usually 4096) that defines the _<pagesize>_ in bytes to which the
-thermodynamic properties are aligned. The remaining integer store the number
-of items in the list. In the following grammar, we name it _<#nodes>_, for
-"number of nodes", in reference to the mesh nodes to which these properties
-would be attached.
-
-Note that by aligning the thermodynamic data to _<pagesize>_, and depending on
-the system requirements, memory mapping can be used to automatically
-load/unload those data on demand (see for example the POSIX C function
-*mmap*(2)).
-
-Padding bytes follow the file header to ensure alignment of the thermodynamic
-properties to _<pagesize>_. These properties are then listed with 8 double
-precision floating point numbers per item (i.e. per node). The set of per node
-data are:
-
-- The pressure in Pascal
-- The temperature in Kelvin
-- The molar fraction of H20 in mol(H20)/mol(mixture)
-- The molar fraction of CO2 in mol(CO2)/mol(mixture)
-- The molar fraction of CO in mol(CO)/mol(mixture)
-- The volumic fraction of soot in m^3(soot)/m^3
-- The number of soot primary particules per agregate
-- The soot primary particles diameter in nm
-
-Finally, additional padding bytes are added after the listed properties to
-align the overall file size to _<pagesize>_.
-
-# BINARY FILE FORMAT
-
-Data are encoded with respect to the little endian bytes ordering, i.e. least
-significant bytes are stored first.
-
-```
-<atrtp> ::= <pagesize> <#nodes>
- <padding>
- <thermo-props>
- <padding>
-
-<pagesize> ::= INT64
-<#cells> ::= INT64
-<padding> ::= [ BYTE ... ]
-
-<thermo-props> ::= <thermo-prop>
- [ <thermo-prop ... ]
-<therm-prop> ::= <pressure>
- <temperature>
- <xH2O>
- <xCO2>
- <xCO>
- <vf-soot>
- <np-soot>
- <dp-soot>
-
-<pressure> ::= <double> # Pressure in Pa
-<temperature> ::= <double> # Temperature in K
-<xH2O> ::= <double> # Molar fraction of H2O in mol(H2O)/mol(mixture)
-<xCO2> ::= <double> # Molar fraction of CO2 in mol(CO2)/mol(mixture)
-<xCO> ::= <double> # Molar fraction of CO in mol(CO)/mol(mixture)
-<vf-soot> ::= <double> # Volumic fraction of soot in m^3(soot)/ m^3
-<np-soot> ::= <double> # Number of primary particles per agregate
-<dp-soot> ::= <double> # Primary particles diameter in nm
-```
-
-# SEE ALSO
-
-*mmap*(2)
