JuliaLang/julia — pull request #8636 by artkuo (2014-10-09 04:09:18+00:00)
Title: doc: clarified use of ellipsis in manual to refer to splice only

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](https://groups.google.com/forum/#!msg/julia-dev/mj3I8hqc71g/8-J7nMvC5-0J) 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.