commit 43c7ca99a61885a7c57f593d5054c15e017a61b4
parent 9ffd3fcfd882e760541ed287c8576a3cab50132f
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 15 Sep 2023 10:35:58 +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 the 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/rnsl.5.scd | | | 55 | ------------------------------------------------------- |
| A | rnsl.5 | | | 58 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 61 insertions(+), 58 deletions(-)
diff --git a/Makefile b/Makefile
@@ -87,7 +87,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" rnsl.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include/rad-net" src/rnsl.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/rnsl" COPYING README.md
-# @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rnsl.5
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" rnsl.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -95,7 +95,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnsl/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/rnsl/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/rad-net/rnsl.h"
-# rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnsl.5"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/rnsl.5"
################################################################################
# Miscellaneous targets
@@ -110,7 +110,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
-# mandoc -Tlint -Wall rnsl.5
+ mandoc -Tlint -Wall rnsl.5 || [ $$? -le 1 ]
################################################################################
# Tests
diff --git a/doc/rnsl.5.scd b/doc/rnsl.5.scd
@@ -1,55 +0,0 @@
-rnsl(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
-
-rnsl - Rad-Net String List file format
-
-# DESCRIPTION
-
-*rnsl* is a text file format that lists strings. Each string is expanded
-and therefore can be composed of variables (e.g. _"${MY_PATH}/file.txt"_)
-
-Characters behind the hash mark (#) are considered comments and are therefore
-ignored, as well as empty lines, i.e. lines without characters or composed
-only of spaces and tabs.
-
-# GRAMMAR
-
-```
-<rnsl> ::= <strings-count>
- STRING
- [ STRING ... ]
-
-<strings-count> ::= INTGER
-```
-
-# EXEMPLE
-
-```
-3
-string0
-"string 1"
-"${MY_VARIABLE}/string 2"
-```
diff --git a/rnsl.5 b/rnsl.5
@@ -0,0 +1,58 @@
+.\" 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 15, 2023
+.Dt RNSL 5
+.Os
+.Sh NAME
+.Nm rnsl
+.Nd Rad-Net String List file format
+.Sh DESCRIPTION
+.Nm
+is a text file format that lists strings.
+Each string is expanded and therefore can be composed of variables
+.Pq e.g. Pa ${MY_PATH}/file.txt .
+.Pp
+Characters behind the hash mark
+.Pq Li #
+are considered comments and are therefore ignored, as well as empty lines,
+i.e. lines without characters or composed only of spaces and tabs.
+.Pp
+The file format is as follows:
+.Bl -column (strings-count) (::=) ()
+.It Ao Va rnsl Ac Ta ::= Ta Ao Va strings-count Ac
+.It Ta Ta Va string
+.It Ta Ta Va ...
+.It Ao Va strings-count Ac Ta ::= Ta Va integer
+.El
+.Sh EXAMPLES
+.Bd -literal
+3
+string0
+"string 1"
+"${MY_VARIABLE}/string 2"
+.Ed
+.Sh HISTORY
+The
+.Nm
+format was first developed for the
+.Xr htrdr-planeto 1
+program.
