Regrettably, this doesn't work properly with the "empty \opt detection": In a case like \opt{\grammarterm{blah}}, there's an error. So I've disabled the check for now.

We can probably fix the empty \opt detection by moving the index entry after the text in \grammarterm. Though I suspect the right fix is to \protect ... something.

@zygoloid: "We can probably fix the empty \opt detection by moving the index entry after the text in \grammarterm." Well, I tried this (unrelated to \opt), and it messes up kerning / spacing, for example when a period or comma follows.
(Also, the empty \opt detection never actually worked for me in the sense of giving a proper error message; I always get the usual "TeX parser is messed up" incomprehensible error blurb for empty \opt.)

You might try the \isempty macro from the xifthen package. It's more robust than \isequal{#1}{}.

@godbyk: It does avoid the error for \opt{\grammarterm{blah}}, but adds a new package dependency. Also, I've simply put an \opt in the middle of running text (no braces), and it doesn't flag the misuse. I'm inclined to believe that I'm fighting an uphill battle against TeX's basic parser here, and we should simply give up on checking for empty \opt arguments.

If you write blah \opt blah, then #1 will be b (and therefore won't be empty).

The \isempty check would catch cases like \opt{} \opt\relax \opt\empty and similar.

@godbyk: Ah, ok. Hm... But that's one of the main motivations/use-cases here: something\opt somethingelse should be an error, if the check is worthwhile to have in the first place. If we can't do that, I'd say scrap the check.

@jensmaurer Ah, I see. Well, it's doable, but it's a bit tricky. One way would be to rewrite the macro to not take an argument via \newcommand. Then within the macro, you'd scan ahead one char to see if it's an open brace {. If not, throw an error. If it is, then continue collecting tokens until you find the closing brace.

However, it might be easier to just add a grep check to the Makefile and/or .travis-ci.yml file to find cases where \opt isn't followed by an open brace.

@godbyk: Agreed regarding adding a Travis-CI check. Done.

Rebased.

@jensmaurer: Could you please take a look at the grammarterm index log? There are a lot of warnings now.

@tkoeppe: I see these warnings:

Warning (input = grammarindex.idx, line = 2206; output = grammarindex.ind, line = 8):

-- Conflicting entries: multiple encaps for the same page under same key.

which is caused by (e.g.) access-specifier defined on page 227 (bold entry) and used on page 227 (non-bold entry). Two entries on the same page with different formatting is apparently disliked by "makeindex".

Do you know how to tell "makeindex" that the "bold" entry should probably win in these cases? Or we can leave the status quo, it's not wrong.

@jensmaurer: I have no idea, I just noticed this, but I would really really like to not have any warnings.

@tkoeppe: Well, feel free to create a new issue so that we can discuss this. Preferably not in a merged pull request.