-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Open
Labels
docsDocumentation-related issuesDocumentation-related issuesenhancementneeds designimplementation details needs to be properly addressedimplementation details needs to be properly addressedui/uxOSD frontend relatedOSD frontend related
Description
These macros would expose to the emulator runtime, useful information for the users. Such information can be displayed when booting a machine and/or within the ui menu (under "machine information" perhaps).
Examples of what the macros would look like in the source code:
DEVICE_DESCRIPTION( zapcomp, "\
ZAP - Z80 Applications Processor\n
\n
driver by: Felipe Correa da Silva Sanches <juca@members.fsf.org>\n
\n
Based on the technical descriptions and\n
assembly listings of the book:\n
\n
'Build Your Own Z80 Microcomputer'\n
by Steve Ciarcia (1981)\n
published by BYTE/McGRAW-HILL" )
DEVICE_USAGE( zapcomp, "\
Basic usage instructions:\n
SHIFT + 0: view and edit memory values\n
SHIFT + 1: view and edit register values\n
SHIFT + 2: execution mode\n
\n
For more info, please check chapter 6 'Monitor software' in the book\n
and/or the assembly listings of the ZAP monitor software\n
avaliable at appendix D." )
Metadata
Metadata
Assignees
Labels
docsDocumentation-related issuesDocumentation-related issuesenhancementneeds designimplementation details needs to be properly addressedimplementation details needs to be properly addressedui/uxOSD frontend relatedOSD frontend related
Type
Projects
Milestone
Relationships
Development
Select code repository
Activity
balr0g commentedon Oct 6, 2015
Wouldn't this make more sense in the XML metadata...?
felipesanches commentedon Oct 6, 2015
When you say "XML metadata" I can think of 2 things:
Which do you mean?
felipesanches commentedon Oct 6, 2015
The rationale behind my proposal is that there is a lot of occurences nowadays of both general description of what a certain device is, as well as of information on how to operate a device, that are kind of "buried" into comments in the headers of driver source files. It seems to be a current common practice. This is useful metadata and, as a documentation and preservation project, I think we would benefit from making all this information accessible on run-time and also in a more structured way so that this metadata can be (1) more accessible to the users and not only to people who take a look at the source code and (2) in a machine-readable manner so that it can be more easily repurposed by automated tools (such as data processing scripts to generate all sorts of visualizations and statistics on our current codebase).
Think of it as something as useful as the other metadata for which we already have macro markups on a driver source file, such as release year, manufacturer name, model name, driver status flags, rom names and hashes, etc...
felipesanches commentedon Oct 6, 2015
Also, other info could perhaps also be better organized with more specialized markup such as:
felipesanches commentedon Oct 6, 2015
In addition to the improved visibility/access of the data within MAME's runtime, one other potential future benefit of this markup would be that projects such as the Internet Archive would be able to more easily extract this information and to expose it to visitors as part of the user interface of their website.
angelosa commentedon Jan 27, 2021
For WYSIWYG style documentation both proposal won't fit due of multi-line handling and/or having to manually deal with [CR]LF.
A better fit would be using markdown flavored files plus a dedicated repository, the hard part would be then to link these howto docs from MAME front-end itself as a design standpoint:
*do we have a mechanism for clicking external URLs at all?
Adds ssoldier to the profile button list (mamedev#368)