HtmlFormatter: filename doesn't work well with linenos=table

[Cartroo]

When using HtmlFormatter with both the linenos=table and filename=testfile options, you get some output like that shown below. The problem is that the filename being output within the <td> for the code throws off the line number alignment.

<table class="highlighttable">
  <tr>
    <td class="linenos">
      <div class="linenodiv">
        <pre>...</pre>
      </div>
    </td>
    <td class="code">
      <div class="highlight">
        <span class="filename">testfile</span>
        <pre>...</pre>
      </div>
    </td>
  </tr>
</table>

I suggest that this is unlikely to be useful to anyone, since it will invariably throw off the line numbering alignment. Hence, in the special case of someone using linenos=table and specifying a filename I would suggest that another table row is output as a caption:

<table class="highlighttable">
  <tr>
    <td colspan="2" class="filename">testfile</td>
  </tr><tr>
    <td class="linenos">
      <div class="linenodiv">
        <pre>...</pre>
      </div>
    </td>
    <td class="code">
      <div class="highlight">
        <pre>...</pre>
      </div>
    </td>
  </tr>
</table>

I can look at entering a pull request to implement this, but I wanted to get some feedback on whether this would be acceptable first.

[Anteru]

That does make sense to me. I'm 100% sure this will break some theme somewhere, and you'll get some weird coloring there if you don't wrap it in highlight and maybe some CSS class will fail to match.

Don't get me wrong -- I'm all for this, but if you want to touch this kind of thing, make sure to document the before/after state and ideally provide some guidelines for theme writers. If you look at the 2.8 release notes, we did some non-trivial CSS change, but with the docs it doesn't seem to have caused nearly as much fallout as previous CSS changes.

I do agree that in practice nobody can be using this seriously as it will look plain broken. I'm just cautious :)

Thanks for your offer to help here!

[Cartroo]

Sure, you're quite right, of course. I'll aim for something more like the snippet below, although clearly may still be breaking for some themes. In principle I guess it could be controlled by another option, to maintain the backwards compatibility, but that's a bit clunky for something that only impacts this one edge case in my view.

<table class="highlighttable">
  <tr>
    <td colspan="2" class="filename"><div class="highlight">
      <span class="filename">testfile</span>
    </div></td>
  </tr><tr>
    <td class="linenos">
      <div class="linenodiv">
        <pre>...</pre>
      </div>
    </td>
    <td class="code">
      <div class="highlight">
        <pre>...</pre>
      </div>
    </td>
  </tr>
</table>

Note that I could make it even closer by using class="code" on the <td> for the filename. But personally I feel that there's a good chance people will want the option to style this caption differently to the code.

[Anteru]

Yes, I don't think <code> is required there, as it's not really code. As long as there is a unique class/CSS path attached to it everything should be fine.

[Cartroo]

Here's a first attempt, I've used <th> partly because I felt it was appropriate (the filename is rather like a heading for the table) and partly because I felt it was less likely to fall foul of people's existing CSS rules (since they'd most likely have applied them on <td> elements).

I'd be interested in your feedback, in particular whether there's any additional documentation you feel should be updated.