Manual: reference to wimp_ICON_BUTTON_TYPE_SHIFT

[Jonathan Coxhead]

    Erik Groenhuis wrote:

> 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" :-(

    Happy new year, one and all!

    There are 2 parts to the problem.

    One is to identify the identifiers in the help text.

    DefMod has 2 ideas of how to rewrite identifiers, defined by the functions 
def_as_macro(), which is used for macros, and means "divide at case-changes, 
convert to upper case except for the prefix, and add underscores", and 
def_as_extern(), which is used for functions, and means "divide at case-changes, 
   convert to lower case, and add underscores".

    So we could introduce 2 mark-up notations, say \v ("variable", for functions 
and types) and \k ("constant" in German, for macros and enumerations), and visit 
all the help strings, annotating them like this:

       Wimp_IconButtonType = Wimp_IconFlags: 0b1111000000000000
               "shift button bits by \k Wimp_IconButtonTypeShift"

    Then it would be reasonably easy to change DefMod* to emit the right strings 
for C, giving this output in the help file:

       shift button bits by wimp_ICON_BUTTON_TYPE_SHIFT

    That's a lot of work, but not too hard.

    The 2nd part of the problem is that (in theory) the help text is language 
independent. There are 3 things that could be done about that:

    (0) Just do the above. Ignore the assembler users, or at least assume they 
can work it out. This is better than the current state, where we effectively 
ignore the C users, assuming *they* can work it out. The numbers indicate we 
should support the C users more than the assembler users.

    (1) Generate a complete separate set of pages for C and assembler. But they 
are quite big already ...

    (2) Put both forms in the same help page, like this

       shift button bits by wimp_ICON_BUTTON_TYPE_SHIFT (C) or
             Wimp_IconButtonTypeShift (Asm)

    This could be done entirely within DefMod, assuming the markup was done, 
though it might lead to some ungrammatical or funny-sounding messages.

    I don't know which of these is better to think about, but I do think the 
current situation is suboptimal.

    *In fact, I think it wouldn't even require a chage in DefMod---it could be 
done entirely inside YACC, as the YACC grammar already contains the logic to 
break up the help strings into words. It would need to recognise the reserved 
words \v and \k and set a state variable. The rule for word_SEQUENCE would 
change from

       word_SEQUENCE: word {strcpy ($$, $1);} |
               word word_SEQUENCE {strcatw ($$, $1, $2);};

to something like

       word_SEQUENCE:
           word
           {
               state == V? strcpy ($$, defmod_as_extern ($1)):
               state == K? strcpy ($$, defmod_as_macro ($1)):
                           strcpy ($$, $1);
               state = START;
           } |
           etc

    It depends on where you like to do your programming!

    Cheers ...
-- 
         /|  Jonathan Coxhead
  o o o (_|/ 23 Camborne Ave
         /|  San Carlos CA 94070
        (_/  +1 (650) 594-1769 (home)
             +1 (650) 430-6564 (mobile)