Manual: reference to wimp_ICON_BUTTON_TYPE_SHIFT

[Tony van der Hoff]

Erik Groenhuis <e.groenhuis at xs4all.nl> wrote in message
<6baffdf04d.root at vertus.xs4all.nl>

> As Tony van der Hoff <tony at vanderhoff.org> wrote:
> 
> > Jonathan Coxhead <jonathan at doves.demon.co.uk> wrote in message
> > <43DBDEC8.5040207 at doves.demon.co.uk>
> > 
> > >     Erik Groenhuis wrote:
> > > 
> > > > How about enclosing the symbols in special characters, so DefMod can
> > > > recognise them. E.g.
> > > > 
> > > >                       "shift button bits by
@Wimp_IconButtonTypeShift@",
> > > > 
> > That is certainly a possibility, but represents quite a lot of work, in
> > manually searching through .swi files.
> 
> I suggest
> 
> for file in * do
>    grep -f regex $file
> done
> 
> where the file regex contains
> 
> ".*_.*"
> 
> which describes a comment that contains an underscore.

Well, yes, that would drag out the strings containing an underscore in
comments :)

> 
> > It is relatively easy for DefMod to gather cross-references where
> > identifiers are defined in one file, and used in another, because files
> > which contain definitions are "included" ("needs" in DefMod-speak) with
> > the those that require them. This woud not, and could not be the case
> > where the cross-references are merely comments. I do not know how
> > significant this is; maybe I'm worrying unnecessarily.
> 
> In the general case, any symbol could occur in a comment. However, I
> strongly suspect that comments will only contain references to symbols
> that are either local or included.
> 
> Off the top of my head, there may be some exceptions involving obsolete
> SWIs, where a reference is put in the comment to the preferred SWI.
> 
> > > 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"
> 
> Though from a language-construction point of view I'd prefer the enclosure
> in special characters, like @Wimp_IconButtonTypeShift@ and
> %Wimp_IconButtonTypeShift%, the above syntax may be easier to handle for
> DefMod. This is because DefMod does not use a lexical analyser. Also the
> names "variable" and "konstant" will probably be easier for the user to
> remember.
> 
> BTW: why "\k", and not "\c". And why not "\f" for function in stead of
> "\v"?
> 
Well, I don't think it matters greatly. Whoever implements the change is, as
far as I'm concerned, welcome to do whatever he wants, provided it doesn't
break anything.

> > > 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.
> > > 
> > Yes, this is a variation of Erik's proposal. The problem is that it's a
> > manual process, and thus tedious, although anyone could contribute (hint
> > to all you users :).
> 
> I'm game. :-) I'll go and find out how many strings are involved in this
> job. If less than, say, 100, I'm prepared to do them by hand.
> 
Thanks, Erik; I suspect it's a lot less than 100.

> > > 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!
> > > 
> > Yes, well, it does :) Although I've fiddled with YACC for DefMod; I have
> > never really got my head round it, but I'd be happy to put the above in
> > the code, if that's all it takes!
> 
> The immediate advantage is, is that the above change will not affect
> behaviour if there are not code tokens in the strings.
> 
> Of course, the Yacc code to recognise \v and \k needs to be added too.
> 
Your patches will be welcome :)

-- 
Tony van der Hoff        | mailto:tony at vanderhoff.org
Buckinghamshire, England