Use AnnotatedIOBuffer + StyledStrings for handling ANSI codes. about documenter.jl HOT 2 OPEN

Just as a note: I think this would need to be implemented in IOCapture. Or, at least, IOCapture is relevant too, since we do do some ANSI code handling there.

This works thanks to a specialised prinstyled(::AnnotatedIOBuffer, ::AnnotatedString) method, but won't work for manually outputted ANSI escape codes.

So.. I haven't followed StyledStrings closely enough to have a super informed opinion here. But, this feels like a major downside -- our current approach seems strictly better, since it handles StyledStrings and other outputs. ANSI codes not being able to see the non-standard styling is a fair point.. but neither will the user using the REPL.. at least in most terminal emulators..?

I think I need some more information here as to what StyleStrings actually does on a low level, and maybe a sketch of what an implementation would look like here, and how it differs from what we have now, to make a call here.

All that said, I do think that, if StyledStrings is the future, which it appears to be, then it does feel right that we should natively support it in Documenter.

from documenter.jl.

Hi Morten,

I think it might be best if I actually address your comments in reverse order.

All that said, I do think that, if StyledStrings is the future, which it appears to be, then it does feel right that we should natively support it in Documenter.

I think it's too early to say what "the" future looks like, but I'm hoping that StyledStrings will be adopted fairly broadly for the benefits it brings to handling styled content in many forms. It's about to be used in the Markdown stdlib, and I believe that Julius is interested in using it with Makie's styled text for example.

This is a bit funny since it's sort-of-terminal but not entirely. The design of StyledStrings is such that it covers terminal capabilities, but also supports other aspects that are only possible in non-terminal contexts (namely font selection and text sizing). I'm not entirely sure how this should work out, but I suspect it would be useful to be able to show StyledStrings content in docs.

I think I need some more information here as to what StyleStrings actually does on a low level, and maybe a sketch of what an implementation would look like here, and how it differs from what we have now, to make a call here.

Simply put, what StyledStrings does is take the new AnnotatedString type from Base (in 1.11+), which allows you to add labelled metadata to regions of a string, and introduces a "styling information" struct (called Face, think "typeface") to put in a metadata slot labelled :faces.

There's a bit more to make it work, make it user-customisable, etc. but that is the core of it.

ANSI codes not being able to see the non-standard styling is a fair point.. but neither will the user using the REPL.. at least in most terminal emulators..?

Well, it does makes drawing attention to those capabilities in @repl docs a bit harder 😛

So.. I haven't followed StyledStrings closely enough to have a super informed opinion here. But, this feels like a major downside -- our current approach seems strictly better, since it handles StyledStrings and other outputs.

Yea, while I would love to see everybody using StyledStrings not manually outputting ANSI codes, that definitely isn't the reality today, so I wouldn't suggest abandoning the SGR-parsing functionality, but I think it would be nice to also be able to work with some of the more advanced capabilities that StyledStrings offers.

I'm not sure what the best path forward is, but that's why I've opened this issue — so we can discuss it.

from documenter.jl.