bug: `parsers.py` can misattribute the `#audit-ignore` comment

[moritz-gross]

see PR #728

as recently spotted by @yasumorishima, the placement # audit-ignore can have some misleading behaviour, as the following example is not properly recognized:

# audit-ignore
- name: per-fraction
  tag: fraction
  match:
  - ...

but on the other hand, this works:

- name: per-fraction # audit-ignore
  tag: fraction
  match:

In the design of the audit-ignore tool, I didn't give this part much attention, but now thinking about it, placing the comment directly in front of the affected rule looks the cleanest to me.

My proposal is to implement this and document it as a best practice in the docs.

thoughts and opinions on this?

[moritz-gross]

@daisy/mathcat-translators

(side question: does using "@..." in an edit of an issue alert other people by sending a notification, or does it have to be a new issue / comment ? )

[MartheGjelstad]

I agree. To place the comment on the line before the rule seems like a good idea.

I received a notification. But your tag was probrably in a new comment. I am not sure what happens if you edit an issue.

[AndersEkl]

We placed it at the end of the first line of the rules, as in your second example. I think both options should be recognised. We would have to update all the Swedish rules again to adjust the placement otherwise.

[MartheGjelstad]

That's a good point, @AndersEkl! I would have to do the same for the Norwegian files.

[AntonLMTM]

I prefer the comment before the rule, and I think only a single option should be valid for readability and ease of use.
I believe it's not too difficult to change and I could do it for the swedish (and norwegian) files.

[yasumorishima]

I counted what is actually in the tree today, since the choice decides how much has to be rewritten. Measured on ja at d65daed1, over all of Rules/Languages/, classifying each # audit-ignore by where it sits:

lang	total	end of the name: line	on the line before the rule	some other line inside the rule
nb	110	76	0	34
sv	101	54	0	47
hu	42	40	0	2
ru	11	0	0	11
ja	2	1	0	1
total	266	176	0	90

So the position being proposed as canonical is the one position nobody uses yet: accepting only "the line before the rule" invalidates all 266 existing markers at once.

@AndersEkl the "end of the first line" convention is also less uniform than it looks from the outside — 47 of the 101 Swedish markers sit on a later line of the rule, and the same is true for 34 of 110 in Norwegian and all 11 in Russian. Those work today only because has_audit_ignore searches the whole rule body. Japanese has one of each form, so either decision is cheap for me; I am reporting the numbers because they are not cheap for sv/nb/ru.

My preference is to keep matching anywhere in the rule body and additionally accept the line immediately before it, then document one recommended position. That fixes the reported bug (the case that silently does nothing today), keeps every existing file valid, and still lets new rules be written the clean way. If a single position really is wanted for readability, it would be worth pairing the parser change with a script that moves the existing markers, so no language is left with silently-ignored audit-ignore comments — the failure mode is invisible until someone reads the audit output and finds extra findings.

(Also happy to be corrected on the counts — the classifier is: a line matching #\s*audit-ignore, then "end of name line" if that same line matches ^\s*-?\s*name:, "before" if the next line does, "other" otherwise.)