How do I typeset mixed-code for docs.racket-lang.org?

[Sage Gerard]

One of my projects allows for embedding Racket modules within <script> elements, within a Markdown page.

## Hello World

<script type="application/racket">

#lang racket/base

...

</script>

In my scribble manual, I want to typeset code examples that look like that and have it look decent. Here's what I tried:

1. I wrapped the whole thing in @verbatim. Easiest to do, but has no linking or syntax highlighting.
   
2. Wrapping everything before a Racket block in @verbatim and wrapping the Racket code in @racketmod. Better, but there's a dotted line to the left of only the Racket code. That, and I don't see an obvious way to control indentation of Racket blocks within a larger code block.
   
3. I used just @racketmod with #:file "<script type=\"application/racket\">, to imply that the module is wrapped.
   

None of them were just right. I'd rather have syntax highlighting and consistent styling for the whole mixed-code block. I'm assuming I will need to write my own styles.

As per the subject line I don't know if there's any sanitization step or other restrictions in place that would break any customizations I put in before my manual appears on docs.racket-lang.org. Are there any such restrictions?

And as a secondary question: Is there an easier way to go about this I have not considered?

~slg

[William J. Bowman]

This got me interested.
I tried a quick hack on my scribble-minted package to allow for nesting
different languages.
Is this something like what you want?
https://www.williamjbowman.com/tmp/scribble-minted/nested.html

Source here:
https://github.com/wilbowma/scribble-minted/tree/nested-minted/nested.scrbl

--
William J. Bowman

On Tue, Oct 08, 2019 at 05:06:40PM +0000, Sage Gerard wrote:
> One of my projects allows for embedding Racket modules within <script> elements, within a Markdown page.
>
> ## Hello World
> <script type="application/racket">
> #lang racket/base
> ...
> </script>
>
> In my scribble manual, I want to typeset code examples that look like that and have it look decent. Here's what I tried:
>

> - I wrapped the whole thing in @verbatim. Easiest to do, but has no linking or syntax highlighting.
> - Wrapping everything before a Racket block in @verbatim and wrapping the Racket code in @racketmod. Better, but there's a dotted line to the left of only the Racket code. That, and I don't see an obvious way to control indentation of Racket blocks within a larger code block.
> - I used just @racketmod with #:file "<script type=\"application/racket\">, to imply that the module is wrapped.

>
> None of them were just right. I'd rather have syntax highlighting and consistent styling for the whole mixed-code block. I'm assuming I will need to write my own styles.
>
> As per the subject line I don't know if there's any sanitization step or other restrictions in place that would break any customizations I put in before my manual appears on docs.racket-lang.org. Are there any such restrictions?
>
> And as a secondary question: Is there an easier way to go about this I have not considered?
>
> ~slg
>

> --
> 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/NiutSl24Fj7L2enxSzKGQ3fj-gZPNlmyNR9BEJ8zbI079gkCQd-uSI-kFcVOM-OqSDMtzjNv2R8m58HIZrtXqLEHBtZUpAd7jT1vTvbunR0%3D%40sagegerard.com.

[Sage Gerard]

Hi William,

Sorry for the delay and thank you for responding so quickly.

It's a night and day difference in terms of presentation. I don't see documentation links functioning (e.g. the "displayln" in your example). I'm assuming that since @minted only applies to styles, it will function fine if composed with @racketmod and friends?


~slg

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Tuesday, October 8, 2019 3:05 PM, William J. Bowman <w...@williamjbowman.com> wrote:

> This got me interested.
> I tried a quick hack on my scribble-minted package to allow for nesting
> different languages.
> Is this something like what you want?
> https://www.williamjbowman.com/tmp/scribble-minted/nested.html
>
> Source here:
> https://github.com/wilbowma/scribble-minted/tree/nested-minted/nested.scrbl
>

> ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

>
> William J. Bowman
>
> On Tue, Oct 08, 2019 at 05:06:40PM +0000, Sage Gerard wrote:
>
> > One of my projects allows for embedding Racket modules within <script> elements, within a Markdown page.
> >

> > Hello World
> >
> > ------------

> >
> > <script type="application/racket">
> > #lang racket/base
> > ...
> > </script>
> > In my scribble manual, I want to typeset code examples that look like that and have it look decent. Here's what I tried:
> >
> > - I wrapped the whole thing in @verbatim. Easiest to do, but has no linking or syntax highlighting.
> > - Wrapping everything before a Racket block in @verbatim and wrapping the Racket code in @racketmod. Better, but there's a dotted line to the left of only the Racket code. That, and I don't see an obvious way to control indentation of Racket blocks within a larger code block.
> > - I used just @racketmod with #:file "<script type=\"application/racket\">, to imply that the module is wrapped.
> >
> > None of them were just right. I'd rather have syntax highlighting and consistent styling for the whole mixed-code block. I'm assuming I will need to write my own styles.
> > As per the subject line I don't know if there's any sanitization step or other restrictions in place that would break any customizations I put in before my manual appears on docs.racket-lang.org. Are there any such restrictions?
> > And as a secondary question: Is there an easier way to go about this I have not considered?
> > ~slg
> > --
> > 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/NiutSl24Fj7L2enxSzKGQ3fj-gZPNlmyNR9BEJ8zbI079gkCQd-uSI-kFcVOM-OqSDMtzjNv2R8m58HIZrtXqLEHBtZUpAd7jT1vTvbunR0%3D%40sagegerard.com.
>
> --
>
> 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/20191008190555.GE710%40williamjbowman.com.

[William J. Bowman]

Oh right I forgot about documentation links.

No, scribble/minted won’t play well with the scribble/manual functions. It hijacks the renderer to use the pygmentize binary to generate typeset target code (HTML or LaTeX); it doesn’t just apply scribble styles.

--
Sent from my phoneamajig

> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/ASzLGsS0L4pgrRyxKTmGD8MWp9vc64rdSO7lLJT_r1etAkrVbN73CXd_v74dkiIh-Jm9UWddAuCzit2sGptPM5gxtLYLJbZ5G6CAf5P6tQo%3D%40sagegerard.com.

[Philip McGrath]

The way I would approach this would probably be to:

1. Create a #lang that accepts your source Markdown+Racket syntax.
2. Add a color lexer as you would for DrRacket, probably using `syntax-color/racket-lexer` for the Racket parts or dynamically getting a color lexer based on the #lang line.
3. In the Scribble manual, embed these fragments with `codeblock` and `code` rather than `racketblock` and `racket`: https://docs.racket-lang.org/scribble/scribble_manual_code.html

-Philip

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/1EA9CB23-7719-4107-958C-943C5982D713%40williamjbowman.com.