Customise codelisting appearance

[giabaio]

Description

This is related to #5142, where I've left some comments (though it's a closed issue)... I think the main problem was that, by default, the codelisting is set up to be placed h, which means some long code blocks get sent at the end of the document.

I've done some more digging and I think that I found out that If I modify the lua filters (where exactly these files are, I think, depends on the OS + the version of quarto... Say for v1.4.550 and under Linux, I think the relevant files are: /opt/quarto/share/filters/main.lua and /opt/quarto/share/filters/crossref/crossref.lua --- but other versions may vary...

If I hard-wire the changes I want there, like changing
"\\@ifundefined{c@chapter}{\\newfloat{codelisting}{h}{lop}}{\\newfloat{codelisting}{h}{lop}[chapter]}\n" .. to "\\@ifundefined{c@chapter}{\\newfloat{codelisting}{H}{lop}}{\\newfloat{codelisting}{H}{lop}[chapter]}\n" .. in both files, I seem to sort the issue and the codelistings are all placed where I want them.

Also, I can make the caption refer to "Box" instead of "Listing" by changing \floatname{codelisting}{" .. as_latex(title("lst", "Listing")) .. "} to "\\floatname{codelisting}{Box}\n". Here, I haven't figured out how to avoid hard-wiring the text I want... thought that I could modify another part of the filters

        caption_location = "top",
        kind = "float",
        name = "Listing",
        prefix = "Listing",
        latex_env = "codelisting",
        ref_type = "lst",
      },

specifically by modifying Listing with Box in the name and/or prefix, but this didn't seem to work... But I guess I'm not doing this right?

I don't love to have to hard-wire things and overwrite the original filters, but I did try to add these changes to customised filters, which it hasn't worked, actually. I wonder whether there's a better way to deal with this, @dragonstyle @cscheid?

[cscheid]

If you want to fully customize the appearance of a particular element in a Quarto document, the standard way to go is to write a Pandoc filter that finds the node and re-emits it in the desired way. In your case, you'd be looking for a FloatRefTarget of type Listing. Something like:

-- filter.lua
function FloatRefTarget(float)
  if float.type ~= "Listing" then return nil end
  -- write your custom renderer here
  -- float has "content" and "caption" fields
end

See https://quarto.org/docs/prerelease/1.4/lua_changes.html for more details.

[giabaio]

Thank you. I'll have a go --- but can I just check? Do you mean I should create a new filter, say mylisting.lua and write it as

function FloatRefTarget(float)
  if float.type ~= "Listing" then return nil end
  -- write your custom renderer here
  -- float has "content" and "caption" fields
end

(assuming I figure out how to add the bits I need) and then call it as

...
filters: 
   - mylisting.lua

in my _quarto.yml file?

Thanks!

[cscheid]

Yes, but your filter declaration will need to be a bit different. You'll want:

filters: 
   - path: mylisting.lua
     at: pre-render

The idea is that you want Quarto to process the FloatRefTarget object all the way through, except for rendering.

[giabaio]

Ah --- OK. I'll have a go. I still haven't got my head around lua, but let's see where I'll get.. :-)

Thank you!

[giabaio]

Sorry to be thick... But isn't this the actual relevant page? I had a quick go, but I didn't seem to be able to make it work fully, though...

[cscheid]

That's the page for defining a new custom crossref type (say, a "Video" or "Diagram"). What you're trying to do is change the way an existing float crossref is rendered. For that you'll need to use filters.

[giabaio]

You're right, of course... Just that it may be easier to fiddle by creating a new/custom float, I guess... I'll keep looking...

[giabaio]

Can I please come back to this? I think I found a way to make it work the way I like. The only thing I haven't figured out is how to redefine the behaviour of @lst-XXX in terms of referring to the object, inline. I have managed to change the name and prefix to Box (which is what I want), but when I write ... @lst-XXX shows something, then the compiled (to pdf) output looks like ... Listing XXX shows something. The actual listing is prefixed with Box, as is the caption... What should I modify to make quarto behave in the above manner? Is it even possible?

Thanks!

[cscheid]

Can you share your code somewhere?

[giabaio]

Of course --- but the path of least resistance for me was simply to work on my fork of the main quarto-cli repo --- and I have figured I needed to change the file src/resources/filters/mainstateinit.lua to

...
{
        caption_location = "top",
        kind = "float",
        name = "Box",
        prefix = "Box",
        latex_env = "codelisting",
        ref_type = "lst",
      }

and the file src/resources/filters/crossref/meta.lua to

          inject(
            usePackage("float") .. "\n" ..
            "\\floatstyle{ruled}\n" ..
            "\\@ifundefined{c@chapter}{\\newfloat{codelisting}{H}{lop}}{\\newfloat{codelisting}{H}{lop}[chapter]}\n" ..
            "\\floatname{codelisting}{Box}\n"
          )

to get the desired effect (bar the quirk above)... I do this because I want to rename the float as "Box" and to make sure that the placement is [H] (instead of the default [h]).

I know I can use custom crossrefs, like

crossref:
 custom:
   - kind: float
     key: mylst
     latex-env: mycodelisting
     reference-prefix: Box
     caption-prefix: Box

and this is even better as I have direct control over the reference-prefix (and then use the custom float mycodelisting and mylst-XXX in the qmd files. But this would need further hacking on the lua filters, I think, to make the placement [H], whereas creating my local version of the repo gets rid of this easily (I've still not had the time to master lua, so I know this is still a bit hacky...).

Does this make sense?

Thanks!

[cscheid]

I'm happy you found a solution that makes sense for you, but changing the source code of quarto-cli unfortunately means you're in "you break it, you buy it" territory.

I apologize, but my original suggestion to use filters remains my recommendation.

[giabaio]

Thank you, @cscheid --- fair enough... Though, for completeness, nothing got broken, I think... Everything compiles perfectly --- if I'm happy to have Listing XXX shows (which I probably won't be too bothered about...), then all works with no issues. It's just finding where the lst-XXX gets defined (which I haven't managed to) --- but again, the code is not compromised, I think... :-)

As for your suggestion, yes: I know that'd be the way to go without touching the core code --- I haven't got the time to get around the way the new filter should work and, like I said, this was a cheaper (though, admittedly, dirtier...) solution...

[cscheid]

It's not about the compromise of the code. It's about my limited time commitment for providing help. When you change quarto-cli, the help I give you will not be usable to other people in the forum, and so I cannot commit time to it.

[giabaio]

I get that! Thank you for all the help!

[giabaio]

BTW I think I was making life much more complicated than I needed to... As it turns out, without any hack on the original quarto code, all I need to do is to define a custom float

crossref:
 custom:
  - kind: float
    key: mylst
    latex-env: mycodelisting
    reference-prefix: Box
    caption-prefix: Box

and then add the following

```{=latex}
% This must be used to redefine the style of the 'codelisting' environment
\floatstyle{ruled}
\newfloat{mycodelisting}{H}{lomylst}[chapter]
\restylefloat{mycodelisting}
```

before the first call to @mylst and then things happen the way I want them. I guess this is still a bit hacky and can probably do in a more elegant way, but at least this way I don't touch the original definitions in the quarto language, which is actually much better because it makes the whole project (much more, if not 100%...) future-proof...

Thanks for the help! :-)