Below is the contents of building_custom.txt, defining the Soapmaker's Workshop
[OBJECT:BUILDING]
[BUILDING_WORKSHOP:SOAP_MAKER]
[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]
[DIM:3:3]
[WORK_LOCATION:2:2]
[BUILD_LABOR:SOAP_MAKER]
[BUILD_KEY:CUSTOM_SHIFT_S]
[BLOCK:1:0:0:0]
[BLOCK:2:0:0:0]
[BLOCK:3:0:0:0]
[TILE:0:1:' ':' ':150]
[TILE:0:2:' ':' ':'/']
[TILE:0:3:'-':' ':' ']
[COLOR:0:1:0:0:0:0:0:0:6:0:0]
[COLOR:0:2:0:0:0:0:0:0:6:0:0]
[COLOR:0:3:6:0:0:0:0:0:0:0:0]
[TILE:1:1:' ':' ':'=']
[TILE:1:2:'-':' ':8]
[TILE:1:3:' ':' ':150]
[COLOR:1:1:0:0:0:0:0:0:6:0:0]
[COLOR:1:2:6:0:0:0:0:0:6:0:0]
[COLOR:1:3:0:0:0:0:0:0:6:0:0]
[TILE:2:1:'-':' ':8]
[TILE:2:2:' ':' ':8]
[TILE:2:3:' ':150:' ']
[COLOR:2:1:6:0:0:0:0:0:6:0:0]
[COLOR:2:2:0:0:0:0:0:0:6:0:0]
[COLOR:2:3:0:0:0:6:0:0:0:0:0]
[TILE:3:1:150:' ':8]
[TILE:3:2:' ':' ':8]
[TILE:3:3:' ':240:' ']
[COLOR:3:1:6:0:0:0:0:0:6:7:0]
[COLOR:3:2:0:0:0:0:0:0:6:7:0]
[COLOR:3:3:0:0:0:7:0:1:0:0:0]
[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]
What can we glean from this text?
I'll address every Tag from top to bottom in order, and explain the ones I can make sense of.
[OBJECT:BUILDING] This tag is probably required at the start of every building. I haven't experimented with it, so I can't be certain of that.
[BUILDING_WORKSHOP:SOAP_MAKER] Since only custom workshops are in at this point, Building_Workshop seems redundant. If the system is generalized to other types of buildings later, maybe it won't be. This tag is what the workshop is named in all other raw references, for permitted buildings in the creature raws for example.
[NAME:Soap Maker's Workshop] This is what is actually going to show up when you hit b in dwarf mode.
[NAME_COLOR:7:0:1] This is the color of the name as it is displayed in the building menu, and possibly after it's already been built, and you 'q' over it, or otherwise visit any menu that references it. it uses the same method as creature colors, foreground:background:brightness
[DIM:3:3] This is an interesting one. In the development logs, he did mention being able to have workshop sizes other than 3x3, and this is the tag to do that. For obvious reasons having either dimension being 0 is impossible, but you can have a building of whatever size you want, within reason. I suspect extremely large sizes are not supported or would cause glitches. I haven't tried putting 500:500 in there, but if anyone wants to see what happens, be my guest.
[WORK_LOCATION:2:2] This defines where in the building the dwarf will stand to work. In this case, in the center
[BUILD_LABOR:SOAP_MAKER] The skill used by the building is defined here. You can't add new job or skill types right now, so you're always going to be refering back to an existent skill as defined under the PERMITTED_JOB tags in entity_default.
[BUILD_KEY:CUSTOM_SHIFT_S] This tag defines the button shortcut for selecting the building. This can be left blank, meaning that you have to use the secondary selectors in the menu to scroll over and highlight the building name to build it. Custom is presumably always required, but can be followed with any letter or Shift_any letter for the capital version, as the tags are always capitalized.
[BLOCK:1:0:0:0]
[BLOCK:2:0:0:0]
[BLOCK:3:0:0:0]
Determines whether any tiles of the building are impassable once built.
[TILE] and [COLOR]: are closely related. First, I must explain why they are iterated three times. It merely shows the progress of the construction, starting at the first and ending at the last.
[TILE] defines the displayed tile at each block, appears to be able to take in characters surrounded by ' ' such as empty spaces or =, or can reference objects on the tileset you're using by number, without ' ' around them.
[COLOR] tags look complicated but aren't. Each line contains three instances of the color codes, foreground:background:brightness, for each tile the building is wide. The first number is not part of the color codes, but instead determines whether it's just been laid down,
- construction is started [1], progressing [2] or finished [3]
[BUILD_ITEM:number of items:item type (if not stone):unknown:unknown:unknown]
(all three unknowns probably have something to do with quality, item material, and if an object like a rope, cloth, or thread, how much is required. Cannot be sure until experiments are done, or Toady tells all.)
[EMPTY] means the object cannot contain anything (like water in this case), presumably.
[CAN_USE_ARTIFACT] The bucket can be an artifact bucket.
[BUILDMAT] Restricts the item to building materials such as wood logs, raw stone, and blocks of wood, stone or metal
[WORTHLESS_STONE_ONLY] Only non-economic stones will be permitted for building this structure. I guess [CAN_USE_ARTIFACT] refers to blocks being used, if somehow a dwarf makes artifact stone blocks.
There may be more tags that are not in the Soapmaker's Workshop. Toady would need to inform us of that.