MAMEWorld Forums - News - Re: Documentation?

> Maybe I'm being dense here... but just noticed this...
>
> -- Went to look for documentation on the new artwork... and the docs folder is all
> different now:
>
> ------ All of the files are Linux MAN files now... what's the best way to view those
> in Windows? (I mean other than Notepad, so that I can read the file as it was meant
> to be... not having to read in between all the printer/screen commands).

Documentation is auto-generated from the .rst files in docs/source every five minutes. Surely Windows has a web browser you can point at the docs site: http://docs.mamedev.org/

> ------ There is no more Config.txt or Windows.txt... but if you run the command "MAME
> -?", you still get the old normal help stuff, and the last line is "For usage
> instructions, please consult the files config.txt and windows.txt" ... so that should
> be fixed?

Yeah, we should probably update the usage information to point people at the online documentation.

> Anyway... could some kind soul point me towards what to read for the new layout
> stuff?

I haven't written it yet. I will get to it, but there's another long overdue piece of functionality I need to emulate in the layout/render stack before I do that.

In the mean time, essentially there are two kinds of parameters: value parameters and generator parameters.

You can set value parameters like this:
<param name="myparam" value="parameter value" />

Value parameters keep their value until you set a new value, and you can overwrite them at any time. There are a few pre-defined value parameters that give you screen dimensions/aspect ratio, owner device tag, view name, etc. Value parameters can be set in layout, group, view, or repeat scope.

You can set generator parameters like this (generates 1, 3, 5, 7...):
<param name="counter" start="1" increment="2" />

Or this (generates 0x01, 0x02, 0x04, 0x08...):
<param name="bit" start="0x01" lshift="1" />

Or this (generates 0x3000, 0x0300, 0x0030...):
<param name="mask" start="0x3000" rshift="4" />

If you specify some combination of increment and shifts, the increment is applied first, and then the shifts are netted off and applied. Generator parameters can only appear in repeat scope. It is an error to reassign a generator parameter in the same scope. The increment/shift applies at the end of the repeat block before it loops or exits.

The layout, group, view and repeat elements all create their own lexical scope block. You can read but not assign parameters from the containing scope. Assigning a parameter always assigns it in the local scope.

In the case of views, the containing scope evaluating the name is the global layout scope. However, the containing scope used for the body is the scope that the group is instantiated from. So a group instantiated from a view can use the view's parameters in its body.

For the most part, elements are processed in reading order. The exception is that views are processed after all parameters and groups in layout scope. This means that a view can refer to a group that appears after it, and will see the final state of any parameters at the end of the layout element.

The repeat element is pretty simple - it just repeats its contents multiple times:
<repeat count="5">  </repeat>

You can use parameters in most attributes and CDATA - "~thing~" expands to the value of the of the parameter named thing if it exists, otherwise no substitution occurs.

It works best for things with lots of repetition. Look at the layouts I changed in these commits for examples - the algorithmic chessboard and alphanumeric matrix display are obvious use cases:
https://github.com/mamedev/mame/commit/dce955c68db3cfc700cae11743ad966036faa64f
https://github.com/mamedev/mame/commit/1f99edeb4d01d3bc5bb9cb44c67a5278c6429125
https://github.com/mamedev/mame/commit/6669489679753daa8c5766ae24b31b0ce0748221