Document config file format

[urso]

Document config file format + structure.

config files with duplicate (out of date) docs:
shared-env-vars.asciidoc
yaml.asciidoc (also shared)

[dedemorton]

should be "than other common data formats" (plural)

[dedemorton]

Great idea!

[tsg]

We could add something like: "In the default configuration files and in all the examples in the documentation, we use 2 spaces per indentation level. We recommend you do the same."

[urso]

How should we add this doc best to our documentation?

On the one hand I like it to be generic (as config file format is same for community-beats) and have beats docs point to this docs, on the other hand it duplicates content in yaml.asciidoc which is just some tips specific per beat (rather would like to include 'Config file format' doc with every beat).

Question: with config file structure having nested namespaces, how can we make namespacing usage more clear beats config reference?

[dedemorton]

change "then" to "than"

[urso]

done

[dedemorton]

@urso I'm done with high level comments. I'd like to do a detailed technical edit of this content after you've merged it (me adding line notes is tedious for everyone). I can take care of the restructuring that I've suggested.

[dedemorton]

@urso One more thing to add: Before introducing the concept of custom named settings, I would first introduce a simple example like:
filebeat.registry_file: ${path.data}/registry

Maybe even call out specifically that you can reference the path settings.

[urso]

good point, will do

[urso]

updated PR + fixed build + squashed all commits.

Currently looks like this:

[andrewkroh]

Is that leading escape on the { required?

[urso]

yes, otherwise doc build breaks for me. {<name>: ...} is obviously something special in asciidoc.

[andrewkroh]

Ok, I thought it might be for asciidoc.

[dedemorton]

It's doing that because you have subs="attributes" defined for the code block. You only need to include subs="attributes" if the code block includes a variable reference that you want asciidoc to resolve. So if you had {beatname_lc} in the example block and wanted it to resolve to Packetbeat or something, you would include subs="attributes".

[andrewkroh]

@urso This is excellent! I really hope people take the time to read it. 👍

[dedemorton]

@urso Intro is much easier to follow now. Looks good! I'll plan to edit the content sometime before the beta release.

[dedemorton]

@urso BTW, I think the current location of the content in the platform ref isn't right (users who are reading the platform ref won't even know about the config file until after they've installed their beat).
If we want to include this doc in the platform ref (so it's available to developers), it belongs under the Developer Guide section.

I can work on getting the content into the appropriate sections after it's merged, if you'd like. Just wanted to flag this issue because the current location isn't right.

[urso]

@dedemorton yeah, that's another thing I struggled with. I put it after 'Getting Started...' so users have hopefully seen beats before, but felt like putting it into developers guide would hide the content. Maybe it makes sense to make this one available in Platform Ref. and per beat docs?