doc: clarified use of ellipsis in manual to refer to splice only

[artkuo]

This is a second attempt at a pull request associated with #8593. The complaint was that "..." is a keyword, but was sometimes used in documentation to mean "etc." and not splice/splat/slurp. To remove ambiguity, the suggestion was made to use "⋯" (midline ellipsis) for "etc." I have tried it out and I like it. I have attempted to preserve all appearances of "..." for splicing (and occasionally "⋮" to mean lines of code), but would appreciate a close look to make sure I did not accidentally change the wrong thing.

A few discussion points:

1. It was pointed out that "dims..." might be what was intended, but I converted these to "dims,⋯" because I believe that agrees best with the accompanying text for that section. The problem is that "dims..." is perfectly legal and might be intended sometimes. I believe the documentation is intended to explain basic syntax, and those familiar with splicing would understand that splicing could apply here.
2. It was pointed out that "⋯" is unicode and might cause font problems for some. On my Mac, the character tool shows midline ellipsis rendered correctly in all 66 font variations shown. So I believe this is an acceptable solution, better than a keyword being used ambiguously. Also, note that the documentation uses unicode characters such as Chinese in various places, as well as pi. But if it is decided that the unicode midline ellipsis is unacceptable, then I suggest that the original "dims..." should be written as "dims, ..." because that is at least more clearly not legal code, whereas the former was completely ambiguous. When "etc." is intended, it should be written in such a way that it is absolutely umambiguous.
3. I have sprinkled in the terms "splat" and "slurp" in a few cases. It was pointed out elsewhere that "splicing" is used inconsistently and does not capture direction. The term "splatting" is more specific and is recognized e.g. in Python as such. The term "slurping" was suggested in that same discussion. I'm not sure how serious people were, but one of my edits uses it; please delete if you don't like it. (Although I do think it would help two separate terms to distinguish the two different uses, and splicing is problematic due to ambiguity.)
4. A completely other possible solution is to retain "..." in documentation to mean "etc." This is what it means in the docs for many other languages, and when new docs are written, it is not guaranteed that people will know to use midline ellipsis. But that means the language syntax should change to not use ellipsis. A possible idea would be "args >.." to mean splatting and "args <.." to mean slurping or ">.. args" as a prefix slurp. This is probably not a popular idea, but I thought I'd throw it out there.

This is my second attempt at a pull request. I messed up horribly on my previous attempt, due to ignorance of how git works. I apologize for my mistake and hope this one works better.

[pao]

This is my second attempt at a pull request. I messed up horribly on my previous attempt, due to ignorance of how git works. I apologize for my mistake and hope this one works better.

Don't worry about it! No harm done.

[JeffBezanson]

Testing this on a Mac is not very convincing, because Macs are known to have extremely good font and character support.

[ivarne]

Looking at the diff on a first generation Nexus 7 only displays squares instead of ⋯, which might be annoying for people using (older?) Android to read docs.

[JeffBezanson]

Yes, we'd be asking for problems like that. It worries me because it's such a spurious way to make the docs hard to read. It trades slightly confusing for totally unreadable on some platforms.

[pao]

We could fill it with a webfont which provides the missing character--this might also be good for the Unicode operator table.

[artkuo]

Some of these questions could be resolved with appropriate policies on unicode, monospaced fonts, and the documentation system. For example, here are two possible policies on unicode:

1. Julia fully embraces unicode, and characters beyond UTF-8 are allowable in official documents and documentation.
2. Julia fully supports unicode in the language, but characters beyond UTF-8 are discouraged in official docs and documentation in most cases, due to uncertain font support.

Pt. 2 doesn't seem to be the policy now. For example, if you type pi, you get out a unicode π (plus some digits and then three periods meaning "etc"!). If Pt. 2 were to be the standard policy, then another solution would be needed regarding the current pull request.

About monospace fonts: In #8593, there was suggestion to use three \cdots U+0B7 (I think it's "⋅⋅⋅") instead of the unusually spaced "⋯". Personally I prefer the latter because it is more distinct from an ellipsis. Also, I feel that monospacing is not so easy to figure out. When editing in monospace, many things in the .rst files do not line up, and there are various escape characters like `` such that the editor view differs from the formatted view. If you want things to line up in monospace, it would need to be decided whether this should favor editor view or formatted view. RST already formats things like tables well, so the only formatting problem is when the .rst is meant to show monospace code, and whether that really needs to line up with something. I would think usually not, plus as unicode takes over, it will tend to whittle away at monospacing.

Here is yet another fallback plan. To preserve monospacing and avoid unicode, perhaps use a comma and "...." to indicate "etc." for example "hcat(A, ....)" This is less likely to be confused with ellipsis. I don't find it as cool as ⋯, but it is more pragmatic. The change could be done very easily, as the effort of this pull request was trying to sort out the ambiguous cases, not in the search and replace.

[StefanKarpinski]

The issue isn't really about ASCII vs. non-ASCII, but rather that this is a relatively new Unicode character that doesn't have widespread support in browsers and such. Greek letters like π have pretty universal support. The language itself has to support all of Unicode, but we can't control what browsers do.

[artkuo]

Then perhaps it would be sensible to go with ", ...." (four dots!) which uses no special characters, preserves monospacing, is clearly not legal code or keyword, and is still relatively unlikely to be confused with splicing.

[pao]

but we can't control what browsers do.

We can probably assume a browser that supports webfonts.

Using STIX (which includes U+022EF, as well as a whole bunch of other technical/mathematical caracters) as a webfont: http://hublog.hubmed.org/archives/001931.html

If I could get Font Squirrel to cooperate, and we could find a suitably licensed MIDLINE HORIZONTAL ELLIPSIS, this would be pretty easy to Firefox crashes FTW

[JeffBezanson]

If only there were a free, open source midline horizontal ellipsis!

[StefanKarpinski]

And thus the Julia WebFont was born...

[pao]

Thanks, Firefox crashes, for readding the end of my comment! (Incorrectly.)

[artkuo]

I don't think a WebFont really addresses the issue of old browsers, and I thought the intent behind .rst was to separate content from form (somewhat), and not depend too closely on fonts. A built-in assumption/requirement of STIX would tie form to content, as would a GIF image of \cdots.

To reiterate above, I'll suggest three possibilities:

1. Use the midline ellipsis ⋯ which would mean dealing with issues with some browsers
2. Convert to the less ambiguous four-dot etc.: "...." which is ugly but reasonably clear
3. Back to the drawing board

(The Julia WebFont sounds great, but to account for increasing pixel densities, best to design a full Postscript font with hinting, and ligatures, so you can render at a variety of resolutions. It should have LaTeX math support too.)

[pao]

I don't think a WebFont really addresses the issue of old browsers

It explicitly doesn't. But as to @ivarne's test above, I'm pretty sure the Jelly Bean browser does support them; if not you can install Chrome or Firefox, and the Nexus 7 (2012) can be upgraded to KitKat. So I'm personally not too worried about pre-WebFont browsers.

We're not depending on fonts--we're depending on the code point to be rendered in some sort of reasonable way, which lots of systems can do (OS X seems fine, as does my Windows 7 machine). We can also manipulate that to ensure that a fallback font exists which can render that code point. The STIX font can provide that fallback.

[quinnj]

It seems there was broad consensus against going with this change due to lack of support for midline ellipsis.