From 4ab590e2a9bdf1ce1a0032883b356c7aa5f653ea Mon Sep 17 00:00:00 2001 From: Tom Cariello Date: Sat, 30 Sep 2023 22:39:06 -0400 Subject: docs: Fixed a number of grammatical errors and editing errors. (#11578) --- docs/source/contributing/softlist.rst | 2 +- docs/source/security.rst | 2 +- docs/source/techspecs/device_disasm_interface.rst | 10 ++++----- docs/source/techspecs/device_memory_interface.rst | 2 +- docs/source/techspecs/floppy.rst | 8 +++---- docs/source/techspecs/inputsystem.rst | 20 ++++++++--------- docs/source/techspecs/layout_files.rst | 26 +++++++++++------------ docs/source/techspecs/layout_script.rst | 4 ++-- docs/source/techspecs/m6502.rst | 4 ++-- docs/source/techspecs/memory.rst | 6 +++--- docs/source/techspecs/naming.rst | 2 +- docs/source/techspecs/object_finders.rst | 2 +- docs/source/techspecs/poly_manager.rst | 2 +- docs/source/tools/imgtool.rst | 4 ++-- 14 files changed, 47 insertions(+), 47 deletions(-) diff --git a/docs/source/contributing/softlist.rst b/docs/source/contributing/softlist.rst index c70523b1fc2..afcfa78ffb0 100644 --- a/docs/source/contributing/softlist.rst +++ b/docs/source/contributing/softlist.rst @@ -164,7 +164,7 @@ programmer Programmer who wrote the code for the software. release Fine-grained release date for the software, if known. Use - YYYYMMDD format with no punctuation. If only the month is know, + YYYYMMDD format with no punctuation. If only the month is known, use “xx” for the day digits. For example ``199103xx`` or ``19940729``. serial diff --git a/docs/source/security.rst b/docs/source/security.rst index d8fc372c614..4e26c4ae97a 100644 --- a/docs/source/security.rst +++ b/docs/source/security.rst @@ -1,7 +1,7 @@ MAME and security concerns ========================== -MAME is not intended or designed to run in secure sites. It has not been security audited for such types of usage, and has been known in the past to have flaws that could be used for malicious intent if run as administator or root. +MAME is not intended or designed to run in secure sites. It has not been security audited for such types of usage, and has been known in the past to have flaws that could be used for malicious intent if run as administrator or root. **We do not suggest or condone the use of MAME as administrator or root and use as such is done at your own risk.** diff --git a/docs/source/techspecs/device_disasm_interface.rst b/docs/source/techspecs/device_disasm_interface.rst index beacaf8e6df..a2ab4fa7eec 100644 --- a/docs/source/techspecs/device_disasm_interface.rst +++ b/docs/source/techspecs/device_disasm_interface.rst @@ -168,7 +168,7 @@ A CPU core derives from **device_disasm_interface** through That method must return a pointer to a newly allocated disassembler object. The caller takes ownership and handles the lifetime. -THis method will be called at most one in the lifetime of the cpu +This method will be called at most one in the lifetime of the cpu object. 4. Disassembler configuration and communication @@ -184,7 +184,7 @@ model name), feel free to use a parameter. Otherwise derive the class. Dynamic configuration must be done by first defining a nested public -struct called "config" in the disassembler, with virtual destructor +struct called ``config`` in the disassembler, with virtual destructor and pure virtual methods to pull the required information. A pointer to that struct should be passed to the disassembler constructor. The cpu core should then add a derivation from that config struct and @@ -195,9 +195,9 @@ the config class to give the information. ---------------- There currently is no way for the debugger GUI to add per-core -configuration. It is needed for in particular the s2650 and the -saturn cores. It should go through the cpu core class itself, since -it's pulled from the config struct. +configuration. In particular, it is needed for the s2650 and Saturn +cores. It should go through the cpu core class itself, since it's +pulled from the config struct. There is support missing in unidasm for per-cpu configuration. That's needed for a lot of things, see the unidasm source code for the diff --git a/docs/source/techspecs/device_memory_interface.rst b/docs/source/techspecs/device_memory_interface.rst index 6056cce81de..1f8e2b1c37b 100644 --- a/docs/source/techspecs/device_memory_interface.rst +++ b/docs/source/techspecs/device_memory_interface.rst @@ -68,7 +68,7 @@ describing its configuration. Some examples to look up when needed: The ``has_configured_map`` method allows to test whether an ``address_map`` has been associated with a given space in the -``memory_space_config`` method . That allows optional memory spaces to +``memory_space_config`` method. That allows optional memory spaces to be implemented, such as ``AS_OPCODES`` in certain CPU cores. diff --git a/docs/source/techspecs/floppy.rst b/docs/source/techspecs/floppy.rst index 609e5c53013..39060d4eddf 100644 --- a/docs/source/techspecs/floppy.rst +++ b/docs/source/techspecs/floppy.rst @@ -23,7 +23,7 @@ The new floppy subsystem aims at emulating the behaviour of floppies and floppy A floppy disk is a disc that stores magnetic orientations on their surface disposed in a series on concentric circles called tracks or cylinders [1]_. Its main characteristics are its size (goes from a diameter of around 2.8" to 8") , its number of writable sides (1 or 2) and its magnetic resistivity. The magnetic resistivity indicates how close magnetic orientation changes can happen and the information kept. That's one third of what defines the term "density" that is so often used for floppies (the other two are floppy drive head size and bit-level encoding). -The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tengentially to the track, e.g in the direction or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to). +The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tangentially to the track, i.e. in the direction of or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc.) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to). A specific position in the disk rotation triggers an index pulse. That position can be detected through a hole in the surface (very visible in 5.25" and 3" floppies for instance) or through a specific position of the rotating center (3.5" floppies, perhaps others). This index pulse is used to designate the beginning of the track, but is not used by every system. Older 8" floppies have multiple index holes used to mark the beginning of sectors (called hard sectoring) but one of them is positioned differently to be recognized as the track start, and the others are at fixed positions relative to the origin one. @@ -70,7 +70,7 @@ In every cell there may or may not be a magnetic orientation transition, e.g. a Of course protections play with that to make formats not reproducible by the system controller, either breaking the three-zeroes rule or playing with the cells durations/sizes. -Bit endocing is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints. +Bit encoding is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints. 2.3.1.2. FM encoding ```````````````````` @@ -108,9 +108,9 @@ Other encodings exist, like M2FM, but they're very rare and system-specific. 2.3.1.6. Reading back encoded data `````````````````````````````````` -Writing encoded data is easy, you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (+/- 2% is not rare) and local perturbations (air turbulence, surface distance...) make the instant speed very variable in general. So to extract the cell values stream the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is build within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows to correct the phase on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used a Phase-Locked Loop (PLL) which vary both phase and window duration to adapt better to wrong rotational speeds, with usually a tolerance of +/- 15%. +Writing encoded data is easy: you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (±2% is not rare), and local perturbations (air turbulence, surface distance…) make the instantaneous speed very variable in general. So to extract the cell values stream, the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is built within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window, the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows the phase to be corrected on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used Phase-Locked Loops (PLLs) which vary both phase and window duration to adapt better to inaccuarate rotational speeds, usually with a tolerance of ±15%. -Once the cell data stream is extracted decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream. +Once the cell data stream is extracted, decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream. 2.3.2. Sector-level organization diff --git a/docs/source/techspecs/inputsystem.rst b/docs/source/techspecs/inputsystem.rst index d7f0c1a74c4..7a027b0ff22 100644 --- a/docs/source/techspecs/inputsystem.rst +++ b/docs/source/techspecs/inputsystem.rst @@ -114,13 +114,13 @@ fields: and neutral positions. They are used for analog joystick axes, displacement-sensitive pedals, paddle knobs, and other emulated inputs with a defined range. -* **Relative analog fields** have a range with with defined - minimum, maximum and starting positions. On each update, the value - accumulates and wraps when it passes either end of the range. - Functionally, this is like the output of an up/down counter connected - to an incremental encoder. They are used for mouse/trackball axes, - steering wheels without limit stops, and other emulated inputs that - have no range limits. +* **Relative analog fields** have a range with defined minimum, maximum + and starting positions. On each update, the value accumulates and + wraps when it passes either end of the range. Functionally, this is + like the output of an up/down counter connected to an incremental + encoder. They are used for mouse/trackball axes, steering wheels + without limit stops, and other emulated inputs that have no range + limits. * DIP switch, configuration and adjuster fields allow the user to set the value through MAME’s user interface. * Additional special field types are used to produce fixed or @@ -147,7 +147,7 @@ In practice, emulated devices and systems rarely interact with the input manager directly. The most common reason to access the input manager is implementing special debug controls, which should be disabled in release builds. Plugins that respond to input need to call the input manager to -raed inputs. +read inputs. I/O port manager ~~~~~~~~~~~~~~~~ @@ -408,7 +408,7 @@ to support a variety of control setups: device item that produced the current value was an absolute axis, the field’s value is set to the current value scaled to the correct range, and no further processing is performed. -* If the current value is non-zero and the input device device item that +* If the current value is non-zero and the input device item that produced the current value was a relative axis, the current value is added to the field’s value, scaled by the field’s sensitivity setting. * The I/O port manager reads the current value for the field’s assigned @@ -444,7 +444,7 @@ analog fields: produced the current value was an absolute axis, the current value is added to the field’s value, scaled by the field’s sensitivity setting, and no further processing is performed. -* If the current value is non-zero and the input device device item that +* If the current value is non-zero and the input device item that produced the current value was a relative axis, the current value is added to the field’s value, scaled by the field’s sensitivity setting. * The I/O port manager reads the current value for the field’s assigned diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst index 5dd1bba0758..4cc3bbf3edd 100644 --- a/docs/source/techspecs/layout_files.rst +++ b/docs/source/techspecs/layout_files.rst @@ -396,8 +396,8 @@ Elements ~~~~~~~~ Elements are one of the basic visual objects that may be arranged, along with -screens, to make up a view. Elements may be built up one or more *components*, -but an element is treated as as single surface when building the scene graph +screens, to make up a view. Elements may be built up of one or more *components*, +but an element is treated as a single surface when building the scene graph and rendering. An element may be used in multiple views, and may be used multiple times within a view. @@ -497,15 +497,15 @@ image human-readable SVG graphics. A ``file`` attribute or ``data`` child element must be supplied; it is an error if neither or both are supplied. - If the ``alphafile`` attribute refers refers to a file, it must have the - same dimensions (in pixels) as the file referred to by the ``file`` - attribute, and must have a bit depth no greater than eight bits per channel - per pixel. The intensity from this image (brightness) is copied to the - alpha channel, with full intensity (white in a greyscale image) - corresponding to fully opaque, and black corresponding to fully transparent. - The ``alphafile`` attribute will be ignored if the ``file`` attribute refers - to an SVG image or the ``data`` child element contains SVG data; it is only - used in conjunction with bitmap images. + If the ``alphafile`` attribute refers to a file, it must have the same + dimensions (in pixels) as the file referred to by the ``file`` attribute, + and must have a bit depth no greater than eight bits per channel per pixel. + The intensity from this image (brightness) is copied to the alpha channel, + with full intensity (white in a greyscale image) corresponding to fully + opaque, and black corresponding to fully transparent. The ``alphafile`` + attribute will be ignored if the ``file`` attribute refers to an SVG image + or the ``data`` child element contains SVG data; it is only used in + conjunction with bitmap images. The image file(s) should be placed in the same directory/archive as the layout file. Image file formats are detected by examining the content of @@ -731,7 +731,7 @@ screen collection Adds screens and/or items in a collection that can be shown or hidden by the user (see :ref:`layfile-parts-collections`). The name of the collection is - specified using the required ``name`` attribute.. There is a limit of 32 + specified using the required ``name`` attribute. There is a limit of 32 collections per view. group Adds the content of the group to the view (see :ref:`layfile-parts-groups`). @@ -1269,7 +1269,7 @@ View item animation Items’ colour and position/size within their containing view may be animated. This is achieved by supplying multiple ``color`` and/or ``bounds`` child elements with ``state`` attributes. The ``state`` attribute of each ``color`` -or ``bounds`` child element must be a non-negative integer. Withing a view +or ``bounds`` child element must be a non-negative integer. Within a view item, no two ``color`` elements may have equal state ``state`` attributes, and no two ``bounds`` elements may have equal ``state`` attributes. diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst index 4015fe69421..370b3eac152 100644 --- a/docs/source/techspecs/layout_script.rst +++ b/docs/source/techspecs/layout_script.rst @@ -623,7 +623,7 @@ Get item horizontal scroll window size horizontal window size as a proportion of the associated element’s width, and takes no parameters. A value of 1.0 will display the entire width of the element; smaller values will display proportionally smaller parts of the - element. Call with ``nil`` as the argument to to restore the default + element. Call with ``nil`` as the argument to restore the default horizontal scroll window size handler (based on the ``xscroll`` child element). Get item vertical scroll window size @@ -638,7 +638,7 @@ Get item vertical scroll window size vertical window size as a proportion of the associated element’s height, and takes no parameters. A value of 1.0 will display the entire height of the element; smaller values will display proportionally smaller parts of the - element. Call with ``nil`` as the argument to to restore the default + element. Call with ``nil`` as the argument to restore the default vertical scroll window size handler (based on the ``xscroll`` child element). Get item horizontal scroll position diff --git a/docs/source/techspecs/m6502.rst b/docs/source/techspecs/m6502.rst index b7fdab5d895..7d67423abb8 100644 --- a/docs/source/techspecs/m6502.rst +++ b/docs/source/techspecs/m6502.rst @@ -18,7 +18,7 @@ Point 1 has been ensured through bisimulation with the gate-level simulation per The 6502 family --------------- -The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this: +The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshoots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this: :: @@ -38,7 +38,7 @@ The MOS 6502 family has been large and productive. A large number of variants ex -The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc) and clock support. +The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc.) and clock support. The deco16 is a Deco variant with a small number of not really understood additional instructions and some I/O. diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst index 9d7eb3c1b29..ebdca9646d1 100644 --- a/docs/source/techspecs/memory.rst +++ b/docs/source/techspecs/memory.rst @@ -361,7 +361,7 @@ Sets a method of the current device or driver to read, write or both for the current entry. The prototype of the method can take multiple forms making some elements optional. ``uNN`` represents ``u8``, ``u16``, ``u32`` or ``u64`` depending on the data width of the handler. -The handler can be narrower than the bus itself (for instance a 8-bit +The handler can be narrower than the bus itself (for instance an 8-bit device on a 32-bit bus). The offset passed in is built from the access address. It starts at @@ -603,7 +603,7 @@ parameter is that trigger width (would be 16 in the 68000 case). This parameter allows to set user-defined flags on the handler which can then be retrieved by an accessing device to change their -behaviour. An example of use the the i960 which marks burstable zones +behaviour. An example of use the i960 which marks burstable zones that way (they have a specific hardware-level support). @@ -653,7 +653,7 @@ changed on-the-fly. They’re powerful but have some issues: * changing the mappings repeatedly can be slow * the address space state is not saved in the saved states, so it has to be rebuilt after state load -* they can be hidden anywhere rather that be grouped in an address map, +* they can be hidden anywhere rather than be grouped in an address map, which can be less readable The methods, rather than decomposing the information in handler, handler diff --git a/docs/source/techspecs/naming.rst b/docs/source/techspecs/naming.rst index b91e5ba9d93..4846876c0cd 100644 --- a/docs/source/techspecs/naming.rst +++ b/docs/source/techspecs/naming.rst @@ -73,7 +73,7 @@ For software list entries where a transliteration is used for the ``name="alt_title"`` attribute. For software items that have multiple titles (for example different -regional titles with the same installation media), use the most most +regional titles with the same installation media), use the most widespread English Latin title for the ``description`` element, and put the other titles in ``info`` elements with ``name="alt_title"`` attributes. diff --git a/docs/source/techspecs/object_finders.rst b/docs/source/techspecs/object_finders.rst index e05146c3167..27fe42fdd50 100644 --- a/docs/source/techspecs/object_finders.rst +++ b/docs/source/techspecs/object_finders.rst @@ -478,7 +478,7 @@ for all elements of the array): }; This finds or creates memory shares with tags ``vram_0`` and ``vram_1``, each of -of which is 8 KiB organised as 4,096 big-Endian 16-bit words. +which is 8 KiB organised as 4,096 big-Endian 16-bit words. Optional object finders diff --git a/docs/source/techspecs/poly_manager.rst b/docs/source/techspecs/poly_manager.rst index e86cf481428..d30a57c39c3 100644 --- a/docs/source/techspecs/poly_manager.rst +++ b/docs/source/techspecs/poly_manager.rst @@ -951,7 +951,7 @@ poly_array poly_array(); -The **poly_array** contructor requires no parameters and simply pre-allocates one +The **poly_array** constructor requires no parameters and simply pre-allocates one chunk of objects in preparation for future allocations. count diff --git a/docs/source/tools/imgtool.rst b/docs/source/tools/imgtool.rst index b874fdfe215..7efa850ca93 100644 --- a/docs/source/tools/imgtool.rst +++ b/docs/source/tools/imgtool.rst @@ -64,7 +64,7 @@ Imgtool Subcommands **put** - **imgtool put ... [--(fileoption)==value] [--filter=filter] [--fork=fork]** + **imgtool put ... [--(fileoption)=value] [--filter=filter] [--fork=fork]** * is the image format, e.g. coco_jvc_rsdos * is the image filename; can specify a ZIP file for image name @@ -173,7 +173,7 @@ Filters are a means to process data being written into or read out of an image i **vzsnapshot** - [todo: VZ Snapshot? Find out what this is....] + [todo: VZ Snapshot? Find out what this is...] **vzbas** -- cgit v1.2.3