Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Tue, Feb 6, 2018 at 7:17 AM, Oleg Kalnichevski wrote: > On Mon, 2018-02-05 at 23:39 -0700, Bindul Bhowmik wrote: > > ... > >> >> If I may ask as a user of the library, would the new site still have >> parts of the site that are generated from releases? For example, >> Javadocs? >> > > Hi Bindul > > Yes, most certainly javadocs would still be there (given that javadoc > content gets published to ASF Nexus / Maven Central with every release > and therefore is available) but some Maven generated reports would > likely be lost. I _personally_ never found them useful, so I do not see > it as a big loss. Hi Oleg, Thank you for taking that into consideration. > > >> Also, irrespective of the site generation tool or content format >> selection, would it help to move the generated site to git (use >> gitpubsub) and have the site built/published from Jenkins? I happened >> to see a discussion [1] on builds@a.o recently about it. Looks like >> the tooling will also be able to provide a staging site (soon). >> > > Absolutely. Being able to take a full advantage of better tooling is a > primary motivating factor for me to consider migration to Jekyll or a > similar content rendering engine. > > This is a great example of a good project web site > > http://struts.apache.org/getting-started/ Good stuff. However, looks like the struts folks also maintain a full maven site (http://struts.apache.org/maven/) under the main site. And looks like they are using Jekyll and Jenkins as well (https://lists.apache.org/thread.html/%3CCAMopvkO7VJ+pKtipKMEvEZ2udVMk5-JWymmjvF=jjfbdalo...@mail.gmail.com%3E). > > What makes it massively better is not a prettier look but that 'Edit on > GitHub' button. I was going to mention that I remember seeing something similar on the maven lists, as Michael mentioned. Bindul > > Oleg > > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Tue, 2018-02-06 at 19:46 +0100, Michael Osipov wrote: > Am 2018-02-06 um 19:39 schrieb Oleg Kalnichevski: > > On Tue, 2018-02-06 at 16:45 +, sebb wrote: > > > On 6 February 2018 at 14:31, Oleg Kalnichevski > > > > ... > > > > > > > > > ... > > > > > > > > > I *am* saying we need to preserve links. > > > > > Moving from Maven may make this harder, so that needs to be > > > > > factored > > > > > in to the decision. > > > > > > > > So, we have made a full circle here: I am aware that we should > > > > preserve > > > > links, eat healthy, be polite, and stay away from those girls. > > > > > > That tone is not helpful. > > > > > > > I can say exactly likewise. Saying that everything is just fine > > when > > someone else has to do all the heavy lifting is not helpful and > > goes > > counter to the very principles of this organization. > > Please look what Hervé Boutemy has done to the Maven site. All > source, > apt, xdoc, md, can be forked and edited on GitHub. This might be a > solution to go for. Just drop him some lines. > Here we go again. I need to drop him a line and ask what exactly? Fix maven site plugin bloody mess for us? If you are not willing to invest a minute of your own time how could you possibly expect me to do so? Besides, I do not see Github doing inside rendering for apt and xdoc like it can do for markdown. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Am 2018-02-06 um 19:39 schrieb Oleg Kalnichevski: On Tue, 2018-02-06 at 16:45 +, sebb wrote: On 6 February 2018 at 14:31, Oleg Kalnichevski ... ... I *am* saying we need to preserve links. Moving from Maven may make this harder, so that needs to be factored in to the decision. So, we have made a full circle here: I am aware that we should preserve links, eat healthy, be polite, and stay away from those girls. That tone is not helpful. I can say exactly likewise. Saying that everything is just fine when someone else has to do all the heavy lifting is not helpful and goes counter to the very principles of this organization. Please look what Hervé Boutemy has done to the Maven site. All source, apt, xdoc, md, can be forked and edited on GitHub. This might be a solution to go for. Just drop him some lines. Michael - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Tue, 2018-02-06 at 16:45 +, sebb wrote: > On 6 February 2018 at 14:31, Oleg Kalnichevski ... > > > ... > > > > > I *am* saying we need to preserve links. > > > Moving from Maven may make this harder, so that needs to be > > > factored > > > in to the decision. > > > > So, we have made a full circle here: I am aware that we should > > preserve > > links, eat healthy, be polite, and stay away from those girls. > > That tone is not helpful. > I can say exactly likewise. Saying that everything is just fine when someone else has to do all the heavy lifting is not helpful and goes counter to the very principles of this organization. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Tue, 2018-02-06 at 16:28 +, sebb wrote: > On 6 February 2018 at 14:17, Oleg Kalnichevski > wrote: > > On Mon, 2018-02-05 at 23:39 -0700, Bindul Bhowmik wrote: > > > > ... > > Absolutely. Being able to take a full advantage of better tooling > > is a > > primary motivating factor for me to consider migration to Jekyll or > > a > > similar content rendering engine. > > > > This is a great example of a good project web site > > > > http://struts.apache.org/getting-started/ > > > > What makes it massively better is not a prettier look but that > > 'Edit on > > GitHub' button. > > Which surely could be done with the current HC site? > No, it cant because (1) we do not use markdown (2) site generation requires custom scripts and multiple maven projects. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 6 February 2018 at 14:31, Oleg Kalnichevski wrote: > On Tue, 2018-02-06 at 09:55 +, sebb wrote: >> On 4 February 2018 at 11:49, Oleg Kalnichevski >> wrote: >> > On Sat, 2018-02-03 at 23:02 +, sebb wrote: >> > > On 3 February 2018 at 10:32, Oleg Kalnichevski >> > >> > ... >> > >> > > >> > > > Like, better tools tend to use markdown. >> > > >> > > But Maven is not a content generation tool; >> > >> > Why are we using it as a content generation tool I am wondering? >> >> We are not; we are using editors etc. >> >> Maven is used to generate the presentation of the content as a >> website >> or a PDF or whatever. >> > > You are confusing content generation with content authoring. To my mind, the two are the same. To generate something is to create it. So generating content is the same as creating/authoring content. The site is then generated from the content. It looks like your phrase "content generation" is what I would call "site generation". Or equally, you are thinking of "site content" whereas I am thinking of information content, i.e. the content of APT, XML or Markdown files. > ... > >> > and cannot generate sites consisting of multiple versions of >> > the same artifact. >> >> AIUI the multiple sites issue is more about svnpubsub, though >> > > No, it is not about svnpubsub at all. It is about unsuitability of > Maven site plugin for our project web site. > >> >> > No, Sebastian, all is peachy and Maven site plugin is just fine as >> > long >> > as you do not have to touch it. >> >> Well, it is working now, is it not? >> > > Working, but badly, so that no one wants to touch it, including myself. > > ... > >> I *am* saying we need to preserve links. >> Moving from Maven may make this harder, so that needs to be factored >> in to the decision. > > So, we have made a full circle here: I am aware that we should preserve > links, eat healthy, be polite, and stay away from those girls. That tone is not helpful. > Oleg > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 6 February 2018 at 14:17, Oleg Kalnichevski wrote: > On Mon, 2018-02-05 at 23:39 -0700, Bindul Bhowmik wrote: > > ... > >> >> If I may ask as a user of the library, would the new site still have >> parts of the site that are generated from releases? For example, >> Javadocs? >> > > Hi Bindul > > Yes, most certainly javadocs would still be there (given that javadoc > content gets published to ASF Nexus / Maven Central with every release > and therefore is available) but some Maven generated reports would > likely be lost. I _personally_ never found them useful, so I do not see > it as a big loss. > > >> Also, irrespective of the site generation tool or content format >> selection, would it help to move the generated site to git (use >> gitpubsub) and have the site built/published from Jenkins? I happened >> to see a discussion [1] on builds@a.o recently about it. Looks like >> the tooling will also be able to provide a staging site (soon). >> > > Absolutely. Being able to take a full advantage of better tooling is a > primary motivating factor for me to consider migration to Jekyll or a > similar content rendering engine. > > This is a great example of a good project web site > > http://struts.apache.org/getting-started/ > > What makes it massively better is not a prettier look but that 'Edit on > GitHub' button. Which surely could be done with the current HC site? > Oleg > > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Tue, 2018-02-06 at 09:55 +, sebb wrote: > On 4 February 2018 at 11:49, Oleg Kalnichevski > wrote: > > On Sat, 2018-02-03 at 23:02 +, sebb wrote: > > > On 3 February 2018 at 10:32, Oleg Kalnichevski > > > > ... > > > > > > > > > Like, better tools tend to use markdown. > > > > > > But Maven is not a content generation tool; > > > > Why are we using it as a content generation tool I am wondering? > > We are not; we are using editors etc. > > Maven is used to generate the presentation of the content as a > website > or a PDF or whatever. > You are confusing content generation with content authoring. ... > AFAICR I have done both, but not recently. > Would you be able to mention any particular contribution of a non- trivial feature or functionality that had also entailed adding a code sample to the project website or adding a new section to the tutorial? ... > > > and cannot generate sites consisting of multiple versions of > > the same artifact. > > AIUI the multiple sites issue is more about svnpubsub, though > No, it is not about svnpubsub at all. It is about unsuitability of Maven site plugin for our project web site. > > > No, Sebastian, all is peachy and Maven site plugin is just fine as > > long > > as you do not have to touch it. > > Well, it is working now, is it not? > Working, but badly, so that no one wants to touch it, including myself. ... > I *am* saying we need to preserve links. > Moving from Maven may make this harder, so that needs to be factored > in to the decision. So, we have made a full circle here: I am aware that we should preserve links, eat healthy, be polite, and stay away from those girls. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Mon, 2018-02-05 at 23:39 -0700, Bindul Bhowmik wrote: ... > > If I may ask as a user of the library, would the new site still have > parts of the site that are generated from releases? For example, > Javadocs? > Hi Bindul Yes, most certainly javadocs would still be there (given that javadoc content gets published to ASF Nexus / Maven Central with every release and therefore is available) but some Maven generated reports would likely be lost. I _personally_ never found them useful, so I do not see it as a big loss. > Also, irrespective of the site generation tool or content format > selection, would it help to move the generated site to git (use > gitpubsub) and have the site built/published from Jenkins? I happened > to see a discussion [1] on builds@a.o recently about it. Looks like > the tooling will also be able to provide a staging site (soon). > Absolutely. Being able to take a full advantage of better tooling is a primary motivating factor for me to consider migration to Jekyll or a similar content rendering engine. This is a great example of a good project web site http://struts.apache.org/getting-started/ What makes it massively better is not a prettier look but that 'Edit on GitHub' button. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 4 February 2018 at 11:49, Oleg Kalnichevski wrote: > On Sat, 2018-02-03 at 23:02 +, sebb wrote: >> On 3 February 2018 at 10:32, Oleg Kalnichevski > > ... > >> >> > Like, better tools tend to use markdown. >> >> But Maven is not a content generation tool; > > Why are we using it as a content generation tool I am wondering? We are not; we are using editors etc. Maven is used to generate the presentation of the content as a website or a PDF or whatever. >> Preference for markdown and its tooling >> Content presentation. >> Site generation. >> >> Only the latter is really down to Maven and you have yet to explain >> what it is about the site generation that is so terrible. >> > > Had you been taking any interest in actually contributing code or > project web site content you might have known. AFAICR I have done both, but not recently. > Maven generates broken links agreed, but AFAIR it can be fixed in Maven (commons did) > inconsistent line delimiters that Svn chokes on Not noticed that. But is it Maven or one of the tools (e.g. Javadoc) that creates them? > and cannot generate sites consisting of multiple versions of > the same artifact. AIUI the multiple sites issue is more about svnpubsub, though > I have spent years trying to get it to work (it is > not a figure of speech) and ended up writing a bunch of gradle scripts > that stitch together content from multiple maven project, post-process > the content to fix the links and line delimiters. Are you sure migration won't involve lots of ongoing work, and then you discover that the new build system has other features that have to be worked round? > No, Sebastian, all is peachy and Maven site plugin is just fine as long > as you do not have to touch it. Well, it is working now, is it not? == There are several independent but related issues here: - the content information format - the site look and feel - how it is generated. I think it is important to be clear about the reasons for any change. So if some existing features are lost, that can be justified in terms of the benefits. The site URLs and links should be considered as part of the 'API' of the documentation. We should not break them unnecessarily. Note: I am not arguing that we have to keep Maven to build the site. I *am* saying we need to preserve links. Moving from Maven may make this harder, so that needs to be factored in to the decision. > Oleg > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Sun, Feb 4, 2018 at 4:49 AM, Oleg Kalnichevski wrote: > On Sat, 2018-02-03 at 23:02 +, sebb wrote: >> On 3 February 2018 at 10:32, Oleg Kalnichevski > > ... > >> >> > Like, better tools tend to use markdown. >> >> But Maven is not a content generation tool; > > Why are we using it as a content generation tool I am wondering? > >> Preference for markdown and its tooling >> Content presentation. >> Site generation. >> >> Only the latter is really down to Maven and you have yet to explain >> what it is about the site generation that is so terrible. >> > > Had you been taking any interest in actually contributing code or > project web site content you might have known. > > Maven generates broken links, inconsistent line delimiters that Svn > chokes on, and cannot generate sites consisting of multiple versions of > the same artifact. I have spent years trying to get it to work (it is > not a figure of speech) and ended up writing a bunch of gradle scripts > that stitch together content from multiple maven project, post-process > the content to fix the links and line delimiters. > > No, Sebastian, all is peachy and Maven site plugin is just fine as long > as you do not have to touch it. > > Oleg If I may ask as a user of the library, would the new site still have parts of the site that are generated from releases? For example, Javadocs? Also, irrespective of the site generation tool or content format selection, would it help to move the generated site to git (use gitpubsub) and have the site built/published from Jenkins? I happened to see a discussion [1] on builds@a.o recently about it. Looks like the tooling will also be able to provide a staging site (soon). Bindul > > [1] https://lists.apache.org/thread.html/c9c387cc3172bd37ff2355866e91bb4e4985baaf44d3fe1931135f4f@%3Cbuilds.apache.org%3E - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Sat, 2018-02-03 at 23:02 +, sebb wrote: > On 3 February 2018 at 10:32, Oleg Kalnichevski ... > > > Like, better tools tend to use markdown. > > But Maven is not a content generation tool; Why are we using it as a content generation tool I am wondering? > Preference for markdown and its tooling > Content presentation. > Site generation. > > Only the latter is really down to Maven and you have yet to explain > what it is about the site generation that is so terrible. > Had you been taking any interest in actually contributing code or project web site content you might have known. Maven generates broken links, inconsistent line delimiters that Svn chokes on, and cannot generate sites consisting of multiple versions of the same artifact. I have spent years trying to get it to work (it is not a figure of speech) and ended up writing a bunch of gradle scripts that stitch together content from multiple maven project, post-process the content to fix the links and line delimiters. No, Sebastian, all is peachy and Maven site plugin is just fine as long as you do not have to touch it. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 3 February 2018 at 10:32, Oleg Kalnichevski wrote: > On Sat, 2018-02-03 at 10:21 +, sebb wrote: >> On 2 February 2018 at 17:41, Oleg Kalnichevski >> wrote: >> > On Fri, 2018-02-02 at 17:05 +, sebb wrote: >> > > On 2 February 2018 at 13:33, Oleg Kalnichevski >> > > wrote: >> > > > On Wed, 2018-01-31 at 20:18 +, sebb wrote: >> > > > > It may not be pretty, but I find it legible and generally >> > > > > easy to >> > > > > navigate so I hope those attributes won't be lost. >> > > > > >> > > > > Also, it's important not to break any links. >> > > > > >> > > > >> > > > It is also important to eat healthy, be polite and stay away >> > > > from >> > > > those >> > > > girls. >> > > > >> > > > I am sorry, Sebastian, but links are likely to get broken and >> > > > some >> > > >> > > It's not necessary to change the site design. >> > > Nor is it necessary to drop Maven. >> > > >> > >> > Of course not, as long as some other poor sucker has to maintain >> > that >> > site. >> > >> > > I think links are a lot more more important than looks. >> > > >> > >> > This is not so much about the look of the site being terrible >> > (which is >> > a consequence, not a cause) but about the way the site gets >> > generated >> > is terrible. >> >> In what way is it terrible? > > Being terribly broken makes it terrible, does it not? In what way is it broken? Specifically what way is the site generation broken? >> And does that have anything to do with Markdown? > > Like, better tools tend to use markdown. But Maven is not a content generation tool; besides it does support markdown. >> >> > Have you ever wondered why there has been literally not a single >> > contribution to our web site from an external contributor? >> > >> > Have you ever wondered why there have been only two substantial >> > contributions to our documentation in the past 10 years? I suspect >> > the >> > reason is the same. >> >> There are lots of reasons why people don't contribute documentation. > > Absolutely. But twisted and broken tooling that generates hideous > looking content does not really help, does it? I think you are conflating several issues here. Preference for markdown and its tooling Content presentation. Site generation. Only the latter is really down to Maven and you have yet to explain what it is about the site generation that is so terrible. > Oleg > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Am 2018-02-03 um 10:31 schrieb Oleg Kalnichevski: On Fri, 2018-02-02 at 23:01 +0100, Michael Osipov wrote: Am 2018-01-31 um 14:06 schrieb Oleg Kalnichevski: Folks We have a dubious honor of having absolutely the most hideous project web site in existence. It makes my eyes bleed every time I have to update it. It is simply horrible. I would like to migrate project website sources from Maven apt and xdoc to markdown format and switch to using either jekyll or hugo site generator to render markdown to html. 1. Does anyone have conceptual objections to using markdown? No, but is there any huge benefit over apt? Massively better tooling. Github support for writing documentation is just awesome. How do we benefit from when we are publishing to ASF infrastructure through 'mvn site'? Michael - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Sat, 2018-02-03 at 10:21 +, sebb wrote: > On 2 February 2018 at 17:41, Oleg Kalnichevski > wrote: > > On Fri, 2018-02-02 at 17:05 +, sebb wrote: > > > On 2 February 2018 at 13:33, Oleg Kalnichevski > > > wrote: > > > > On Wed, 2018-01-31 at 20:18 +, sebb wrote: > > > > > It may not be pretty, but I find it legible and generally > > > > > easy to > > > > > navigate so I hope those attributes won't be lost. > > > > > > > > > > Also, it's important not to break any links. > > > > > > > > > > > > > It is also important to eat healthy, be polite and stay away > > > > from > > > > those > > > > girls. > > > > > > > > I am sorry, Sebastian, but links are likely to get broken and > > > > some > > > > > > It's not necessary to change the site design. > > > Nor is it necessary to drop Maven. > > > > > > > Of course not, as long as some other poor sucker has to maintain > > that > > site. > > > > > I think links are a lot more more important than looks. > > > > > > > This is not so much about the look of the site being terrible > > (which is > > a consequence, not a cause) but about the way the site gets > > generated > > is terrible. > > In what way is it terrible? Being terribly broken makes it terrible, does it not? > And does that have anything to do with Markdown? Like, better tools tend to use markdown. > > > Have you ever wondered why there has been literally not a single > > contribution to our web site from an external contributor? > > > > Have you ever wondered why there have been only two substantial > > contributions to our documentation in the past 10 years? I suspect > > the > > reason is the same. > > There are lots of reasons why people don't contribute documentation. Absolutely. But twisted and broken tooling that generates hideous looking content does not really help, does it? Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Sat, 2018-02-03 at 10:18 +, sebb wrote: > On 3 February 2018 at 09:31, Oleg Kalnichevski > wrote: > > On Fri, 2018-02-02 at 23:01 +0100, Michael Osipov wrote: > > > Am 2018-01-31 um 14:06 schrieb Oleg Kalnichevski: > > > > Folks > > > > > > > > We have a dubious honor of having absolutely the most hideous > > > > project > > > > web site in existence. It makes my eyes bleed every time I have > > > > to > > > > update it. It is simply horrible. > > > > > > > > I would like to migrate project website sources from Maven apt > > > > and > > > > xdoc > > > > to markdown format and switch to using either jekyll or hugo > > > > site > > > > generator to render markdown to html. > > > > > > > > 1. Does anyone have conceptual objections to using markdown? > > > > > > No, but is there any huge benefit over apt? > > > > Massively better tooling. Github support for writing documentation > > is > > just awesome. > > Does it preclude using Maven? > Of course not, especially if one intentionally wants to make things unnecessary complex. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 2 February 2018 at 17:41, Oleg Kalnichevski wrote: > On Fri, 2018-02-02 at 17:05 +, sebb wrote: >> On 2 February 2018 at 13:33, Oleg Kalnichevski >> wrote: >> > On Wed, 2018-01-31 at 20:18 +, sebb wrote: >> > > It may not be pretty, but I find it legible and generally easy to >> > > navigate so I hope those attributes won't be lost. >> > > >> > > Also, it's important not to break any links. >> > > >> > >> > It is also important to eat healthy, be polite and stay away from >> > those >> > girls. >> > >> > I am sorry, Sebastian, but links are likely to get broken and some >> >> It's not necessary to change the site design. >> Nor is it necessary to drop Maven. >> > > Of course not, as long as some other poor sucker has to maintain that > site. > >> I think links are a lot more more important than looks. >> > > This is not so much about the look of the site being terrible (which is > a consequence, not a cause) but about the way the site gets generated > is terrible. In what way is it terrible? And does that have anything to do with Markdown? > Have you ever wondered why there has been literally not a single > contribution to our web site from an external contributor? > > Have you ever wondered why there have been only two substantial > contributions to our documentation in the past 10 years? I suspect the > reason is the same. There are lots of reasons why people don't contribute documentation. > Oleg > > > > >> > Maven generated reports are not going to be there anymore. If some >> > people feel strongly about it, they are welcome to help fixing them >> > and >> > provide missing content. >> > >> > Oleg >> > >> > >> > > If the site is no longer built using Maven, then it may be >> > > difficult >> > > to preserve all the links (e.g. project info page links). >> > > >> > > It appears to be possible to use Markdown with Maven: >> > > https://stackoverflow.com/questions/14829190/how-to-use-markdown- >> > > for- >> > > maven-project-site >> > > >> > > Ideally anchors (internal page links) will also be maintained as >> > > far >> > > as possible. >> > > >> > > S. >> > > >> > > On 31 January 2018 at 19:15, Gary Gregory > > > > >> > > wrote: >> > > > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski > > > > e.or >> > > > g> wrote: >> > > > >> > > > > On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: >> > > > > > > >> > > > > >> > > > > ... >> > > > > >> > > > > >> > > > > > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > > > > > > pach >> > > > > > e.org> >> > > > > > wrote: >> > > > > > >> > > > > > Granted the site is not the most attractive, the only time >> > > > > > I >> > > > > > want to >> > > > > > dedicate to this topic is to discuss it here. I do not care >> > > > > > about >> > > > > > which >> > > > > > tools we use to get us to a new site. For my money, I'd >> > > > > > simply >> > > > > > try to >> > > > > > improved what we have now we a different stylesheet >> > > > > > (Fluido?). >> > > > > > For >> > > > > > example, >> > > > > > this is fine with me: >> > > > > > https://logging.apache.org/log4j/2.x/manual/architecture.ht >> > > > > > ml >> > > > > > and >> > > > > > it's all >> > > > > > Maven. >> > > > > > >> > > > > >> > > > > I understand that but you opinion might rapidly change once >> > > > > you >> > > > > actually need to author a substantial amount of content with >> > > > > xdoc >> > > > > or >> > > > > apt. >> > > > > >> > > > >> > > > Bah, it's just one format vs. another, it just depends on how >> > > > much >> > > > control >> > > > you want. >> > > > >> > > > For >> > > > https://www.manning.com/books/java-persistence-with-hibernate-s >> > > > econ >> > > > d-edition, >> > > > we wrote it all in XHTML. >> > > > >> > > > Gary >> > > > >> > > > >> > > > > >> > > > > Oleg >> > > > > >> > > > > --- >> > > > > >> > > > > -- >> > > > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> > > > > For additional commands, e-mail: dev-h...@hc.apache.org >> > > > > >> > > > > >> > > >> > > --- >> > > -- >> > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> > > For additional commands, e-mail: dev-h...@hc.apache.org >> > > >> > >> > - >> > >> > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> > For additional commands, e-mail: dev-h...@hc.apache.org >> > >> >> - >> To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> For additional commands, e-mail: dev-h...@hc.apache.org >> > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apa
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 3 February 2018 at 09:31, Oleg Kalnichevski wrote: > On Fri, 2018-02-02 at 23:01 +0100, Michael Osipov wrote: >> Am 2018-01-31 um 14:06 schrieb Oleg Kalnichevski: >> > Folks >> > >> > We have a dubious honor of having absolutely the most hideous >> > project >> > web site in existence. It makes my eyes bleed every time I have to >> > update it. It is simply horrible. >> > >> > I would like to migrate project website sources from Maven apt and >> > xdoc >> > to markdown format and switch to using either jekyll or hugo site >> > generator to render markdown to html. >> > >> > 1. Does anyone have conceptual objections to using markdown? >> >> No, but is there any huge benefit over apt? > > Massively better tooling. Github support for writing documentation is > just awesome. Does it preclude using Maven? > Oleg > > >> xdoc is horrible. >> >> > 2. Does anyone have any preference with regards to static site >> > generators? >> >> Maven Doxia includes now Markdown support based on flexmark-java. >> >> Have you considered that instead of build another chain? >> >> Michael >> > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Fri, 2018-02-02 at 23:01 +0100, Michael Osipov wrote: > Am 2018-01-31 um 14:06 schrieb Oleg Kalnichevski: > > Folks > > > > We have a dubious honor of having absolutely the most hideous > > project > > web site in existence. It makes my eyes bleed every time I have to > > update it. It is simply horrible. > > > > I would like to migrate project website sources from Maven apt and > > xdoc > > to markdown format and switch to using either jekyll or hugo site > > generator to render markdown to html. > > > > 1. Does anyone have conceptual objections to using markdown? > > No, but is there any huge benefit over apt? Massively better tooling. Github support for writing documentation is just awesome. Oleg > xdoc is horrible. > > > 2. Does anyone have any preference with regards to static site > > generators? > > Maven Doxia includes now Markdown support based on flexmark-java. > > Have you considered that instead of build another chain? > > Michael > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Am 2018-01-31 um 14:06 schrieb Oleg Kalnichevski: Folks We have a dubious honor of having absolutely the most hideous project web site in existence. It makes my eyes bleed every time I have to update it. It is simply horrible. I would like to migrate project website sources from Maven apt and xdoc to markdown format and switch to using either jekyll or hugo site generator to render markdown to html. 1. Does anyone have conceptual objections to using markdown? No, but is there any huge benefit over apt? xdoc is horrible. 2. Does anyone have any preference with regards to static site generators? Maven Doxia includes now Markdown support based on flexmark-java. Have you considered that instead of build another chain? Michael - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Fri, 2018-02-02 at 17:05 +, sebb wrote: > On 2 February 2018 at 13:33, Oleg Kalnichevski > wrote: > > On Wed, 2018-01-31 at 20:18 +, sebb wrote: > > > It may not be pretty, but I find it legible and generally easy to > > > navigate so I hope those attributes won't be lost. > > > > > > Also, it's important not to break any links. > > > > > > > It is also important to eat healthy, be polite and stay away from > > those > > girls. > > > > I am sorry, Sebastian, but links are likely to get broken and some > > It's not necessary to change the site design. > Nor is it necessary to drop Maven. > Of course not, as long as some other poor sucker has to maintain that site. > I think links are a lot more more important than looks. > This is not so much about the look of the site being terrible (which is a consequence, not a cause) but about the way the site gets generated is terrible. Have you ever wondered why there has been literally not a single contribution to our web site from an external contributor? Have you ever wondered why there have been only two substantial contributions to our documentation in the past 10 years? I suspect the reason is the same. Oleg > > Maven generated reports are not going to be there anymore. If some > > people feel strongly about it, they are welcome to help fixing them > > and > > provide missing content. > > > > Oleg > > > > > > > If the site is no longer built using Maven, then it may be > > > difficult > > > to preserve all the links (e.g. project info page links). > > > > > > It appears to be possible to use Markdown with Maven: > > > https://stackoverflow.com/questions/14829190/how-to-use-markdown- > > > for- > > > maven-project-site > > > > > > Ideally anchors (internal page links) will also be maintained as > > > far > > > as possible. > > > > > > S. > > > > > > On 31 January 2018 at 19:15, Gary Gregory > > > > > > wrote: > > > > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski > > > e.or > > > > g> wrote: > > > > > > > > > On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: > > > > > > > > > > > > > > > > > ... > > > > > > > > > > > > > > > > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > > > > > pach > > > > > > e.org> > > > > > > wrote: > > > > > > > > > > > > Granted the site is not the most attractive, the only time > > > > > > I > > > > > > want to > > > > > > dedicate to this topic is to discuss it here. I do not care > > > > > > about > > > > > > which > > > > > > tools we use to get us to a new site. For my money, I'd > > > > > > simply > > > > > > try to > > > > > > improved what we have now we a different stylesheet > > > > > > (Fluido?). > > > > > > For > > > > > > example, > > > > > > this is fine with me: > > > > > > https://logging.apache.org/log4j/2.x/manual/architecture.ht > > > > > > ml > > > > > > and > > > > > > it's all > > > > > > Maven. > > > > > > > > > > > > > > > > I understand that but you opinion might rapidly change once > > > > > you > > > > > actually need to author a substantial amount of content with > > > > > xdoc > > > > > or > > > > > apt. > > > > > > > > > > > > > Bah, it's just one format vs. another, it just depends on how > > > > much > > > > control > > > > you want. > > > > > > > > For > > > > https://www.manning.com/books/java-persistence-with-hibernate-s > > > > econ > > > > d-edition, > > > > we wrote it all in XHTML. > > > > > > > > Gary > > > > > > > > > > > > > > > > > > Oleg > > > > > > > > > > --- > > > > > > > > > > -- > > > > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > > > > > For additional commands, e-mail: dev-h...@hc.apache.org > > > > > > > > > > > > > > > > --- > > > -- > > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > > > For additional commands, e-mail: dev-h...@hc.apache.org > > > > > > > - > > > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > > For additional commands, e-mail: dev-h...@hc.apache.org > > > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 2 February 2018 at 13:33, Oleg Kalnichevski wrote: > On Wed, 2018-01-31 at 20:18 +, sebb wrote: >> It may not be pretty, but I find it legible and generally easy to >> navigate so I hope those attributes won't be lost. >> >> Also, it's important not to break any links. >> > > It is also important to eat healthy, be polite and stay away from those > girls. > > I am sorry, Sebastian, but links are likely to get broken and some It's not necessary to change the site design. Nor is it necessary to drop Maven. I think links are a lot more more important than looks. > Maven generated reports are not going to be there anymore. If some > people feel strongly about it, they are welcome to help fixing them and > provide missing content. > > Oleg > > >> If the site is no longer built using Maven, then it may be difficult >> to preserve all the links (e.g. project info page links). >> >> It appears to be possible to use Markdown with Maven: >> https://stackoverflow.com/questions/14829190/how-to-use-markdown-for- >> maven-project-site >> >> Ideally anchors (internal page links) will also be maintained as far >> as possible. >> >> S. >> >> On 31 January 2018 at 19:15, Gary Gregory >> wrote: >> > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski > > g> wrote: >> > >> > > On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: >> > > > > >> > > >> > > ... >> > > >> > > >> > > > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > > > > e.org> >> > > > wrote: >> > > > >> > > > Granted the site is not the most attractive, the only time I >> > > > want to >> > > > dedicate to this topic is to discuss it here. I do not care >> > > > about >> > > > which >> > > > tools we use to get us to a new site. For my money, I'd simply >> > > > try to >> > > > improved what we have now we a different stylesheet (Fluido?). >> > > > For >> > > > example, >> > > > this is fine with me: >> > > > https://logging.apache.org/log4j/2.x/manual/architecture.html >> > > > and >> > > > it's all >> > > > Maven. >> > > > >> > > >> > > I understand that but you opinion might rapidly change once you >> > > actually need to author a substantial amount of content with xdoc >> > > or >> > > apt. >> > > >> > >> > Bah, it's just one format vs. another, it just depends on how much >> > control >> > you want. >> > >> > For >> > https://www.manning.com/books/java-persistence-with-hibernate-secon >> > d-edition, >> > we wrote it all in XHTML. >> > >> > Gary >> > >> > >> > > >> > > Oleg >> > > >> > > --- >> > > -- >> > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> > > For additional commands, e-mail: dev-h...@hc.apache.org >> > > >> > > >> >> - >> To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> For additional commands, e-mail: dev-h...@hc.apache.org >> > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Wed, 2018-01-31 at 20:18 +, sebb wrote: > It may not be pretty, but I find it legible and generally easy to > navigate so I hope those attributes won't be lost. > > Also, it's important not to break any links. > It is also important to eat healthy, be polite and stay away from those girls. I am sorry, Sebastian, but links are likely to get broken and some Maven generated reports are not going to be there anymore. If some people feel strongly about it, they are welcome to help fixing them and provide missing content. Oleg > If the site is no longer built using Maven, then it may be difficult > to preserve all the links (e.g. project info page links). > > It appears to be possible to use Markdown with Maven: > https://stackoverflow.com/questions/14829190/how-to-use-markdown-for- > maven-project-site > > Ideally anchors (internal page links) will also be maintained as far > as possible. > > S. > > On 31 January 2018 at 19:15, Gary Gregory > wrote: > > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski > g> wrote: > > > > > On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: > > > > > > > > > > > ... > > > > > > > > > > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > > > e.org> > > > > wrote: > > > > > > > > Granted the site is not the most attractive, the only time I > > > > want to > > > > dedicate to this topic is to discuss it here. I do not care > > > > about > > > > which > > > > tools we use to get us to a new site. For my money, I'd simply > > > > try to > > > > improved what we have now we a different stylesheet (Fluido?). > > > > For > > > > example, > > > > this is fine with me: > > > > https://logging.apache.org/log4j/2.x/manual/architecture.html > > > > and > > > > it's all > > > > Maven. > > > > > > > > > > I understand that but you opinion might rapidly change once you > > > actually need to author a substantial amount of content with xdoc > > > or > > > apt. > > > > > > > Bah, it's just one format vs. another, it just depends on how much > > control > > you want. > > > > For > > https://www.manning.com/books/java-persistence-with-hibernate-secon > > d-edition, > > we wrote it all in XHTML. > > > > Gary > > > > > > > > > > Oleg > > > > > > --- > > > -- > > > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > > > For additional commands, e-mail: dev-h...@hc.apache.org > > > > > > > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
It may not be pretty, but I find it legible and generally easy to navigate so I hope those attributes won't be lost. Also, it's important not to break any links. If the site is no longer built using Maven, then it may be difficult to preserve all the links (e.g. project info page links). It appears to be possible to use Markdown with Maven: https://stackoverflow.com/questions/14829190/how-to-use-markdown-for-maven-project-site Ideally anchors (internal page links) will also be maintained as far as possible. S. On 31 January 2018 at 19:15, Gary Gregory wrote: > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski wrote: > >> On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: >> > > >> >> ... >> >> >> > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski >> > wrote: >> > >> > Granted the site is not the most attractive, the only time I want to >> > dedicate to this topic is to discuss it here. I do not care about >> > which >> > tools we use to get us to a new site. For my money, I'd simply try to >> > improved what we have now we a different stylesheet (Fluido?). For >> > example, >> > this is fine with me: >> > https://logging.apache.org/log4j/2.x/manual/architecture.html and >> > it's all >> > Maven. >> > >> >> I understand that but you opinion might rapidly change once you >> actually need to author a substantial amount of content with xdoc or >> apt. >> > > Bah, it's just one format vs. another, it just depends on how much control > you want. > > For > https://www.manning.com/books/java-persistence-with-hibernate-second-edition, > we wrote it all in XHTML. > > Gary > > >> >> Oleg >> >> - >> To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org >> For additional commands, e-mail: dev-h...@hc.apache.org >> >> - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski wrote: > On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: > > > > > ... > > > > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > > wrote: > > > > Granted the site is not the most attractive, the only time I want to > > dedicate to this topic is to discuss it here. I do not care about > > which > > tools we use to get us to a new site. For my money, I'd simply try to > > improved what we have now we a different stylesheet (Fluido?). For > > example, > > this is fine with me: > > https://logging.apache.org/log4j/2.x/manual/architecture.html and > > it's all > > Maven. > > > > I understand that but you opinion might rapidly change once you > actually need to author a substantial amount of content with xdoc or > apt. > Bah, it's just one format vs. another, it just depends on how much control you want. For https://www.manning.com/books/java-persistence-with-hibernate-second-edition, we wrote it all in XHTML. Gary > > Oleg > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > >
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On 1/31/2018 6:36 PM, Oleg Kalnichevski wrote: Folks We have a dubious honor of having absolutely the most hideous project web site in existence. It makes my eyes bleed every time I have to update it. It is simply horrible. I would like to migrate project website sources from Maven apt and xdoc to markdown format and switch to using either jekyll or hugo site generator to render markdown to html. 1. Does anyone have conceptual objections to using markdown? I have no objections.. 2. Does anyone have any preference with regards to static site generators? Jekyll appears to be the tool of choice for many ASF projects. I personally tend to lean toward Hugo more. No preference here.. I think we must use what is easier for us to maintain, and not what other ASF projects use most. thanks asankha -- Asankha C. Perera AdroitLogic, https://www.adroitlogic.com http://esbmagic.blogspot.com - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote: > > ... > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski > wrote: > > Granted the site is not the most attractive, the only time I want to > dedicate to this topic is to discuss it here. I do not care about > which > tools we use to get us to a new site. For my money, I'd simply try to > improved what we have now we a different stylesheet (Fluido?). For > example, > this is fine with me: > https://logging.apache.org/log4j/2.x/manual/architecture.html and > it's all > Maven. > I understand that but you opinion might rapidly change once you actually need to author a substantial amount of content with xdoc or apt. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski wrote: > Folks > > We have a dubious honor of having absolutely the most hideous project > web site in existence. It makes my eyes bleed every time I have to > update it. It is simply horrible. > > I would like to migrate project website sources from Maven apt and xdoc > to markdown format and switch to using either jekyll or hugo site > generator to render markdown to html. > > 1. Does anyone have conceptual objections to using markdown? > > 2. Does anyone have any preference with regards to static site > generators? > > Jekyll appears to be the tool of choice for many ASF projects. I > personally tend to lean toward Hugo more. > > Please let me know what you think. > Granted the site is not the most attractive, the only time I want to dedicate to this topic is to discuss it here. I do not care about which tools we use to get us to a new site. For my money, I'd simply try to improved what we have now we a different stylesheet (Fluido?). For example, this is fine with me: https://logging.apache.org/log4j/2.x/manual/architecture.html and it's all Maven. Gary > > Oleg > > - > To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org > For additional commands, e-mail: dev-h...@hc.apache.org > >
[DISCUSS] Migrating project website content to markdown (2nd attempt)
Folks We have a dubious honor of having absolutely the most hideous project web site in existence. It makes my eyes bleed every time I have to update it. It is simply horrible. I would like to migrate project website sources from Maven apt and xdoc to markdown format and switch to using either jekyll or hugo site generator to render markdown to html. 1. Does anyone have conceptual objections to using markdown? 2. Does anyone have any preference with regards to static site generators? Jekyll appears to be the tool of choice for many ASF projects. I personally tend to lean toward Hugo more. Please let me know what you think. Oleg - To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org For additional commands, e-mail: dev-h...@hc.apache.org
