Hi all, I'd like to get your feedback on some proposed formatting changes to the imuxsock module doc. I mention my preference below, but the end goal is to standardize the formatting and make the docs easier to work with, so my personal preferences can take a backseat in the scheme of things. ;)
I've broken this out into sections with a brief label, the link and some short notes on each one. Thanks in advance for any feedback you may have (GitHub links at the bottom of this email, responses here appreciated as well)! ============= v8-stable: ============= http://rsyslog.whyaskwhy.org/v8-stable/configuration/modules/imuxsock.html ============= master: ============= http://rsyslog.whyaskwhy.org/master/configuration/modules/imuxsock.html Almost the same thing, but the addition of an early "seealso" for the omuxsock doc and an explicit label to help make clear the the doc is in the "original" format of using bullet points for the parameters http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock.html ========================== parameters as directives ========================== http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-directives.html Here the idea is to use the "function" or "data" Sphinx directives to list out each parameter. The "function" directive will alter the display to include parenthesis unless you place something behind the parameter name, so it is common in the docs to find a bracketed listing of the possible options with the default setting in bold. As with the next prototype, the idea here was to break out the values in a separate table. PR #6 (rsyslog/rsyslog-doc) was an inspiration for that. I will likely expand the table to cover other details not already present. I initially thought of a vertical two-column table, but a horizontal one likely works better here. ========================== parameters as sections/headers ========================== http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-headers.html I personally like this one the best: * individual parameters are easily accessible via the Table of Contents in the sidebar * each parameter can be directly linked to without the maintainers of the doc having to place manual labels next to each parameter * it is minor in the scheme of things, but I like how the content is _not_ indented in the source doc as it is one less thing to get wrong when adding new content * each parameter is clearly separated from the next, unlike the bullet point approach which while a little more compact is more difficult to jump right into a retrieve a value you're after * because each parameter is clearly separated, I feel it would be easy to grow the table out to cover additional details that may not be covered now ========================== Your feedback is appreciated! ========================== Please feel free to respond here or to the related GitHub issue and pull request: * https://github.com/rsyslog/rsyslog-doc/pull/476 * https://github.com/rsyslog/rsyslog-doc/issues/6 Thanks! _______________________________________________ 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.
