On Thu, May 15, 2014 at 2:11 PM, Thomas D. <[email protected]> wrote: > Hi, > > Rainer Gerhards wrote: > > Most importantly, it hopefully is more clear which legacy statements are > > actually global and which not. > > Mh... I am not sure if I see the changes. > > For example > <http://www.rsyslog.com/doc/master/configuration/global/index.html>: > > This site is listing "$MarkMessagePeriod" as a global directive but it > isn't. Only when using the old syntax... > > Two things:
as I said, I work on v5-stable and just moved things up. So we are talking about legacy syntax only. No changes yet to the new constructs. Secondly, $MarkMessagePeriod is now flagged as being immark-related. In what I have done the past hours, this is now also moved to a specific input file "global" statement page. Hopefully that makes it clearer. > Same with > <http://www.rsyslog.com/doc/master/configuration/action/index.html>: > From reading these docs I would expect I can set > > $FileOwner > $FileGroup > > before my actions (new syntax) to specify defaults, but I cannot (mixing > old and new syntax). But I don't get that information from reading the > documentation. > > But as said, maybe you were working on other parts of the documentation... > > yeah, again, this is something that needs to be added to v7 and up, where I had not yet a chance to look at. > > > PS: Just an idea: > > Why don't you/we start with a *new* documentation? Throw everything > away. Yes, for the beginning, many features will be undocumented (well, > not really... the old documentation is still accessible) but this will > allow us to get rid of all the current problems: > > 1) There's no consistency > > 1.1) See > <http://www.rsyslog.com/doc/master/configuration/modules/omfile.html>: > > Template[templateName] > DynaFileCacheSize(not mandatory, default 10 > ZipLevel0..9 [default 0] > ASyncWritingon/off [default off] > IOBufferSize<size_nbr>, default 4k > DirCreateMode[default equelly-named module parameter] > > 1.2) Sometimes the documentation is split in new/legacy syntax mode, > sometimes not. Also the way we display the old/new syntax can be improved. > > 2) The visual appearance is not really readable, see > <http://f.666kb.com/i/codcurab5nda9w1qk.jpg> (and the examples from 1.1, > too). > > > You all do your best to get these things fixed, but personally I think > you cannot win. It is too much you need to fix. > > If we would start over, start with defining how we want to display > information (to prevent things shown in 1.1; find a way how we want to > show current and legacy syntax; how we want to structure) rewriting > should be more easier than fixing these things today. > ...and we should focus on the *new* syntax. The new syntax should be > completely documented (currently, sometimes I have to read the source > code to get some parameters or default values). Legacy syntax isn't that > important and remember, the old documentation is still there. > That was my initial approach, but a lot of folks said we need to look at v5, too. Comment on the rewrite below, for now let's assume a gradual update. With a gradual update, I need to work from v5 up, otherwise fixes in older branches will result in merge hell. So my plan is/was to start there and move up. > > The important thing is: Keep the new documentation clean. Only rewritten > documentation in our new "format" is allowed to get added. > > Maybe it will take a year or more to get where we are in the moment (in > extent of documentation), but if we would start with the most > important/common used parts, the new documentation will be better in 2-3 > month than the old one ever was. > > Thoughts? > > I like the rewrite idea, but experience tells it has a major stumbling stone: nobody want's to do this work ;) I cannot do, because I have not enough ideas of how I could actually *do* that work. So someone else would need to invest a serious amount of time. I had hoped that this would happen when we started with rsyslog-doc in december, but looking at it's state in May, this for sure did not materialize. So I again went into doc mode and am now trying the best I can do to get us to some better (not good, not even decent) stage. Besides this time issue, the current doc is merely a reference section. So I think it would still make sense to migrate over parts of the content. But again, as long as nobody is really serious in doing all this sorts of things, we don't need to discuss the details I am now digging in ;) Again, I like the idea, but I say "it does not work". Prove me wrong, Pull Requests are happily accepted ;) Rainer > -Thomas > > _______________________________________________ > 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.
