(Non) empty description in .swi files

[Tony van der Hoff]

Erik Groenhuis wrote:
> As John Tytgat wrote on 31 Dec 2008:
> 
Hm, meant to repliy to the earlier posting:

[snip]

>> Any reason for this inconsistency ? Is there an usecase to limit the
>> use of SWIs without description (and without a star) ?
> 
I don't think so. I rather suspect it's a bug, which has not been picked 
up throughout OSLib's lifecycle. I would agree it needs fixing.

However, looking at the grammar, I note:

description:
    DESCRIPTION
       {  tracef ("DESCRIPTION \"%s\"\n" _ $1);
          $$ = Empty;
          $$.description = EMPTY ($1)? NULL: qstrdup ($1);
          $$.starred_swi = TRUE;
       } |
    STAR
       {  $$ = Empty;
          $$.description = NULL;
          $$.starred_swi = TRUE;
       };
This looks like it's intended that the STAR case is treated the same as 
the EMPTY case, and that therefore something is broken elsewhere.

I'm probably misinterpreting this (it's years since I pretended to 
understand DefMod), but it doesn't seem logical that $$.starred_swi is 
set true in any case. I don't think it's relevant to this problem. 
Unfortunately, I'm at present not really in a position to dig deeper.

>> My proposal is the make the empty description case the same was the
>> 'star' case, so an artificial description gets automatically
>> generated.
> 
Aye.

> I expect that SWIs without a description will be left out of the
> generated StrongHelp manuals, and SWIs with a star will be included.
> 
> This might be a feature that is currently in use, so the distinction
> between no description and 'star' should remain. This should be checked.
> If this is the case, the problem would have to be solved in another way.
> 
I don't think so, and there would be little point in having these 
"undocumented" veneers. However, if that's the way things work out, then 
  it's not a problem either way.

> On the other hand, the quoted documentation does not mention the 'no
> description' case. This would suggest that it is an unfortunate
> by-product of the parser, maybe intended to allow liberal input.
> 
Eric, with all respect, it would really have been much more helpful if 
you'd sought the facts, rather than indulging in idle speculation, and 
dictating what needs to be done based upon that speculation.

> In that case your proposal is a good one. I'd also suggest making the
> 'no description' case an error, demanding a description or at least a
> star. In case there are too many uses of 'no description' in the
> existing .swi files, I'd suggest making it a warning. Both error and
> warning should preferably be controlable with switches (e.g. "suppress
> 'no description' warning", or "reduce 'no description' error to a
> warning".  
> 

Um, unless you're proposing to do this work yourself, in which case we'd 
welcome your patches, I think what you're proposing is an overkill; 
certainly at this stage of the game. I think it's best to let John make 
the minimal changes as he proposes, without trying to gild the lily.

The philosophy throughout the development of OSLib, first expounded by 
Jonathan, is that whoever does the work should decide on the extent of 
the job.

That does not, of course prevent anyone from making proposals, as you 
have done, and for which we are truly grateful. Baing them on known 
facts would have been preferable.

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