Copy button on documentation code examples produces unusable code

[Maria-12648430]

Describe the bug
Most code examples in the documentation follow this pattern:

1> do_something().
{ok, some_result}
2> do_something_else().
{ok, other_result}

That is, prompt+input followed by output.

When using the copy button on such code examples, what gets copied to the clipboard is garbage, give or take.

The prompts are removed from the input lines, which is fine.

The results are not removed, and moreover, the following input line is placed directly after it, on the same line.

Even if the results were to be left out from the examples, the following inputs are placed directly after the previous one. Since that way, there is no whitespace after the . finishing the previous input line, this is a syntax error.

(Note: Don't be confused by the copy button on my example above. This one is put there by GitHub.)

To Reproduce
Taking code examples from ets:select_reverse/1 for illustration.

This is what is shown in the document:

1> T = ets:new(x,[ordered_set]).
2> [ ets:insert(T,{N}) || N <- lists:seq(1,10) ].
...
3> {R0,C0} = ets:select_reverse(T,[{'_',[],['$_']}],4).
...
4> R0.
[{10},{9},{8},{7}]
5> {R1,C1} = ets:select_reverse(C0).
...
6> R1.
[{6},{5},{4},{3}]
7> {R2,C2} = ets:select_reverse(C1).
...
8> R2.
[{2},{1}]
9> '$end_of_table' = ets:select_reverse(C2).
...

... and this is what ends up on the clipboard when the copy button is used:

T = ets:new(x,[ordered_set]).[ ets:insert(T,{N}) || N <- lists:seq(1,10) ].
...{R0,C0} = ets:select_reverse(T,[{'_',[],['$_']}],4).
...R0.
[{10},{9},{8},{7}]{R1,C1} = ets:select_reverse(C0).
...R1.
[{6},{5},{4},{3}]{R2,C2} = ets:select_reverse(C1).
...R2.
[{2},{1}]'$end_of_table' = ets:select_reverse(C2).
...

Expected behavior
The copy button should produce code that can be directly pasted into the shell. Otherwise, if that can't be done, remove the copy button since it is useless.

Affected versions
All that use the new documentation system (?)

[frazze-jobb]

We should not have "..." in the documentation, instead output lines should just be omitted.
But we still have a problem since output seems to be pasted without a newline in between it and the following input line. We have output in the examples that are used as expected output for tests. See ets:select_replace/2.
This is part of ex_docs, and how it should be fixed I don't know. Either this newline thing is fixed, which means that we would paste the output lines into the shell, (hopefully they are valid terms, but unnecessary).
Or output lines are omitted entirely.
If there are usecases where you would like to copy the output lines also, maybe two buttons would be needed.
Ping @josevalim

[frazze-jobb]

The whitespace problem seem to be a problem with erlang docs only, not a problem of elixir docs. I will continue investigating what we do differently there.

[josevalim]

The project that does syntax highlighting is this: https://github.com/elixir-makeup/makeup_erlang

I will take a look it, it seems to be a silly issue. If you look at the code, you can see the line break that precedes the prompt is being made part of the unselectable. I will compare Erlang and Elixir and hopefully do a quick fix:

<span class="gp unselectable">
2&gt; </span>

[Maria-12648430]

We should not have "..." in the documentation, instead output lines should just be omitted.

I'm fine with that, it may take some manual work though, finding all ... or whatever serves as a placeholder for irrelevant output.

which means that we would paste the output lines into the shell, (hopefully they are valid terms, but unnecessary).

No, I don't think this is at all feasible. Doc examples usually mimick shell input/output (hence the included prompts, N> ), so the outputs should also mimick what the shell would do. Which includes pretty-printing and ellipsizing.

For illustration, imagine an example for lists:seq, 1, 1000). In my shell, it looks like this:

1> lists:seq(1, 1000).
[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,
 23,24,25,26,27,28,29|...]

This shows that the output is a) not a valid term (because |...]), and b) does not end in an .
To make it a valid term, it would have to be a) output in full, and b) have a . tacked on. Neither of this is what the shell would display.

Or output lines are omitted entirely.

This is what I would prefer, unconditionally.

If there are usecases where you would like to copy the output lines also, maybe two buttons would be needed.

Not a bad idea actually. There may be use cases where you want to copy everything, prompts and outputs included, eg for use in teaching material. And there are the use cases where you want to copy and paste in the shell, in which case there should only the input lines, ie no prompts and no output lines.

In fact, right now the copy feature is a useless mixture of both:
It can't be pasted in the shell; the prompts are removed, but the output lines are there, plus the whitespace issue (which looks like to be fixed fast, thanks @josevalim 🤗).
It can't be used to copy everything either; the prompts are removed, they are not even selectable if you select manually (in my opening post, I had to manually add them back for one of the examples).

I can imagine that it is not exactly easy to not copy the output lines, they're not easy to identify. But again, as it is now, the copy feature is not useful. Even with the whitespace issue solved, I would still have to paste it in a text editor, delete the output lines, then copy that again and paste that in the shell.

That all said, I just noticed that there are examples written in a way where it makes no sense at all to have them copied, see for example ets:match_spec_run/2. There are ellipses all over the place even in the input lines.

[josevalim]

Whitespace fixed here: elixir-makeup/makeup_erlang@31b3c2c

v1.0.3 is out, I have also bumped the version in ex_doc. I can ship a new ex_doc if necessary.

---

There are two use cases for the copy button:

1. You want to copy the whole snippet as is
2. You want to copy only the prompts

The current situation is not good for any of those cases. I agree that solving 2 is hard, so we should at least make 1 work. @Maria-12648430, if you agree with the above, can you please open up an issue on ExDoc? I think the only actionable item for OTP is to remove the .... It looks like one of the things coding agents can do quickly and you just verify later.

[Maria-12648430]

There are two use cases for the copy button:
...
The current situation is not good for any of those cases.

That summarizes it perfectly 👍

can you please open up an issue on ExDoc?

Sure, I will see to it tomorrow 🙂

[frazze-jobb]

I guess we could do some kind of convention that, input lines that span several lines, are indented with '..' like the default in the shell, but have those ".." unselectable.

-doc """
_Example_

```erlang
1> fun(X) ->
..    X + 1
..  end.
#Fun<erl_eval.42.20128056>

´´´
"""

Then lines not starting with "\d>" or ".." are output lines. Or am I missing something?

[josevalim]

The main issue is that makeup doesn't really distinguish between Erlang code snippets and Erlang shell snippets. So basically, all snippets are treated the same and we simply mark anything that looks like a prompt unselectable. For this to work, we would need to have two styles, erlang and erlang-shell or similar, or a heuristic that checks if it starts with a prompt and then select accordingly. It is definitely doable, but it is more work.

In any case, supporting .. as a prompt could also be done (it is a separate discussion).

[Maria-12648430]

@frazze-jobb I haven't even thought of multi-line inputs yet, but yeah, that has to be considered, too.

It would make preparing examples in the shell and copying them over to docs a bit cumbersome. The ..s disappear in the shell as soon as you finish the input line, so you have to add them back. This is IMO acceptable, you're not going to do this every day.

The pattern would have to be refined a little. Ie, if the length of the prompt number is >1, the .. is indented by spaces in the shell; it must also be followed by either an immediate newline (ie, empty line in a multi-line input) or a space.

The following is more severe, though.

Then lines not starting with "\d>" or ".." are output lines. Or am I missing something?

-doc """
_Example_

```erlang
1> io:format(".. do_something().\n").
.. do_something().
ok
´´´
""".

This is exactly what you would see in the shell if you typed in the part after the 1>. However, having that in an example, the copy button going by "if it starts with .., it is part of a multi-line input" would put...

io:format(".. do_something().\n").
do_something().

... on the clipboard. And if that gets pasted in the shell, there would be a call to do_something()..

That may look silly and contrived, and as presented here I agree 😜 But what it boils down to is that you can't include in examples the output of stuff that produces anything that starts with \d+> or .. .

[Maria-12648430]

The main issue is that makeup doesn't really distinguish between Erlang code snippets and Erlang shell snippets. So basically, all snippets are treated the same and we simply mark anything that looks like a prompt unselectable. For this to work, we would need to have two styles, erlang and erlang-shell or similar, or a heuristic that checks if it starts with a prompt and then select accordingly. It is definitely doable, but it is more work.

In any case, supporting .. as a prompt could also be done (it is a separate discussion).

Hm, without having tried it out, this would mean that in a contrived example like this:

-module(foo).

test() ->
"
1>
..
".

... the 1> would become unselectable/not copied? If yes, making .. a prompt would only extend that quirk to the ..?

[Maria-12648430]

(Sorry if I'm making this even more complicated than it already is 😅)

[garazdawi]

Whatever your conclusion here is, please also keep in mind the decisions made in the shell docs test module regarding how the shell examples should look like.