[DRAFT] Our man page is currently unmaintained - do not install it by FeralChild64 · Pull Request #2820 · dosbox-staging/dosbox-staging

FeralChild64 · 2023-09-02T09:30:36Z

Related to discussion in #2574

Since no one wants to maintain the man page, we shouldn't provide it - outdated documentation causes too much confusion.

I didn't delete the file completely (just moved to outdated subdirectory), as maybe it will be worth to bring it back at some point - but definitely in a revised form (maybe autogenerated from other documentation?), the current one contains too much detailed information instead of pointing the user to the intro command or the online documentation.

[edit] Changed back to draft, as @Grounded0 volunteered to have a look into the man page :)

Grounded0 · 2023-09-02T09:32:31Z

I could rewrite it.

Grounded0 · 2023-09-02T09:55:27Z

Parts of it are around 10 years out of date. 😁

Grounded0 · 2023-09-02T09:55:59Z

I will rewrite this. Expect few days turnaround and i post it here for review.

johnnovak · 2023-09-02T10:27:10Z

@Grounded0 We have already established that we don't need a man page, so let's just nuke it. It's wasted effort...

FeralChild64 · 2023-09-02T11:02:26Z

@johnnovak I did some search, and I'm afraid we need a man page. See here:

https://qa.debian.org/man-pages.html

As per Debian's Policy, every executable file in Debian has to supply a man page. However, many packages don't follow this requirement yet. Below is a listing of all executables for which no corresponding man page is available yet. If you use any of these packages listed below, please consider writing a man page for its executable files and submit it to the Bug Tracking System (BTS)

I would prefer not to upset Debian devs - their distro forms a base for such popular ones like Ubuntu or Mint, and Linux has probably the highest percentage of tech-savy users (read: potential contributors) among the systems we support. So the effort of @Grounded0 definitely won't be wasted.

The catch is we need a man page that isn't too hard to maintain. My proposals:

INTERNAL COMMANDS section should mention intro, maybe help or exit - this is enough
maybe we could synchronize the description of available options with the list printed out by dosbox -h command?
we do not need to keep the list of all the keyboard shortcuts in the man page - it is enough to mention a few most important ones, like exiting the emulator, switching between windowed and fullscreen mode, mouse grab/ungrab
our source code should contain comments in appropriate places, like this particular keyboard shortcut is documented in our man page; if you change it, please update it too - this will prevent the man page from being outdated in the future

Grounded0 · 2023-09-02T11:39:11Z

Here's a start... Already nuked all the performance sections as around 10 years out of date. Nroff sucks.

johnnovak · 2023-09-02T12:05:20Z

Yeah if you guys think it's important to have one for Linux and you're willing to maintain it going forward, who am I to say no 😄

What you wrote sounds like a reasonable compromise @FeralChild64 and @Grounded0. Just start with some bare essentials, then the user manual will have a much more detailed section on the CLI options anyway, at which point you can simply lift content from the manual into the man pages. But yeah, you can come up with something in the interim that fills the gaps.

johnnovak · 2023-09-02T12:08:16Z

Here's a start... Already nuked all the performance sections as around 10 years out of date. Nroff sucks.

Just a tip: @weirddan455 and myself have normalised the CLI options and came up with better descriptions, so now two dashes is the standard for long form options, and single dash for the abbreviations. Single dashes are still accepted for the long options, but we should not really "advertise" that as that's for legacy compatibility only. Maybe just mention it somewhere at the end once and hopefully not too many people will find it 😄

Grounded0 · 2023-09-02T14:07:06Z

Rewrote:
Metadata ✅
NAME ✅
SYNOPSIS ✅
DESCRIPTION ✅
OPTIONS ✅
INTERNAL COMMANDS ✅
FILES ✅
SPECIAL KEYS ✅
NOTES ✅
ENVIRONMENT ✅
BUGS ✅
SEE ALSO ✅
AUTHOR ✅

man page file (nroff):
dosbox.1.txt

You can view man page files at least with man program distributed with Linux like this:

$ man -l dosbox.1.txt

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  <configfile>]
       [--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 DOSBox.

       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 automatically. 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 soundfont=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  sys‐
       tems 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 di‐
       rectory)  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_CON‐
       FIG_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 config‐
       file).  The directory has to exist prior to starting dosbox else nothing 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 com‐
       puter, there is no standard.

ENVIRONMENT
       Any configuration option can be override using an environment variable.   Environment  variables
       starting with prefix DOSBOX are processed and interpreted as follows: DOSBOX_SECTIONNAME_PROPER‐
       TYNAME=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-staging/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-stag‐
       ing.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)

johnnovak · 2023-09-03T06:09:16Z

Quick feedback @Grounded0. Got bored about 30% in, but better than nothing 😄

This would be better ("C drive"):
"run with the directory mounted as the C drive."

Add comma:
"For an introduction, type INTRO inside DOSBox Staging."

Remove it, it's a redundant sentence (we're in the OPTIONS section).
"A summary of options is included below."

All options in the OPTIONS section use single dashes; please use --.

The options listed in SYNOPSIS and OPTIONS are not in sync.

"tandy Tandy Graphics Adapter (Tandy 1000)"
This emulates a whole tandy machine, not just the graphics adapter (e.g., it
also turns on Tandy sound, and the whole Tandy BIOS and memory mapping is
different, etc.)

"
svga_paradise
VESA SVGA - Paradise Systems PVGA1A - VBE 2.0

svga_et3000
VESA SVGA - Tseng ET3000 - VBE 2.0

svga_et4000
VESA SVGA - Tseng ET4000 - VBE 2.0
"

These are all pre-VESA SVGA cards; none of them support VESA at all. Please remove 'VBE 2.0' from all of them.

"The machinetype affects the video card and the available sound cards."

Kinda/sorta, but it's murky. I'd remove this sentence.

"Runs the specified command before running file."

FILE (uppercase)

"Each command should start with -c though."
Remove 'though'.

" -exit dosbox will close itself when the DOS program specified by file
ends."

DOSBox

Grounded0 · 2023-09-03T06:19:41Z

I've marked the sections i've worked over with ✅ in the index. All other issues addressed.

johnnovak · 2023-09-03T06:43:10Z

I've marked the sections i've worked over with ✅ in the index. All other issues addressed.

Sure.

One more:

If it is a dos executable, (.com .exe .bat) the program will run automatically.

Should be;

If it is a DOS executable (.COM, .EXE, or .BAT file extension), the program will run automatically.

Grounded0 · 2023-09-03T07:11:40Z

FeralChild64

Are those SPECIAL KEYS still the same on Linux? I can't check since i'm on macOS.

Grounded0 · 2023-09-03T13:43:25Z

kcgen already helped with Linux default keymap.

INTERNAL COMMANDS left to do.

Grounded0 · 2023-09-04T06:09:51Z

@kcgen @johnnovak @FeralChild64

Ready for review.

FeralChild64 · 2023-09-04T08:36:57Z

dosbox - DOSBox Staging, a modern continuation of DOSBox

I would change it to something like:

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

INTERNAL COMMANDS

mem and keyb commands should be omitted here, in my opinion

a file named dosbox.conf

Isn’t it called dosbox-staging.com? I’m not at home at the moment, so I can’t check.

AUTHOR

Don’t forget to add yourself :)

Torinde · 2023-09-04T09:06:20Z

Isn’t it called dosbox-staging.com?

It is: dosbox-staging.conf

Grounded0 · 2023-09-04T09:25:20Z

@FeralChild64

All issues addressed.

Grounded0 · 2023-09-04T09:39:17Z

If anyone else has no further objections feel free to merge it and close this ticket.

johnnovak · 2023-09-04T09:42:26Z

Looks good @Grounded0, great job and it's not overdone 👍🏻 The period is missing from the end of the first sentence in the DESCRIPTION section.

Btw, I'd drop this full justification attempt if I were you. It looks like crap with monospaced fonts 😄 Just left-justify.

$ DOSBOX_SBLASTER_SBTYPE=sbpro2 dosbox – is still still supported? I have no idea.

Grounded0 · 2023-09-04T09:58:36Z

@johnnovak

Missing period added.

Text formatting is nroff text-formatting language interpreted by man and universally like that. See man emacs for example.

This Linux stuff needs to be tested by someone with Linux.

johnnovak · 2023-09-04T10:44:06Z

Text formatting is nroff text-formatting language interpreted by man and universally like that. See man emacs for example.

man ls gives me this. No bad looking full-justify.

Grounded0 · 2023-09-04T10:54:38Z

Guess i have to learn more about badly documented text-formatting language developed at Bell Labs in 1970s than i ever wanted to.

Grounded0 · 2023-09-04T11:29:42Z

"By default, nroff and troff both fill and justify text. Justification implies filling, but it is possible to have filling without justification.":

https://www.oreilly.com/library/view/unix-text-processing/9780810462915/Chapter04.html

Diverging from this will significantly increase document maintenance burden in the future. Reason why larger man pages like GNU Emacs use defaults is to reduce document maintenance burden.

It will significantly increase the amount of markup to hack this together which i will not do. If someone wants to do this they can do it on their own volition. Historically this document was fill and justify.

kcgen · 2023-09-04T15:01:01Z

"By default, nroff and troff both fill and justify text. Justification implies filling, but it is possible to have filling without justification.":

https://www.oreilly.com/library/view/unix-text-processing/9780810462915/Chapter04.html

Diverging from this will significantly increase document maintenance burden in the future. Reason why larger man pages like GNU Emacs use defaults is to reduce document maintenance burden.

Thanks for these references @Grounded0, and agree to follow this pathway (very similar to PR's using the code-formatter for source). It might not always be to our personal tastes, but it's standardized, and that brings predictability for readers across all the man pages.

Grounded0 · 2023-09-05T14:32:08Z

If anyone else has no further objections feel free to merge it and close this ticket.

kcgen · 2023-09-05T15:09:52Z

Merging.
@Grounded0 , when we merge your updated man page PR, I will revert this commit to re-activate its installation.

Grounded0 · 2023-09-05T16:51:45Z

@kcgen

All issues addressed.

man page file (nroff):
dosbox.1.txt

You can view man page files at least with man program distributed with Linux like this:

$ man -l dosbox.1.txt

Grounded0 · 2023-09-08T13:59:45Z

Closed by:

Update the Linux man page #2837

Do not install outdated and unmaintained man page

0412bd9

FeralChild64 added the documentation Improvements or additions to documentation label Sep 2, 2023

FeralChild64 requested review from johnnovak and kcgen September 2, 2023 09:30

FeralChild64 self-assigned this Sep 2, 2023

FeralChild64 marked this pull request as draft September 2, 2023 09:56

FeralChild64 changed the title ~~Our man page is currently unmaintained - do not install it~~ [DRAFT] Our man page is currently unmaintained - do not install it Sep 2, 2023

kcgen approved these changes Sep 5, 2023

View reviewed changes

kcgen marked this pull request as ready for review September 5, 2023 15:09

kcgen merged commit 693e040 into main Sep 5, 2023

Grounded0 mentioned this pull request Sep 6, 2023

Update the Linux man page #2837

Merged

FeralChild64 deleted the fc/man-outdated-1 branch September 21, 2023 19:21

Grounded0 mentioned this pull request Nov 17, 2023

DOSBox Staging 0.81 release steering ticket #3091

Closed

4 tasks

Grounded0 mentioned this pull request Apr 26, 2024

Manpage and help are outdated #1983

Closed

Uh oh!

Conversation

FeralChild64 commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 2, 2023

Uh oh!

Grounded0 commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnnovak commented Sep 2, 2023

Uh oh!

FeralChild64 commented Sep 2, 2023

Uh oh!

Grounded0 commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnnovak commented Sep 2, 2023

Uh oh!

johnnovak commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnnovak commented Sep 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 3, 2023

Uh oh!

johnnovak commented Sep 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 4, 2023

Uh oh!

FeralChild64 commented Sep 4, 2023

Uh oh!

Torinde commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnnovak commented Sep 4, 2023

Uh oh!

Grounded0 commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnnovak commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 4, 2023

Uh oh!

kcgen commented Sep 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 5, 2023

Uh oh!

kcgen commented Sep 5, 2023

Uh oh!

Grounded0 commented Sep 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Grounded0 commented Sep 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

FeralChild64 commented Sep 2, 2023 •

edited

Loading

Grounded0 commented Sep 2, 2023 •

edited

Loading

Grounded0 commented Sep 2, 2023 •

edited

Loading

Grounded0 commented Sep 2, 2023 •

edited

Loading

johnnovak commented Sep 2, 2023 •

edited

Loading

Grounded0 commented Sep 2, 2023 •

edited

Loading

johnnovak commented Sep 3, 2023 •

edited

Loading

johnnovak commented Sep 3, 2023 •

edited

Loading

Grounded0 commented Sep 3, 2023 •

edited

Loading

Grounded0 commented Sep 3, 2023 •

edited

Loading

Torinde commented Sep 4, 2023 •

edited

Loading

Grounded0 commented Sep 4, 2023 •

edited

Loading

Grounded0 commented Sep 4, 2023 •

edited

Loading

Grounded0 commented Sep 4, 2023 •

edited

Loading

johnnovak commented Sep 4, 2023 •

edited

Loading

Grounded0 commented Sep 4, 2023 •

edited

Loading

kcgen commented Sep 4, 2023 •

edited

Loading

Grounded0 commented Sep 5, 2023 •

edited

Loading

Grounded0 commented Sep 8, 2023 •

edited

Loading