From c4e9d9a66f6fc0eba0e5ca8d093b8feac1eabb57 Mon Sep 17 00:00:00 2001
From: Daichi Fukui <when.a.cat.sits.beside.you@gmail.com>
Date: Sun, 26 Jan 2025 02:27:10 +0000
Subject: [PATCH] doc/man: Add man pages jsonnet.1 and jsonnetfmt.1

This commit adds man pages for the jsonnet and jsonnetfmt commands.
The Debian Lintian quality checker warns that each binary should have
a manual page, but hopefully this idea would also apply to non-Debian users.
These man pages are created using the help2man command, so the contents are
substantially the same as the output of the help option.
---
 CMakeLists.txt         |  5 +++
 doc/man/CMakeLists.txt |  2 +
 doc/man/jsonnet.1      | 97 ++++++++++++++++++++++++++++++++++++++++++
 doc/man/jsonnetfmt.1   | 70 ++++++++++++++++++++++++++++++
 4 files changed, 174 insertions(+)
 create mode 100644 doc/man/CMakeLists.txt
 create mode 100644 doc/man/jsonnet.1
 create mode 100644 doc/man/jsonnetfmt.1

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 77331f6f..44717359 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -46,6 +46,11 @@ endif()
 set(CMAKE_CXX_STANDARD 17)
 
 
+# Manuals
+add_subdirectory(doc/man)
+install(FILES doc/man/jsonnet.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+install(FILES doc/man/jsonnetfmt.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+
 # Include external googletest project. This runs a CMake sub-script
 # (CMakeLists.txt.in) that downloads googletest source. It's then built as part
 # of the jsonnet project. The conventional way of handling CMake dependencies is
diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt
new file mode 100644
index 00000000..86f2324c
--- /dev/null
+++ b/doc/man/CMakeLists.txt
@@ -0,0 +1,2 @@
+install(DIRECTORY man1/ DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
+                FILES_MATCHING PATTERN "*.1")
diff --git a/doc/man/jsonnet.1 b/doc/man/jsonnet.1
new file mode 100644
index 00000000..d82f79db
--- /dev/null
+++ b/doc/man/jsonnet.1
@@ -0,0 +1,97 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH JSONNET "1" "January 2025" "Jsonnet commandline interpreter v0.20.0" "User Commands"
+.SH NAME
+Jsonnet \- Jsonnet data templating language interpreter
+.SH DESCRIPTION
+Jsonnet commandline interpreter v0.20.0
+.PP
+jsonnet {<option>} <filename>
+.SS "Available options:"
+.TP
+\fB\-h\fR / \fB\-\-help\fR
+This message
+.TP
+\fB\-e\fR / \fB\-\-exec\fR
+Treat filename as code
+.TP
+\fB\-J\fR / \fB\-\-jpath\fR <dir>
+Specify an additional library search dir (right\-most wins)
+.HP
+\fB\-o\fR / \fB\-\-output\-file\fR <file> Write to the output file rather than stdout
+.TP
+\fB\-m\fR / \fB\-\-multi\fR <dir>
+Write multiple files to the directory, list files on stdout
+.TP
+\fB\-y\fR / \fB\-\-yaml\-stream\fR
+Write output as a YAML stream of JSON documents
+.TP
+\fB\-S\fR / \fB\-\-string\fR
+Expect a string, manifest as plain text
+.TP
+\fB\-s\fR / \fB\-\-max\-stack\fR <n>
+Number of allowed stack frames
+.TP
+\fB\-t\fR / \fB\-\-max\-trace\fR <n>
+Max length of stack trace before cropping
+.TP
+\fB\-\-gc\-min\-objects\fR <n>
+Do not run garbage collector until this many
+.HP
+\fB\-\-gc\-growth\-trigger\fR <n> Run garbage collector after this amount of object growth
+.TP
+\fB\-\-version\fR
+Print version
+.PP
+Available options for specifying values of 'external' variables:
+Provide the value as a string:
+.TP
+\fB\-V\fR / \fB\-\-ext\-str\fR <var>[=<val>]
+If <val> is omitted, get from environment var <var>
+.HP
+\fB\-\-ext\-str\-file\fR <var>=<file> Read the string from the file
+.SS "Provide a value as Jsonnet code:"
+.TP
+\fB\-\-ext\-code\fR <var>[=<code>]
+If <code> is omitted, get from environment var <var>
+.HP
+\fB\-\-ext\-code\-file\fR <var>=<file> Read the code from the file
+.PP
+Available options for specifying values of 'top\-level arguments':
+Provide the value as a string:
+.TP
+\fB\-A\fR / \fB\-\-tla\-str\fR <var>[=<val>]
+If <val> is omitted, get from environment var <var>
+.HP
+\fB\-\-tla\-str\-file\fR <var>=<file> Read the string from the file
+.SS "Provide a value as Jsonnet code:"
+.TP
+\fB\-\-tla\-code\fR <var>[=<code>]
+If <code> is omitted, get from environment var <var>
+.HP
+\fB\-\-tla\-code\-file\fR <var>=<file> Read the code from the file
+.PP
+Environment variables:
+JSONNET_PATH is a colon (semicolon on Windows) separated list of directories added
+in reverse order before the paths specified by \fB\-\-jpath\fR (i.e. left\-most wins)
+E.g. JSONNET_PATH=a:b jsonnet \fB\-J\fR c \fB\-J\fR d is equivalent to:
+JSONNET_PATH=d:c:a:b jsonnet
+jsonnet \fB\-J\fR b \fB\-J\fR a \fB\-J\fR c \fB\-J\fR d
+.PP
+In all cases:
+<filename> can be \- (stdin)
+Multichar options are expanded e.g. \fB\-abc\fR becomes \fB\-a\fR \fB\-b\fR \fB\-c\fR.
+The \fB\-\-\fR option suppresses option processing for subsequent arguments.
+Note that since filenames and jsonnet programs can begin with \-, it is advised to
+use \fB\-\-\fR if the argument is unknown, e.g. jsonnet \fB\-\-\fR "$FILENAME".
+.SH "SEE ALSO"
+The full documentation for
+.B Jsonnet
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B Jsonnet
+programs are properly installed at your site, the command
+.IP
+.B info Jsonnet
+.PP
+should give you access to the complete manual.
diff --git a/doc/man/jsonnetfmt.1 b/doc/man/jsonnetfmt.1
new file mode 100644
index 00000000..1fab710b
--- /dev/null
+++ b/doc/man/jsonnetfmt.1
@@ -0,0 +1,70 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
+.TH JSONNET "1" "January 2025" "Jsonnet reformatter v0.20.0" "User Commands"
+.SH NAME
+Jsonnet \- Jsonnet data templating language reformatter
+.SH DESCRIPTION
+Jsonnet reformatter v0.20.0
+.PP
+jsonnetfmt {<option>} { <filename> }
+.SS "Available options:"
+.TP
+\fB\-h\fR / \fB\-\-help\fR
+This message
+.TP
+\fB\-e\fR / \fB\-\-exec\fR
+Treat filename as code
+.HP
+\fB\-o\fR / \fB\-\-output\-file\fR <file> Write to the output file rather than stdout
+.TP
+\fB\-i\fR / \fB\-\-in\-place\fR
+Update the Jsonnet file(s) in place.
+.TP
+\fB\-\-test\fR
+Exit with failure if reformatting changed the file(s).
+.TP
+\fB\-n\fR / \fB\-\-indent\fR <n>
+Number of spaces to indent by (default 2, 0 means no change)
+.TP
+\fB\-\-max\-blank\-lines\fR <n>
+Max vertical spacing, 0 means no change (default 2)
+.TP
+\fB\-\-string\-style\fR <d|s|l>
+Enforce double, single (default) quotes or 'leave'
+.HP
+\fB\-\-comment\-style\fR <h|s|l> # (h), // (s)(default), or 'leave'; never changes she\-bang
+.HP
+\fB\-\-[no\-]pretty\-field\-names\fR Use syntax sugar for fields and indexing (on by default)
+.TP
+\fB\-\-[no\-]pad\-arrays\fR
+[ 1, 2, 3 ] instead of [1, 2, 3]
+.TP
+\fB\-\-[no\-]pad\-objects\fR
+{ x: 1, y: 2 } instead of {x: 1, y: 2} (on by default)
+.TP
+\fB\-\-[no\-]sort\-imports\fR
+Sorting of imports (on by default)
+.TP
+\fB\-\-debug\-desugaring\fR
+Unparse the desugared AST without executing it
+.TP
+\fB\-\-version\fR
+Print version
+.PP
+In all cases:
+<filename> can be \- (stdin)
+Multichar options are expanded e.g. \fB\-abc\fR becomes \fB\-a\fR \fB\-b\fR \fB\-c\fR.
+The \fB\-\-\fR option suppresses option processing for subsequent arguments.
+Note that since filenames and jsonnet programs can begin with \-, it is advised to
+use \fB\-\-\fR if the argument is unknown, e.g. jsonnet \fB\-\-\fR "$FILENAME".
+.SH "SEE ALSO"
+The full documentation for
+.B Jsonnet
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B Jsonnet
+programs are properly installed at your site, the command
+.IP
+.B info Jsonnet
+.PP
+should give you access to the complete manual.