documentation inconsistently uses ... to mean splice/splat/slurp vs ellipsis

[artkuo]

The language uses three periods "..." to mean splice/splat/slurp, e.g.

as documented in varargs-functions.

But the documentation also often uses ellipsis not to literally mean three periods in a row, but to mean the equivalent of et cetera. From the same page,

I find this confusing especially in the documentation on arrays, where both meanings are used liberally, and sometimes both interpretations are legal, and sometimes not.

I propose that documentation should only use three periods to indicate splice/splat/slurp, since they are explicitly part of the language. Three periods should therefore never be used to mean et cetera or yada yada, because of the ambiguity.

Unfortunately , I do not have a good solution to this problem. One possibility is to reserve the actual ellipsis character "…" (a single character, often the product of auto-correct) to mean yada yada (or perhaps splice), but this is not necessarily easy to distinguish. Perhaps a leading space (as sometimes is used in current documentation) followed by ellipsis in a distinct color would help, but perhaps not enough to be clear to those unfamiliar with the convention. The problem is that humans will naturally tend to write "..." which is usually not legal code and therefore can be read correctly by other humans.

[ArchRobison]

Perhaps for etc. use three Unicode "middle dots"? Example: [A B C ···]. Middle dot is used by Julia for dot product, but three in a row would clearly be not that.

[jiahao]

There is U+022EF = \cdots = ⋯ = MIDLINE HORIZONTAL ELLIPSIS.

[StefanKarpinski]

Using the ⋯ character seems like a good idea.

[ArchRobison]

Yes. I would have suggested it if I'd known it existed. I see that the Wikipedia entry for ellipses has a table with it.

[artkuo]

Here's what it looks like with middle ellipsis. I think it is sufficiently distinguishable.

I have tried this out in a fork of doc/manual/arrays.rst and it seems to look sensible. However I don't dare submit a pull request because I am new at this and am still confused about it. There cases where the docs say "dims..." and I think they mean ellipsis, but the literal ... is both legal and in some cases even meaningful. This whole inquiry started because I saw somewhere that you can use hcat(A...) to do amazing things, so I started to look for cases where this was done, and discovered many where the intent was (probably) ellipsis. I would be happy to help out somehow, if I knew where splice/splat is definitely intended.

[nalimilan]

Just make a PR, possibly highlighting a few places where you aren't sure, and people will check them. No worries, you will be able to update it at will!

[JeffBezanson]

I think the midline ellipsis is risky given possible lack of support in many fonts.

... by itself is not valid syntax; it has to be attached directly to an expression. i.e. f(x...) is valid syntax, but f(x, ...) is not. Therefore I would use the latter one for "etcetera". I think that's the best solution.

[toivoh]

There's also #5405, which proposes to make indexing such as A[..., i, k] valid. I agree that the font support is risky, but this seems a bit too subtle.

[ArchRobison]

Indeed I was having trouble finding a fixed-width font for Windows with U+022EF (\cdots). There are a few, but choices are limited. U+0B7 (\cdot) seems fairly common.

[JeffBezanson]

Ok, if U+0B7 is widely supported then I'd be ok with using three of those.

[JeffBezanson]

Until, of course, somebody wants to use them within the language :)

[JeffBezanson]

Ah, apparently U+0B7 is actually \cdotp.

[brenhinkeller]

So a lot has changed in the docs over the last 8 years; there are probably still some cases where ... is has multiple possible conflicting interpretations but I don't see many particularly confusing ones at a glance. I'll close this, but if anyone sees something along these lines in the docs that particularly annoys them, feel free to open a PR.