rsyslog-doc icon indicating copy to clipboard operation
rsyslog-doc copied to clipboard

Update documentation to use substitution references in place of literal config format name text

Open deoren opened this issue 7 years ago • 4 comments

This is a continuation of the work started recently on #391. Now that the configuration format name substitutions have been defined, we need to update all references to the one of the three configuration format names to use them.

The goal is to make the names consistent going forward and (hopefully) allow for easier maintenance when/if the config format names are finalized (see #391 for a discussion of what those format names may be called in the near future).

I hope to submit a PR for this soon.

refs: #416, #414, #391

deoren avatar Dec 11 '17 15:12 deoren

as you go forward (and I can't today): would you mind shortening the name replacements? I think the "...formatNew" (or so ;-)) part is not necessary. We should probably not need to refer to the old names more than once on the initial page. And the shorter replacements is more joy to type -- just my 2cts...

rgerhards avatar Dec 11 '17 15:12 rgerhards

@rgerhards: as you go forward (and I can't today): would you mind shortening the name replacements?

My plan exactly.

@rgerhards: I thing the "...formatNew" (or so ;-)) part is not necessary.

Probably not. I think I was being overly verbose to keep it straight in my head while prototyping the setup.

@rgerhards: We should probably not need to refer to the old names more than once on the initial page.

You're probably right. Whatever we do, I'll make sure to search the docs to make sure there is more than 1 use of each substitution. If not, I can prune any unused substitutions so that only active substitutions are kept.

@rgerhards: And the shorter replacements is more joy to type -- just my 2cts...

Understood. I have to admit that using editors like Microsoft Visual Code or Atom have spoiled me a bit with their offered suggestions as I type, so I may not be giving as much weight to shorter names as I should.

deoren avatar Dec 11 '17 15:12 deoren

I think this is closed. If not @deoren please re-open.

rgerhards avatar Dec 14 '17 08:12 rgerhards

I was planning to use this issue to track the work of replacing the literal format names in the docs with the substitution references. I just haven't worked on this much yet due to my focus on other parts of the docs.

deoren avatar Dec 14 '17 08:12 deoren