summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/contributing/softlist.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/contributing/softlist.rst')
-rw-r--r--docs/source/contributing/softlist.rst175
1 files changed, 175 insertions, 0 deletions
diff --git a/docs/source/contributing/softlist.rst b/docs/source/contributing/softlist.rst
new file mode 100644
index 00000000000..afcfa78ffb0
--- /dev/null
+++ b/docs/source/contributing/softlist.rst
@@ -0,0 +1,175 @@
+.. _contributing-softlist:
+
+Guidelines for Software Lists
+=============================
+
+.. contents:: :local:
+
+
+.. _contributing-softlist-intro:
+
+Introduction
+------------
+
+MAME’s software lists describe known software media for emulated
+systems in a form that can be used to identify media image files for
+known software, verify media image file integrity, and load media
+image files for emulation. Software lists are implemented as XML
+files in the ``hash`` folder. The XML structure is described in the
+file ``hash/softwarelist.dtd``.
+
+Philosophically, software list items should represent the original
+media, rather than a specific dump of the media. Ideally, it should be
+possible for anyone with the media to dump it and produce the same image
+file. Of course, this isn’t always possible in practice – in particular
+it’s problematic for inherently analog media, like home computer
+software stored on audio tape cassettes.
+
+MAME strives to document the best available media images. It is not our
+intention to propagate corrupted, truncated, defaced, watermarked, or
+otherwise bad media images. Where possible, file structures matching
+the original media structure are preferred. For example we prefer
+individual files for separate ROM chips in cartridge media, and we use
+disk images rather than archives of files extracted from the original
+disks.
+
+
+.. _contributing-softlist-itempart:
+
+Items and parts
+---------------
+
+A software list is a collection of *items* and each item may have
+multiple *parts*. An item represents a piece of software, as
+distributed as a complete package. A part represents a single piece of
+media within the package. Parts can be mounted individually in
+emulated media devices. For example a piece of software distributed on
+three floppy disks will be a single item, while each floppy disk will be
+one part within that item.
+
+Sometimes, logically separate parts of a single physical piece of media
+are represented as separate parts within a software item. For example
+each side of an audio tape cassette is represented as a separate part.
+However individual ROM chips within a cartridge may be separate files,
+but they are *not* separate parts, as the cartridge is mounted as a
+whole.
+
+Each item is a ``software`` element. The ``software`` element may have
+the following attributes:
+
+name (required)
+ The short name identifying the item. This is used for file names,
+ command line arguments, database keys, URL fragments, and many other
+ purposes. It should be terse but still recognisable. It must be
+ unique within the software list. Valid characters are lowercase
+ English letters, decimal digits and underscores. The maximum
+ allowed length is sixteen characters.
+cloneof (optional)
+ The short name of the parent item if the item is a clone. The
+ parent must be within the same software list – parent/clone
+ relationships spanning multiple software lists are not supported.
+supported (optional)
+ One of the values ``yes`` (fully usable in emulation), ``no`` (not
+ usable in emulation), or ``partial`` (usable in emulation with
+ limitations). If the attribute is not present, it is equivalent to
+ ``yes``. Examples of partially supported software include games
+ that are playable with graphical glitches, and office software where
+ some but not all functionality works.
+
+Each part is a ``part`` element within the ``software`` element. The
+``part`` element must have the following attributes:
+
+name (required)
+ The short name identifying the part. This is used for command line
+ arguments, database keys, URL fragments, and many other purposes.
+ It must be unique within the item. It is also used as the display
+ name if a separate display name is not provided. Valid characters
+ are lowercase English letters, decimal digits and underscores. The
+ maximum allowed length is sixteen characters.
+interface (required)
+ This attribute is used to identify suitable emulated media devices
+ for mounting the software part. Applicable values depend on the
+ emulated system.
+
+
+.. _contributing-softlist-metadata:
+
+Metadata
+--------
+
+Software lists support various kinds of metadata. All software list
+items require the following metadata elements to be present:
+
+description
+ This is the primary display name for the software item. It should
+ be the original name of the software, transliterated into English
+ Latin script if necessary. It must be unique within the software
+ list. If extra text besides the title itself is required for
+ disambiguation, use lowercase outside of proper nouns, initialisms
+ and verbatim quotes.
+year
+ The year of release or copyright year for the software. If unknown,
+ use an estimate with a question mark. Items can be filtered by year
+ in the software selection menu.
+publisher
+ The publisher of the software. This may be the same as the
+ developer if the software was self-published. Items can be filtered
+ by published in the software selection menu.
+
+Most user-visible software item metadata is provided using ``info``
+elements. Each ``info`` element must have a ``name`` attribute and a
+``value`` attribute. The ``name`` attribute identifies the type of
+metadata, and the ``value`` attribute is the metadata value itself.
+Note that ``name`` attributes do not need to be unique within an item.
+Multiple ``info`` elements with the same ``name`` may be present if
+appropriate. This is frequently seen for software sold using different
+titles in different regions.
+
+MAME displays metadata from ``info`` elements in the software selection
+menu. The following ``name`` attributes are recognised specifically,
+and can show localised names:
+
+alt_title
+ Used for alternate titles. Examples are different tiles used in
+ different languages, scripts or regions, or different titles used
+ on the title screen and packaging. MAME searches alternate titles
+ as well as the description.
+author
+ Author of the software. Items can be filtered by author in the
+ software selection menu.
+barcode
+ Barcode number identifying the software package (typically an EAN).
+developer
+ Developer responsible for implementing the software. Items can be
+ filtered by developer in the software selection menu.
+distributor
+ Party responsible for distributing the software to retailers (or
+ customers in the case of direct sales). Items can be filtered by
+ distributor in the software selection menu.
+install
+ Installation instructions.
+isbn
+ ISBN for software included with a commercial book.
+oem
+ Original equipment manufacturer, typically used with customised
+ versions of software distributed by a hardware vendor.
+original_publisher
+ The original publisher, for items representing software re-released
+ by a different publisher.
+partno
+ Distributor’s part number for the software.
+pcb
+ Printed circuit board identifier, typically for cartridge media.
+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 known,
+ use “xx” for the day digits. For example ``199103xx`` or
+ ``19940729``.
+serial
+ Number identifying the software within a series of releases.
+usage
+ Usage instructions.
+version
+ Version number of the software.