Mark up math variables using <var>

[hartig]

As suggested by @gkellogg, symbols used in formal definitions (e.g., μ and Ψ) should be marked up using <var> (or |) throughout the whole document.

[hartig]

I want to suggest to postpone taking action on this issue here until #105 #106 #107 and #94 are addressed. Each of these issues touches on parts that contain formulas and, thus, PRs for these issues would likely cause merge conflicts with a PR for the issue here.

[afs]

And like #101, please style the <var> tag when used. It makes detailed CSS control easier.

The SPARQL docs, especially query, have detailed semantic markup (due to EricP) which has been useful.

[TallTed]

[@afs] And like #101, please style the tag when used. It makes detailed CSS control easier.

Explicit advice/instruction is helpful.

In #101, you suggested <code class="syntax">, which I think should only be used for "SPARQL expressions and SPARQL keywords"? Is that correct?

Presuming so, what would you suggest for the <var> class? Is one such class all we need for all <var> instances?

[afs]

The request is to follow the patterns in the existing content. It makes it easier to work on a large document with text tools when there is a consistent approach.

A single class, for now, is better than no class. Having an indirection between reSpec defaults and our docs seems a wise investment.

A better process is that someone should coordinate a proposal for the overall style, presenting alternatives, and examples and allowing others to take that proposal and try out their ideas. By doing that outside of point-by-point pull requests, we can avoid the extra work that can be caused by merge conflicts (see #102 (comment)).

When there is agreement, make the changes in a short period of time.
Let's learn from the situation we have with display on mobile devices.

[TallTed]

follow the patterns in the existing content

Sure, happy to start with that.

But right now, so far as I can tell, there is no <var class="...">, there are only <var>, so following the patterns in the existing content means no class on var elements which does not seem to be what you wanted.

Which is why I asked —

what would you suggest for the <var> class? Is one such class all we need for all <var> instances?

[afs]

But right now, so far as I can tell, there is no , there are only ,

You mean your suggested changes?
#98 (comment)

This issue came from that discussion.

[TallTed]

You asked that I do something like <var class="something"> instead of <var>, and you asked that I follow existing style to figure out what that class="something" should be, but there is no existing style to follow.

All this seems to add up to me picking an arbitrary class value, like class="arbitrary", to put into the <var> tags.

Is that what you're asking me to do?

[afs]

That is my suggest for the changes. Having the same class now is IMO better than no class.

This is an issue - we're discussing options. As noted above, working on the appearance issues (e.g. #101, #102, #103) concurrently with other work on several sections may cause both work items to have to do extra work.

[TallTed]

OK. So, don't follow existing style (since there is now no <var class="...">), but rather, when fixing #102 by tagging with <var>, tag with <var class="var"> (unless you have another explicit suggestion for the class value).

Now the question is what PRs have to be finished before we can address #101, #102, and #103 — or should we just do these three now, address whatever conflicts arise with other active PRs, and not have to worry about further/future conflicts with these three PRs?

[TallTed]

Right now, I see no open PRs on sparql-query, and only 4 overall. This seems like an opportune moment to apply the markup of #101, #102, and #103 to sparql-query, and if they work out, to move forward on the other repositories.

[afs]

There is one in draft: https://github.com/w3c/sparql-query/pulls has one from Olaf #110.

Olaf's request:

I want to suggest to postpone taking action on this issue here until #105 #106 #107 and #94 are addressed.

Maybe there is progress locally.

[TallTed]

#105 #106 #107 and #94

— are issues, not PRs... but I see that resolving each of those (as well as #110) is likely to involve a number of characters and expressions that will be impacted by #101, #102, and #103...

So I guess we remain in a holding pattern.

[hartig]

No need to wait on this issue now.

The other issues, #105 #106 #107 (#94 is closed already), can be addressed also after changing the markup. I currently don't have anything local for them (and am not planning to produce anything during my vacation now).

As for the WIP PR #110, don't worry about that one either! It is a proposal for discussion, with only a minimum number of changes to demonstrate what I have in mind there. If people are generally in favor of this proposal, then I can also reproduce and fully implement it on top of an updated version of the document after the markup has been changed.