I think that putting a set of links to different version sections further down the same page is a great compromise.
Then, keep the newest at the top, and push the older down like a stack. --Robert ________________________________ From: Rainer Gerhards<mailto:[email protected]> Sent: 9/20/2013 5:41 AM To: rsyslog-users<mailto:[email protected]> Subject: Re: [rsyslog] Multipe doc versions online? On Fri, Sep 20, 2013 at 1:34 PM, David Lang <[email protected]> wrote: > On Fri, 20 Sep 2013, Rainer Gerhards wrote: > > On Fri, Sep 20, 2013 at 12:33 PM, David Lang <[email protected]> wrote: >> >> hmm, I tried to login to respond, and after putting in the >>> username/password in the web form, I then got a browser popup asking for >>> the site username/password, so something seems odd there. >>> >>> I think it's worth clearly splitting v5 and earlier from the latest. Many >>> pages are split this way (referring to the legacy format), but it's not >>> always clear that that is required for 5.x and optional for the current >>> version. Occasionally I run into a page (although this may be google >>> finding the documentation experiment) that gives the new format, but not >>> the old. >>> >>> >> I fear that when we put up the old version docs as well, this "google >> problem" will likely happen even more often - and I would even bet that >> from then on google will tend to serve the old style (as of Murphy's law >> ;)). >> > > true, a single page with better clarification of the fact that the new > stuff doesn't work on 5.x and earlier is probably far better. > but then this needs to be linked to from each other page, or am I missing something? > I think some of the confusion is due to the fact that you have to scroll > down a ways before you see any indication of the old stuff, and someone who > just upgraded to the latest version of their distro isn't thinking in terms > of it being 'legacy' :-) > > if there's a way to automate it, having a note that for distros .... > require legacy format at the top of the pages could help (right now it's > just about every distro, but at some point it will change from RHEL to RHEL > up to vX so you need a way to change that list in one place and have every > page updated) > > mhhh... I don't want to move the legacy stuff towards the top of the page, as the casual googler usually picks the first he finds. That would mean we'll never get rid of the complex legacy constructs. But I could add a sentence a la "If you use an outdated (pre-v6) version of rsyslog, please scroll down to the legacy format section, as the enhanced format does not work for those old versions." to the top of each page. Do you think that would help (would sufficient people even notice it while scanning the page)? > > that part of the problem is in the formatting. I'd write it that way >> >> if ... then { >> action() >> stop >> } >> >> so that from the nesting the block is clearly visible. >> > > tried that, didn't help interesting - then I really don't have a cure. > > > Besides, there is no >> problem in using & ~ if it is just a simple filter. >> > > actually, rsyslog outputs a bunch of warnings about this being depriciated ah, yes, that's because of the tilde char. That is very problematic, if you look into the grammar. So & stop works - also too unreadable??? Without trying to bash someone: I think it is unavoidable that some folks don't like parts of the format -no matter what you use, this will always happen. Trying to solve that dilemma is probably the root cause why it took many years to finally settle on a decent (IMO;)) format. With legacy conf, the overwhelming comment was that it was extremely complex and getting complex things done was extremely hard. I frankly admit that even I sometimes had a hard time finding the right set - and sequence! - of parameters. And then think about auto-reset and non-reset statements in legacy conf... and when doing simple files and forwarding, the old style is MUCH easier >> to read than the new style. >> > > > yup - that's why I constantly say it will stay AND be a preferred method of > doing simple things. > there are several places in the docs that say things along the lines of > "you should use the new style if at all possible". I know I saw it an hour > or so ago, but I'm not finding it right now :-( Maybe that's some leftover from early work - or talking about complex things. I *strongly* discourage using legacy format for complex things, as it is extremely easy to get that wrong. With proper scoping and blocks, complex things are much easier to do. As a rule of thumb, if you need to use $somestatement directives, you are doing complex things and should use new format, where as if not, the old style is probably better. I think that mail.info /var/log/mail.log is probably more efficient to do than if prifilt("mail.info") then action(type="omfile" file="/var/log/mail.log") Or, in other words: use old style for everything that sysklogd could do. Use new style for the rest. > > you have the config optimizer, I wonder how hard it would be to have a >>> flag that would tell rsyslogd to read the config, optimize it, then >>> output >>> what it sees as the config (using all the new syntax)? this would flatten >>> includes so that stuff wouldn't be hidden by them, and make debugging >>> easier as it would specify every value for every option (including the >>> ones >>> that are defaults), no matter if they are listed in the old style or new >>> style format >>> >>> >> It's quite a bit of work, as (contrary to the optimizer) all modules would >> need to be updated (action & input parameters are only visible by the >> module in question). >> > > oh well, probably not worth a lot of work, although even doing a handful > of the most common modules would get a big return. > > > David Lang > > ______________________________**_________________ > rsyslog mailing list > http://lists.adiscon.net/**mailman/listinfo/rsyslog<http://lists.adiscon.net/mailman/listinfo/rsyslog> > http://www.rsyslog.com/**professional-services/<http://www.rsyslog.com/professional-services/> > What's up with rsyslog? Follow https://twitter.com/rgerhards > NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad > of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you > DON'T LIKE THAT. > _______________________________________________ rsyslog mailing list http://lists.adiscon.net/mailman/listinfo/rsyslog http://www.rsyslog.com/professional-services/ What's up with rsyslog? Follow https://twitter.com/rgerhards NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T LIKE THAT. _______________________________________________ rsyslog mailing list http://lists.adiscon.net/mailman/listinfo/rsyslog http://www.rsyslog.com/professional-services/ What's up with rsyslog? Follow https://twitter.com/rgerhards NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T LIKE THAT.
