Create macro markup for DEVICE_USAGE() & DEVICE_DESCRIPTION()

[felipesanches]

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." )

[balr0g]

Wouldn't this make more sense in the XML metadata...?

[felipesanches]

When you say "XML metadata" I can think of 2 things:

• -listxml
• the softlist XML files

Which do you mean?

[felipesanches]

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]

Also, other info could perhaps also be better organized with more specialized markup such as:

DRIVER_AUTHOR(zapcomp, "Felipe Correa da Silva Sanches", "juca@members.fsf.org")

[felipesanches]

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]

DEVICE_DESCRIPTION( zapcomp, "\ ZAP - Z80 Applications Processor\n \n [...]

Wouldn't this make more sense in the XML metadata...?

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:

1. single document from the driver handle or multiple arrays with metadata instead? i.e. how much responsibility a "core" should have by supporting this feature in a grand scale from 0 to 1 string handlers?
2. UX wise I'm not convinced that an inline help should be displayed in the internal MAME UI itself, would be a better fit to just have clickable external URLs* in a dedicated plugin and serve on demand instead, and deal with issues such as "no documentation found" far better than having to render internally.

*do we have a mechanism for clicking external URLs at all?