I have some time next week. Let me sit down with Sphinx and see how customizable it is. If it can be customized to generate documentation that has a similar look and feel as the current HTML ones, I'll let you know.
-- James -----Original Message----- From: [email protected] [mailto:[email protected]] On Behalf Of Rainer Gerhards Sent: Friday, December 13, 2013 7:42 AM To: rsyslog-users Subject: Re: [rsyslog] Rsyslog => Apache? On Fri, Dec 13, 2013 at 2:36 PM, Boylan, James <[email protected]>wrote: > In regards to documentation. Have you considered something like Sphinx? > It's a python application for generating documentation. The nice part > being that you write the documentation in a Markup language for Sphinx > and it can then be output as man pages, epub, text, LaTeX, HTML and > several other options. > > I think there are several other tools like that as well. It would > allow for a single document source base that could be used to generate > final content that is displayed and available in multiple places. > > we had several proposals in similar regards. I think one is still sitting in my mailbox. The bottom line is that I need something that gets going very quickly ... or someone who cares about that and walks me through for a jump start. Michael Biebl did so when I initially started with git (I can't be thankful enough!) and without him, I'd probably still struggle with cvs... Rainer > -- James > > > -----Original Message----- > From: [email protected] [mailto: > [email protected]] On Behalf Of Pavel Levshin > Sent: Friday, December 13, 2013 2:38 AM > To: [email protected] > Subject: Re: [rsyslog] Rsyslog => Apache? > > 13.12.2013 0:12, Rainer Gerhards: > > On Thu, Dec 12, 2013 at 8:01 PM, Otis Gospodnetic < > > [email protected]> wrote: > > > >> Hi, > >> > >> Thanks David & Rainer. The last few emails were very constructive > >> and pragmatic. Based on what I heard I'd think you'd want to push > >> things towards Github. Ignore Apache for now at least. > >> * Make Github *the only* source (i.e. not Adiscon git) > >> > > why? > > I see no reason to make it *the only*, but it should be more visible > than it is now, and, if so, it should be at least equal to Adiscon > repo in terms of "actuality". Taking me as an example, I've found this > GitHub repository by accident, while browsing through other obsolete forks. > > GitHub interface is more user-friendly than git.adicson.com, it has > many usable features, and it allows to contribute more than a single patch. > > >> * Make > >> > >> https://github.com/rgerhards/rsyslog/blob/master/doc/build_from_repo. > >> htmlmore > >> prominent (and markup, not HTML) > >> > > "markup, not HTML" easy said... > > Indeed, but this is a major problem with rsyslog documentation. HTML > does not imply anything about how things should look. Therefore, > differently-looking doc pages become an ugly, unstructured heap. This > also prevents others to contribute or improve docs. > > > Many years ago, I've used Perl POD in an alike situation. It is > oversimplified, and this allows to concentrate on contents. It helped > in my case. But I do not think this one is suitable for rsyslog. > > I hope someone knows a format which will fit rsyslog better. > > >> * Link it from rsyslog.com. Your github repo clearly doesn't have > >> much Google juice. Maybe David can pull some strings? ;) > >> > >> > > that'll happen tomorrow > > I would suggest to have GitHub repos crosslinked from git.adiscon.com, > also. BTW, some of smaller adiscon repos did not work for me when I've > tried to pull via http://... > > > what saddens me is that we seem to be conceived as "closed". The > > root of rsyslog is that we wanted to provide a real open soure > > alternative to an (at that time) becoming more and more closed syslog-ng: > > Rsyslog can appear "closed", indeed, because it is not obvious for > anyone not on the list that you, being a maintainer, backed by a > company, will accept anything. It needs some PR to form public opinion. > For example, a track of succesful pull requests, or even a "banner" on > main page of official site, and much more than that. Try to look to > the project from outside, and you'll see. > > > -- > Pavel Levshin > > _______________________________________________ > 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. > _______________________________________________ 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.
