Manual: reference to wimp_ICON_BUTTON_TYPE_SHIFT

[Erik Groenhuis]

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.

> 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"?

> > 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.

> > 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.

-- 
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