improve doc on settings file by describing options #5713
Conversation
|
PS I need to do more work on the CLI topic (in a separate PR) because I think the order of options is based on the old -h output (which I'm not sure makes sense, but I will investigate). |
| See <<command-line-flags>> for a description of the available options. | ||
| The `logstash.yml` file includes the following settings: | ||
|
|
||
| *`node.name`*:: |
There was a problem hiding this comment.
Can we convert this into a table with 3 columns: setting type, setting definition and default value
There was a problem hiding this comment.
This will make it really easy to read
There was a problem hiding this comment.
@suyograo I think you're saying that you would like to see these options presented in a 3 column table instead of a definition list, right? In that case, I would suggest that we have the column headings Setting, Description, and Default value. For this particular content, I'm OK with formatting the info as a table (though I think the descriptions are a tad long). My only caveat is that we shouldn't use a table format if we expect that we'll ever need to add multi-line code examples to a description. Multi-line code examples in tables of 3 or more columns don't display very well because of how line wrapping works. Definition lists are much more flexible, which is why we tend to use them for reference content. So...I'm open to reformatting. Let me know if you still want me to do this.
There was a problem hiding this comment.
Yeah, I think a table will be easy to read. Can we try that? +1 on Setting, Description, and Default value as column heading.s
|
LGTM |
This PR addresses the request in issue #5148 to improve the settings file.
I Frankensteined the descriptions of the CLI options and the comments from the logstash.yml file to come up with descriptions for the doc. I also edited the CLI doc (lightly) to make it more consistent with the descriptions I added for the settings file. I don't like (essentially) duplicating content, but reuse isn't really feasible due to the differences in how the values are specified in the YAML vs from the command line as flags.