commit c96c9a1b9138fbbc91a52114ef230347c2448e0c
parent 9d7868ca928fd30d8fe50b9bd1094f277ccd47de
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 27 Jul 2023 17:57:58 +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 | | | 2 | ++ |
| D | doc/sbuf.5.scd | | | 66 | ------------------------------------------------------------------ |
| A | sbuf.5 | | | 74 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 76 insertions(+), 66 deletions(-)
diff --git a/Makefile b/Makefile
@@ -80,6 +80,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" sbuf.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/star" src/sbuf.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/star-buffer" COPYING README.md
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" sbuf.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -87,6 +88,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-buffer/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-buffer/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/star/sbuf.h"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/sbuf.5"
################################################################################
# Miscellaneous targets
diff --git a/doc/sbuf.5.scd b/doc/sbuf.5.scd
@@ -1,66 +0,0 @@
-sbuf(5)
-
-; Copyright (C) 2022, 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
-
-sbuf - Star-Buffer file format
-
-# DESCRIPTION
-
-*sbuf* is a binary file format for storing data in a 1-dimensional array.
-
-A *sbuf* file begins with a header of four 64-bits integers. The first integer
-is a power of two (usually 4096) that defines the size of the memory page in
-bytes (_pagesize_) on wich the array is aligned. By aligning the array on
-_pagesize_, and depending on system requirements, memory mapping can be used to
-automatically load/unload the array items on demand (see *mmap*(2)). The second
-integer is the _size_ of the array. Finally, the 2 remaining integers store the
-memory size and the memory alignment of each array element.
-
-Fill bytes follow the file header to align the array to _pagesize_. The array
-elements are then listed. Fill bytes are finally added to ensure that the
-overall file size is a multiple of _pagesize_.
-
-# BINARY FILE
-
-Data are encoded with respect to the little endian bytes ordering, i.e. least
-significant bytes are stored first.
-
-```
-<sbuf> ::= <pagesize> <size> <szitem> <alitem>
- <padding>
- <list>
- <padding>
-
-<pagesize> ::= UINT64
-<size> ::= UINT64 # Number of items stored
-<szitem> ::= UINT64 # Size of an item in bytes
-<alitem> ::= UINT64 # Alignment of an item (must be <= pagesize)
-
----
-
-<list> ::= <element> <padding> [ <element> <padding> ]...
-<element> ::= BYTE [ BYTE ... ]
-
----
-
-<padding> ::= [ BYTE ... ] # Ensure alignement
-```
-
-# SEE ALSO
-
-*mmap*(2)
diff --git a/sbuf.5 b/sbuf.5
@@ -0,0 +1,74 @@
+.\" Copyright (C) 2022, 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 27, 2023
+.Dt SBUF 5
+.Os
+.Sh NAME
+.Nm sbuf
+.Nd Star-Buffer file format
+.Sh DESCRIPTION
+.Nm
+is a binary file format for storing data in a 1-dimensional array.
+.Pp
+A
+.Nm
+file begins with a header of four 64-bits 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 wich the array is aligned.
+By aligning the array on
+.Va pagesize ,
+and depending on system requirements, memory mapping can be used to
+automatically load/unload the array items on demand
+.Pq see Xr mmap 2 .
+The second integer is the
+.Va size
+of the array.
+Finally, the 2 remaining integers store the memory size and the memory
+alignment of each array element.
+.Pp
+Fill bytes follow the file header to align the array to
+.Va pagesize .
+The array elements are then listed.
+Fill bytes are finally added to ensure that the overall file size is a multiple
+of
+.Va pagesize .
+.Pp
+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 sbuf Ac Ta ::= Ta Ao Va pagesize Ac Ao Va size Ac Ao Va szitem Ac Ao Va alitem Ac
+.It Ta Ta Aq Va padding
+.It Ta Ta Aq Va list
+.It Ta Ta Aq Va padding
+.It Ta Ta
+.It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t
+.It Ao Va size Ac Ta ::= Ta Vt uint64_t
+# Number of items stored
+.It Ao Va szitem Ac Ta ::= Ta Vt uint64_t
+# Size of an item in bytes
+.It Ao Va alitem Ac Ta ::= Ta Vt uint64_t
+# Alignement of an item (<= pagesize)
+.It Ta Ta
+.It Ao Va list Ac Ta ::= Ta Ao Va element Ac Va ...
+.It Ao Va element Ac Ta ::= Ta Ao Va item Ac Ao Va padding Ac
+.It Ao Va item Ac Ta ::= Ta Vt char ...
+.It Ta Ta
+.It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ...
+.El
+.Sh SEE ALSO
+.Xr mmap 2
