Manual: reference to wimp_ICON_BUTTON_TYPE_SHIFT

[Tony van der Hoff]

Jonathan Coxhead <jonathan at doves.demon.co.uk> wrote in message
<43DBDEC8.5040207 at doves.demon.co.uk>

>     Erik Groenhuis wrote:
> 
> > As Tony van der Hoff <tony at vanderhoff.org> wrote:
> > 
> > 
[snip]
> > 
> > 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@",
> > 
That is certainly a possibility, but represents quite a lot of work, in
manually searching through .swi files. 

My initial thinking on this is that when defmod performs the name mangling
on identifiers, it could probably search through the comments for an
identifier matching the one it's presently working on, and do the same
mangling there. That would probably not be a lot of work, but may be
somewhat simplistic.

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

I was subconciously thinking of a method that doesn't involve mark-up;
simply fom the viewpoint of minimisig effort. It has no bearing on the
stronghelp files; but simply getting it in the right format in the first
place.

[snip]

> 
>     Happy new year, one and all!
> 
It's good to hear from you again, Jonathan; and nice to know you're still
keeping a watchful eye on how things are going here :)

Happy new year to you, too.

>     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".
> 
Heh, I have just added those comments to the DefMod source!

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

However, unless I'm missing something, I believe it could be automated as I
proposed above; there may be some cases where it results in peculiarities
(e.g. typos in the comment strings, or inappropriate translations), but
these could be dealt with on a case-by-case basis. 

A further thought is that we could combine the two ideas, using the mark-up
method, by writing code to process the .swi files, thus removing most of the
tedium from the process. It would only need to be run once; and maybe could
be done in a PERL script (my PERL is, at best, shaky, however).

> 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.
> 
(0) I'm not convinced that Asm users use the help much; I don't think it's
very useful to them; perhaps they would like to comment? However, the theory
is of language-independance; and it wouldn't be sensible to travel along a
path that pre-supposes C.

(1) I think, to a large extent, we already generate seperate pages for each
language; I suspect that the increase is likely to be fairly minor.

(2) 
> *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! It certainly beats coding a lot of C.

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