Add more examples for cat

[inkydragon]

• cat 2 2D arrays
• cat 2 3D arrays
• cat 2 strings

[mcabbott]

FWIW, #46429 recently tried to provide examples of different cats, in increasing order of complexity, without unduly wasting vertical space.

The assumption in the existing docs, preserved there, was that you ought to understand hcat & vcat first.

Maybe cat(x...; dims) should have more. But how long should it end up being?

E.g. maybe showing strings is nice, because that is where the word comes from. But if it does, why spend lines defining a, b etc, and make multiple blocks... and not just say something like:

julia> cat("a", "bcd"; dims=2)  # does not join strings!
1×2 Matrix{String}:
 "a"  "bcd"

[inkydragon]

But how long should it end up being?

I have another thought: maybe we should make a difference between the help message and the documentation page.

cat in Matlab

• help message:

>> help cat
 cat Concatenate arrays.
    cat(DIM,A,B) concatenates the arrays A and B along
    the dimension DIM.  
    cat(2,A,B) is the same as [A,B].
    cat(1,A,B) is the same as [A;B].
 
    B = cat(DIM,A1,A2,A3,A4,...) concatenates the input
    arrays A1, A2, etc. along the dimension DIM.
 
    When used with comma separated list syntax, cat(DIM,C{:}) or 
    cat(DIM,C.FIELD) is a convenient way to concatenate a cell or
    structure array containing numeric matrices into a single matrix.
 
    Examples:
      a = magic(3); b = pascal(3); 
      c = cat(4,a,b)
    produces a 3-by-3-by-1-by-2 result and
      s = {a b};
      for i=1:length(s), 
        siz{i} = size(s{i});
      end
      sizes = cat(1,siz{:})
    produces a 2-by-2 array of size vectors.
      
    See also [num2cell](matlab:help num2cell -displayBanner).

    [Documentation for cat](matlab:doc cat)
    [Other functions named cat](matlab:matlab.internal.language.introspective.overloads.displayOverloads('cat'))

• documentation page:
  https://www.mathworks.com/help/matlab/ref/double.cat.html

The help message printed out by ?cat should be kept brief.
And the documentation page for cat should be as detailed as possible.

The assumption in the existing docs, preserved there, was that you ought to understand hcat & vcat first.

For short help messages, I agree with this.
But for documentation pages, maybe self-contained is a better option.

But if it does, why spend lines defining a, b etc, and make multiple blocks... and not just say something like:

I think this is a style of programming, though probably better suited to documentation pages.

Of course, defining a variable is only necessary if the variable will be used multiple times, mainly to make the comparison of cases clearer.

---

It may be necessary to open a separate issue to discuss whether the documentation for each function needs to be a separate page.

[ViralBShah]

Yes, this is a larger discussion, and perhaps should be opened up as an issue. We clearly do need longer form api documentation, but it is not always a good idea to have that in the help, but it would be nice to have it in the documentation on the website. Perhaps there are other issues open that discuss this.

[mcabbott]

The manual page is pretty good, BTW, slowly building up what concatenation means:
https://docs.julialang.org/en/v1/manual/arrays/#man-array-concatenation
Perhaps I would lean towards writing vcat, hcat etc. alongside the syntax earlier.

[ViralBShah]

I have an issue talking about documentation of each function being a separate page: JuliaDocs/Documenter.jl#1922

[vtjnash]

There is a notion of # Extended Help already, which will keep ?cat short but make ??cat and the documentation longer