Wrap code block HTML table in a div element

[sapek]

Syntax highlighted code blocks are written out as HTML tables which are
impossible to format via styles for different screen widths. This means
that pandoc generated pages with code blocks must have a fixed minimal
width, making them hard to read on narrower screens.

Wrapping the table in a <div> allows formating a code block that will
have a horizontal scroll bar if the content doesn't fit the screen
width, by adding the following style:

div.sourceCode {
    overflow-x: auto;
}

This enables pandoc to generate responsive HTML pages.

[sapek]

Here's an example of a page generated with the modified pandoc: https://microsoft.github.io/bond/manual/bond_cpp.html. When displayed on small screen (or narrow browser window) some of the code blocks will have horizontal scroll bar while the regular text will adjust to browser window width.

[linquize]

interesting! Microsoft uses Haskell.

[mb21]

HTML tables which are impossible to format via styles for different screen widths.

Really? Could you elaborate or post an example to a jsfiddle or similar?

Note that it's actually the {.numberLines} attribute on a code block that toggles on the table.

[sapek]

Here's an example: http://jsfiddle.net/jdxpbd6o/

[timtylin]

My guess is that tables don't take well to the CSS overflow scrollbar property, or at least that it has poor browser support.

Note that you can easily use filters to wrap all the code block elements around a div.

[sapek]

Yes, tables violate a lot of CSS rules.

I'm not familiar with filters. Do you have some pointers? Does that allow having a special class on div surrounding code blocks?

[mpickering]

You can read a bit more about filters here1. It should be very easy to
inject the necessary div.

On Thu, Jan 29, 2015 at 4:10 AM, Adam Sapek notifications@github.com
wrote:

Yes, tables violate a lot of CSS rules.

I'm not familiar with filters. Do you have some pointers? Does that allow
having a special class on div surrounding code blocks?

—
Reply to this email directly or view it on GitHub
#1903 (comment).

[sapek]

Thanks. That's pretty neat. So the idea is to insert <div> as raw HTML nodes into AST?

On a more general note, is pandoc the right tool for what I'm doing: converting software documentation to HTML? Pandoc doesn't seem focused on easy customization of the HTML output. The filters look very powerful but it is a very roundabout way to "template" HTML output...

[mpickering]

In this case it would probably be easier to inject a pandoc Div element but injecting raw html would also be possible.

Pandoc should be suited for that. Usually it is enough to specify a stylesheet to personalise your documentation. Occasionally it is necessary to use a simple filter if you want fine-grained control.

If there is anything you are finding particularly troublesome then please ask.

[mb21]

@sapek You could also use CSS to set display: block on the table, see the updated fiddle. There may be edge cases where this breaks the table layout, but I don't think the simple two-cell layout pandoc uses to wrap code blocks for line numbering is one of them.

btw, it might be better for pandoc to not use a table here anyway, since it's not a semantic table. divs and some CSS (even display: table if we have to) could be used instead.

[sapek]

@mb21 This is not as good because the block always has a disabled horizontal scroll bar, even when it is not needed. It would look rather ugly, especially with many small code blocks.

Do you guys see a drawback of wrapping code blocks in a div? Most other things pandoc outputs are already div wrapped. I understand that there is the workaround with the filters but it is relatively heavy weight: if you want to generate docs in your build, let's say in CI, instead of simply installing pandoc binary package you now need to install Haskell with all the dependent packages or Python with the pandoc package.

[timtylin]

(there's CI environments that don't have some sort of rudimentary Python?)

Well if resource really is a issue then you can always output the JSON representation and manipulate the intermediate DOM in whatever scripting environment you need, then feed it back into Pandoc to convert to HTML.

I guess there's technically no problem with wrapping code blocks in div. It's just that everyone probably have their own needs for some kind of tiny tweak in the reading/writing behavior, and filters were supposed to be the solution for all that.

[sapek]

@timtylin To me filters make sense for adding something that is not needed by everyone (the <ruby> annotation in the docs is a good example). I think that code blocks displaying properly on mobile devices should be the default that everyone wants/gets/doesn't need to understand. But I understand that this is a matter of philosophical approach to the balance between out-of-box experience and ultimate flexibility.

[jgm]

I don't see any problem with wrapping in a div by default.

[sapek]

Does the change look OK or do you guys want me to change something?

[jgm]

Some thoughts: Wouldn't it make more sense to put this in jgm/highlighting-kate? That would also give us the possibility of using the div wrapper only when line numbers (and hence tables) are needed, preserving the simpler structure for the other cases. (Though I'm not sure this would be better.)

Further thought: perhaps we should replace the table with something else (again, this would be a change in jgm/highlighting-kate). I'm open to suggestions here; we just need something that will reliably preserve alignment of line numbers with lines, and work well across all browsers in common use. At the time I wrote highlighting-kate, this meant using tables, but maybe now two side-by-side divs would work?

[sapek]

I also thought about putting this in highlighting-kate.

The only advantage of always wrapping code in a <div> with sourceCode class is that it makes for simpler CSS. If we only wrap code with line numbers then overflow style (and possibly others) has to be applied to both <div> and <pre>. Also generated <pre> doesn't have a class so it can only be styled globally.

[jgm]

I just had another idea. What if we put all code blocks inside pre tags with class sourceCode? When line numbers are used, the whole table element can go inside the pre tags. (I just tried this and it works.) Then you could solve your problem by putting CSS on pre.sourceCode.
(This would, of course, be a change in highlighting-kate rather than pandoc.)

[sapek]

Yes, pre works as well. Do you already have a change in highlighting-kate ready or should I prepare a PR?

[jgm]

I don't have the change ready. If you'd like to prepare it, go ahead.

+++ Adam Sapek [Mar 07 15 18:26 ]:

Yes, pre works as well. Do you already have a change in highlighting-kate ready or should I prepare a PR?

---

Reply to this email directly or view it on GitHub:
#1903 (comment)

[sapek]

Here's the change in highlighting-kate: jgm/highlighting-kate#65.