There are places where the reference could use a little TLC. Things might be worded a little better than they are, and some more (small!) inline images wouldn't go amiss. To that end, I'd like to invite folks to post proposed reference changes here.

Rules:

1) For any section of the reference you change, please post the exact type path, the lines you removed, and the lines you added. They should be inside DM tags. This will make it easy for me to find and replace the old text.

2) KISS. Less text is better, as long as it's clear.

3) If you want to provide a new image to use, you don't have to inline it yourself. I can handle that part if I like the image. Just point the <img> tag to the image's location, and include the image in the thread. (It's actually better if I handle the optimization and inlining myself, as I can shrink the image using AdvPNG and pngout for best results. But if you want to try using those as well, by all means.) I want to keep images super small wherever possible.

4) The few images that are present use Trebuchet MS as the font. This would be preferred for consistency.

A couple of years back, the website had a "dynamic" reference that allowed moderators to add comments to entries. Do you still have the data for that? I don't remember how many comments were actually added (I think Garthor wrote most of them), but it might be a good starting point for the community to spruce some of them up and integrate them more directly into the body text.

A couple of years back, the website had a "dynamic" reference that allowed moderators to add comments to entries. Do you still have the data for that? I don't remember how many comments were actually added (I think Garthor wrote most of them), but it might be a good starting point for the community to spruce some of them up and integrate them more directly into the body text.

The underlying posts that were created should still exist (and the comments with them), and the conversion tool should still work. The problem is, the old reference thing was really never updated to work with our new forum setup and requires a major refurb, so it's been back-burnered.

This is a list of icons which are displayed on top of the object's main icon.

The individual items in the list may not be directly accessed, since they are stored in a special internal format. However, the list operators +=, -=, and the procedures Add, Remove, and Cut work normally.

The overlays/underlays list is absolutely not a list of icons, nor is the list inaccessible.

Proposed change:

"This is a list of appearances, which are displayed on top of the main object's appearance.

The invidivudal items in this list can be directly accessed, though it will not reflect exactly what was added. See appearances for further details. All list operators can be used with this list, but be aware that Find() and Copy() will use and return appearance objects rather than the values added initially.

When a data type is added to this list, it is converted to an appearance internally. Data types that may be used as overlays are icons, icon states (text strings), atoms, and atom types. If the appearance of an atom is changed between addition and removal, the intended appearance may not actually be removed. This is because when an atom is used as an overlay, the appearance represents a static "snapshot" of the atom. Future changes to the atom will not change the overlay appearance."

How can you have too many examples? Heck I didn't know what tag was for 5 years until someone mentioned you could use it with locate.

I still have no idea what /ref is and I've never seen it used.

\ref is a text macro that allows you to get the internal id of an object. Every datum, list, client, appearance, sound, matrix, icon, savefile, etc. currently created in the world has a unique reference id. This can be used as a sort of "weak" reference to refer to an object, though it's traditionally used to determine the object that will receive Topic() calls when clicking on a link in a browser or in output.

+ Any changes to the above variables for an atom or image will cause the engine to check for a matching appearance. If it exists, the atom's appearance will change to that existing appearance. If it does not exist, a new appearance will be created instead. Only one identical appearance will exist for each unique combination of these values. When an appearance no longer is associated to any atoms or overlays, it will be removed. The maximum number of unique appearances at runtime is X.

+ ..() will search for the last defined override for the current type's proc in the project. If none is found, it will search backward up the heirarchy up to the first definition of the proc. This should be avoided where at all possible because it incurs extra overhead. The only cases where multiple overrides of the same proc should be used are in the case of making self-contained libraries that do not interfere with existing code.

I made a change to ..() along those lines. This is what I added, right before the paragraph "..() can also be used for predefined procs":

If O overrides the same proc more than once, ..() will search for the previous version and use that. For instance, you could have two O.history() procs; the second overrides the first, but the original could still be called via ..(). The original in turn could call ..() to reach P.history(). Overriding the same proc more than once in the same type should be avoided wherever possible, because it incurs extra overhead, it makes the code harder to read, and it isn't always clear which one gets called first. (Usually, the only time you'll want this to happen is when using libraries.)

The reference completely neglects any mention of UP/DOWN in the get_step, step and walk functions as a possible bit flag for the dir argument. (actually, the reference completely forgoes the explanation that directions are bitflags in DM)

In the entry for 'cache', it mentions:
"It is also possible to include additional supplementary .rsc files by using the #include statement. "

It might be a good idea to add this to the entry for the include directive. This was added back in version 230:

You may now include entire resource cache archives. This might be useful in library code that has its own resource files. Instead of distributing all the individual resource files (and having to worry about the directory where the user installs them), you can just compile your library and distribute the source code along with the .rsc file. The user can then simply include your .dm and .rsc files (or you could include the .rsc file yourself), eg:

#include "mudlib.rsc" turf/icon = 'glob.dmi'//this could be a file that exists in mudlib.rsc

Does this merely merge the two rscs into one, or does this actually allow you to share resource pools with another game making it so that you don't have to download the exact same rsc twice if two games share it?

Yeah, you can literally pre-compile a rsc and distribute it in a project. Or compiling projects with different themes...something. Fast changing of mass resources.

Like, imagine if people made 'mapper packages' (for mappers who don't need to see much code) WITHOUT SHARING ANY ICONS!

Does this merely merge the two rscs into one, or does this actually allow you to share resource pools with another game making it so that you don't have to download the exact same rsc twice if two games share it?

Technically, this shouldn't be happening either way? I thought BYOND did some checking in terms of not downloading the same files across worlds.

This is what we did with Eternia's map maker, we included the Eternia.rsc but not the actual dmi files. The first time you compile you'll get a warning about the file only existing in the rsc, but it'll go away in subsequent compiles that session.