ID:104336
 
Keywords: dm, reference
Libraries will never be as easy to use as BYOND's built-in features because their documentation cannot be accessed as easily. It's possible to add your own entries to DM's reference so that pressing F1 can show reference pages related to content your created in a library. Having these reference pages would be useful for any library. Reference pages are simple to make, but unfortunately they're a hassle to maintain and difficult for the end user to setup (some built-in support would really help here).

This post on my forum outlines the process a user has to go through to set up a custom DM reference.

As you can see there are some problems with this:
1. If another library provided a custom reference you'd have to pick between which pages you wanted. One info.html file would overwrite the other.
2. It's a hassle to set up. It's not terribly difficult but the user shouldn't have to do any work to set this up.

That being said, here is how you can create your own reference pages:

Start by locating DM's reference. If you installed BYOND to c:\program files\byond\ the reference will be in the c:\program files\byond\help\ref folder. There are four HTML files in that folder. Even if you don't know HTML you should be able to figure out what they do.

contents.html controls what is displayed in the "Contents" tab of the help window.

info.html contains the majority of the reference. It is a list of pages. Dream Maker splits this huge document into pages. For each page there is an entry in the listbox on the "Topic" tab of the help window.

A page in info.html looks like this:

<hr>

<a name=/atom/var/x>
<h2>x var (atom)</h2>

<dl><dt><b>See also:</b>
<dd><a href=#/atom/var/loc>loc var (atom)</a>
</dl>

<dl><dt><b>Default value:</b>
<dd>The x coordinate of the object on the map.
</dl>

<p>You may assign the coordinates of movable objects (mobs and objs), but this
is not advisable. It is better to compute the new location (with
<code>locate()</code>) and move them to that. Then you can use the normal
<code>Move()</code> procedure, which enables all the normal movement behavior.

<p>For areas that are on the map, this is the coordinate of the turf with the
lowest z, y, and x coordinate (in that order) that is contained by the area.

<hr>


The page is contained between the <hr> tags. The first <a> tag creates an anchor that you can use to link to this page (for creating the "see also" links). The <h2> tag contains the title of the page that gets displayed in the list. These are the only required tags. The rest of the content can be structured however you want, though it's a good idea to follow the established conventions. You can look through info.html to see how code snippets and other things are put into reference pages.

By adding pages with this format to info.html you can create your own reference pages. The Dream Maker program will automatically add these pages and display them when a user searches for help. This way a user can press F1 to get help about a proc that is part of a library. For example, if you press F1 with the cursor over "set_pos" you'll see this help page about my sidescroller library:



In the list of topics you can see other pages that I added (set_background and set_camera). This topics list, being able to press F1 for help, and following "see also" links can make libraries much easier to understand and use.
It would be nice if DM supported reference pages as part of libraries. Perhaps something like a .dmr (DM Reference) that you can create and then add pages for the reference to use. The pages would be automatically added to the reference whenever you have the dmr included (inherently through a lib or directly from your source).
I made a feature request similar to that. Initially I had flagged it as being a security risk but I wanted to make this documentation available for my library.

http://www.byond.com/members/ DreamMakers?command=view_tracker_issue&tracker_issue=2360