From 9a39251f444f0bbf96449250a5e758b9988e2dba Mon Sep 17 00:00:00 2001
From: Michele Guerini Rocco <m.guerinirocco2@campus.unimib.it>
Date: Wed, 15 Dec 2021 02:31:17 +0100
Subject: [PATCH] doc/gray.1 generate from gray --help

---
 Makefile    | 10 +++++--
 default.nix |  3 +-
 doc/gray.1  | 79 ++++++++++++++++++++++++-----------------------------
 3 files changed, 45 insertions(+), 47 deletions(-)

diff --git a/Makefile b/Makefile
index d13e711..c0d6762 100644
--- a/Makefile
+++ b/Makefile
@@ -93,12 +93,12 @@ clean:
 	rm -r $(BUILDDIR)
 
 # Install libraries, binaries and documentation
-install: $(BINARIES) $(LIBRARIES) doc/gray.1
+install: $(BINARIES) $(LIBRARIES) $(SHAREDIR)/gray.1
 	install -Dm555 -t $(PREFIX)/bin $(BINDIR)/*
 	install -Dm555 -t $(PREFIX)/lib $(LIBDIR)/*
 	install -Dm644 -t $(PREFIX)/share/doc $(SHAREDIR)/doc/manual.*
 	install -Dm644 -t $(PREFIX)/share/doc/res $(SHAREDIR)/doc/res/*
-	install -Dm644 -t $(PREFIX)/share/man/man1 doc/gray.1
+	install -Dm644 -t $(PREFIX)/share/man/man1 $(SHAREDIR)/*.1
 
 # GRAY binary
 $(GRAY): $(shell ./depend $(OBJDIR)/main.o) | $(BINDIR)
@@ -114,9 +114,13 @@ $(LIBGRAY).a: $(LIBGRAY).a($(MODULES))
 
 # All documentation
 docs: | $(SHAREDIR)
-	make -C doc
+	+make -C doc
 	cp -t $(SHAREDIR) -r doc/build/*
 
+# Generated man pages
+$(SHAREDIR)/gray.1: $(GRAY) doc/gray.1 | $(SHAREDIR)
+	help2man '$<' -i doc/gray.1 -N -n 'beam-tracing code for EC waves' > '$@'
+
 # Visualise the dependency graph
 # Note: requires makefile2graph and graphviz
 graph.svg: Makefile
diff --git a/default.nix b/default.nix
index 2b6d8f7..7c3a728 100644
--- a/default.nix
+++ b/default.nix
@@ -36,7 +36,8 @@ in
       makefile2graph graphviz
 
       # documentation
-      pandoc haskellPackages.pandoc-crossref
+      help2man pandoc
+      haskellPackages.pandoc-crossref
       (texlive.combine {
         inherit (texlive) scheme-small xetex fontspec;
       })
diff --git a/doc/gray.1 b/doc/gray.1
index 97da05c..b02a970 100644
--- a/doc/gray.1
+++ b/doc/gray.1
@@ -1,47 +1,40 @@
-.TH GRAY 1
-.SH NAME
-gray \- A quasi-optical beam-tracing code for EC waves in tokamaks
-.SH SYNOPSIS
-.B gray
-[\fB\-hnqvV\fR]
-[\fB\-p\fR \fIparam\-file\fR]
-[\fIoutput\-dir\fR]
-.SH DESCRIPTION
-GRAY is a quasi-optical beam-tracing code for Electron Cyclotron Gaussian beams in tokamak plasmas.
-It computes wave absorption with a fully-relativistic formulation and current drive including momentum conservation.
-.SH OPTIONS
+[INPUT FILES]
+All files used by \fBgray\fR are only named by convention since their filenames
+must be manually specified, except the parameters file.
+The latter defaults to \fCgray_params.data\fR and is configured using the
+\fB-p\fR option. All other filepaths are relative to its parent directory.
+
 .TP
-\fB\-h, \-\-help\fR
-Display help and exit
+.I gray_params.data
+Parameters file
+
+This file allows configuring all the parameters of a GRAY simulation, including
+all other input files.
 .TP
-\fB\-n, \-\-no-output\fR
-Suppress output files
+.I beamdata.txt
+Beam description file
+
+This file contains the the description of the EC beam and additional parameters
+of the wave launcher.
 .TP
-\fB\-p \fIfilename\fB, \-\-param\-file\fR=\fIfilename\fR
-Set the parameters file name (default \fIfilename\fR=gray_params.data)
+.I magneticdata.eqdsk
+MHD equilibrium description file
+
+This file is contains the description of the tokamak MHD equilibrium in the
+standard G-EQDSK format.
 .TP
-\fB\-q, \-\-quiet\fR
-Quiet mode.
-Suppress all messages on standard output
-.TP
-\fB\-v, \-\-verbose\fR
-Verbose mode.
-Additional information messages on standard output
-.TP
-\fB\-V, \-\-version\fR
-Display version information and exit
-.SH EXIT STATUS
-0 on success, 1 if an error occurred while reading the inputs or writing the outputs, 2 if an error occurred during the simulation.
-.SH AUTHOR
-Daniela Farina, Lorenzo Figini.
-Istituto per la Scienza e Tecnologia dei Plasmi - CNR Milano, Italy
-.PP
-The reference paper for the code is
-.PP
-.nf
-.RS
-D. Farina, Fusion Sci. Technol. 52 (2007) 154\-160
-.RE
-.fi
-.SH SEE ALSO
-The full documentation for the code is available at ...
+.I profiles.txt
+Plasma kinetic profiles file
+
+This file contains the radial profiles of the plasma temperature, density and
+effective charge.
+
+[OUTPUT FILES]
+GRAY output files are named according to the Fortran unit number (e.g
+\fCfort.4\fR) and written to the current directory, by default. The
+location can be changed with the \fB-o\fR option.
+
+For a list of the unit numbers and their descriptions see the GRAY user manual.
+
+[SEE ALSO]
+\fBgray_params.data\fR(5), \fBbeamdata.txt\fR(5), \fBprofiles.txt\fR(5)