Code snippets in sentences

Stream: general

[Martin Dvořák]

How can we make code snippets look good in sentences? Example:

We write f x because we ...

It somehow looks good here in Zulip, but when I write a similar thing in Word or LaTeX, it ends up looking horrible. Instead of "f x" looking connected, it optically groups "write f" together and "x because" together. Absolutely disgusting!

The problem is, obviously, that spaces in a monospace font are wider than spaces in normal text.
What can we do about it? A few options came to my mind...

1. Make the space before/after a code snippet at least as wide as a monospace space.
2. Not use a true monospace for code snippets in text but modify the font to have a narrower space. Keep true monospace only for code in a display mode.
3. Add a background color (probably very light gray) to the code snippets. To be effective, however, the background color must extend slightly to the sides of the code snippets (and only the white part of the space before/after a code snippet is a standard space), which partially includes the first suggestion (results in a wider gap in total).
4. Add a frame (rectangle) around the code snippet.

A disadvantage of (1) and (4) is that it looks weird. I don't know if I would get used to it if I saw it often.

A disadvantage of (2) is that it make code snippets look differently in sentence vs in display mode, and most texts need to combine both versions. As long as the font looks identical otherwise, it is hopefully acceptable?

A disadvantage of (3) is that it limits how we can use lexical highlighting inside a code block because we have less available contrast between the color of the background and possible colors that we can use for characters (without adding white as a feasible option for characters). Moreover, certain combinations of placement of code snippets in consecutive lines start to look slightly weird.

What do you think?

[Jireh Loreaux]

These are solutions waiting for a problem.

[Eric Wieser]

This is what I did in my thesis:
da7c2241-19c5-4a38-8b02-9a5fffb044a2.png
b2d6bc20-36ff-46b5-a1f2-edcb5bb4b1ec.png

(I needed two colors, one for Lean 3 and one for Lean 4)

[Eric Wieser]

But along the lines of what Jireh says, this is ultimately not that interesting a question, because either a journal will have thought of this and made their own decision, or will not and will mangle code snippets horribly whatever you do.

[Martin Dvořák]

Well, sometimes we are in charge of our own typesetting (in my case, for my Ph.D. thesis).

[Gavin Zhao]

Have you considered using Typst?

[Martin Dvořák]

No. Should I?

Does it have better defaults for code snippets? Or is it easier to setup the style I want to have?

[Gavin Zhao]

Yes, you should definitely try it out! You write it like Markdown with backticks and it automatically renders code snippets as you expect how it would render in Markdown, example here: https://typst.app/docs/reference/text/raw/

[Gavin Zhao]

(also with reasonable syntax highlighting for Lean snippets)

[Martin Dvořák]

I don't think the example they provided looks good.

[Joscha Mennicken]

As far as I know, typst has no easy way for inline code blocks with all three of these properties:

• background color
• rounded corners
• line wrapping

mostly due to https://github.com/typst/typst/issues/2939. Sacrificing rounded corners or line wrapping makes the other two properties possible. Adding extra space around inline code blocks is easy.

[Martin Dvořák]

I never use automatic line wrapping, but thanks for the info.
Thank you for further reïnforcing my decision to not use Typst.

[Joscha Mennicken]

By line wrapping, I mean an inline code block that wraps over one or more line breaks.

[Martin Dvořák]

Yes — in such a case, I either rephrase the sentence so that it stays in a single line, or I change it to display mode.

[Eric Wieser]

As opposed to inserting a continuation zigzag as I do above?

[Martin Dvořák]

Yes.

[Joscha Mennicken]

In that case, typst is easy to make look good.

[Martin Dvořák]

Oh!

[Joscha Mennicken]

See https://typst.app/project/rcn8LqfZSSvQYGohluxTAA for a few possible ways to style code blocks in typst

[Martin Dvořák]

Looks good! Thanks.

[Martin Dvořák]

One things I noticed is that Zulip still makes the space inside a code snippet wider than the space before/after a code snippet, but thanks to the gray background, it doesn't look too disturbing. Behold (zoomed in):
image.png

For my Ph.D. thesis, however, I didn't want a non-white background, so I essentially followed the approach (2). Tweaking the font would be difficult; instead, I made the font size smaller for spaces (but only in inlined code).

PM me if you want to hear more thoughts on this topic.

[Eric Wieser]

I'm surprised it's not possible to invoke the standard tex glue machinery here

[Martin Dvořák]

In which setting? I am writing my Ph.D. thesis in MS Word.

[Eric Wieser]

By "glue machinery", I'm referring to how regular spaces in $\TeX$ are resized to adjust the line width. Monospace spaces in \verb are not by default, because a) this would make them not match the letter widths, and b) I think this glue machinery does not permit multiple adjacent spaces.

[Eric Wieser]

Martin Dvořák said:

instead, I made the font size smaller for spaces

Doing this in word for a thesis-sized document with more than 10 code snippets sounds absolutely insane to me; are you really going to inspect every space to check you applied the right font size to it, which I assume you will do via clicking on each one in turn?

[Martin Dvořák]

Eric Wieser said:

By "glue machinery", I'm referring to how regular spaces in $\TeX$ are resized to adjust the line width. Monospace spaces in \verb are not by default, because a) this would make them not match the letter widths, and b) I think this glue machinery does not permit multiple adjacent spaces.

Ah yes, I know how glue works in TeX. I suppose you can hack \verb to do it the same way glue works in normal text?

[Martin Dvořák]

Eric Wieser said:

Martin Dvořák said:

instead, I made the font size smaller for spaces

Doing this in word for a thesis-sized document with more than 10 code snippets sounds absolutely insane to me; are you really going to inspect every space to check you applied the right font size to it, which I assume you will do via clicking on each one in turn?

Of course! Moreover, I adjust the width of the space according to the semantics of given code snippet and the line breaks in my paragraph.

[Eric Wieser]

I suppose if you wrote a visual basic macro to do this space resizing automatically for you this would be a little less of a time sink, though still mad in its own way

[Eric Wieser]

Maybe if you built a whole suite of macros you'd end up with a document preparation system that looks perfect algorithmically...

[Martin Dvořák]

It isn't such a horrible time sink. When compared to how long it takes me to compose a good English sentence, the extra work to do three additional clicks for every inline-code spacebar press is small.

[Michael Rothgang]

I'm amazed you can write your thesis in MS Word and survive in the end. (I never looked back after switching to LaTeX, only sideways to markdown :-))

[Martin Dvořák]

Well, let's talk about survival when I am done with it!

[Patrick Massot]

Who forced you to do that?

[Martin Dvořák]

Nobody. Do I sound like I'm complaining?

[Eric Wieser]

Michael Rothgang said:

I'm amazed you can write your thesis in MS Word and survive in the end. (I never looked back after switching to LaTeX, only sideways to markdown :-))

I was very sympathetic to @Edward Ayers' take that LaTeX sucked and html was the right way to write a thesis, but ultimately chickened out once I remembered the university wanted pagination in a physical book

[Martin Dvořák]

To be fair, I did sound like I was complaining in the beginning, because I was really complaining — I was complaining about something I didn't know how to solve in any of the two programs. But now that I have a working solution in MS Word (and moreover, I believe that a good solution in TeX exists as well), so I am completely happy now!

[Joscha Mennicken]

My bachelor's is written in LaTeX and my master's in Typst. Luckily, my uni didn't have strict requirements on the exact format for the master's thesis :)

[Julia Scheaffer]

Eric Wieser said:

html was the right way to write a thesis

I enjoy HTML as a typesetting system too, but it seems to be an unpopular opinion. :sweat_smile:

HTML/CSS does have systems for typesetting for print that are quite useful, but I'm sure LaTeX or Typst are better suited for it.