Item14626: Incorrect example in System.Macros / System.PreferenceSettings

Priority: Normal
Current State: Closed
Released In: 2.1.6
Target Release: patch
Applies To: Engine
Component: Documentation
Branches: Release02x01 master Item14288
Reported By: CrawfordCurrie
Waiting For:
Last Change By: GeorgeClark
When viewing System.Macros, in the Parameters section, the example says

   * Set CONDITIONS = According to [[%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).

but the expansion is

According to Item14626 the sea is choppy today (Set in ...).

This is because the CONDITIONS macro is actually set in System.Macros as follows:

   * Set CONDITIONS = According to [[%BASETOPIC%]], The %WHAT% is %STATE% today. (Set in [[Macros]]).
   * Set WEATHER = It's %DEFAULT{default="raining"}%.

Similarly when viewing PreferenceSettings the example expands incorrectly (there's an extra .)

Not the end of the world, but needs fixing.

-- CrawfordCurrie - 14 Feb 2018

I'm hijacking this to fix a bunch of things.
  • PreferenceSettings never was updated to include %SET{}% dynamic settings.
  • Needs to be documented how they fit into the stack, and effect of FINAL
  • Still documented the deprecated ALLVARIABLES and not SHOWPREFRENCE
  • A number of other inconsistencies and omissions.

-- GeorgeClark - 24 Feb 2018

But ... with all this, I'm not 100% sure I really understood the initial report. I reworked the example a bit, but still needs review. Please check it out if you get a chance.

-- GeorgeClark - 24 Feb 2018

The note is correct, but is a bit lost as the first thing in the Parameters section. You could move it down a few lines:
---+++ Parameters
   * Set CONDITIONS = According to [[%BASETOPIC%]], the %WHAT% is %STATE% today (Set in PreferenceSettings).
   * Set WEATHER = It's %DEFAULT{default="raining"}%.
Macros defined using preference settings can take parameters. These are symbols passed in the call to the macro to define local macros that will be expanded in the output. For example,
< verbatim class="tml">
   * Set CONDITIONS = According to [[%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).
</ verbatim>
You can call this macro passing in values for =WHAT= and =STATE=. For example:
   * =%<nop>CONDITIONS{WHAT="sea" STATE="choppy"}%=
      * expands to =%CONDITIONS{WHAT="sea" STATE="choppy"}%=.
ALERT! Note that %CONDITIONS% expands differently when this example is viewed in Macros. This is because Set statements in included topics are not active in topics that include them. OR you could rework the example so that this confusion doesn't arise in the first place.

-- Main.CrawfordCurrie - 24 Feb 2018 - 09:16

I've relocated the note, and added a blockquote to make the included block it's referring to a bit more obvious.

-- GeorgeClark - 24 Feb 2018
Topic revision: r6 - 13 Jun 2018, GeorgeClark - This page was cached on 20 Jan 2019 - 15:54.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy