Up to Main Index Up to Journal for November, 2020 JOURNAL FOR SATURDAY 28TH NOVEMBER, 2020 ______________________________________________________________________________ SUBJECT: Undocumented feature fixed and officially documented DATE: Sat 28 Nov 20:45:30 GMT 2020 While working on updating the zone files recently I tried to be clever, not a good idea. It started when I tried to use an @REF in a free text block: %% Ref: L38N1 Name: some rubbish Alias: RUBBISH Inventory: Narrative: This rubbish is dirty and smelly. Why are you wasting your time with it? %% Ref: L39N1 Name: some rubbish Alias: RUBBISH Inventory: Narrative: @L38N1 %% There are multiple definitions for rubbish and I thought to just reference the first description. If you are wondering why there are multiple definitions of RUBBISH — something is hidden there somewhere ;) Specifying the @REF on L39N1 to reuse the free text block from L38N1 worked. If I examined the rubbish: >exam rubbish You examine the rubbish. This rubbish is dirty and smelly. Why are you wasting your time with it? However the dangling @L38N1 on the definition looked odd and I could see it being easily overlooked. The free text block in a record jar does not have a field name specified. When a record jar is read a field name can be specified to use for the free text block and it will automatically be assigned. In the case of WolfMUD zone files the free text block is automatically named Description. There is an undocumented feature that lets you specify the free text block field directly. So I modified the above example to: %% Ref: L38N1 Name: some rubbish Alias: RUBBISH Inventory: Narrative: This rubbish is dirty and smelly. Why are you wasting your time with it? %% Ref: L39N1 Name: some rubbish Alias: RUBBISH Inventory: Narrative: Description: @L38N1 %% That should have worked, it did work previously… >exam rubbish You examine the rubbish. Description: This rubbish is dirty and smelly. Why are you wasting your time with it? Oops, the field name ‘Description:’ has been included as well :( Things start to get worse if you specify a named Description field and a free text block for the same record, or if the named Description field continues over more than one line. Hrm, undocumented and broken. I’ve just pushed a change to the public dev branch that fixes these issues and makes a named Description field work correctly with or without a free text block. In the case of both being specified the free text block is appended to the text for the Description field, as if it is a continuation line. However, the free text block portion will retain any special blank line and white-space formatting within it. When would you use a named Description field and/or a free text block? A Description field can be used for simple, usually shorter, text without any white-space formatting. The free text block should be used for longer text or where white-space formatting is required. When would you use both together? No idea, I can’t think of a good example — if you come up with one let me know ;) In the case of a description consisting of just an @REF, using the named Description field is perfectly acceptable. As I said, the fix is out on the public dev branch. I’ve also updated the documentation in docs/zone-files.txt to include the Description field and updated the description of the free text block. New tests have also been added to cover these cases as well. Note also that this will work regardless of what you call the free text block. If you call it ‘Text’ when reading the record jar you will get a ‘Text’ named field that works just like ‘Description’ above. -- Diddymus Up to Main Index Up to Journal for November, 2020