commit 3146d06527698bf385c0bb7d85b995fcb03aacb3
parent 7b94f19b895fc649084971efbf58f0727202e8ab
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 30 Aug 2023 15:47:40 +0200
Translate scdoc man page 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.
Diffstat:
| M | Makefile | | | 3 | +++ |
| A | atrri.5 | | | 70 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | doc/atrri.5.scd | | | 65 | ----------------------------------------------------------------- |
3 files changed, 73 insertions(+), 65 deletions(-)
diff --git a/Makefile b/Makefile
@@ -81,6 +81,7 @@ install: build_library pkg
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/lib/pkgconfig" atrri.pc
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/include" src/atrri.h
@$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/doc/atrri" COPYING README.md
+ @$(SHELL) make.sh install "$(DESTDIR)$(PREFIX)/share/man/man5" atrri.5
uninstall:
rm -f "$(DESTDIR)$(PREFIX)/lib/$(LIBNAME)"
@@ -88,6 +89,7 @@ uninstall:
rm -f "$(DESTDIR)$(PREFIX)/share/doc/atrri/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/atrri/README.md"
rm -f "$(DESTDIR)$(PREFIX)/include/atrri.h"
+ rm -f "$(DESTDIR)$(PREFIX)/share/man/man5/atrri.5"
################################################################################
# Miscellaneous targets
@@ -102,6 +104,7 @@ distclean: clean
lint:
shellcheck -o all make.sh
+ mandoc -Tlint -Wall atrri.5
################################################################################
# Tests
diff --git a/atrri.5 b/atrri.5
@@ -0,0 +1,70 @@
+.\" Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 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 ATRRI 5
+.Os
+.Sh NAME
+.Nm atrri
+.Nd AsToRia: Refractive Index
+.Sh DESCRIPTION
+.Nm
+is a plain text file format for storing a list of refractive indices
+that vary spectrally.
+Each refractive index is defined by 3 double precision
+floating point numbers: the wavelength in nanometers at which the index is
+set, followed by the real part and the imaginary part of the refractive index
+itself.
+Note that the listed refractive indices should be sorted in ascending
+order relative to their wavelength.
+.Pp
+Characters behind the pound sign
+.Pq Li #
+are considered comments and are therefore
+ignored.
+Empty lines, that is, lines without characters or consisting solely of
+spaces and tabs, are simply ignored.
+.Pp
+The file format is as follows:
+.Bl -column (refractive-index) (::=) ()
+.It Ao Va atrri Ac Ta ::= Ta Ao Va refractive-index Ac
+.It Ta Ta Va ...
+.It Ao Va refractive-index Ac Ta ::= Ta
+.Aq Va wavelength
+.Aq Va n
+.Aq Va kappa
+.It Ao Va wavelength Ac Ta ::= Ta Ao Va real Ac
+# In nm
+.It Ao Va n Ac Ta ::= Ta Ao Va real Ac
+# Real part
+.It Ao Va kappa Ac Ta ::= Ta Ao Va real Ac
+# Imaginary part
+.El
+.Sh EXAMPLES
+.Bd -literal
+# Wavelength in nm real part imaginary part
+
+300.000011921 1.740000010 0.469999999
+310.000002384 1.741990328 0.469004273
+319.999992847 1.743917465 0.468010038
+329.999983311 1.745785475 0.467014253
+339.999973774 1.748130083 0.465993971
+349.999964237 1.750000000 0.464985400
+359.999954700 1.750000000 0.463959038
+369.999945164 1.750000000 0.462961257
+379.999935627 1.750000000 0.461990029
+389.999926090 1.750000000 0.460981935
+399.999916553 1.750000000 0.459957659
+.Ed
diff --git a/doc/atrri.5.scd b/doc/atrri.5.scd
@@ -1,65 +0,0 @@
-atrri(5)
-
-; Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com)
-; Copyright (C) 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
-
-atrri - AsToRia: Refractive Index
-
-# DESCRIPTION
-
-*atrri* is a plain text file format for storing a list of refractive indices
-that vary spectrally. Each refractive index is defined by 3 double precision
-floating point numbers: the wavelength in nanometers at which the index is
-set, followed by the real part and the imaginary part of the refractive index
-itself. Note that the listed refractive indices should be sorted in ascending
-order relative to their wavelength.
-
-Characters behind the pound sign (#) are considered comments and are therefore
-ignored. Empty lines, that is, lines without characters or consisting only of
-spaces and tabs, are simply skipped.
-
-# GRAMMAR
-
-```
-<atrri> ::= <refractive-index>
- [ <refractive-index> ... ]
-
-<refractive-index> ::= <wavelength> <n> <kappa>
-
-<wavelength> ::= <double> # In nm
-<n> ::= <double> # Real part
-<kappa> ::= <double> # Imaginary part
-```
-
-# EXAMPLE
-
-```
-# Wavelength in nm real part imaginary part
-
- 300.000011921 1.740000010 0.469999999
- 310.000002384 1.741990328 0.469004273
- 319.999992847 1.743917465 0.468010038
- 329.999983311 1.745785475 0.467014253
- 339.999973774 1.748130083 0.465993971
- 349.999964237 1.750000000 0.464985400
- 359.999954700 1.750000000 0.463959038
- 369.999945164 1.750000000 0.462961257
- 379.999935627 1.750000000 0.461990029
- 389.999926090 1.750000000 0.460981935
- 399.999916553 1.750000000 0.459957659
-```
