Suggestions for "The Racket Guide"

[Liwei Chou]

Hello there, I’m reading "The Racket Guide" online and I have a little suggestion that if you can make the code easier to copy, it will be much easier for beginners to go through.

For example, just like Wolfram Language’s tutorial, if you hover your mouse over a code snippet, it will appear a little bubble. If you click that bubble, it copies the code to the clipboard.

https://www.wolfram.com/language/fast-introduction-for-programmers/en/interactive-usage/

My two cents. :)

[Stephen De Gabrielle]

That’s a good suggestion! Do you know the relevant JavaScript we can try it out with. Might be an easy PR.

[Ben Greenman]

On 4/8/20, Stephen De Gabrielle <spdega...@gmail.com> wrote:
> That’s a good suggestion! Do you know the relevant JavaScript we can try it
> out with. Might be an easy PR.
>

Beware that snippets are not always self-contained.

A button should grab any requires and earlier code needed to make the
example run. That'd be very very useful --- but maybe not so easy.

[Sorawee Porncharoenwase]

Thoughts:

- I take a look at the compiled HTML document. It doesn't seem suffice to only change JavaScript because the information about "what is the input" is pretty much lost at the HTML level.

- IIUC, Scribble targets older version of HTML (HTML4?), so it doesn't really care about the semantics of tags -- only the appearance is considered. It might be possible to add an ad-hoc hack to make this feature work, but it would be even better to follow the modern HTML practice in the first place, which would make these kind of customization trivial.

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAFUu9R5QLaMvnMh4krLZJTBHz%3Dbo1aLv%3DYkS1amF-2yJU55-aw%40mail.gmail.com.

[Greg Trzeciak]

Found in an old file of mine:

 

<script type="text/javascript">
  'use strict';
  var codeblock = document.getElementsByTagName('blockquote');
  for (var i = 0;i<codeblock.length; i++) {
    var isCode = codeblock[i].className.indexOf('SCodeFlow');
    if ( isCode === 0 ) {
       var button = document.createElement('button');
                    button.className = 'copy-button';
                    button.textContent = 'Copy';
                    codeblock[i].appendChild(button);
    }
  }
  var copyCode = new Clipboard('.copy-button', {
    target: function(trigger) {
        return trigger.previousElementSibling;
    }
  });
 
</script>



<style type="text/css">
.SCodeFlow { position:relative; }
  .copy-button {
        opacity: 0.2;
        -moz-box-shadow:inset 0px 1px 0px 0px #ffffff;
        -webkit-box-shadow:inset 0px 1px 0px 0px #ffffff;
        box-shadow:inset 0px 1px 0px 0px #ffffff;
        background-color:transparent;
        -moz-border-radius:6px;
        -webkit-border-radius:6px;
        border-radius:6px;
        border:1px solid #dcdcdc;
        display:inline-block;
        cursor:pointer;
        color:#666666;
        font-family:Miso;
        font-size:20px;
        font-weight:bold;
        padding:4px 18px;
        text-decoration:none;
        text-shadow:0px 1px 0px #ffffff;
        position:absolute;
        top:0;
        right:0;
  }
  /*.SCodeFlow:hover > .copy-button:hover {  */
  .copy-button:hover {
        opacity: 0.7;
        -moz-transition-property: opacity;
        -webkit-transition-property: opacity;
        transition-property: opacity;
        -moz-transition-duration: 0.15s;
        -webkit-transition-duration: 0.15s;
        transition-duration: 0.15s;
        /*background-color:transparent;*/
  }
  /*
  .copy-button:active {
        position:relative;
        top:1px;
  }
  */
 
</style>

[Robby Findler]

The information is there at the source level in the way the evaluators are used but I guess it gets discarded by the time the code gets to html. 

There is also the issue that some of the context code is relevant and some isn't, so not all of the information is actually there to make the most compact examples to copy. 

Robby 

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CADcuegsRAXZ8jOTY0Mt52i6X_BD5N%3DjCO8ypyCYrAjBDZomfRQ%40mail.gmail.com.

[Greg Trzeciak]

I forgot the dependecy used:

  <script type="text/javascript"

          src="http://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.4.2/clipboard.min.js"></script>

[James Platt]

While we are looking at the possibility of improving The Guide, one of the things which I find confusing in Racket documentation is that The Guide, The Reference and various manuals all look the same. On several occasions I have started in The Guide, followed links, and then discover that I am in The Reference instead. I think what is happening is that The Guide links to stuff in the other manuals and then the manuals link to both The Guide and The Reference. You can easily end up moving from on to the other without realizing it. The easiest way to figure out where you are, as far as I can tell, is to examine the URL of the page but this is an easy thing to miss. I think it would help quite a bit to adopt some visual cue as to where you are. This could be as simple as a change in the background color of the page or something like that. It would also be great, in any case where an item appears in both The Guide and The Reference, to have a link from one to the other. For example, in The Guide, you would have a link for each item with a label called something like "See this page in The Reference."

[Matthew Butterick]

I use the same Clipboard.js library on Beautiful Racket to support code copying. (I use v.1.5.15, though apparently the lib is now at 2.0.6).

I've not had any problems or complaints. 

One wrinkle in implementation is that you don't want to pass formatted HTML to the clipboard. Obviously, what the user wants is the plain code. What I found is that I had to put two versions of each code block on the page: one that's visible, with all the styling annotations, and one that's plain (though not plain text — you still need to observe HTML whitespace and escaping conventions) that gets fed to the clipboarding function. I suppose one could go the other way, and scrape the formatting markup off the visible code. I have no patience for this kind of "software" "engineering".

On Apr 8, 2020, at 10:45 AM, Greg Trzeciak <gtrz...@gmail.com> wrote:

I forgot the dependecy used:

  <script type="text/javascript"

          src="http://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.4.2/clipboard.min.js"></script>

On Wednesday, April 8, 2020 at 7:24:20 PM UTC+2, Greg Trzeciak wrote:

Found in an old file of mine: