From a0bb830679dc639702607315f7b067c2eee6f58c Mon Sep 17 00:00:00 2001 From: Rangi Date: Wed, 22 Oct 2025 14:48:24 -0400 Subject: [PATCH] More consistent man page descriptions for CLI options --- man/rgbasm.1 | 63 ++++++++++++++++++++++++++++++++++++------- man/rgbfix.1 | 74 ++++++++++++++++++++++++++++++++++++++++----------- man/rgbgfx.1 | 62 +++++++++++++++++++++++++++--------------- man/rgblink.1 | 63 ++++++++++++++++++++++++++++++++++++------- 4 files changed, 207 insertions(+), 55 deletions(-) diff --git a/man/rgbasm.1 b/man/rgbasm.1 index 7ab81382..94bf33ff 100644 --- a/man/rgbasm.1 +++ b/man/rgbasm.1 @@ -36,14 +36,14 @@ The program creates an RGB object file from an assembly source file. The object file format is documented in .Xr rgbds 5 . -.Pp -The input -.Ar asmfile -can be a path to a file, or -.Cm \- -to read from standard input. -.Pp -Note that options can be abbreviated as long as the abbreviation is unambiguous: +.Sh ARGUMENTS +.Nm +accepts the usual short and long options, such as +.Fl V +and +.Fl -version . +Options later in the command line override those set earlier, except for when duplicate options are considered an error. +Options can be abbreviated as long as the abbreviation is unambiguous: .Fl \-verb is .Fl \-verbose , @@ -51,7 +51,52 @@ but .Fl \-ver is invalid because it could also be .Fl \-version . -The arguments are as follows: +.Pp +Unless otherwise noted, passing +.Ql - +(a single dash) as a file name makes +.Nm +use standard input (for input files) or standard output (for output files). +To suppress this behavior, and open a file in the current directory actually called +.Ql - , +pass +.Ql ./- +instead. +Using standard input or output for more than one file in a single command may produce unexpected results. +.Pp +.Nm +accepts decimal, hexadecimal, octal, and binary for numeric option arguments. +Decimal numbers are written as usual; hexadecimal numbers must be prefixed with either +.Ql $ +or +.Ql 0x ; +octal numbers must be prefixed with either +.Ql & +or +.Ql 0o ; +and binary numbers must be prefixed with either +.Ql % +or +.Ql 0b . +(The prefixes +.Ql $ +and +.Ql & +will likely need escaping or quoting to avoid being interpreted by the shell.) +Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. +For example, all of these are equivalent: +.Ql 42 , +.Ql 042 , +.Ql 0x2A , +.Ql 0X2A , +.Ql 0x2a , +.Ql &52 , +.Ql 0o52 , +.Ql 0O052 , +.Ql 0b00101010 , +.Ql 0B101010 . +.Pp +The following options are accepted: .Bl -tag -width Ds .It Fl B Ar param , Fl \-backtrace Ar param Configures how location backtraces are printed if warnings or errors occur. diff --git a/man/rgbfix.1 b/man/rgbfix.1 index aade72a2..d72eb44a 100644 --- a/man/rgbfix.1 +++ b/man/rgbfix.1 @@ -39,23 +39,67 @@ Developers are advised to fill those fields with 0x00 bytes in their source code .Nm , and to have already populated whichever fields they don't specify using .Nm . -.Pp -The input -.Ar file -can be a path to a file, or -.Cm \- -to read from standard input. -.Pp -Note that options can be abbreviated as long as the abbreviation is unambiguous: -.Fl \-verb -is -.Fl \-verbose , -but +.Sh ARGUMENTS +.Nm +accepts the usual short and long options, such as +.Fl V +and +.Fl -version . +Options later in the command line override those set earlier, except for when duplicate options are considered an error. +Options can be abbreviated as long as the abbreviation is unambiguous: .Fl \-ver +is +.Fl \-version , +but +.Fl \-v is invalid because it could also be -.Fl \-version . -Options later in the command line override those set earlier. -Accepted options are as follows: +.Fl \-validate . +.Pp +Unless otherwise noted, passing +.Ql - +(a single dash) as a file name makes +.Nm +use standard input (for input files) or standard output (for output files). +To suppress this behavior, and open a file in the current directory actually called +.Ql - , +pass +.Ql ./- +instead. +Using standard input or output for more than one file in a single command may produce unexpected results. +.Pp +.Nm +accepts decimal, hexadecimal, octal, and binary for numeric option arguments. +Decimal numbers are written as usual; hexadecimal numbers must be prefixed with either +.Ql $ +or +.Ql 0x ; +octal numbers must be prefixed with either +.Ql & +or +.Ql 0o ; +and binary numbers must be prefixed with either +.Ql % +or +.Ql 0b . +(The prefixes +.Ql $ +and +.Ql & +will likely need escaping or quoting to avoid being interpreted by the shell.) +Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. +For example, all of these are equivalent: +.Ql 42 , +.Ql 042 , +.Ql 0x2A , +.Ql 0X2A , +.Ql 0x2a , +.Ql &52 , +.Ql 0o52 , +.Ql 0O052 , +.Ql 0b00101010 , +.Ql 0B101010 . +.Pp +The following options are accepted: .Bl -tag -width Ds .It Fl C , Fl \-color-only Set the Game Boy Color\(enonly flag diff --git a/man/rgbgfx.1 b/man/rgbgfx.1 index 6a5fc2a7..6f602eb7 100644 --- a/man/rgbgfx.1 +++ b/man/rgbgfx.1 @@ -43,7 +43,13 @@ is to divide the input PNG into 8\[tmu]8 pixel convert each of those squares into 1bpp or 2bpp tile data, and save all of the tile data in a file. It also has options to generate a tile map, attribute map, and/or palette set as well; more on that and how the conversion process can be tweaked below. .Sh ARGUMENTS -Note that options can be abbreviated as long as the abbreviation is unambiguous: +.Nm +accepts the usual short and long options, such as +.Fl V +and +.Fl -version . +Options later in the command line override those set earlier, except for when duplicate options are considered an error. +Options can be abbreviated as long as the abbreviation is unambiguous: .Fl \-verb is .Fl \-verbose , @@ -52,26 +58,6 @@ but is invalid because it could also be .Fl \-version . .Pp -.Nm -accepts decimal, binary, and hexadecimal numbers in option arguments. -Decimal numbers are written as usual; binary numbers must be prefixed with either -.Ql % -or -.Ql 0b , -and hexadecimal numbers must be prefixed with either -.Ql $ -(which will likely need escaping or quoting to avoid being interpreted by the shell), or -.Ql 0x . -Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. -All of these are equivalent: -.Ql 42 , -.Ql 042 , -.Ql 0b00101010 , -.Ql 0B101010 , -.Ql 0x2A , -.Ql 0X2A , -.Ql 0x2a . -.Pp Unless otherwise noted, passing .Ql - (a single dash) as a file name makes @@ -82,7 +68,39 @@ To suppress this behavior, and open a file in the current directory actually cal pass .Ql ./- instead. -Using standard input or output more than once in a single command will likely produce unexpected results. +Using standard input or output for more than one file in a single command may produce unexpected results. +.Pp +.Nm +accepts decimal, hexadecimal, octal, and binary for numeric option arguments. +Decimal numbers are written as usual; hexadecimal numbers must be prefixed with either +.Ql $ +or +.Ql 0x ; +octal numbers must be prefixed with either +.Ql & +or +.Ql 0o ; +and binary numbers must be prefixed with either +.Ql % +or +.Ql 0b . +(The prefixes +.Ql $ +and +.Ql & +will likely need escaping or quoting to avoid being interpreted by the shell.) +Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. +For example, all of these are equivalent: +.Ql 42 , +.Ql 042 , +.Ql 0x2A , +.Ql 0X2A , +.Ql 0x2a , +.Ql &52 , +.Ql 0o52 , +.Ql 0O052 , +.Ql 0b00101010 , +.Ql 0B101010 . .Pp The following options are accepted: .Bl -tag -width Ds diff --git a/man/rgblink.1 b/man/rgblink.1 index 57d52865..b690e7d3 100644 --- a/man/rgblink.1 +++ b/man/rgblink.1 @@ -48,14 +48,14 @@ Also, if your ROM is designed for a monochrome Game Boy, you can make sure that option, which implies .Fl w but also prohibits the use of banked VRAM. -.Pp -The input -.Ar file -can be a path to a file, or -.Cm \- -to read from standard input. -.Pp -Note that options can be abbreviated as long as the abbreviation is unambiguous: +.Sh ARGUMENTS +.Nm +accepts the usual short and long options, such as +.Fl V +and +.Fl -version . +Options later in the command line override those set earlier, except for when duplicate options are considered an error. +Options can be abbreviated as long as the abbreviation is unambiguous: .Fl \-verb is .Fl \-verbose , @@ -63,7 +63,52 @@ but .Fl \-ver is invalid because it could also be .Fl \-version . -The arguments are as follows: +.Pp +Unless otherwise noted, passing +.Ql - +(a single dash) as a file name makes +.Nm +use standard input (for input files) or standard output (for output files). +To suppress this behavior, and open a file in the current directory actually called +.Ql - , +pass +.Ql ./- +instead. +Using standard input or output for more than one file in a single command may produce unexpected results. +.Pp +.Nm +accepts decimal, hexadecimal, octal, and binary for numeric option arguments. +Decimal numbers are written as usual; hexadecimal numbers must be prefixed with either +.Ql $ +or +.Ql 0x ; +octal numbers must be prefixed with either +.Ql & +or +.Ql 0o ; +and binary numbers must be prefixed with either +.Ql % +or +.Ql 0b . +(The prefixes +.Ql $ +and +.Ql & +will likely need escaping or quoting to avoid being interpreted by the shell.) +Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. +For example, all of these are equivalent: +.Ql 42 , +.Ql 042 , +.Ql 0x2A , +.Ql 0X2A , +.Ql 0x2a , +.Ql &52 , +.Ql 0o52 , +.Ql 0O052 , +.Ql 0b00101010 , +.Ql 0B101010 . +.Pp +The following options are accepted: .Bl -tag -width Ds .It Fl B Ar param , Fl \-backtrace Ar param Configures how location backtraces are printed if warnings or errors occur.