search

elixir-lang / ex_doc

ExDoc produces HTML and EPUB documentation for Elixir projects
http://elixir-lang.org
Other
1.44k stars 324 forks source link

Selectable/copyable text includes evaluation output #1944

Closed harrisi closed 1 week ago

harrisi commented 3 weeks ago

Example code that shows output from iex nicely doesn't copy the iex prompt, so you can paste it into iex without issues. However, the output of the evaluated input is copied, which sometimes causes issues, or just unnecessary evaluations.

This isn't a huge problem, but I think it can be slightly improved. I think either the output can also be non-selectable, or perhaps when the code is copied, a # is prepended to the output lines.

I'm trying to remember where I had an instance where pasting the copyable text into iex caused in issue, but I can't find it right now. I'll update this when I find it (it was somewhere in Elixir's docs). I know the try, catch, and rescue iex examples cause issues, but I think there was others.

Any thoughts about this would be helpful. Happy to implement any changes, but I wanted to see if there was a preference for one of the changes, or if none is required.

josevalim commented 3 weeks ago

If this is something we can improve, it would be welcome, but I have a feeling that it won't be straight-forward at all. Please explore and let us know!

harrisi commented 3 weeks ago

One other instance is anything that outputs a pid in a container, for example from supervision trees and applications, although there are other pages that this happens with.

I'll also say that the comment approach seems less ideal, I think. Presumably the purpose of the iex examples is only to paste it into iex. I considered the comment approach only because if you copy and paste the code as text for a comment to reference or notes or something, seeing that output would occur is slightly handy. That seems like a more niche use case.

harrisi commented 1 week ago

I looked a bit more into this and I think it's more work than I initially thought. More importantly, if I'm not mistaken, this is more of an Makeup issue, I think. I believe that's where the "selectability" of lines is actually defined. So this should really be an issue for that repo, I think?

In the interest of not leaving stale issues, it may be worth opening an issue over there, or just leaving it as is for now and if I get time I'll try to open a PR.

josevalim commented 1 week ago

Given it needs to happen on makeup first, we can close this one. But I think we will need to change it here too, by discarding some classes from selection, but the changes here would be minimal. :) Thank you for investigating!