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