Logstash Reference: options table and text collides with side navigation

[inqueue]

Text in the options table on these plugin reference pages collides with the navigation bar on the right side.

Beats input

Kafka output

[inqueue]

The same is observed in these browsers (all OS X):

• Chrome 55.0.2883.95 (64-bit)
• Safari 10.0.1 (11602.2.14.0.7)
• Firefox 50.1.0

[inqueue]

Screenshot links:
https://www.elastic.co/guide/en/logstash/current/plugins-outputs-kafka.html
https://www.elastic.co/guide/en/logstash/current/plugins-inputs-beats.html

[dedemorton]

@ph @suyograo I need your help figuring out how to resolve these display issues. Clint has indicated that we need to fix this on a case-by-case basis in the source. However, because this doc is generated from values in the Ruby source code, I'm not sure how we can do this.

Let's look at the example shown above from the Beats input plugin. The text in the Default value column next to cipher_suites overruns the navigation in the formatted doc because some of values are too long for that column. However, because these values are generated from the code here, I don't really have control over what gets added to the column.

@clintongormley ^^ So you can see the problem we're facing here. IMHO, it would be better for the table to have a scroll bar at the bottom rather than allowing the text to overrun the navigation pane. I'm not sure how to go about fixing this problem in asciidoc, let alone the doc gen script. Maybe if you can explain the fix, we can add some logic to the script. What I want to avoid is the need to manually tweak the asciidoc every time we regenerate the docs.

[clintongormley]

We can set table-layout:fixed which means the table won't grow out of its area, but the columns will look like this:

So we could also adjust the column widths, eg

[cols="<40%,<10%,<10%,<40%m",options="header",]
|=======================================================================

which will make it look more like this:

but also

But none of this will solve the problem with laying out tables in PDFs - the PDF renderers don't do any column resizing, so you just end up with the table going off the right side of the page.

The recommendation is to avoid tables as much as possible, and to use things like definition lists instead.

[dedemorton]

@ph If we decided to go with definition lists instead of tables for formatting reference content (like the content shown above), how much work would it take to update the doc generation script? IMHO, definition lists are harder to scan at a glance than tables, but they are more mobile-friendly and don't have the formatting problems (cell/page overruns) that tables have.

[ph]

@dedemorton It's a template, this shouldn't take to much time to change, from my experience definition list will provide a more fluid layout or at least we can control it better.

Concerning the formatting, how do you that in the html one definition list per attribute?

[dedemorton]

@ph Actually, when I look at the table more closely, I think we need to take a step back. I worry that converting the table to a DL will just make it look a lot like the content that follows (which looks a bit like an DL, even though it's not). We need to think about why these overview tables exist. They're mainly meant to be jump tables so that you can go to the setting quickly (without having to scroll around much), right? I'm concerned that using DLs instead of tables will force users to do even more scrolling, not less, and there will be a lot of duplicated info. The only info unique to these tables (that's not covered in the Details section) is the Required column. So I wonder: Are these tables even necessary? If they are necessary, do we need to provide the default value in the overview table, or could we drop the Default column from the table entirely? With the Default column removed, we would have reasonably sized tables that display OK and still help the user jump to the description. Copying @suyograo for input.

[dedemorton]

There's consensus on removing the "Default" column from the overview tables, so @ph will modify the script as required.