Re: nice wiki doc of haproxy
On 09-04-2012 20:37, Willy Tarreau wrote: Hi Aleks, On Mon, Apr 09, 2012 at 06:38:42PM +0200, Aleksandar Lazic wrote: Some questions for open discussion. 1.) Where is the right page for the 'HTMLFIED' document? http://haproxy.1wt.eu/#docs = separate page such as doc.haproxy.1wt.eu ... We need to ensure we can automate the update so that when the doc is updated on the primary site, it's automatically updated on Cyril's site too. 2.) automatic build or a separate build option 'make htmldoc' I prefer the second way We could think about merging Cyril's work in the contrib dir of haproxy, but since he expects some fast development on it soon, this would slow the process a lot. Better let his project evolve quickly and maybe at some point we could take a snapshot of it into haproxy so that make htmldoc works out of the box. I have now added the used python modules page https://github.com/cbonte/haproxy-dconv/wiki/Python-Modules so that the pre requirements are more clear ;-) I think that at some point, some users might be interested in implementing other backends such as asciidoc which creates very nice outputs for a wide variety of formats (including man and pdf). But let's not start to divert the nice job from what it currently is :-) Full Ack. Cheers Aleks
Re: nice wiki doc of haproxy
Hi, On 10-04-2012 15:07, Aleksandar Lazic wrote: On 09-04-2012 20:37, Willy Tarreau wrote: Hi Aleks, On Mon, Apr 09, 2012 at 06:38:42PM +0200, Aleksandar Lazic wrote: Some questions for open discussion. 1.) Where is the right page for the 'HTMLFIED' document? http://haproxy.1wt.eu/#docs = separate page such as doc.haproxy.1wt.eu ... We need to ensure we can automate the update so that when the doc is updated on the primary site, it's automatically updated on Cyril's site too. 2.) automatic build or a separate build option 'make htmldoc' I prefer the second way We could think about merging Cyril's work in the contrib dir of haproxy, but since he expects some fast development on it soon, this would slow the process a lot. Better let his project evolve quickly and maybe at some point we could take a snapshot of it into haproxy so that make htmldoc works out of the box. I have now added the used python modules page https://github.com/cbonte/haproxy-dconv/wiki/Python-Modules so that the pre requirements are more clear ;-) I have created a tgz for the style and js files. http://www.none.at/haproxy-style-js.tar.gz how about to link to twitter or add the files to the repo. Cheers Aleks
Re: nice wiki doc of haproxy
Hi all, Le 09/04/2012 20:37, Willy Tarreau a écrit : Hi Aleks, On Mon, Apr 09, 2012 at 06:38:42PM +0200, Aleksandar Lazic wrote: Some questions for open discussion. 1.) Where is the right page for the 'HTMLFIED' document? http://haproxy.1wt.eu/#docs = separate page such as doc.haproxy.1wt.eu ... We need to ensure we can automate the update so that when the doc is updated on the primary site, it's automatically updated on Cyril's site too. I think I'll configure a bot soon (this week-end ?) to automatically : - fetch daily configuration.txt from HTTP for haproxy 1.4 and 1.5 (or maybe from the git repository for 1.5). - generate documentation for both with the last converter snapshot - push the documentations on the web site. 2.) automatic build or a separate build option 'make htmldoc' I prefer the second way We could think about merging Cyril's work in the contrib dir of haproxy, but since he expects some fast development on it soon, this would slow the process a lot. Better let his project evolve quickly and maybe at some point we could take a snapshot of it into haproxy so that make htmldoc works out of the box. I agree, It's maybe too soon to think about that but as soon as we get something really stable, it will be feasable. Btw, do you prefer us to use a dedicated mailing list for this development or is it OK to post here ? I can create one (again this will probably be this week-end) if you want. I think that at some point, some users might be interested in implementing other backends such as asciidoc which creates very nice outputs for a wide variety of formats (including man and pdf). But let's not start to divert the nice job from what it currently is :-) I thought about that, but I don't see it in a near future ;-) -- Cyril Bonté
Re: nice wiki doc of haproxy
Le 09/04/2012 22:28, Baptiste a écrit : Hey, I'd be keen to participate as well. Good news, happy to read this ;-) Thanks ! A few months I started my own script to do the same, using awk (https://github.com/bedis/haproxy_doc_to_html). cheers -- Cyril Bonté
Re: nice wiki doc of haproxy
Hi Aleksandar, Le 10/04/2012 16:28, Aleksandar Lazic a écrit : I have created a tgz for the style and js files. http://www.none.at/haproxy-style-js.tar.gz how about to link to twitter or add the files to the repo. Well, actually, they already are...but currently only in the gh-pages branch. I agree it will need to be in the master branch too ;-) -- Cyril Bonté
Re: nice wiki doc of haproxy
Hi Cyril, On Tue, Apr 10, 2012 at 10:01:53PM +0200, Cyril Bonté wrote: I think I'll configure a bot soon (this week-end ?) to automatically : - fetch daily configuration.txt from HTTP for haproxy 1.4 and 1.5 (or maybe from the git repository for 1.5). - generate documentation for both with the last converter snapshot - push the documentations on the web site. Fine! When you're done, feel free to send me the definitive URLs and I'll happily add them to the main site. Btw, do you prefer us to use a dedicated mailing list for this development or is it OK to post here ? I can create one (again this will probably be this week-end) if you want. Better use the same, since the users of your doc are here :-) There is not too much traffic here so it's not a problem at all. And since some updates might require minor changes to the original format, it even more makes sense to have this discussion here. Cheers, Willy
Re: nice wiki doc of haproxy
Hi Cyril, really nice work. On 08-04-2012 21:42, Cyril Bonté wrote: [snipp] The code itself is in python and recently started to use Mako Templates as a first attempt to make the code cleaner. Oh python, ok. The generated pages are based on Bootstrap, from Twitter. I believe it will help to easily add some smart features such as keyword auto-completion. That's cool ;-) The project sources : http://github.com/cbonte/haproxy-dconv The project web page : http://cbonte.github.com/haproxy-dconv/ Generated documentations : - for haproxy 1.4 : http://cbonte.github.com/haproxy-dconv/configuration-1.4.html - for haproxy 1.5 : http://cbonte.github.com/haproxy-dconv/configuration-1.5.html Feel free to give me some feedbacks. Again, help will be very welcomed to enhance the project and the documentation ;-) I'm willing to help, as written before ;-) Is there any roadmap or some planned next steps, except the TODO's ;-) Some questions for open discussion. 1.) Where is the right page for the 'HTMLFIED' document? http://haproxy.1wt.eu/#docs = separate page such as doc.haproxy.1wt.eu ... 2.) automatic build or a separate build option 'make htmldoc' I prefer the second way Cheers Aleks
Re: nice wiki doc of haproxy
Hi Aleks, On Mon, Apr 09, 2012 at 06:38:42PM +0200, Aleksandar Lazic wrote: Some questions for open discussion. 1.) Where is the right page for the 'HTMLFIED' document? http://haproxy.1wt.eu/#docs = separate page such as doc.haproxy.1wt.eu ... We need to ensure we can automate the update so that when the doc is updated on the primary site, it's automatically updated on Cyril's site too. 2.) automatic build or a separate build option 'make htmldoc' I prefer the second way We could think about merging Cyril's work in the contrib dir of haproxy, but since he expects some fast development on it soon, this would slow the process a lot. Better let his project evolve quickly and maybe at some point we could take a snapshot of it into haproxy so that make htmldoc works out of the box. I think that at some point, some users might be interested in implementing other backends such as asciidoc which creates very nice outputs for a wide variety of formats (including man and pdf). But let's not start to divert the nice job from what it currently is :-) Cheers, Willy
Re: nice wiki doc of haproxy
Hey, I'd be keen to participate as well. A few months I started my own script to do the same, using awk (https://github.com/bedis/haproxy_doc_to_html). cheers
Re: nice wiki doc of haproxy
Hi all, I wake up this old thread. Le 15/06/2011 22:59, Willy Tarreau a écrit : Hi Cyril, On Wed, Jun 15, 2011 at 10:21:21PM +0200, Cyril Bonté wrote: Yes, I still have this in my TODO list but couldn't find time to cleanup the process : the code was really too awfull and unreadable to be published :-) I'll try to restart this development as soon as possible and submit a minimal version of the converter. Then it will be possible to enhance it incrementally. Believe me, you should never ever feel ashamed of any work you find ugly, especially when there are people who are actively asking for it. If some users are that much waiting for seeing it, probably that as soon as it's published, a few ones will take it, review it, and perform the cleanup way before you find enough time to work on it. Maybe a few ones will totally fork it believing it's crap and they can do something much better. Maybe they'll be right, maybe they'll fail. It doesn't matter. I couldn't find much time for this since the last message...until this week. The code is still ugly. Honestly, I'm quite ashamed of it :-) But I'm not ashamed of the result, so it's time to make it public and to ask for help to cleanup the code, fix some issues and enhance the converter and the generated documentation. The project is shared on gihtub. Also, converted documentation for haproxy 1.4.20 and 1.5 are available there. The code itself is in python and recently started to use Mako Templates as a first attempt to make the code cleaner. The generated pages are based on Bootstrap, from Twitter. I believe it will help to easily add some smart features such as keyword auto-completion. The project sources : http://github.com/cbonte/haproxy-dconv The project web page : http://cbonte.github.com/haproxy-dconv/ Generated documentations : - for haproxy 1.4 : http://cbonte.github.com/haproxy-dconv/configuration-1.4.html - for haproxy 1.5 : http://cbonte.github.com/haproxy-dconv/configuration-1.5.html Feel free to give me some feedbacks. Again, help will be very welcomed to enhance the project and the documentation ;-) -- Cyril Bonté
Re: nice wiki doc of haproxy
Hi Cyril, On Sun, Apr 08, 2012 at 09:42:19PM +0200, Cyril Bonté wrote: I couldn't find much time for this since the last message...until this week. Better late than never :-) The code is still ugly. Honestly, I'm quite ashamed of it :-) You should not, what is important is that it exists and does the job well! But I'm not ashamed of the result, so it's time to make it public and to ask for help to cleanup the code, fix some issues and enhance the converter and the generated documentation. The result is really great, I mean *really*. The project is shared on gihtub. Also, converted documentation for haproxy 1.4.20 and 1.5 are available there. The code itself is in python and recently started to use Mako Templates as a first attempt to make the code cleaner. The generated pages are based on Bootstrap, from Twitter. I believe it will help to easily add some smart features such as keyword auto-completion. The project sources : http://github.com/cbonte/haproxy-dconv The project web page : http://cbonte.github.com/haproxy-dconv/ Generated documentations : - for haproxy 1.4 : http://cbonte.github.com/haproxy-dconv/configuration-1.4.html - for haproxy 1.5 : http://cbonte.github.com/haproxy-dconv/configuration-1.5.html Feel free to give me some feedbacks. Again, help will be very welcomed to enhance the project and the documentation ;-) I hope some people contribute to it as much as I received contribs for haproxy. Maybe you have started a new doc conversion language without yet being aware of it :-) Kudos for the good job! Willy
nice wiki doc of haproxy
There is a nice wiki doc on haproxy configuration at http://code.google.com/p/haproxy-docs/ I m sharing this because i didn't see it's mention on main site http://haproxy.1wt.eu/ it's easy to read than original txt doc
Re: nice wiki doc of haproxy
On Wed, Jun 15, 2011 at 06:43:14PM +0530, shreyas pandya wrote: There is a nice wiki doc on haproxy configuration at http://code.google.com/p/haproxy-docs/ I m sharing this because i didn't see it's mention on main site http://haproxy.1wt.eu/ it's easy to read than original txt doc Yes, this one is really nice. However it seems it was converted by hand, and as anything converted by hand, it eventually dies by lack of time. What we need is an automatic converter for various formats. Some very nice conversions were posted something like one year ago, which were almost automatic but unfortunately nobody had time to takeover the project and continue on this work. Regards, Willy
Re: nice wiki doc of haproxy
Hi all, Le mercredi 15 juin 2011 22:12:18, Willy Tarreau a écrit : On Wed, Jun 15, 2011 at 06:43:14PM +0530, shreyas pandya wrote: There is a nice wiki doc on haproxy configuration at http://code.google.com/p/haproxy-docs/ I m sharing this because i didn't see it's mention on main site http://haproxy.1wt.eu/ it's easy to read than original txt doc Yes, this one is really nice. However it seems it was converted by hand, and as anything converted by hand, it eventually dies by lack of time. What we need is an automatic converter for various formats. Some very nice conversions were posted something like one year ago, which were almost automatic but unfortunately nobody had time to takeover the project and continue on this work. Yes, I still have this in my TODO list but couldn't find time to cleanup the process : the code was really too awfull and unreadable to be published :-) I'll try to restart this development as soon as possible and submit a minimal version of the converter. Then it will be possible to enhance it incrementally. -- Cyril Bonté
Re: nice wiki doc of haproxy
Looks trivial to fork this and turn the regex.txt into a script. I'm up for taking that once we have free cycles at work (couple days max). https://github.com/tmslnz/HAProxy_Markdown On Wed, Jun 15, 2011 at 1:12 PM, Willy Tarreau w...@1wt.eu wrote: On Wed, Jun 15, 2011 at 06:43:14PM +0530, shreyas pandya wrote: There is a nice wiki doc on haproxy configuration at http://code.google.com/p/haproxy-docs/ I m sharing this because i didn't see it's mention on main site http://haproxy.1wt.eu/ it's easy to read than original txt doc Yes, this one is really nice. However it seems it was converted by hand, and as anything converted by hand, it eventually dies by lack of time. What we need is an automatic converter for various formats. Some very nice conversions were posted something like one year ago, which were almost automatic but unfortunately nobody had time to takeover the project and continue on this work. Regards, Willy
Re: nice wiki doc of haproxy
Just throwing my $.02; how about converting the documentation to something more easily parse-able, like markdown? -- -jim
Re: nice wiki doc of haproxy
Hi Cyril, On Wed, Jun 15, 2011 at 10:21:21PM +0200, Cyril Bonté wrote: What we need is an automatic converter for various formats. Some very nice conversions were posted something like one year ago, which were almost automatic but unfortunately nobody had time to takeover the project and continue on this work. Yes, I still have this in my TODO list but couldn't find time to cleanup the process : the code was really too awfull and unreadable to be published :-) I'll try to restart this development as soon as possible and submit a minimal version of the converter. Then it will be possible to enhance it incrementally. Believe me, you should never ever feel ashamed of any work you find ugly, especially when there are people who are actively asking for it. If some users are that much waiting for seeing it, probably that as soon as it's published, a few ones will take it, review it, and perform the cleanup way before you find enough time to work on it. Maybe a few ones will totally fork it believing it's crap and they can do something much better. Maybe they'll be right, maybe they'll fail. It doesn't matter. I know how you feel about what it's like to publish ugly things (hint: there are a lot of even uglier things on 1wt.eu/tools/ that I accepted to publish because people were asking for them). But those ugly things are often useful to people who don't pay attention to the appearance, and who sometimes will be a lot less critical than you on your work. Haproxy was started as something ugly 10 years ago. Some would say that the ugliness has remained or even increased. Still, opening it has tremendously helped improving it. Git is another example of something that started ugly by one tech guy with strong requirements, quickly taken over by a team who made it much more user-friendly, promoting it to the success we know. I'd say that there could be three reasons for not publishing it too fast : - you did that work in a context of a paid job and you're not certain you have the right to publish it ; - you fear that you have sensitive info that you'd like not to disclose (eg: comments about one customer you started the work for, etc...) ; - you think that only you can understand how your code works and you fear that it will be much more work to explain someone else how to do the cleanup than doing it yourself. I remember having seen examples of what you managed to produce and was really impressed. I also remember about another older one which produced great results but I don't remember from whom. Anyway, that means to me that it's hard for everyone to find time to work on such a project, and this is another reason to ask for help. Just keep in mind that you must find the license that suits your expectations the most, and possibly emit strong opinions on some directions you want it to take. Best regards, Willy
Re: nice wiki doc of haproxy
On Wed, Jun 15, 2011 at 04:37:16PM -0400, James Bardin wrote: Just throwing my $.02; how about converting the documentation to something more easily parse-able, like markdown? You mean the mainline doc ? If so, it's been discussed to great length in the past, and the short answer is no. The documentation is always what lags behind code. Whatever barrier you put in front of doc contribs will simply slow them down. I've experienced this a lot in the past with the french doc version which was never updated in contribs. Here I already see what will happen : I've updated the doc but I'm not sure about the end results as I don't have the tool to regenerate it. The current format leaves no excuse for this. I want a human to be able to parse it and to have to conform to very few rules. What I want is a *smart* converter which understands the doc format. Once we spot the real issues (ambiguous situations where we cannot guess), then we'll fix the format and add a few rules. Also, I regularly receive support from people who work on production systems where they have no choice but reading the doc in the 80x25 text console with vi or less. I absolutely want the doc to be optimally usable there. This means no tags, no long lines, etc... Just plain text formatted right and convertible to other formats for a nicer experience when it's possible. BTW, a man output would be nice too ;-) I remember about asciidoc and such which were able to produce various formats, and which could serve as an intermediary format later when we're able to parse what we have. Regards, Willy
Re: nice wiki doc of haproxy
Le 15/06/11 23:09, Willy Tarreau a écrit : On Wed, Jun 15, 2011 at 04:37:16PM -0400, James Bardin wrote: Just throwing my $.02; how about converting the documentation to something more easily parse-able, like markdown? You mean the mainline doc ? If so, it's been discussed to great length in the past, and the short answer is no. The documentation is always what lags behind code. Whatever barrier you put in front of doc contribs will simply slow them down. I've experienced this a lot in the past with the french doc version which was never updated in contribs. Here I already see what will happen : I've updated the doc but I'm not sure about the end results as I don't have the tool to regenerate it. The current format leaves no excuse for this. I want a human to be able to parse it and to have to conform to very few rules. What I want is a *smart* converter which understands the doc format. Once we spot the real issues (ambiguous situations where we cannot guess), then we'll fix the format and add a few rules. Also, I regularly receive support from people who work on production systems where they have no choice but reading the doc in the 80x25 text console with vi or less. I absolutely want the doc to be optimally usable there. This means no tags, no long lines, etc... Just plain text formatted right and convertible to other formats for a nicer experience when it's possible. BTW, a man output would be nice too ;-) I remember about asciidoc and such which were able to produce various formats, and which could serve as an intermediary format later when we're able to parse what we have. markdown and asciidoc pretty are similar, and human readable. That said I agree with everything you said. For instance, Mercurial documentation was migrated from standalone text file to simplified reStructuredText version (a popular format in python world) mostly embedded in source code and this has been a huge win. We are now able to generate documentation in different formats (console output, manpages, HTML), display the same documentation from the CLI or web interface and even generate documentation dynamically for features brought by third-parties plugins. -- Patrick Mézard
