commit 9155f498b62f63c6c679389c7ff0e60612ae2815
parent feb5f109ece528d55135823b5a198d24d2e7631b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 27 Jul 2023 10:51:57 +0200
Write the manual using mdoc's roff macros
Removes the scdoc dependency used to generate the man page from the
intermediate scdoc file format. Note that if mandoc becomes a new
dependency, it is very often installed, if not always on UNIX systems.
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 | .gitignore | | | 1 | - |
| M | Makefile | | | 11 | ++++------- |
| M | README.md | | | 2 | +- |
| D | doc/smsh.5.scd | | | 82 | ------------------------------------------------------------------------------- |
| A | smsh.5 | | | 98 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
5 files changed, 103 insertions(+), 91 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -10,4 +10,3 @@ test*
.test
tags
*.pc
-smsh.5
diff --git a/Makefile b/Makefile
@@ -58,10 +58,6 @@ $(LIBNAME_STATIC): $(OBJ)
.c.o:
$(CC) $(CFLAGS) $(RSYS_CFLAGS) -DSMSH_SHARED_BUILD -c $< -o $@
-smsh.5: doc/smsh.5.scd
- command -v scdoc > /dev/null || exit 1
- scdoc < doc/$@.scd > $@
-
################################################################################
# Installation
################################################################################
@@ -80,7 +76,7 @@ smsh-local.pc: smsh.pc.in
-e 's#@RSYS_VERSION@#$(RSYS_VERSION)#g'\
smsh.pc.in > $@
-install: build_library pkg smsh.5
+install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib" $(LIBNAME)
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" smsh.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/star" src/smsh.h
@@ -98,10 +94,10 @@ uninstall:
################################################################################
# Miscellaneous targets
################################################################################
-all: build_library build_tests smsh.5
+all: build_library build_tests
clean: clean_test
- rm -f $(OBJ) $(TEST_OBJ) $(LIBNAME) .config .test smsh.5 smsh.pc smsh-local.pc
+ rm -f $(OBJ) $(TEST_OBJ) $(LIBNAME) .config .test smsh.pc smsh-local.pc
rm -f test_file.smsh
distclean: clean
@@ -109,6 +105,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
+ mandoc -T lint -Wbase smsh.5
################################################################################
# Tests
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ See smsh.5 for details.
- POSIX make
- pkg-config
- [RSys](https://gitlab.com/vaplv/rsys)
-- [scdoc](https://git.sr.ht/~sircmpwn/scdoc)
+- [mandoc](https://mandoc.bsd.lv) (optional)
## Installation
diff --git a/doc/smsh.5.scd b/doc/smsh.5.scd
@@ -1,82 +0,0 @@
-smsh(5)
-
-; Copyright (C) 2020-2023 |Méso|Star> (contact@meso-star.com)
-;
-; 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
-
-smsh - Star-Mesh file format
-
-# DESCRIPTION
-
-*smsh* is a binary file format that describes an indexed mesh (surface or
-volume). Only the geometric data of the mesh is stored; no additional properties
-are attached to its nodes or cells.
-
-A *smsh* file begins with a header that describes the layout of the data,
-followed by the geometric data itself, i.e. the list of nodes and the list of
-cells.
-
-The header consists of 5 integers. The first integer is a power of two (usually
-4096) that defines the size of the memory page in bytes (_pagesize_) on which
-the list of nodes and the list of cells are aligned. By aligning data to
-_pagesize_, and depending on system requirements, memory mapping can be used to
-automatically load/unload pages on demand (see *mmap*(2)). The remaining
-integers store the number of nodes (_#nodes_) and the number of cells
-(_#cells_), followed by the size of a node (_dimnode_) and the size of a cell
-(_dimcell_), respectively.
-
-Fill bytes follow the file header to align nodes to _pagesize_. The nodes are
-then listed with a list of _#nodes_ _dimnode_ double-precision floating-point
-numbers per node, where _#nodes_ is the number of mesh nodes and _dimnode_ is
-the number of floating-point numbers per node. Additional fill bytes are added
-after the node list to align the list of upcoming cells to _pagesize_. The cells
-are then listed using _dimcell_ 64-bit signed integers per node where each integer
-indexes a node in the previously defined list of nodes (indexing starts at 0).
-Finally, fill bytes are added 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.
-
-```
-<smsh> ::= <pagesize> <#nodes> <#cells> <dimnode> <dimcell>
- <padding>
- <nodes>
- <padding>
- <cells>
- <padding>
-<pagesize> ::= UINT64
-<#nodes> ::= UINT64
-<#cells> ::= UINT64
-<dimnode> ::= UINT32
-<dimcell> ::= UINT32
-
-<padding> ::= [ BYTE ... ]
-
-<nodes> ::= <node-pos>
- [ <node-pos> ... ]
-
-<cells> ::= <cell-ids>
- [ <cell-ids> ... ]
-
-<node-pos> ::= DOUBLE ...
-<cell-ids> ::= UINT64 ...
-```
-
-# SEE ALSO
-
-*mmap*(2)
diff --git a/smsh.5 b/smsh.5
@@ -0,0 +1,98 @@
+.\" Copyright (C) 2020-2023 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" 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 July 26, 2023
+.Dt SMSH 5
+.Os
+.Sh NAME
+.Nm smsh
+.Nd Star-Mesh file format
+.Sh DESCRIPTION
+.Nm
+is a binary file format that describes an indexed mesh
+.Pq surface or volume .
+Only the geometric data of the mesh is stored; no additional properties are
+attached to its nodes or cells.
+.Pp
+A
+.Nm
+file begins with a header that describes the layout of the data, followed by
+the geometric data itself, i.e. the list of nodes and the list of cells.
+.Pp
+The header consists of 5 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 nodes and the list of cells 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 remaining integers store the number of nodes
+.Pq Va #nodes
+and the number of cells
+.Pq Va #cells ,
+followed by the size of a node
+.Pq Va dimnode
+and the size of a cell
+.Pq Va dimcell ,
+respectively.
+.Pp
+Fill bytes follow the file header to align nodes to
+.Va pagesize .
+The nodes are then listed with a list of
+.Va #nodes dimnode
+double-precision floating-point numbers per node, where
+.Va #nodes
+is the number
+of mesh nodes and
+.Va dimnode
+is the number of floating-point numbers per node.
+Additional fill bytes are added after the node list to align the list of
+upcoming cells to
+.Va pagesize .
+The cells are then listed using
+.Va dimcell
+64-bit unsigned integers per node where each
+integer indexes a node in the previously defined list of nodes
+.Pq indexing starts at 0 .
+Finally, fill bytes are added to align the overall file size to
+.Va pagesize .
+.Sh BINARY FILE FORMAT
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+.Bl -column (pagesize) (::=) ()
+.It Ao Va smsh Ac Ta ::= Ta Ao Va pagesize Ac Ao Va #nodes Ac Ao Va #cells Ac Ao Va dimnode Ac Ao Va dimcel Ac
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va nodes
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va cells
+.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 Ao Va #cells Ac Ta ::= Ta Vt uint64_t
+.It Ao Va dimnode Ac Ta ::= Ta Vt uint32_t
+.It Ao Va dimcell Ac Ta ::= Ta Vt uint32_t
+.It Ta Ta
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+.It Ta Ta
+.It Ao Va nodes Ac Ta ::= Ta Ao Va node-pos Ac Va ...
+.It Ao Va cells Ac Ta ::= Ta Ao Va cell-ids Ac Va ...
+.It Ao Va node-pos Ac Ta ::= Ta Vt double ...
+.It Ao Va cell-ids Ac Ta ::= Ta Vt uint64_t ...
+.El
+.Sh SEE ALSO
+.Xr mmap 2
