ndctl/SOURCES/0048-scripts-Add-a-man-page-template-generator.patch

From 706a418798633ccb550b114eca7cc11038ab2695 Mon Sep 17 00:00:00 2001
From: Vishal Verma <vishal.l.verma@intel.com>
Date: Tue, 14 Dec 2021 19:01:02 -0700
Subject: [PATCH 048/217] scripts: Add a man page template generator

Add a script to generate man page templates for the utils and libraries
under ndctl - including cxl, libcxl, ndctl, and daxctl.

The script can control certain include options depending on the options
supplied, and either dump the templates to stdout, or write the actual
files in their eventual directories, and open up an editor to further
edit them (unless --no-edit is used).

Link: https://lore.kernel.org/r/20211215020102.97880-1-vishal.l.verma@intel.com
Cc: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>
---
 scripts/docsurgeon                     | 339 +++++++++++++++++++++++++
 scripts/docsurgeon_parser_generator.m4 |  23 ++
 2 files changed, 362 insertions(+)
 create mode 100755 scripts/docsurgeon
 create mode 100644 scripts/docsurgeon_parser_generator.m4

diff --git a/scripts/docsurgeon b/scripts/docsurgeon
new file mode 100755
index 0000000..ca0ad78
--- /dev/null
+++ b/scripts/docsurgeon
@@ -0,0 +1,339 @@
+#!/bin/bash -eE
+
+this_script="docsurgeon"
+script_dir="$(cd "$(dirname "$(readlink -e "${BASH_SOURCE[0]}")")" && pwd)"
+env_file="${script_dir}/.env"
+if [ -e "$env_file" ]; then
+	# shellcheck source=.env
+	. "$env_file"
+fi
+
+sources_file="${script_dir}/.sources"
+
+parser_generator="${script_dir}/${this_script}_parser_generator.m4"
+parser_lib="${script_dir}/${this_script}_parser.sh"
+if [ ! -e "$parser_lib" ] || [ "$parser_generator" -nt "$parser_lib" ]; then
+	if command -V argbash > /dev/null; then
+		argbash --strip user-content "$parser_generator" -o "$parser_lib"
+	else
+		echo "error: please install argbash" >&2
+		exit 1
+	fi
+fi
+
+if [[ $1 != "bin" ]]; then
+	# shellcheck source=docsurgeon_parser.sh
+	. "${script_dir}/${this_script}_parser.sh" || { echo "Couldn't find $parser_lib" >&2; exit 1; }
+fi
+
+# some script defaults - override using '.env'
+docbase="Documentation"
+copyright_cli="// SPDX-License-Identifier: GPL-2.0"
+copyright_footer_cli="include::../copyright.txt[]"
+copyright_lib="// SPDX-License-Identifier: LGPL-2.0"
+copyright_footer_lib="include::../../copyright.txt[]"
+
+# List of files we're creating, to be edited/renamed later
+# This starts out blank, and is filled in as we go by gen_*() functions
+declare -a outfiles
+
+cleanup()
+{
+	if [ ${#outfiles[@]} -gt 0 ]; then
+		rm -f "${outfiles[@]}"
+	fi
+	set +x
+}
+
+trap cleanup EXIT
+
+auto_detect_params()
+{
+	fs=""
+	module=""
+	section=""
+
+	# if module and section were explicitly specified, respect them
+	if [[ $_arg_module ]] && [[ $_arg_section ]]; then
+		return
+	fi
+
+	# check if names are self-consistent, and determine 'fs'
+	for name in ${_arg_name[@]}; do
+		if [[ ! $fs ]]; then
+			if [[ $name == *-* ]]; then
+				fs="-"
+			elif [[ $name == *_* ]]; then
+				fs="_"
+			else
+				# can't autodetect section
+				return
+			fi
+		fi
+		if [[ $fs == "-" ]] && [[ $name == *_* ]]; then
+			die "can't auto-detect params with mixed-style names"
+		fi
+		if [[ $fs == "_" ]] && [[ $name == *-* ]]; then
+			die "can't auto-detect params with mixed-style names"
+		fi
+	done
+
+	# try to detect module name
+	for name in ${_arg_name[@]}; do
+		str=${name%%$fs*}
+		if [[ $module ]]; then
+			if [[ $str != $module ]]; then
+				die "Can't autodetect module because of mixed names ($str and $module)"
+			fi
+		else
+			module="$str"
+		fi
+	done
+
+	# try to detect section number
+	case "$fs" in
+	-)
+		section=1
+		;;
+	_)
+		section=3
+		;;
+	*)
+		die "Unknown fs, can't autodetect section number"
+		;;
+	esac
+
+	if [[ $module ]]; then
+		_arg_module="$module"
+	fi
+	if [[ $section ]]; then
+		_arg_section="$section"
+	fi
+}
+
+process_options_logic()
+{
+	if [[ $_arg_debug == "on" ]]; then
+		set -x
+	fi
+
+	auto_detect_params
+}
+
+gen_underline()
+{
+	name="$1"
+	char="$2"
+	num="${#name}"
+
+	printf -v tmpstring "%-${num}s" " "
+	echo "${tmpstring// /$char}"
+}
+
+gen_header()
+{
+	printf "\n%s\n%s\n" "$1" "$(gen_underline "$1" "=")"
+}
+
+gen_section()
+{
+	printf "\n%s\n%s\n" "$1" "$(gen_underline "$1" "-")"
+}
+
+gen_section_name()
+{
+	name="$1"
+
+	gen_section "NAME"
+	cat <<- EOF
+		$name - 
+	EOF
+}
+
+gen_section_synopsis_1()
+{
+	name="$1"
+
+	gen_section "SYNOPSIS"
+	cat <<- EOF
+		[verse]
+		'$_arg_module ${name#*-} [<options>]'
+	EOF
+}
+
+gen_section_synopsis_3()
+{
+	name="$1"
+
+	gen_section "SYNOPSIS"
+	cat <<- EOF
+		[verse]
+		----
+		#include <$_arg_module/lib$_arg_module.h>
+
+		<type> $name();
+		----
+	EOF
+}
+
+gen_section_example_1()
+{
+	name="$1"
+
+	gen_section "EXAMPLE"
+	cat <<- EOF
+		----
+		# $_arg_module ${name#*-}
+		----
+	EOF
+}
+
+gen_section_example_3()
+{
+	name="$1"
+
+	gen_section "EXAMPLE"
+	cat <<- EOF
+		See example usage in test/lib$_arg_module.c
+	EOF
+}
+
+gen_section_options_1()
+{
+	gen_section "OPTIONS"
+cat << EOF
+-o::
+--option::
+	Description
+EOF
+
+	if [[ $_arg_human_option == "on" ]]; then
+		printf "\n%s\n" "include::human-option.txt[]"
+	fi
+	if [[ $_arg_verbose_option == "on" ]]; then
+		printf "\n%s\n" "include::verbose-option.txt[]"
+	fi
+}
+
+gen_section_seealso_1()
+{
+	gen_section "SEE ALSO"
+	cat <<- EOF
+	link$_arg_module:$_arg_module-list[$_arg_section],
+	EOF
+}
+
+gen_section_seealso_3()
+{
+	gen_section "SEE ALSO"
+	cat <<- EOF
+	linklib$_arg_module:${_arg_module}_other_API[$_arg_section],
+	EOF
+}
+
+gen_cli()
+{
+	name="$1"
+	path="$docbase/$_arg_module"
+	if [ ! -d "$path" ]; then
+		die "Not found: $path"
+	fi
+
+	tmp="$(mktemp -p "$path" "$name.txt.XXXX")"
+	outfiles+=("$tmp")
+
+	# Start template generation
+	printf "%s\n" "$copyright_cli" > "$tmp"
+	gen_header "$name" >> "$tmp"
+	gen_section_name "$name" >> "$tmp"
+	gen_section_synopsis_1 "$name" >> "$tmp"
+	gen_section "DESCRIPTION" >> "$tmp"
+	gen_section_example_1 "$name" >> "$tmp"
+	gen_section_options_1 >> "$tmp"
+	printf "\n%s\n" "$copyright_footer_cli" >> "$tmp"
+	gen_section_seealso_1 >> "$tmp"
+}
+
+gen_lib()
+{
+	name="$1"
+	path="$docbase/$_arg_module/lib"
+	if [ ! -d "$path" ]; then
+		die "Not found: $path"
+	fi
+
+	tmp="$(mktemp -p "$path" "$name.txt.XXXX")"
+	outfiles+=("$tmp")
+
+	# Start template generation
+	printf "%s\n" "$copyright_lib" > "$tmp"
+	gen_header "$name($_arg_section)" >> "$tmp"
+	gen_section_name "$name" >> "$tmp"
+	gen_section_synopsis_3 "$name" >> "$tmp"
+	gen_section "DESCRIPTION" >> "$tmp"
+	gen_section "RETURN VALUE" >> "$tmp"
+	gen_section_example_3 "$name" >> "$tmp"
+	printf "\n%s\n" "$copyright_footer_lib" >> "$tmp"
+	gen_section_seealso_3 >> "$tmp"
+}
+
+gen_man()
+{
+	name="$1"
+	case "$_arg_section" in
+	1)
+		gen_cli "$name"
+		;;
+	3)
+		gen_lib "$name"
+		;;
+	*)
+		die "Unknown section: $_arg_section"
+		;;
+	esac
+}
+
+gen_include()
+{
+	echo "in gen_include"
+}
+
+main()
+{
+	process_options_logic
+
+	cmd="$_arg_command"
+	case "$cmd" in
+	gen-man)
+		for name in ${_arg_name[@]}; do
+			gen_man "$name"
+		done
+		;;
+	gen-include)
+		for name in ${_arg_name[@]}; do
+			gen_include
+		done
+		;;
+	*)
+		die "Unknown command: $cmd"
+		;;
+	esac
+
+	if [[ $_arg_dump == "on" ]]; then
+		for file in ${outfiles[@]}; do
+			echo "${file##*/}"
+			cat "$file"
+			rm "$file"
+		done
+	elif [ ${#outfiles[@]} -gt 0 ]; then
+		if [[ $_arg_edit = "on" ]]; then
+			vim -p "${outfiles[@]}"
+		fi
+
+		for file in ${outfiles[@]}; do
+			mv "$file" "${file%.*}"
+		done
+	fi
+}
+
+main "$@"
diff --git a/scripts/docsurgeon_parser_generator.m4 b/scripts/docsurgeon_parser_generator.m4
new file mode 100644
index 0000000..9283c7c
--- /dev/null
+++ b/scripts/docsurgeon_parser_generator.m4
@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# m4_ignore(
+echo "This is just a parsing library template, not the library - pass this file to 'argbash' to fix this." >&2
+exit 11  #)Created by argbash-init v2.9.0
+# Rearrange the order of options below according to what you would like to see in the help message.
+# ARG_OPTIONAL_REPEATED([name], [n], [Command or function name to generate a template for.\n Can be repeated for multiple names. ], [])
+# ARG_OPTIONAL_BOOLEAN([edit], [e], [Edit template files after creation], [on])
+# ARG_OPTIONAL_BOOLEAN([debug], [], [Debug script problems (enables set -x)], )
+# ARG_OPTIONAL_BOOLEAN([dump], [], [Write generated file to stdout instead of a file], )
+# ARG_OPTIONAL_SINGLE([module], [m], [Module (Docs subdir) in which to create the template], [])
+# ARG_OPTIONAL_SINGLE([section], [s], [man section for which to create the template], [])
+# ARG_OPTIONAL_BOOLEAN([human-option], [u], [Include the human option in 'OPTIONS'], )
+# ARG_OPTIONAL_BOOLEAN([verbose-option], [V], [Include the verbose option in 'OPTIONS'], )
+# ARG_POSITIONAL_DOUBLEDASH()
+# ARG_POSITIONAL_SINGLE([command], [Operation to perform:\n  gen-man\n  gen-include], [])
+# ARGBASH_SET_DELIM([ =])
+# ARG_OPTION_STACKING([getopt])
+# ARG_RESTRICT_VALUES([no-local-options])
+# ARG_DEFAULTS_POS
+# ARG_HELP([Tool to aid in creating and managing man page templates])
+# ARG_VERSION([echo "docsurgeon 0.1"])
+# ARGBASH_GO
-- 
2.27.0