Get rid of old-legacy configuration format

[mostolog]

Hi

Documentation pages contain several examples, some among them using old-legacy-(you-should-move-to-cool-fancy-new-rainer's-format). We could consider having a "legacy-configuration-example-file" to document as much legacy's as we can, and removing legacy examples from configuration pages but linking "If you still want to use that old-fashioned-ugly format, a configuration file full using it can be found at ...".

This also could serve fix #88 while reviewing/improving configuration examples.

[radu-gheorghe]

I think there are a number of issues here. Here are the ones I see:

• lack of time to make such an involved contribution. While I think we all agree that, by and large, rsyslog documentation sucks, doing a major restructuring like the one suggested in https://github.com/rsyslog/rsyslog-doc/pull/188 is something none of us has found time to do
• some modules only support the new configuration format (e.g. omelasticsearch), some only the old (e.g. ompgsql), some support both (e.g. omfile. But even then, I can't say to which extent)

I think what you're suggesting should work for modules that support both, where/if we can safely assume that the old config format won't change so we might as well put that docs in a different place so we don't bloat the main docs. Not sure if an example config file would be a good choice, though, because it won't include all the options. I don't really know what a good option would be here :(

What I can suggest, though, is a small-steps approach. If you, or I, or anyone else has time to contribute, we can start by working on docs pointed out by https://github.com/rsyslog/rsyslog-doc/issues/88. For example, those about TLS or rulesets, they surely need some love to get updated to the new config format.

Basically, what I'm saying is, once we clean up individual pages (so at least people going to docs from Google, which I bet are the most) can get a decent experience, then it will be easier to get rid of the pieces that aren't useful anymore and do a restructuring as suggested in https://github.com/rsyslog/rsyslog-doc/pull/188

[mostolog]

Ok about #188, but I would pray not to leave it as a never done zombie issue, but setting a roadmap for changes. One page reviewed/updated per week? Two per month?

If you agree, I can start solving #88 while creating legacy configuration example file approach for the modules I'm working with. and we can see if that's a good starting point.

BTW: I'm not sure if there was an issue for this, but I ask here: Do we have a "formal" template on how properties should be documented? For example, for omhiredis:

...
**serverport**: port where redis server is listening to
required: no
default: 6379
...

[radu-gheorghe]

@mostolog first of all, thanks for being so active here! It's hard to overstate how much your contributions help rsyslog.

Regarding #88, if you can help that would be awesome! Though I would rather start with "concept" pages (like TLS or rulesets) which really miss the new config format, rather than the modules. Up to you, though.

I wouldn't remove the legacy parts just yet, I'd just put them further down, like they are in omfwd: http://www.rsyslog.com/doc/v8-stable/configuration/modules/omfwd.html#legacy-configuration-directives

Then we can decide what to do with those.

Regarding:

BTW: I'm not sure if there was an issue for this, but I ask here: Do we have a "formal" template on how properties should be documented?

I'm not aware of such a formal template, but I believe that mentioning whether something is required and the default would be very nice, like the Redis output has.

Finally, regarding #188, I don't want it to be a zombie issue either. It would be nice to have a roadmap, but it's hard to mention times, because it's hard to make people commit to such deadlines (I know I'm not up for that, unfortunately). What I think can be done there:

• iterate (discuss) on that ToC until we are happy with it ("progress, not perfection" should be kept in mind, IMO)
• since the transition to a new ToC may be a lot of work, maybe we can break it into chunks?
• might need to decide what to do with links, as many referred ones may become obsolete
• do the actual transition :)

But I guess that's a discussion to have on that issue.