doc/gray.1 generate from gray --help

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

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;
       })

doc/gray.1

@@ -1,47 +1,40 @@
-.TH GRAY 1
+[INPUT FILES]
-.SH NAME
+All files used by \fBgray\fR are only named by convention since their filenames
-gray \- A quasi-optical beam-tracing code for EC waves in tokamaks
+must be manually specified, except the parameters file.
-.SH SYNOPSIS
+The latter defaults to \fCgray_params.data\fR and is configured using the
-.B gray
+\fB-p\fR option. All other filepaths are relative to its parent directory.
-[\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
 .TP
-\fB\-h, \-\-help\fR
+.I gray_params.data
-Display help and exit
+Parameters file
+
+This file allows configuring all the parameters of a GRAY simulation, including
+all other input files.
 .TP
-\fB\-n, \-\-no-output\fR
+.I beamdata.txt
-Suppress output files
+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
+.I magneticdata.eqdsk
-Set the parameters file name (default \fIfilename\fR=gray_params.data)
+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
+.I profiles.txt
-Quiet mode.
+Plasma kinetic profiles file
-Suppress all messages on standard output
+
-.TP
+This file contains the radial profiles of the plasma temperature, density and
-\fB\-v, \-\-verbose\fR
+effective charge.
-Verbose mode.
+
-Additional information messages on standard output
+[OUTPUT FILES]
-.TP
+GRAY output files are named according to the Fortran unit number (e.g
-\fB\-V, \-\-version\fR
+\fCfort.4\fR) and written to the current directory, by default. The
-Display version information and exit
+location can be changed with the \fB-o\fR option.
-.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.
+For a list of the unit numbers and their descriptions see the GRAY user manual.
-.SH AUTHOR
+
-Daniela Farina, Lorenzo Figini.
+[SEE ALSO]
-Istituto per la Scienza e Tecnologia dei Plasmi - CNR Milano, Italy
+\fBgray_params.data\fR(5), \fBbeamdata.txt\fR(5), \fBprofiles.txt\fR(5)
-.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 ...