summaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2021-05-07 03:41:10 +1000
committer Vas Crabb <vas@vastheman.com>2021-05-07 03:41:10 +1000
commit73cd2b55b876dbf57b8318fa6ae46b0c268d547f (patch)
tree824731933951bf65e57eddb3c842d86b349bac4c
parentfc77338e37b416d1fbf1f17409a81aa8039d3fed (diff)
Docmumentation update/expansion. [Firehawke, Vas Crabb]
-rw-r--r--docs/source/initialsetup/compilingmame.rst105
-rw-r--r--docs/source/initialsetup/configuringmame.rst77
-rw-r--r--docs/source/initialsetup/index.rst4
-rw-r--r--docs/source/initialsetup/installingmame.rst12
-rw-r--r--docs/source/initialsetup/mameintro.rst118
-rw-r--r--docs/source/license.rst13
-rw-r--r--docs/source/usingmame/mamemenus.rst4
-rw-r--r--docs/source/usingmame/usingmame.rst91
8 files changed, 326 insertions, 98 deletions
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index a00fc77460b..51d63588149 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -19,11 +19,11 @@ All Platforms
difficult to troubleshoot problems.
* If you want to add various additional tools to the compile, such as
- *CHDMAN*, add a **TOOLS=1** to your make statement, like
+ *chdman*, add a **TOOLS=1** to your make command, like
**make REGENIE=1 TOOLS=1**
* You can do driver specific builds by using *SOURCES=<driver>* in your
- make statement. For instance, building Pac-Man by itself would be
+ make command. For instance, building Pac-Man by itself would be
**make SOURCES=src/mame/drivers/pacman.cpp REGENIE=1** including the
necessary *REGENIE* for rebuilding the settings.
@@ -33,7 +33,7 @@ All Platforms
An excessive number of concurrent jobs may increase compilation time.
The optimal number depends on many factors, including number of CPU
cores, available RAM, disk and filesystem performance, and memory
- bandwidh.* For instance, **make -j5** is a good starting point on a
+ bandwidth.* For instance, **make -j5** is a good starting point on a
system with a quad-core CPU.
* Debugging information can be added to a compile using *SYMBOLS=1*
@@ -160,7 +160,11 @@ Building with Microsoft Visual Studio
* Adding **MSBUILD=1** to the make options will build the solution using
the Microsoft Build Engine after generating the project files. Note that this
requires paths and environment variables to be configured so the correct
- Visual Studio tools can be located.
+ Visual Studio tools can be located; please refer to the Microsoft-provided
+ instructions on `using the Microsoft C++ toolset from the command line
+ <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line>`_.
+ You may find it easier to not use **MSBUILD=1** and load the project file into
+ Visual Studio’s GUI for compilation.
* The MSYS2 environment is still required to generate the project files, convert
built-in layouts, compile UI translations, etc.
@@ -264,7 +268,8 @@ Apple macOS
-----------
You’ll need a few prerequisites to get started. Make sure you’re on OS X 10.14
-Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will need SDL2 2.0.4 or later for Intel or SDL2 2.0.14 on Apple Silicon.
+Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will
+need SDL2 2.0.4 or later for Intel or SDL2 2.0.14 on Apple Silicon.
* Install **Xcode** from the Mac App Store or `ADC <https://developer.apple.com/download/more/>`_ (AppleID required).
* To find the corresponding Xcode for your MacOS release please visit `xcodereleases.com <https://xcodereleases.com>`_ to find the latest version of Xcode available to you.
@@ -275,9 +280,13 @@ Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will
Next you’ll need to get SDL2 installed.
-* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the *Mac OS X* .dmg file
-* If the .dmg doesn’t auto-open, open it
-* Click “Macintosh HD” (your Mac’s hard disk) in the Locations sidebar of a **Finder** window, then open the **Library** folder and drag the **SDL2.framework** folder from the SDL disk image into the **Frameworks** folder. You will have to authenticate with your user password.
+* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the
+ *macOS* .dmg file
+* If the .dmg doesn’t open automatically, open it
+* Click “Macintosh HD” (or whatever your Mac’s hard disk is named) in the left
+ pane of a **Finder** window, then open the **Library** folder and drag the
+ **SDL2.framework** folder from the SDL disk image into the **Frameworks**
+ folder. You will have to authenticate with your user password.
Lastly to begin compiling, use Terminal to navigate to where you have the MAME
source tree (*cd* command) and follow the normal compilation instructions from
@@ -290,13 +299,13 @@ Emscripten Javascript and HTML
------------------------------
First, download and install Emscripten 1.37.29 or later by following the
-instructions at the `official site <https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`_
+instructions at the `official site <https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`_.
Once Emscripten has been installed, it should be possible to compile MAME
-out-of-the-box using Emscripten’s **emmake** tool. Because a full MAME compile
-is too large to load into a web browser at once, you will want to use the
-**SOURCES** parameter to compile only a subset of the project, e.g. (in the mame
-directory):
+out-of-the-box using Emscripten’s **emmake** tool. Because a full MAME
+compile is too large to load into a web browser at once, you will want to use
+the SOURCES parameter to compile only a subset of the project, e.g. (in the
+MAME directory):
.. code-block:: bash
@@ -316,12 +325,12 @@ The value of the **SUBTARGET** parameter serves only to differentiate multiple
builds and need not be set to any specific value.
Emscripten supports compiling to WebAssembly with a JavaScript loader instead of
-all-JavaScript, and in later versions this is actually the default. To force
+all-JavaScript, and in later versions this is actually the default. To force
WebAssembly on or off, add **WEBASSEMBLY=1** or **WEBASSEMBLY=0** to the make
-command line.
+command line, respectively.
-Other make parameters can also be used, e.g. **-j** for parallel compilation, as
-described earlier.
+Other make parameters can also be used, e.g. **-j** for multithreaded
+compilation as described earlier.
When the compilation reaches the emcc phase, you may see a number of
*"unresolved symbol"* warnings. At the moment, this is expected for
@@ -335,7 +344,8 @@ not used at run-time.
If all goes well, a **.js** file will be output to the current directory. This
file cannot be run by itself, but requires an HTML loader to provide it with a
canvas to draw to and to pass in command-line parameters. The
-`Emularity project <https://github.com/db48x/emularity>`_ provides such a loader.
+`Emularity project <https://github.com/db48x/emularity>`_ provides such a
+loader.
There are example **.html** files in that repository which can be edited to
point to your newly compiled MAME **.js** file and pass in whatever parameters
@@ -367,36 +377,61 @@ Compiling the Documentation
Compiling the documentation will require you to install several packages
depending on your operating system.
-On Debian/Ubuntu flavors of Linux, you’ll need python3-sphinx/python-sphinx
-and the python3-pip/python-pip packages, depending on whether you’re using
-Python 3 or Python 2::
+.. _compiling-docs-windows:
- sudo apt-get install python3-sphinx python3-pip
+Compiling the Documentation on Microsoft Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-or::
+On Windows, you’ll need a couple of packages from the MSYS2 environment. You
+can install these packages with
- sudo apt-get install python-sphinx python-pip
+.. code-block:: bash
+
+ pacman -S mingw-w64-x86_64-librsvg mingw-w64-x86_64-python-sphinx mingw-w64-x86_64-python-sphinxcontrib-svg2pdfconverter
+
+Note that no LaTeX packages currently exist for MSYS2 so you will not be able to
+generate a PDF file without using external tools.
-You’ll then need to install the SVG handler::
+.. _compiling-docs-debian:
+Compiling the Documentation on Debian and Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Debian/Ubuntu flavors of Linux, you’ll need **python3-sphinx/python-sphinx**
+and the **python3-pip/python-pip** packages:
+
+.. code-block:: bash
+
+ sudo apt-get install python3-sphinx python3-pip
pip3 install sphinxcontrib-svg2pdfconverter
-or::
+or
+.. code-block:: bash
+
+ sudo apt-get install python-sphinx python-pip
pip install sphinxcontrib-svg2pdfconverter
depending on whether you’re using Python 3 or Python 2.
-If you intend on making a PDF via LaTeX, you’ll need to install a LaTeX
-distribution such as TeX Live::
+On Debian, you’ll need to install the **librsvg2-bin** package:
+
+.. code-block:: bash
+
+ sudo apt-get install librsvg2-bin
+
+If you intend to make a PDF via LaTeX, you’ll need to install a LaTeX
+distribution such as TeX Live:
+
+.. code-block:: bash
- sudo apt-get install latexmk texlive texlive-science texlive-formats-extra
+ sudo apt-get install librsvg2-bin latexmk texlive texlive-science texlive-formats-extra
-From this point, you can do **make html** or **make latexpdf** from the docs
-folder to generate the output of your choice. Typing **make** by itself will
-tell you all available formats. The output will be in the docs/build folder in
-a subfolder based on the type chosen (e.g. **make html** will create
-*docs/build/html* containing the output).
+From this point you can do ``make html`` or ``make latexpdf`` from the **docs**
+folder to generate the output of your choice. Typing ``make`` by itself will
+tell you all available formats. The output will be in the docs/build folder in
+a subfolder based on the type chosen (e.g. ``make html`` will create
+*docs/build/html* with the output.)
.. _compiling-options:
@@ -464,7 +499,7 @@ NO_USE_PORTAUDIO
Set to **1** to disable building the PortAudio sound output module.
USE_QTDEBUG
Set to **1** to include the Qt debugger on platforms where it’s not built by
- default (e.g. Windows or MacOS), or to **0** to disable it. You’ll need to
+ default (e.g. Windows or macOS), or to **0** to disable it. You’ll need to
install Qt development libraries and tools to build the Qt debugger. The
process depends on the platform.
diff --git a/docs/source/initialsetup/configuringmame.rst b/docs/source/initialsetup/configuringmame.rst
new file mode 100644
index 00000000000..3a0c8830cdf
--- /dev/null
+++ b/docs/source/initialsetup/configuringmame.rst
@@ -0,0 +1,77 @@
+Configuring MAME
+================
+
+.. contents:: :local:
+
+Getting Started: A Quick Preface
+--------------------------------
+
+Once you have MAME installed, the next step is to configure it. There are
+several ways to do this, and each will be covered in turn.
+
+If you are on Windows, the MAME executable will be called ``mame.exe``.
+
+If you are on Linux or MacOS, the MAME executable will be called ``mame``.
+
+
+Initial Setup: Creating mame.ini From Command Line on Windows
+-------------------------------------------------------------
+
+First, you will need to *cd* to the directory where you installed MAME into.
+If, for instance, you have MAME installed in ``C:\Users\Public\MAME`` you will
+need to type ``cd C:\Users\Public\MAME`` into the command prompt.
+
+Then you have MAME create the config file by typing ``mame64 -createconfig``
+or ``mame -createconfig`` depending on if you are using the 64-bit version of
+MAME or the 32-bit version.
+
+MAME will then create the ``mame.ini`` file in the MAME installation folder.
+This file contains the default configuration settings for a new MAME
+installation.
+
+
+Initial Setup: Creating mame.ini From Command Line on Linux or MacOS
+--------------------------------------------------------------------
+
+The steps for Linux and MacOS are similar to those of Windows. If you
+installed MAME using the package manager that came from a Linux distro, you will
+type ``mame64 -createconfig`` or ``mame -createconfig`` into your terminal
+of choice, depending on if you have a 64-bit version of MAME or a 32-bit
+one.
+
+If you have compiled from source or downloaded a binary package of MAME,
+you will ``cd`` into the directory you put the MAME files into.
+
+For instance, ``cd /home/myusername/mame``
+
+Then you will type ``./mame64 -createconfig`` or ``./mame -createconfig`` into
+your terminal of choice, depending on if you have a 64-bit version of MAME or a
+32-bit one.
+
+You can then need to edit the ``mame.ini`` file in your favorite text editor,
+e.g. *Notepad* on Windows or *vi* on Linux/MacOS, or you can change settings
+from inside of MAME.
+
+
+Initial Setup: Graphical Setup
+------------------------------
+
+This is the easiest way to get started. Start MAME by opening the MAME icon
+in the location where you installed it. This will be ``mame64.exe`` or
+``mame.exe`` on Windows, ``mame64`` or ``mame`` on Linux and macOS.
+
+Once MAME has started, you can either use your mouse to click on the
+**Configure Options** menu selection at the bottom center of your screen,
+or you can switch panes to the bottom one (default key is Tab), then press
+the menu accept button (default key is Return/Enter) to go into the
+Configuration menu.
+
+Choose **Save Configuration** to create the ``mame.ini`` file with default
+settings. From here, you can either continue to configure things from the
+graphical user interface or edit the ``mame.ini`` file in your favorite
+text editor.
+
+
+Configuring MAME
+----------------
+
diff --git a/docs/source/initialsetup/index.rst b/docs/source/initialsetup/index.rst
index bd3b3a0d80d..32319dd7367 100644
--- a/docs/source/initialsetup/index.rst
+++ b/docs/source/initialsetup/index.rst
@@ -1,7 +1,8 @@
Getting MAME prepared
---------------------
-This section covers initial preparation work needed to use MAME, including downloading and compiling MAME.
+This section covers initial preparation work needed to use MAME, including
+downloading MAME, compiling MAME from source, and configuring MAME.
.. toctree::
:titlesonly:
@@ -9,3 +10,4 @@ This section covers initial preparation work needed to use MAME, including downl
mameintro
installingmame
compilingmame
+ configuringmame
diff --git a/docs/source/initialsetup/installingmame.rst b/docs/source/initialsetup/installingmame.rst
index 3ace07ade80..c276b3d7a5c 100644
--- a/docs/source/initialsetup/installingmame.rst
+++ b/docs/source/initialsetup/installingmame.rst
@@ -4,10 +4,18 @@ Installing MAME
Microsoft Windows
-----------------
-You simply have to download the latest binary archive available from http://www.mamedev.org and to extract its content to a folder. You will end up with many files (below you will find explanations about some of these), and in particular ``MAME.EXE``. This is a command line program. The installation procedure ends here. Easy, isn't it?
+You simply have to download the latest binary archive available from
+http://www.mamedev.org and to extract its content to a folder. You will end up
+with many files (below you will find explanations about some of these), and in
+particular **mame.exe**. This is a command line program. The installation
+procedure ends here. Easy, isn’t it?
Other Operating Systems
-----------------------
-In this case, you can either look for pre-compiled (SDL)MAME binaries (e.g. in the repositories of your favorite Linux distro) which should simply extract all the needed files in a folder you choose, or compile the source code by yourself. In the latter case, see our section on :ref:`compiling-all`.
+In this case, you can either look for pre-compiled (SDL)MAME binaries (e.g. in
+the repositories of your favorite Linux distro) which should simply extract all
+the needed files in a folder you choose, or compile the source code by
+yourself. In the latter case, see our section on
+:ref:`compiling MAME <compiling-all>`.
diff --git a/docs/source/initialsetup/mameintro.rst b/docs/source/initialsetup/mameintro.rst
index b63a6b3beda..61be99b68a9 100644
--- a/docs/source/initialsetup/mameintro.rst
+++ b/docs/source/initialsetup/mameintro.rst
@@ -1,64 +1,122 @@
An Introduction to MAME
-=======================
+-----------------------
-MAME, formerly was an acronym which stood for Multi Arcade Machine Emulator, documents and reproduces through emulation the inner components of arcade machines, computers, consoles, chess computers, calculators, and many other types of electronic amusement machines. As a nice side-effect, MAME allows to use on a modern PC those programs and games which were originally developed for the emulated machines.
+MAME, formerly an acronym which stood for Multi Arcade Machine Emulator,
+documents and reproduces through emulation the inner components of arcade
+machines, computers, consoles, chess computers, calculators, and many other
+types of electronic amusement machines. As a nice side-effect, MAME allows to
+use on a modern PC those programs and games which were originally developed for
+the emulated machines.
-At one point there were actually two separate projects, MAME and MESS. MAME covered arcade machines, while MESS covered everything else. They are now merged into the one MAME.
+At one point there were actually two separate projects, MAME and MESS. MAME
+covered arcade video games, while MESS covered home and business systems. They
+are now merged into the one MAME.
-MAME is mostly programmed in C with some core components in C++. MAME can currently emulate over 32000 individual systems from the last 5 decades.
+MAME is written in C++ and can currently emulate over 32,000 individual systems
+from the last five decades.
Purpose of MAME
-===============
+---------------
-The primary purpose of MAME is to preserve decades of arcade, computer, and console history. As technology continues to rush forward, MAME prevents these important “vintage” systems from being lost and forgotten.
+The primary purpose of MAME is to preserve decades of arcade, computer, and
+console history. As technology continues to rush forward, MAME prevents these
+important “vintage” systems from being lost and forgotten.
Systems Emulated by MAME
-========================
-
-
-ProjectMESS contains a complete list of the systems currently emulated. As you will notice, being supported does not always mean that the status of the emulation is perfect. You may want
-
-1. to check the status of the emulation in the wiki pages of each system, accessible from the drivers page (e.g. for Apple Macintosh, from the page for the mac.c driver you can reach the pages for both **macplus** and **macse**),
-2. to read the corresponding **sysinfo.dat** entry in order to better understand which issues you may encounter while running a system in MAME (again, for Apple Macintosh Plus you have to check this entry).
-
-Alternatively, you can simply see the status by yourself, launching the system emulation and taking a look to the red or yellow warning screen which appears before the emulation starts, if any. Notice that if you have information which can help to improve the emulation of a supported system, or if you can directly contribute fixes and/or addition to the current source, you can follow the instructions at the contact page or post to the MAME Forums at http://forum.mamedev.org/
+------------------------
+
+The `Arcade Database <http://adb.arcadeitalia.net/>`_ contains a complete list
+of the systems currently emulated. As you will notice, being supported does not
+always mean that the status of the emulation is perfect. You may want
+
+1. to check the status of the emulation in the wiki pages of each system,
+ accessible from the drivers page (e.g. for Apple Macintosh, from the page for
+ the mac128.cpp driver you can reach the pages for both **macplus** and
+ **macse**),
+2. to read the corresponding **sysinfo.dat** entry in order to better understand
+ which issues you may encounter while running a system in MAME (again, for
+ Apple Macintosh Plus you have to check this entry).
+
+Alternatively, you can simply see the status by yourself, launching the system
+emulation and taking a look at the red or yellow warning screen which appears
+before the emulation starts, if any. Notice that if you have information which
+can help to improve the emulation of a supported system, or if you can directly
+contribute fixes and/or addition to the current source, you can do any of the
+following:
+
+* Send in a pull request (for code) or open an issue (information) on our
+ `GitHub page <https://github.com/mamedev/mame/>`_
+* Post the information or code on the
+ `MAME Forums <https://forum.mamedev.org/>`_
+* Follow the instructions on our
+ `contact page <https://www.mamedev.org/contact.html>`_
Supported OS
-============
-
-The current source code can be directly compiled under all the main OSes: Microsoft Windows (both with DirectX/BGFX native support or with SDL support), Linux, FreeBSD, and Mac OS X. Also, both 32-bit and 64-bit are supported, but be aware 64-bit often shows significant speed increases.
+------------
+The current source code can be directly compiled under all the main operating
+systems: Microsoft Windows (both with DirectX/BGFX native support or with SDL
+support), Linux, FreeBSD, and macOS.
System Requirements
-===================
+-------------------
-MAME is written in fairly generic C/C++, and has been ported to numerous platforms. Over time, as computer hardware has evolved, the MAME code has evolved as well to take advantage of the greater processing power and hardware capabilities offered.
+MAME is written in C++, and has been ported to numerous platforms. Over time, as
+computer hardware has evolved, the MAME code has evolved as well to take
+advantage of the greater processing power and hardware capabilities offered.
-The official MAME binaries are compiled and designed to run on a standard Windows-based system. The minimum requirements are:
+The official MAME binaries are compiled and designed to run on a standard
+Windows-based system. The minimum requirements are:
-* Intel Core series CPU or equivalent, at least 2.0 GHz
-* 32-bit OS (Vista SP1 or later on Windows, 10.9 or later on Mac)
+* Intel Core 2-series CPU or equivalent, at least 2.0 GHz
+* 64-bit OS (Windows 7 or later on Windows, macOS 10.9 or later on Mac)
* 4 GB RAM
* DirectX 9.0c for Windows
* A Direct3D, or OpenGL capable graphics card
-* Any DirectSound capable sound card/onboard audio
-Of course, the minimum requirements are just that: minimal. You may not get optimal performance from such a system, but MAME should run. Modern versions of MAME require more power than older versions, so if you have a less-capable PC, you may find that using an older version of MAME may get you better performance, at the cost of greatly lowered accuracy and fewer supported systems.
+Of course, the minimum requirements are just that: minimal. You may not get
+optimal performance from such a system, but MAME should run. Modern versions of
+MAME require more power than older versions, so if you have a less-capable PC,
+you may find that using an older version of MAME may get you better
+performance, at the cost of greatly lowered accuracy and fewer supported
+systems.
-MAME will take advantage of 3D hardware for compositing artwork and scaling the games to full screen. To make use of this, you should have a modern Direct3D 8-capable video card with at least 16MB of video RAM.
+MAME will take advantage of 3D hardware for compositing artwork and scaling
+displayed software to full screen. To make use of this, you should have at least
+a semi-modern computer with semi-modern 3D hardware made within the last five
+to ten years.
-HLSL or GLSL special effects such as CRT simulation will put a very heavy load on your video card, especially at higher resolutions. You will need a fairly powerful modern video card, and the load on your video card goes up exponentially as your resolution increases. If HLSL or GLSL are too intensive, try dropping your output resolution.
+HLSL or GLSL special effects such as CRT simulation will put a very heavy load
+on your video card, especially at higher resolutions. You will need a fairly
+powerful modern video card, and the load on your video card goes up
+exponentially as your resolution increases. If HLSL or GLSL are too intensive,
+try reducing your output resolution.
-Keep in mind that even on the fastest computers available, MAME is still incapable of playing some systems at full speed. The goal of the project isn't to make all system run speedy on your system; the goal is to document the hardware and reproduce the behavior of the hardware as faithfully as possible.
+Keep in mind that even on the fastest computers available, MAME is still
+incapable of playing some systems at full speed. The goal of the project isn’t
+to make all system run speedy on your system; the goal is to document the
+hardware and reproduce the behavior of the hardware as faithfully as possible.
BIOS Dumps and Software
-----------------------
-Most of the systems emulated by MAME requires a dump of the internal chips of the original system. These can be obtained by extracting the data from an original unit, or finding them (at your own risk) in the WorldWideWeb. Being copyrighted material, MAME does not come with any of these.
+Most of the systems emulated by MAME requires a dump of the internal chips of
+the original system. These can be obtained by extracting the data from an
+original unit, or finding them (at your own risk) on various place on the
+Internet. Being copyrighted material, MAME does not come with any of these.
+
+Also, you may want to find some software to be run on the emulated machine
+where it does not have internal software (e.g. some computers will need a
+disk to boot to an operating system).
-Also, you may want to find some software to be run on the emulated machine. Again, Google and other search engines are your best friends. MAME does not provide any software to be run on the emulated machines because it is very often (almost always, in the case of console software) copyrighted material.
+Again, Google and other search engines are your best friends. MAME does not
+provide any software in the MAME package to be run on the emulated machines
+because it is very often (almost always, in the case of console software)
+protected by copyright.
+The MAME team has been permitted to redistribute some old software, which can be
+found in the `ROMS section of the MAME site <https://www.mamedev.org/roms/>`_.
diff --git a/docs/source/license.rst b/docs/source/license.rst
index b53cb1eca3c..fd72712d9d8 100644
--- a/docs/source/license.rst
+++ b/docs/source/license.rst
@@ -2,9 +2,15 @@ The MAME License
================
-The MAME project as a whole is distributed under the terms of the `GNU General Public License, version 2 or later <http://opensource.org/licenses/GPL-2.0>`_ (GPL-2.0+), since it contains code made available under multiple GPL-compatible licenses. A great majority of files (over 90% including core files) are under the `BSD-3-Clause License <http://opensource.org/licenses/BSD-3-Clause>`_ and we would encourage new contributors to distribute files under this license.
+The MAME project as a whole is distributed under the terms of the
+`GNU General Public License, version 2 or later <http://opensource.org/licenses/GPL-2.0>`_ (GPL-2.0+),
+since it contains code made available under multiple GPL-compatible licenses.
+A great majority of files (over 90% including core files) are under the
+`3-Clause BSD License <http://opensource.org/licenses/BSD-3-Clause>`_ and we
+would encourage new contributors to distribute files under this license.
-Please note that MAME is a registered trademark of Gregory Ember, and permission is required to use the "MAME" name, logo, or wordmark.
+Please note that MAME is a registered trademark of Gregory Ember, and permission
+is required to use the “MAME” name, logo, or wordmark.
Copyright (C) 1997-2021 MAMEDev and contributors
@@ -22,4 +28,5 @@ Please note that MAME is a registered trademark of Gregory Ember, and permission
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-Please see `LICENSE.md <https://github.com/mamedev/mame/blob/master/LICENSE.md>`_ for further details.
+Please see the `license information <https://github.com/mamedev/mame/blob/master/COPYING>`_
+for further details.
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index 38e66c81a35..ca40b5668ed 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -1,7 +1,9 @@
MAME Menus
==========
-If you started MAME without any command line parameters, you'll be shown the game selection menu immediately. While the keys listed above will let you navigate the menus, you can also use a mouse.
+If you started MAME without any command line parameters, you'll be shown the
+system selection menu immediately. While the keys listed above will let you
+navigate the menus, you can also use a mouse.
[todo: This needs SERIOUS expansion. Waiting on answer to a few questions..]
diff --git a/docs/source/usingmame/usingmame.rst b/docs/source/usingmame/usingmame.rst
index 28f20d03394..9e66c611c50 100644
--- a/docs/source/usingmame/usingmame.rst
+++ b/docs/source/usingmame/usingmame.rst
@@ -1,11 +1,20 @@
Using MAME
----------
-If you want to dive right in and skip the command line, there's a nice graphical way to use MAME without the need to download and set up a front end. Simply start MAME with no parameters, by doubleclicking the **mame.exe** file or running it directly from the command line. If you're looking to harness the full power of MAME, keep reading further.
+If you want to dive right in and skip the command line, there's a nice graphical
+way to use MAME without the need to download and set up a front end. Simply
+start MAME with no parameters, by doubleclicking the **mame.exe** file or
+running it directly from the command line. If you're looking to harness the
+full power of MAME, keep reading further.
-On Macintosh OS X and \*nix-based platforms, please be sure to set your font up to match your locale before starting, otherwise you may not be able to read the text due to missing glyphs.
+On macOS and \*nix-based platforms, please be sure to set your font up to match
+your locale before starting, otherwise you may not be able to read the text due
+to missing glyphs.
-If you are a new MAME user, you could find this emulator a bit complex at first. Let's take a moment to talk about softlists, as they can simplify matters quite a bit. If the content you are trying to play is a documented entry on one of the MAME softlists, starting the content is as easy as
+If you are a new MAME user, you could find this emulator a bit complex at
+first. Let's take a moment to talk about software lists, as they can simplify
+matters quite a bit. If the content you are trying to play is a documented
+entry on one of the MAME sotware lists, starting the content is as easy as
**mame.exe** *<system>* *<software>*
@@ -18,55 +27,85 @@ will load the USA version of Metroid for the Nintendo Entertainment System.
Alternatively, you could start MAME with
- **mame.exe nes**
+ **mame.exe nes**
-and choose the *software list* from the cartridge slot. From there, you could pick any softlist-compatible software you have in your roms folders. Please note that many older dumps of cartridges and discs may either be bad or require renaming to match up to the softlist in order to work in this way.
+and choose the *software list* from the cartridge slot. From there, you could
+pick any software list-compatible software you have in your roms folders. Please
+note that many older dumps of cartridges and discs may either be bad or require
+renaming to match up to the software list in order to work in this way.
-If you are loading an arcade board or other non-softlist content, things are only a little more complicated:
-
+If you are loading an arcade board or other non-software list content, things
+are only a little more complicated:
The basic usage, from command line, is
- **mame.exe** *<system>* *<media>* *<software>* *<options>*
+ **mame.exe** *<system>* *<media>* *<software>* *<options>*
where
-* *<system>* is the shortname of the system you want to emulate (e.g. nes, c64, etc.)
-* *<media>* is the switch for the media you want to load (if it's a cartridge, try **-cart** or **-cart1**; if it's a floppy disk, try **-flop** or **-flop1**; if it's a CD-ROM, try **-cdrom**)
-* *<software>* is the program / game you want to load (and it can be given either as the fullpath to the file to load, or as the shortname of the file in our software lists)
-* *<options>* is any additional command line option for controllers, video, sound, etc.
+* *<system>* is the short name of the system you want to emulate (e.g. nes, c64,
+ etc.)
+* *<media>* is the switch for the media you want to load (if it's a cartridge,
+ try **-cart** or **-cart1**; if it's a floppy disk, try **-flop** or
+ **-flop1**; if it's a CD-ROM, try **-cdrom**)
+* *<software>* is the program / game you want to load (and it can be given
+ either as the fullpath to the file to load, or as the shortname of the file in
+ our software lists)
+* *<options>* is any additional command line option for controllers, video,
+ sound, etc.
-Remember that if you type a <system> name which does not correspond to any emulated system, MAME will suggest you some possible choices which are close to what you typed; and if you don't know which <media> switch are available, you can always launch
+Remember that if you type a *<system>* name which does not correspond to any
+emulated system, MAME will suggest some possible choices which are close to
+what you typed; and if you don't know which *<media>* switch are available, you
+can always launch
- **mame.exe** *<system>* **-listmedia**
+ **mame.exe** *<system>* **-listmedia**
-If you don't know what *<options>* are available, there are a few things you can do. First of all, you can check the command line options section of this manual. You can also try one of the many :ref:`frontends` available for MAME.
+If you don't know what *<options>* are available, there are a few things you
+can do. First of all, you can check the command line options section of this
+manual. You can also try one of the many :ref:`frontends` available for MAME.
-Alternatively, you should keep in mind the following command line options, which might be very useful on occasion:
+Alternatively, you should keep in mind the following command line options,
+which might be very useful on occasion:
- **mame.exe -help**
+ **mame.exe -help**
-tells what MAME is the basic structure of MAME launching options, i.e. as explained above.
+gives a basic summary of command line options for MAME, as explained above.
- **mame.exe -showusage**
+ **mame.exe -showusage**
-gives you the (quite long) list of available command line options for MAME. The main options are described, in the :ref:`universal-command-line` section of this manual.
+gives you the (quite long) list of available command line options for MAME.
+The main options are described, in the :ref:`universal-command-line` section of
+this manual.
- **mame.exe -showconfig**
+ **mame.exe -showconfig**
-gives you a (quite long) list of available configuration options for MAME. These configuration can always be modified at command line, or by editing them in mame.ini which is the main configuration file for MAME. You can find a description of some configuration options in the :ref:`universal-command-line` section of the manual (in most cases, each configuration option has a corresponding command line option to configure and modify it).
+gives you a (quite long) list of available configuration options for MAME.
+These optons can always be modified at command line, or by editing them in
+mame.ini which is the main configuration file for MAME. You can find a
+description of some configuration options in the :ref:`universal-command-line`
+section of the manual (in most cases, each configuration option has a
+corresponding command line option to configure and modify it).
- **mame.exe -createconfig**
+ **mame.exe -createconfig**
-creates a brand new **mame.ini** file, with default configuration settings. Notice that mame.ini is basically a plain text file, hence you can open it with any text editor (e.g. Notepad, Emacs or TextEdit) and configure every option you need. However, no particular tweaks are needed to start, so you can basically leave most of the options unaltered.
+creates a brand new **mame.ini** file, with default configuration settings.
+Notice that mame.ini is basically a plain text file, so you can open it with any
+text editor (e.g. Notepad, Emacs or TextEdit) and configure every option you
+need. However, no particular tweaks are needed to start, so you can leave most
+of the options unaltered.
-If you execute **mame -createconfig** when you already have an existing mame.ini from a previous MAME version, MAME automatically updates the pre-existing mame.ini by copying changed options into it.
+If you execute **mame64 -createconfig** when you already have an existing
+mame.ini from a previous MAME version, MAME automatically updates the
+pre-existing mame.ini by copying changed options into it.
-Once you are more confident with MAME options, you may want to configure a bit more your setup. In this case, keep in mind the order in which options are read; see :ref:`advanced-multi-CFG` for details.
+Once you are more confident with MAME options, you may want to adjust the
+configuration of your setup a bit more. In this case, keep in mind the order in
+which options are read; see :ref:`advanced-multi-CFG` for details.