Update the Linux man page

[kcgen]

text format:

DOSBOX(1)                        General Commands Manual                       DOSBOX(1)

NAME
       dosbox - DOSBox Staging, x86/DOS emulator, a modern continuation of DOSBox

SYNOPSIS
       dosbox [--fullscreen] [--startmapper] [--noautoexec] [--securemode] [--conf <con‐
       figfile>] [--lang <langfile>] [--machine <type>] [--socket <num>] [-c  <command>]
       [--exit] [FILE]

       dosbox --help

       dosbox --version

       dosbox --printconf

       dosbox --editconf

       dosbox --eraseconf

       dosbox --noprimaryconf

       dosbox --nolocalconf

       dosbox --set <property>=<value>

       dosbox --working-dir <path>

       dosbox --list-glshaders

       dosbox --erasemapper

       dosbox --opencaptures

DESCRIPTION
       This  manual page briefly documents DOSBox Staging, a modern continuation of DOS‐
       Box.

       The optional FILE argument should be a DOS executable or a directory. If it is  a
       DOS  executable  (.COM, .EXE, or .BAT file extension), the program will run auto‐
       matically. If it is a directory, a  DOS  session  will  run  with  the  directory
       mounted as the C drive.

       For an introduction, type INTRO inside DOSBox Staging.

       The document will refer to DOSBox Staging as dosbox from now on for readability.

OPTIONS
       Legacy single dash abbrevations still work for backwards compatibility.

       --conf <configfile>      Start with the options specified in <configfile>.
                                Multiple configfiles can be specified.
                                Example: --conf conf1.conf --conf conf2.conf

       --printconf              Print the location of the default configuration file.
                                If it does not exist, create it.

       --editconf               Open the default configuration file in a text editor.

       --eraseconf              Delete the default configuration file.

       --noprimaryconf          Don't read settings from the default configuration file
                                located in your user folder.

       --nolocalconf            Don't read settings from "dosbox.conf" if present in
                                the current working directory.

       --set <property>=<value> Set a configuration property.
                                Example:   --set   mididevice=fluidsynth   --set  sound‐
       font=mysoundfont.sf2

       --working-dir <path>     Set working directory to <path>. DOSBox will act as if
                                started from this directory.

       --list-glshaders         List available GLSL shaders and their directories.
                                Results are useable in the "glshader = " config setting.

       --fullscreen             Start in fullscreen mode.

       --lang <langfile>        Start with the language specified in <langfile>.

       --machine <type>         Emulate a specific type of machine. The machine type has
                                influence on both the emulated video and sound cards.
                                Valid choices are: hercules, cga, cga_mono, tandy,
                                pcjr, ega, svga_s3 (default), svga_et3000, svga_et4000,
                                svga_paradise, vesa_nolfb, vesa_oldvbe.

       -c <command>             Run the specified DOS command before running FILE.
                                Multiple commands can be specified.

       --noautoexec             Don't execute any [autoexec] actions.

       --exit                   Exit after the DOS program specified by FILE has ended.
                                If no FILE has been specified, execute [autoexcec] and
                                terminate.

       --startmapper            Run the mapper GUI.

       --erasemapper            Delete the default mapper file.

       --securemode             Enable secure mode. The [config] and [autoexec] sections
                                of the loaded configuration file will be skipped,
                                and commands such as MOUNT and IMGMOUNT are disabled.

       --socket <num>           Run nullmodem on the specified socket number.

       --opencaptures           Call program with as first parameter the location of the
                                captures folder.

       --help                   Print help message and exit.

       --version                Print version information and exit.

INTERNAL COMMANDS
       dosbox has a comprehensive internal help system which can be accessed by  running
       HELP command.

       dosbox  supports  most of the DOS commands found in COMMAND.COM. In addition, the
       following extra commands are frequently used:

       MOUNT

       Program to mount local directories as drives inside dosbox.

       IMGMOUNT

       A utility to mount disk images and CD‐ROM images in dosbox.

       CONFIG

       Change dosbox internal configuration on the fly. May not work with all options.

       LOADFIX

       Program to reduce the amount of  memory available. Useful for old programs  which
       don't expect much memory to be free.

       RESCAN

       Make  dosbox reread the directory structure. Useful if you changed something on a
       mounted drive outside dosbox. Ctrl+F4 does this as well.

       BOOT

       BOOT will start floppy images or hard disk images independent  of  the  operating
       system  emulation  offered by dosbox. This will allow you to play booter floppies
       or boot to other operating systems inside dosbox.

FILES
       Configuration and language files use a format similar to Windows .ini files.   If
       no  configfile  is specified at the commandline, a file named dosbox-staging.conf
       (if present in the current directory) will be  loaded automatically. We also will
       read and load dosbox.conf locally too, if dosbox-staging.conf isn't present.

       If a configfile is specified at the commandline that one will be used instead. If
       no configfile is specified or found in the current directory   then  dosbox  will
       load one from $XDG_CONFIG_HOME/dosbox/  (which defaults to ~/.config/dosbox/). It
       will try to create a new default config file if it does not exist yet.

SPECIAL KEYS
       Alt+Enter   Switch between fullscreen and window mode.

       Alt+Pause   Pause/Unpause emulator.

       Ctrl+F1     Start the keymapper.

       Ctrl+F4     Swap mounted disk‐image (only used with imgmount).  Update  directory
                   cache for all drives.

       Ctrl+F5     Save a screenshot of the DOS pre-rendered image.

       Alt+F5      Save a screenshot of the rendered image.

       Ctrl+F6     Start/Stop recording sound output to a wave file.

       Ctrl+F7     Start/Stop recording video output to a zmbv file.

       Ctrl+F8     Mute/Unmute the audio.

       Ctrl+F9     Kill dosbox.

       Ctrl+F10    Capture/Release the mouse.

       Ctrl+F11    Slow down emulation (Decrease number of cycles/s).

       Ctrl+F12    Speed up emulation (Increase number of cycles/s).

       Alt+F12     Unlock speed (turbo button).

       These  are  the  default  keybindings. They can be changed in the keymapper. More
       bindable actions can be found in the keymapper.

NOTES
       Saved/recorded files can be found in current_directory/capture (can be changed in
       the  configfile).  The directory has to exist prior to starting dosbox else noth‐
       ing gets saved/recorded !

       Once you increase your dosbox cycles beyond your computer's maximum capacity,  it
       will  produce  the  same effect as slowing down the emulation.  This maximum will
       vary from computer to computer, there is no standard.

ENVIRONMENT
       Any configuration option can be override using an environment variable.  Environ‐
       ment  variables starting with prefix DOSBOX are processed and interpreted as fol‐
       lows: DOSBOX_SECTIONNAME_PROPERTYNAME=value

       For example, you can override Sound Blaster type to Sound Blaster Pro 2 this way:

       $ DOSBOX_SBLASTER_SBTYPE=sbpro2 dosbox

BUGS
       To report  a  bug,  please  visit  https://github.com/dosbox-staging/dosbox-stag‐
       ing/issues

SEE ALSO
       You'll  find  long  and  detailed manual in README file in /usr/share/doc/dosbox-
       staging

AUTHOR
       DOSBox Staging project is maintained by the DOSBox Staging Team  (https://dosbox-
       staging.github.io/)

       This  manual page was written by Peter Veenstra <H.P.Veenstra@student.rug.nl> and
       James Oakley <jfunk@funktronics.ca>, for the Debian system (but may  be  used  by
       others),  updated  by  Patryk  Obara  <dreamer.tan@gmail.com>  and  Antti Peltola
       <antti.peltola@kolumbus.fi> for DOSBox Staging project.

                                       Sep 2, 2023                             DOSBOX(1)

[kcgen]

Thanks, @Grounded0 !

[kcgen]

Reviewed and approved on my side.
Will wait for any other comments, then merge tomorrow.

[kcgen]

@Grounded0
All issues addressed.

Ok; merging if the prior feedback was addressed. Can always make point-fixes after.

[Grounded0]

Added a lot of context above for future maintainers of the man page since this will become outdated yet again.

Since nroff is a text-formatting language developed at Bell Labs in the 1970s this helped me a lot to author this man page:

O'Reilly: UNIX° TEXT PROCESSING by nroff and troff

At least Emacs has an nroff mode which will make authoring man pages significantly easier. I used Emacs to author this man page:

Nroff Mode (GNU Emacs Manual)

More about nroff:

nroff - Wikipedia