Add comments with TODOs after LaTeXML issue is fixed

[henrikt-ma]

These are notes for the future, after narrowing down what #2867 was really about.

[henrikt-ma]

Now that I understand the mechanisms behind the problems, I realized that it made more sense to put a workaround in place than just wait for the external issues to be fixed.

[HansOlsson]

I'm not sure about skipping angles here (and the similar line below). The n here should normally be replaced by a number (such as 3 for quaternions).

[henrikt-ma]

Couldn't we solve this nicely by rephrasing this slightly and placing it before the listing?

The \lstinline!residue! output of the \lstinline!equalityConstraint! function shall have known size, say constant $n$.

[eshmoylova]

I also like having it as <n>.

[henrikt-ma]

I don't find the angle bracket construct very pretty in general, but still useful for placeholders in need of a textual description. For something acting as a placeholder for a number, I find it more consistent to use the rather well established use of "meta variables" typeset as math.

[eshmoylova]

What are the well-established meta-variables? Where are they established?

[henrikt-ma]

It strikes me now that the use of n in the listing would actually assume that it is an Integer dimension – is this really the current intention? To me, the current text would actually allow an array indexed by Boolean or enumeration (both of which will result in a constant size, which is the requirement), and I don't see that it would really be a problem to do so. If we want to make it more clear that this is allowed, I suggest this:

Suggested change

	output Real residue[$n$];
	output Real residue[$\langle$$\mbox{\emph{constant size dimension}}$$\rangle$];

In the text, we could elaborate this further:

The \lstinline!residue! output of the \lstinline!equalityConstraint! function shall have known size, say constant $n$. (That is, $n$ cannot depend on inputs to the function, and the array cannot have flexible size given by colon (\lstinline!:!).)

[eshmoylova]

I would be OK with removing the angled brackets around n. But I feel like we need to open a separate issue to clarify what "known size" means. If we come up with a concise wording we could consider putting that into the angle brackets in the code.

[eshmoylova]

Created #2886.

[henrikt-ma]

Good. @HansOlsson, would you then be OK with the resolution to move (with some rephrasing) the sentence introducing n to before the listing?

[HansOlsson]

I would be ok with different variants of that - and I agree with @eshmoylova that it seems best to have a separate issue for that, so resolving, accepting and merging this.