fix command line doc

doc/8-advanced/README.md

@@ -24,6 +24,6 @@ as listed in the "Window" menu:
 - [log viewer](log-viewer.md)
 - [stats](stats.md)
 
-at the command line:
+other:
 
-- [command line](commandline.md)
+- [command line usage](command-line.md)

doc/8-advanced/command-line.md

@@ -0,0 +1,100 @@
+# command line usage
+
+## NAME
+
+Furnace - a chiptune tracker
+
+## SYNOPSIS
+
+`furnace [params...] [file]`
+
+## DESCRIPTION
+
+Furnace is a chiptune tracker that supports many systems and sound chips from the 8/16-bit era.
+even though it is primarily controlled by using its graphical user interface, Furnace also offers a command line interface, which is described here.
+
+## USAGE
+
+starting Furnace without arguments will start the graphical user interface (GUI), as long as Furnace has been compiled with GUI enabled.
+
+passing the path to a file will open that file at start-up. if Furnace cannot open that file, it will report an error and quit.
+
+the following parameters may be used:
+
+**general**
+
+- `-help`: display the following help.
+- `-console`: enable command-line interface (CLI) player.
+  - see the COMMAND LINE INTERFACE section for more information
+- `-loglevel <level>`: set the logging level to one of the following:
+  - `error`: critical errors only
+  - `warning`: errors and warnings
+  - `info`: errors, warnings, and useful information
+  - `debug`: all of the above, including debug information
+  - `trace`: like debug, but with even more details (default)
+
+- `-info`: get information about a song.
+  - you must provide a file, otherwise Furnace will quit.
+
+- `-version`: display version information.
+- `-warranty`: view warranty disclaimer.
+
+**engine**
+
+- `-audio sdl|jack|portaudio`: override audio backend to one of the following:
+  - `sdl`: SDL (default)
+  - `jack`: JACK Audio Connection Kit
+  - `portaudio`: PortAudio
+- `-view <type>`: set visualization of data to one of the following:
+  - `pattern`: order and pattern
+  - `commands`: engine commands
+  - `nothing`: guess (default)
+- `-loops <count>`: set number of loops
+  - `-1` means loop forever.
+- `-subsong <number>`: set sub-song to play.
+- `-safemode`: enable safe mode (software rendering without audio).
+- `-safeaudio`: enable safe mode (software rendering with audio).
+- `-benchmark render|seek`: run performance test and output total time.
+  - `render`: measure render time
+  - `seek`: measure time to seek through the entire song
+  - you must provide a file, otherwise Furnace will quit.
+
+**audio export**
+
+- `-output path`: export audio in .wav format to `path`.
+  - you must provide a file, otherwise Furnace will quit.
+- `-outmode one|persys|perchan`: set audio export output mode.
+  - `one`: single file (default)
+  - `persys`: one file per chip (`_sXX` will be appended to file name, where `XX` is the chip number)
+  - `perchan`: one file per channel (`_cXX` will be appended to file name, where `XX` is the channel number)
+
+**VGM export**
+
+- `-vgmout path`: output VGM data to `path`.
+  - you must provide a file, otherwise Furnace will quit.
+- `-direct`: enable VGM export direct stream mode.
+  - this mode is useful for DualPCM export.
+  - note that this will increase file size by a huge amount!
+
+**export (other)**
+
+- `-zsmout path`: output Zsound Music data for Commander X16.
+  - you must provide a file, otherwise Furnace will quit.
+
+- `-cmdout path`: output command stream dump to `path`.
+  - you must provide a file, otherwise Furnace will quit.
+- `-binary`: set command stream output format to binary.
+
+## COMMAND LINE INTERFACE
+
+Furnace provides a command-line interface (CLI) player which may be activated through the `-console` option.
+
+the following controls may be used:
+
+- `Left`/`H`: go to previous order.
+- `Right`/`L`: go to next order.
+- `Space`: pause/resume playback.
+
+## SEE ALSO
+
+the Furnace user manual in the `manual.pdf` file.

doc/8-advanced/commandline.md

@@ -1,39 +0,0 @@
-# command line
-
-to start Furnace at the command line, use the following command (may vary by operating system):
-
-`furnace [params] [filename]`
-
-the following parameters may be used:
-
-- `-help`: display help.
-- `-audio <engine>`: set audio engine to one of the following:
-  - `jack`: JACK Audio Connection Kit. only on Linux.
-  - `sdl`: SDL. default.
-  - `portaudio`: PortAudio.
-- `-output <filename>`: export audio to `filename`.
-- `-vgmout <filename>`: output .vgm data to `filename`.
-- `-direct`: set VGM export direct stream mode.
-- `-zsmout <filename>`: output .zsm data for Commander X16 Zsound.
-- `-cmdout <filename>`: output command stream.
-- `-binary`: set command stream output format to binary.
-- `-loglevel <level>`: set the logging level to one of the following:
-  - `error`: critical errors only.
-  - `warning`: errors and warnings.
-  - `info`: errors, warnings, and useful information.
-  - `debug`: all of the above and information useful for debugging.
-  - `trace`: most verbose. includes details of inner workings. default.
-- `-view <type>`: set visualization of data to one of the following:
-  - `pattern`: order and pattern.
-  - `commands`: commands.
-  - `nothing`: no visualization. default.
-- `-info`: get info about a song.
-- `-console`: enable console mode.
-- `-loops <count>`: set number of loops. `-1` means loop forever.
-- `-subsong <number>`: set sub-song.
-- `-outmode one|persys|perchan`: set file output mode: all in one file, one file per chip, or one file per channel. default is `one`.
-- `-safemode`: enable safe mode (software rendering without audio).
-- `-safeaudio`: enable safe mode (software rendering with audio).
-- `-benchmark render|seek`: run performance test.
-- `-version`: version information.
-- `-warranty`: view warranty disclaimer.

src/main.cpp

@@ -554,7 +554,7 @@ int main(int argc, char** argv) {
 
   if (safeMode && (consoleMode || benchMode || infoMode || outName!="" || vgmOutName!="" || cmdOutName!="")) {
     logE("you can't use safe mode and console/export mode together.");
-    return 0;
+    return 1;
   }
 
   if (safeMode && !safeModeWithAudio) {