Skip to content

Create macro markup for DEVICE_USAGE() & DEVICE_DESCRIPTION() #368

@felipesanches

Description

@felipesanches
Contributor

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

Activity

balr0g

balr0g commented on Oct 6, 2015

@balr0g
Contributor

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

felipesanches

felipesanches commented on Oct 6, 2015

@felipesanches
ContributorAuthor

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

  • -listxml
  • the softlist XML files

Which do you mean?

felipesanches

felipesanches commented on Oct 6, 2015

@felipesanches
ContributorAuthor

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

felipesanches commented on Oct 6, 2015

@felipesanches
ContributorAuthor

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

felipesanches commented on Oct 6, 2015

@felipesanches
ContributorAuthor

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

angelosa commented on Jan 27, 2021

@angelosa
Member

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?

added
ui/uxOSD frontend related
docsDocumentation-related issues
needs designimplementation details needs to be properly addressed
on Jan 27, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation-related issuesenhancementneeds designimplementation details needs to be properly addressedui/uxOSD frontend related

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @felipesanches@balr0g@angelosa@rb6502

        Issue actions

          Create macro markup for DEVICE_USAGE() & DEVICE_DESCRIPTION() · Issue #368 · mamedev/mame