diff options
Diffstat (limited to 'docs/source/contributing/softlist.rst')
-rw-r--r-- | docs/source/contributing/softlist.rst | 175 |
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..c70523b1fc2 --- /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 know, + 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. |