Manual: reference to wimp_ICON_BUTTON_TYPE_SHIFT

[Erik Groenhuis]

As Tony van der Hoff <tony at vanderhoff.org> wrote:

> To put some more flesh on that; Wimp.swi contains, amongst other things:
> 
> //Icon flags bits
> TYPE Wimp_IconFlags = .Bits;
> CONST
>    Wimp_IconButtonTypeShift= .Int: 12, //shift
>    Wimp_IconButtonType     = Wimp_IconFlags: 0b1111000000000000
>                         "shift button bits by Wimp_IconButtonTypeShift",
> 
> Wimp_IconButtonTypeShift is declared as a CONST, but its use is described in
> a comment field.
> 
> When DefMod generates the C headers, for anything defined as CONST, it
> performs the appropriate action on the name, thus: 
> Wimp_IconButtonTypeShift becomes wimp_ICON_BUTTON_TYPE_SHIFT. 
> 
> It performs different renaming tactics on other parts of the code, and, of
> course, assembler headers are left unmangled.
> 
> However, it presently does not perform any action on comments, so in this
> case the Wimp_IconButtonTypeShift remains unmangled.

[snip: Changeing the comment text to suit C is not feasible]

It is indeed a separate case. Normal symbol names are part of the
syntax of the .swi file. In the comment, it is embedded in a string.
DefMod would have to recognise a symbol inside a string, and change it
as appropriate.

How about enclosing the symbols in special characters, so DefMod can
recognise them. E.g. 

                      "shift button bits by @Wimp_IconButtonTypeShift@",

Which for the StrongHelp manual can be replaced by:

Description: 	shift button bits by
 <Wimp_ICON_BUTTON_TYPE_SHIFT=>Wimp_ICON_BUTTON_TYPE_SHIFT>

Or, because it is a local (Wimp_) reference:

Description: 	shift button bits by <Wimp_ICON_BUTTON_TYPE_SHIFT>

And for assembler (I'm on less familiar ground here) replaced with:

    ; shift button bits by Wimp_IconButtonTypeShift

that is, simply remove the special characters.

This method also allows you to control which symbols to convert, and
which not (e.g. "called on entry to Wimp_Poll" for Wimp_FilterPrePoll).

> A programmatic solution is therefore desirable, and I guess feasable within
> file scope, but as DefMod only processes a single file at a time, and some
> of these things span multiple files, it would be a very nasty hack to catch
> all cases.

Can you indicate what the problem is when it spans multiple files? As I
understand it, StrongHelp currently handles references to symbols that
are defined in other .swi files very well (using the <xxx=>xxx> syntax
as above).

For example: the type wimp_open refers to os_box with "<osbox=>os_box>",
and refers to the (local) symbol wimp_w with "<wimp_w>".

> I think I'll shift my position from "not trivial" to "near impossible" :-(

Do not despair. Help is at hand :-)

-- 
Erik Groenhuis http://www.xs4all.nl/~erikgrnh
Home of RCS for RISC OS v5.7.1.2
StrongARM / RISC OS 4.02 || AMD K7-7 (Duron) / Red Hat Linux 9.2