commit e0d16801808d5eab16c594fd9c94ede6899eef17
parent 6ce86d5ccb38aa98400995058738e17d7a60fbc9
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 26 Sep 2023 09:26:18 +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.
Note that several referenced htrdr-planeto 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/rngt.5.scd | | | 71 | ----------------------------------------------------------------------- |
| D | doc/rnpfi.5.scd | | | 71 | ----------------------------------------------------------------------- |
| A | rngt.5 | | | 94 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | rnpfi.5 | | | 93 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
5 files changed, 190 insertions(+), 145 deletions(-)
diff --git a/Makefile b/Makefile
@@ -132,7 +132,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" rnatm.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/rad-net" src/rnatm.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/rnatm" COPYING README.md
-# @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rngt.5 rnpfi.5
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rngt.5 rnpfi.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -140,8 +140,8 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnatm/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnatm/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/rad-net/rnatm.h"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rngt.5"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnpfi.5"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rngt.5"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnpfi.5"
################################################################################
# Miscellaneous targets
diff --git a/doc/rngt.5.scd b/doc/rngt.5.scd
@@ -1,71 +0,0 @@
-rngt(5)
-
-; Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
-; Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
-; Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
-; Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
-; Copyright (C) 2022, 2023 Observatoire de Paris
-; Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
-; Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
-; Copyright (C) 2022, 2023 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
-
-rngt - Rad-Net Gas Temperatures
-
-# DESCRIPTION
-
-*rngt* is a binary file format for storing gas temperatures. The temperatures
-are discretized according to the mesh of the gas. The mesh to which the
-temperatures are attached is _not_ described there but must be defined in a
-separate file, for example in an *smsh*(5) file. The number of temperatures and
-their order must therefore correspond to the data of the mesh to which they are
-attached, i.e. to the nodes|cells listed in the corresponding mesh.
-
-*rngt* file is actually a Star-Buffer file (see *sbuf*(5)). It starts with a
-header of 4 64-bit integers describing the layout of the data. The first integer
-is a power of two (usually 4096) that defines the size of the memory page in
-bytes to which the list of temperatures aligns (_pagesize_). The second integer
-is the _size_ of the array, i.e. the number of temperatures defined in the list.
-Finally, the 2 remaining integers store the memory size (4 bytes) and the memory
-alignment (4 bytes) of a temperature.
-
-Padding bytes follow the file header to align the listed temperatures to
-_pagesize_.
-
-The end of the file is eventually padded with dummy bytes to ensure that the
-overall file size is a multiple of _pagesize_.
-
-# BINARY FILE FORMAT
-
-Data are encoded with respect to the little endian bytes ordering, i.e. least
-significant bytes are stored first.
-
-```
-<rngt> ::= <pagesize> <size> 4 4
- <padding>
- <temperatures>
- <padding>
-
-<pagesize> ::= UINT64
-<size> ::= UINT64 # Number of temperatures stored
-<temperatures> ::= FLOAT ... # In K
-<padding> ::= [ BYTE ... ] # Ensure alignement
-```
-
-# SEE ALSO
-
-*sbuf*(5), *smsh*(5)
diff --git a/doc/rnpfi.5.scd b/doc/rnpfi.5.scd
@@ -1,71 +0,0 @@
-rnpfi(5)
-
-; Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
-; Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
-; Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
-; Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
-; Copyright (C) 2022, 2023 Observatoire de Paris
-; Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
-; Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
-; Copyright (C) 2022, 2023 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
-
-rnpfi - Rad-Net Phase Function Indices
-
-# DESCRIPTION
-
-*rnpfi* is a binary file format for storing a list of indices referring to phase
-functions. The indices are attached to a volumetric mesh which is _not_
-described there but must be defined in a separate file, for example in an
-*smsh*(5) file. The number of indices and their order must therefore correspond
-to the data of the mesh to which they are attached, i.e. to the nodes|cells
-listed in the corresponding mesh.
-
-*rnpfi* file is actually a Star-Buffer file (see *sbuf*(5)). It starts with a
-header of 4 64-bit integers describing the layout of the data. The first integer
-is a power of two (usually 4096) that defines the size of the memory page in
-bytes to which the list of indices aligns (_pagesize_). The second integer is
-the _size_ of the array, i.e. the number of indices defined in the list.
-Finally, the 2 remaining integers store the memory size (4 bytes) and the memory
-alignment (4 bytes) of an index.
-
-Padding bytes follow the file header to align the listed indices to
-_pagesize_.
-
-The end of the file is eventually padded with dummy bytes to ensure that the
-overall file size is a multiple of _pagesize_.
-
-# BINARY FILE FORMAT
-
-Data are encoded with respect to the little endian bytes ordering, i.e. least
-significant bytes are stored first.
-
-```
-<rngt> ::= <pagesize> <size> 4 4
- <padding>
- <indices>
- <padding>
-
-<pagesize> ::= UINT64
-<size> ::= UINT64 # Number of indices stored
-<indices> ::= UINT32 ...
-<padding> ::= [ BYTE ... ] # Ensure alignement
-```
-
-# SEE ALSO
-
-*sbuf*(5), *smsh*(5)
diff --git a/rngt.5 b/rngt.5
@@ -0,0 +1,94 @@
+.\" Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
+.\" Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
+.\" Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2022, 2023 Observatoire de Paris
+.\" Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
+.\" Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
+.\" Copyright (C) 2022, 2023 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 26, 2023
+.Dt RNGT 5
+.Os
+.Sh NAME
+.Nm rngt
+.Nd Rad-Net Gas Temperatures
+.Sh DESCRIPTION
+.Nm
+is a binary file format for storing gas temperatures.
+The temperatures are discretized according to the mesh of the gas.
+The mesh to which the temperatures are attached is
+.Em not
+described there but must be defined in a separate file, for example in an
+.Xr smsh 5
+file.
+The number of temperatures and their order must therefore correspond to
+the data of the mesh to which they are attached, i.e. to the nodes or
+cells listed in the corresponding mesh.
+.Pp
+A
+.Nm
+file is actually a Star-Buffer file
+.Pq see Xr sbuf 5 .
+It starts with a header of 4 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 list of temperatures are aligned.
+By aligning data to pagesize, and depending on system requirements,
+memory mapping can be used to automatically load/unload pages on demand
+.Pq see Xr mmap 2 .
+The second integer is the
+.Va size
+of the array, i.e. the number of temperatures stored in the list.
+The two remaining integers store the memory size
+.Pq 4 bytes
+and the memory alignment
+.Pq 4 bytes
+of a temperature.
+.Pp
+Padding bytes follow the file header to align the listed temperatures to
+.Va pagesize .
+.Pp
+Padding bytes are finally added at the end of the file to align its
+overall size with the size of a page.
+.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 (temperature) (::=) ()
+.It Ao Va rngt Ac Ta ::= Ta Ao Va pagesize Ac Ao Va size Ac Li 4 4
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va temperatures
+.It Ta Ta Aq Va padding
+.It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t
+.It Ao Va size Ac Ta ::= Ta Vt uint64_t
+# Number of temperatures stored
+.It Ao Va temperatures Ac Ta ::= Ta Vt float ...
+# In K
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+.El
+.Sh SEE ALSO
+.Xr mmap 2 ,
+.Xr sbuf 5 ,
+.Xr smsh 5
+.Sh HISTORY
+The
+.Nm
+format was first developed for the
+.Xr htrdr-planeto 1
+program.
diff --git a/rnpfi.5 b/rnpfi.5
@@ -0,0 +1,93 @@
+.\" Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace
+.\" Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris
+.\" Copyright (C) 2022, 2023 |Méso|Star>(contact@meso-star.com)
+.\" Copyright (C) 2022, 2023 Observatoire de Paris
+.\" Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne
+.\" Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin
+.\" Copyright (C) 2022, 2023 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 26, 2023
+.Dt RNPFI 5
+.Os
+.Sh NAME
+.Nm rnpfi
+.Nd Rad-Net Phase Function Indices
+.Sh DESCRIPTION
+.Nm
+is a binary file format for storing a list of indices referring to
+phase functions.
+The indices are attached to a volumetric mesh which is
+.Em not
+described there but must be defined in a separate file, for example in an
+.Xr smsh 5
+file.
+The number of indices and their order must therefore correspond to the
+data of the mesh to which they are attached, i.e. to the nodes or cells
+listed in the corresponding mesh.
+.Pp
+A
+.Nm
+file is actually a Star-Buffer file
+.Pq see Xr sbuf 5 .
+It starts with a header of 4 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 list of indices are aligned.
+By aligning data to pagesize, and depending on system requirements,
+memory mapping can be used to automatically load/unload pages on demand
+.Pq see Xr mmap 2 .
+The second integer is the
+.Va size
+of the array, i.e. the number of indices stored in the list.
+The two remaining integers store the memory size
+.Pq 4 bytes
+and the memory alignment
+.Pq 4 bytes
+of an index.
+.Pp
+Padding bytes follow the file header to align the listed indices to
+.Va pagesize .
+.Pp
+Padding bytes are finally added at the end of the file to align its
+overall size with the size of a page.
+.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 (pagesize) (::=) ()
+.It Ao Va rnpfi Ac Ta ::= Ta Ao Va pagesize Ac Ao Va size Ac Li 4 4
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va indices
+.It Ta Ta Aq Va padding
+.It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t
+.It Ao Va size Ac Ta ::= Ta Vt uint64_t
+# Number of indices stored
+.It Ao Va indices Ac Ta ::= Ta Vt uint32_t ...
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+.El
+.Sh SEE ALSO
+.Xr mmap 2 ,
+.Xr sbuf 5 ,
+.Xr smsh 5
+.Sh HISTORY
+The
+.Nm
+format was first developed for the
+.Xr htrdr-planeto 1
+program.
