Split combined manpage into individual ones for each command

Makefile

@@ -41,6 +41,7 @@ deref_symlinks ?= ## Deference symbolic links for `make install`
 O := .build
 SOURCES := $(shell find src -name '*.cr')
 SPEC_SOURCES := $(shell find spec -name '*.cr')
+MAN1PAGES := $(patsubst doc/man/%.adoc,man/%.1,$(wildcard doc/man/*.adoc))
 override FLAGS += -D strict_multi_assign -D preview_overload_order $(if $(release),--release )$(if $(stats),--stats )$(if $(progress),--progress )$(if $(threads),--threads $(threads) )$(if $(debug),-d )$(if $(static),--static )$(if $(LDFLAGS),--link-flags="$(LDFLAGS)" )$(if $(target),--cross-compile --target $(target) )$(if $(interpreter),,-Dwithout_interpreter )
 SPEC_WARNINGS_OFF := --exclude-warnings spec/std --exclude-warnings spec/compiler --exclude-warnings spec/primitives
 override SPEC_FLAGS += $(if $(verbose),-v )$(if $(junit_output),--junit_output $(junit_output) )$(if $(order),--order=$(order) )
@@ -163,7 +164,7 @@ generate_data: ## Run generator scripts for Unicode, SSL config, ...
 	$(MAKE) -B -f scripts/generate_data.mk
 
 .PHONY: install
-install: $(O)/$(CRYSTAL_BIN) man/crystal.1.gz ## Install the compiler at DESTDIR
+install: $(O)/$(CRYSTAL_BIN) $(MAN1PAGES) ## Install the compiler at DESTDIR
 	$(INSTALL) -d -m 0755 "$(DESTDIR)$(BINDIR)/"
 	$(INSTALL) -m 0755 "$(O)/$(CRYSTAL_BIN)" "$(DESTDIR)$(BINDIR)/$(CRYSTAL_BIN)"
 
@@ -172,7 +173,7 @@ install: $(O)/$(CRYSTAL_BIN) man/crystal.1.gz ## Install the compiler at DESTDIR
 	rm -rf "$(DESTDIR)$(DATADIR)/crystal/$(LLVM_EXT_OBJ)" # Don't install llvm_ext.o
 
 	$(INSTALL) -d -m 0755 "$(DESTDIR)$(MANDIR)/man1/"
-	$(INSTALL) -m 644 man/crystal.1.gz "$(DESTDIR)$(MANDIR)/man1/crystal.1.gz"
+	$(INSTALL) -m 644 $(MAN1PAGES) "$(DESTDIR)$(MANDIR)/man1/"
 	$(INSTALL) -d -m 0755 "$(DESTDIR)$(DATADIR)/licenses/crystal/"
 	$(INSTALL) -m 644 LICENSE "$(DESTDIR)$(DATADIR)/licenses/crystal/LICENSE"
 
@@ -253,10 +254,12 @@ $(LLVM_EXT_OBJ): $(LLVM_EXT_DIR)/llvm_ext.cc
 	$(call check_llvm_config)
 	$(CXX) -c $(CXXFLAGS) -o $@ $< $(shell $(LLVM_CONFIG) --cxxflags)
 
+man/: $(MAN1PAGES)
+
 man/%.gz: man/%
 	gzip -c -9 $< > $@
 
-man/crystal.1: doc/man/crystal.adoc
+man/%.1: doc/man/%.adoc
 	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) asciidoctor -a crystal_version=$(CRYSTAL_VERSION) $< -b manpage -o $@
 
 .PHONY: clean

doc/man/crystal-build.adoc

@@ -0,0 +1,104 @@
+= crystal-build(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-build - Compile a Crystal program
+
+== Synopsis
+*crystal build* [options] [programfile] [--] [arguments]
+
+== Options
+
+*--cross-compile*::
+Generate an object file for cross compilation and prints the command to build the executable.	The object file should be copied
+to the target system and the printed command should be executed
+there. This flag mainly exists for porting the compiler to new
+platforms, where possible run the compiler on the target platform
+directly.
+*-d*, *--debug*::
+Generate the output with symbolic debug symbols.  These are read
+when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for
+those tools.
+*--no-debug*::
+Generate the output without any symbolic debug symbols.
+*-D* _FLAG_, *--define* _FLAG_::
+Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given
+with *--target-triple*  or the hosts default, if none is given.
+*--emit* [asm|llvm-bc|llvm-ir|obj]::
+Comma separated list of types of output for the compiler to emit.
+You can use this to see the generated LLVM IR, LLVM bitcode, assembly, and object files.
+*--frame-pointers* [auto|always|non-leaf]::
+Control the preservation of frame pointers. The default value,
+`--frame-pointers=auto`, will preserve frame pointers on debug
+builds and try to omit them on release builds (certain platforms
+require them to stay enabled). `--frame-pointers=always` will always preserve them, and non-leaf will only force their preservation on non-leaf functions.
+*-f* text|json, *--format* text|json::
+Format of output. Defaults to text. The json format can be used
+to get a more parser-friendly output.
+*--error-trace*::
+Show full error trace.
+*--ll*:: 	 Dump LLVM assembly file to output directory.
+*--link-flags* _FLAGS_::
+Pass additional flags to the linker. Though you can specify those
+flags on the source code, this is useful for passing environment
+specific information directly to the linker, like non-standard
+library paths or names. For more information on specifying linker
+flags on source, you can read the "C bindings" section of the
+documentation available on the official web site.
+*--mcpu* _CPU_::
+Specify a specific CPU to generate code for. This will pass a
+-mcpu flag to LLVM, and is only intended to be used for cross-
+compilation. For a list of available CPUs, invoke "llvm-as <
+/dev/null | llc -march=xyz -mcpu=help".  Passing --mcpu native
+will pass the host CPU name to tune performance for the host.
+*--mattr* _CPU_::
+Override or control specific attributes of the target, such as
+whether SIMD operations are enabled or not. The default set of
+attributes is set by the current CPU. This will pass a -mattr
+flag to LLVM, and is only intended to be used for cross-compilation. For a list of available attributes, invoke "llvm-as <
+/dev/null | llc -march=xyz -mattr=help".
+*--mcmodel* default|kernel|small|medium|large::
+Specifies a specific code model to generate code for. This will
+pass a --code-model flag to LLVM.
+*--no-color*::
+Disable colored output.
+*--no-codegen*::
+Don't do code generation, just parse the file.
+*-o*::  Specify filename of output.
+*--prelude*::
+Specify prelude to use. The default one initializes the garbage
+collector. You can also use --prelude=empty to use no preludes.
+This can be useful for checking code generation for a specific
+source code file.
+*-O* _LEVEL_::  Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for
+details.
+*--release*::
+Compile in release mode. Equivalent to *-O3 --single-module*
+*--error-trace*::
+Show full stack trace. Disabled by default, as the full trace
+usually makes error messages less readable and not always deliver
+relevant information.
+*-s*, *--stats*::
+Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler process.
+*-p*, *--progress*::
+Print statistics about the progress for the current build.
+*-t*, *--time*::
+Print statistics about the execution time.
+*--single-module*::
+Generate a single LLVM module.  By default, one LLVM module is
+created for each type in a program.  *--release* implies this option.
+*--threads* _NUM_::
+Maximum number of threads to use for code generation. The default
+is 8 threads.
+*--target* _TRIPLE_::
+Enable target triple; intended to use for cross-compilation. See
+llvm documentation for more information about target triple.
+*--verbose*::
+Display the commands executed by the system.
+*--static*::	 Create a statically linked executable.
+*--stdin-filename* _FILENAME_::
+Source file name to be read from STDIN.

doc/man/crystal-docs.adoc

@@ -0,0 +1,65 @@
+= crystal-docs(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-doc - Generate API docs for Crystal code
+
+== Synopsis
+*crystal build* [options] [programfile] [--] [arguments]
+
+== Description
+
+Generate documentation from comments using a subset of markdown. The output
+is saved in html format on the created docs/ folder. More information about
+documentation conventions can be found at <https://crystal-lang.org/docs/conventions/documenting_code.html>.
+
+== Options
+
+*--project-name* _NAME_::
+Set the project name. The default value is extracted from
+shard.yml if available.
++
+In case no default can be found, this option is mandatory.
+*--project-version* _VERSION_::
+Set the project version. The default value is extracted from current git commit or shard.yml if available.
++
+In case no default can be found, this option is mandatory.
+*--json-config-url* _URL_::
+Set the URL pointing to a config file (used for discovering versions).
+*--source-refname* _REFNAME_::
+Set source refname (e.g. git tag, commit hash). The default value
+is extracted from current git commit if available.
++
+If this option is missing and can't be automatically determined,
+the generator can't produce source code links.
+*--source-url-pattern* _URL_::
+Set URL pattern for source code links. The default value is extracted from git remotes ("origin" or first one) if available and
+the provider's URL pattern is recognized.
++
+Supported replacement tags:
++
+--
+*%{refname}*::  commit reference
+*%{path}*::     path to source file inside the repository
+*%{filename}*::
+  basename of the source file
+*%{line}*::     line number
+--
++
+If this option is missing and can't be automatically determined,
+the generator can't produce source code links.
+*-o* _DIR_, *--output* _DIR_::
+Set the output directory (default: ./docs).
+*-b* _URL_, **--canonical-base-url** _URL_::
+Indicate the preferred URL with rel="canonical" link element.
+*-b* _URL_, *--sitemap-base-url* _URL_::
+Set the sitemap base URL. Sitemap will only be generated when
+this option is set.
+*--sitemap-priority* _PRIO_::
+Set the priority assigned to sitemap entries (default: 1.0).
+*--sitemap-changefreq* _FREQ_::
+Set the changefreq assigned to sitemap entries (default: never).

doc/man/crystal-env.adoc

@@ -0,0 +1,40 @@
+= crystal-env(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-env - Print environment variables for the Crystal compiler
+
+== Synopsis
+*crystal env* [variables]
+
+== Description
+
+Print Crystal-specific environment variables in a format compatible with
+shell scripts. If one or more variable names are given as arguments, it
+prints only the value of each named variable on its own line.
+
+Variables:
+
+*CRYSTAL_CACHE_DIR*::
+Please see ENVIRONMENT VARIABLES.
+
+*CRYSTAL_LIBRARY_PATH*::
+Please see ENVIRONMENT VARIABLES.
+
+*CRYSTAL_PATH*::
+Please see ENVIRONMENT VARIABLES.
+
+*CRYSTAL_VERSION*::
+Contains Crystal version.
+
+== Informative Variables
+
+These variables expose information about the Crystal compiler and cannot be configured externally.
+
+=== CRYSTAL_VERSION
+
+Contains Crystal version.

doc/man/crystal-eval.adoc

@@ -0,0 +1,42 @@
+= crystal-eval(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-eval - Evaluate a crystal program
+
+== Synopsis
+*crystal eval* [options] [source]
+
+== Description
+
+Evaluate code from arguments or, if no arguments are passed, from the standard input. Useful for experiments.
+
+== Options
+
+*-d*, *--debug*::
+Generate the output with symbolic debug symbols.  These are read
+when debugging the built program with tools like lldb, gdb, valgrind etc. and provide mappings to the original source code for
+those tools.
+*--no-debug*::
+Generate the output without any symbolic debug symbols.
+*-D* _FLAG_, *--define* _FLAG_::
+Define a compile-time flag. This is useful to conditionally define types, methods, or commands based on flags available at compile time. The default flags are from the target triple given
+with --target-triple or the hosts default, if none is given.
+*--error-trace*::
+Show full error trace.
+*-O* _LEVEL_::	 Optimization mode: 0 (default), 1, 2, 3. See *OPTIMIZATIONS* for details.
+*--release*::
+Compile in release mode. Equivalent to *-O3 --single-module*
+*-s*, *--stats*::
+Print statistics about the different compiler stages for the current build. Output time and used memory for each compiler
+process.
+*-p*, *--progress*::
+Print statistics about the progress for the current build.
+*-t*, *--time*::
+Print statistics about the execution time.
+*--no-color*::
+Disable colored output.

doc/man/crystal-init.adoc

@@ -0,0 +1,30 @@
+= crystal-init(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-init - Create a a new Crystal project
+
+== Synopsis
+*crystal init* TYPE [DIR | NAME DIR]
+
+== Description
+
+TYPE is one of:
+
+*lib*	 Creates a library skeleton +
+*app*	 Creates an application skeleton
+
+This initializes the lib/app project folder as a git repository, with a license file, a README file, a shard.yml for use with shards (the Crystal dependency manager), a .gitignore file, and src and spec folders.
+
+DIR  - directory where project will be generated
+
+NAME - name of project to be generated (default: basename of DIR)
+
+== Options
+
+*-f, --force*:: Force overwrite existing files.
+*-s, --skip-existing*:: Skip existing files.

doc/man/crystal-play.adoc

@@ -0,0 +1,25 @@
+= crystal-play(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-play - Run the Crystal playground
+
+== Synopsis
+*crystal play* [options] [file]
+
+== Description
+
+Starts the *crystal* playground server on port 8080, by default.
+
+== Options
+
+*-p* _PORT_, *--port* _PORT_::
+Run the playground on the specified port. Default is 8080.
+*-b* _HOST_, *--binding* _HOST_::
+Bind the playground to the specified IP.
+*-v*, *--verbose*::
+Display detailed information of the executed code.

doc/man/crystal-run.adoc

@@ -0,0 +1,20 @@
+= crystal-run(1)
+:doctype: manpage
+:date: {localdate}
+:crystal_version: {crystal_version}
+:man manual: Crystal Compiler Command Line Reference Guide
+:man source: crystal {crystal_version}
+
+== Name
+crystal-run - Compile and run a Crystal program
+
+== Synopsis
+*crystal run* [options] [programfile] [--] [arguments]
+
+== Description
+
+The default command. Compile and run program.
+
+== Options
+
+Same as the build options.