You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Oleg Kalnichevski <ol...@apache.org> on 2018/01/31 13:06:51 UTC
[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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
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 +0000, sebb wrote:
> > > On 6 February 2018 at 14:31, Oleg Kalnichevski <ol...@apache.org>
> >
> > ...
> >
> > >
> > > > ...
> > > >
> > > > > 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Michael Osipov <mi...@apache.org>.
Am 2018-02-06 um 19:39 schrieb Oleg Kalnichevski:
> On Tue, 2018-02-06 at 16:45 +0000, sebb wrote:
>> On 6 February 2018 at 14:31, Oleg Kalnichevski <ol...@apache.org>
>
> ...
>
>>
>>> ...
>>>
>>>> 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2018-02-06 at 16:45 +0000, sebb wrote:
> On 6 February 2018 at 14:31, Oleg Kalnichevski <ol...@apache.org>
...
>
> > ...
> >
> > > 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 6 February 2018 at 14:31, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Tue, 2018-02-06 at 09:55 +0000, sebb wrote:
>> On 4 February 2018 at 11:49, Oleg Kalnichevski <ol...@apache.org>
>> wrote:
>> > On Sat, 2018-02-03 at 23:02 +0000, sebb wrote:
>> > > On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org>
>> >
>> > ...
>> >
>> > >
>> > > > 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2018-02-06 at 09:55 +0000, sebb wrote:
> On 4 February 2018 at 11:49, Oleg Kalnichevski <ol...@apache.org>
> wrote:
> > On Sat, 2018-02-03 at 23:02 +0000, sebb wrote:
> > > On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org>
> >
> > ...
> >
> > >
> > > > 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 4 February 2018 at 11:49, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Sat, 2018-02-03 at 23:02 +0000, sebb wrote:
>> On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org>
>
> ...
>
>>
>> > 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2018-02-06 at 16:28 +0000, sebb wrote:
> On 6 February 2018 at 14:17, Oleg Kalnichevski <ol...@apache.org>
> 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 6 February 2018 at 14:17, Oleg Kalnichevski <ol...@apache.org> 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by Bindul Bhowmik <bi...@gmail.com>.
On Tue, Feb 6, 2018 at 7:17 AM, Oleg Kalnichevski <ol...@apache.org> 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=jjfBdALogBg@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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by Bindul Bhowmik <bi...@gmail.com>.
On Sun, Feb 4, 2018 at 4:49 AM, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Sat, 2018-02-03 at 23:02 +0000, sebb wrote:
>> On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org>
>
> ...
>
>>
>> > 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2018-02-03 at 23:02 +0000, sebb wrote:
> On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org>
...
>
> > 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 3 February 2018 at 10:32, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Sat, 2018-02-03 at 10:21 +0000, sebb wrote:
>> On 2 February 2018 at 17:41, Oleg Kalnichevski <ol...@apache.org>
>> wrote:
>> > On Fri, 2018-02-02 at 17:05 +0000, sebb wrote:
>> > > On 2 February 2018 at 13:33, Oleg Kalnichevski <ol...@apache.org>
>> > > wrote:
>> > > > On Wed, 2018-01-31 at 20:18 +0000, 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2018-02-03 at 10:21 +0000, sebb wrote:
> On 2 February 2018 at 17:41, Oleg Kalnichevski <ol...@apache.org>
> wrote:
> > On Fri, 2018-02-02 at 17:05 +0000, sebb wrote:
> > > On 2 February 2018 at 13:33, Oleg Kalnichevski <ol...@apache.org>
> > > wrote:
> > > > On Wed, 2018-01-31 at 20:18 +0000, 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 2 February 2018 at 17:41, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Fri, 2018-02-02 at 17:05 +0000, sebb wrote:
>> On 2 February 2018 at 13:33, Oleg Kalnichevski <ol...@apache.org>
>> wrote:
>> > On Wed, 2018-01-31 at 20:18 +0000, 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 <garydgregory@gmail.com
>> > > >
>> > > wrote:
>> > > > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <olegk@apach
>> > > > 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 <olegk@a
>> > > > > > 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-unsubscribe@hc.apache.org
>> > > > > For additional commands, e-mail: dev-help@hc.apache.org
>> > > > >
>> > > > >
>> > >
>> > > ---------------------------------------------------------------
>> > > ------
>> > > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> > > For additional commands, e-mail: dev-help@hc.apache.org
>> > >
>> >
>> > -----------------------------------------------------------------
>> > ----
>> > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> > For additional commands, e-mail: dev-help@hc.apache.org
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> For additional commands, e-mail: dev-help@hc.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Fri, 2018-02-02 at 17:05 +0000, sebb wrote:
> On 2 February 2018 at 13:33, Oleg Kalnichevski <ol...@apache.org>
> wrote:
> > On Wed, 2018-01-31 at 20:18 +0000, 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 <garydgregory@gmail.com
> > > >
> > > wrote:
> > > > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <olegk@apach
> > > > 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 <olegk@a
> > > > > > 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-unsubscribe@hc.apache.org
> > > > > For additional commands, e-mail: dev-help@hc.apache.org
> > > > >
> > > > >
> > >
> > > ---------------------------------------------------------------
> > > ------
> > > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> > > For additional commands, e-mail: dev-help@hc.apache.org
> > >
> >
> > -----------------------------------------------------------------
> > ----
> > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> > For additional commands, e-mail: dev-help@hc.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 2 February 2018 at 13:33, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Wed, 2018-01-31 at 20:18 +0000, 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 <ga...@gmail.com>
>> wrote:
>> > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <olegk@apache.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 <olegk@apach
>> > > > 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-unsubscribe@hc.apache.org
>> > > For additional commands, e-mail: dev-help@hc.apache.org
>> > >
>> > >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> For additional commands, e-mail: dev-help@hc.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Wed, 2018-01-31 at 20:18 +0000, 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 <ga...@gmail.com>
> wrote:
> > On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <olegk@apache.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 <olegk@apach
> > > > 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-unsubscribe@hc.apache.org
> > > For additional commands, e-mail: dev-help@hc.apache.org
> > >
> > >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
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 <ga...@gmail.com> wrote:
> On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <ol...@apache.org> wrote:
>
>> On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote:
>> > >
>>
>> ...
>>
>>
>> > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski <ol...@apache.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-second-edition,
> we wrote it all in XHTML.
>
> Gary
>
>
>>
>> Oleg
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> For additional commands, e-mail: dev-help@hc.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by Gary Gregory <ga...@gmail.com>.
On Wed, Jan 31, 2018 at 7:57 AM, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote:
> > >
>
> ...
>
>
> > On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski <ol...@apache.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-second-edition,
we wrote it all in XHTML.
Gary
>
> Oleg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Wed, 2018-01-31 at 07:43 -0700, Gary Gregory wrote:
> >
...
> On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski <ol...@apache.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.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by Gary Gregory <ga...@gmail.com>.
On Wed, Jan 31, 2018 at 6:06 AM, Oleg Kalnichevski <ol...@apache.org> 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2018-02-03 at 10:18 +0000, sebb wrote:
> On 3 February 2018 at 09:31, Oleg Kalnichevski <ol...@apache.org>
> 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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd attempt)
Posted by sebb <se...@gmail.com>.
On 3 February 2018 at 09:31, Oleg Kalnichevski <ol...@apache.org> 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-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Michael Osipov <mi...@apache.org>.
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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Oleg Kalnichevski <ol...@apache.org>.
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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by Michael Osipov <mi...@apache.org>.
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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [DISCUSS] Migrating project website content to markdown (2nd
attempt)
Posted by "Asankha C. Perera" <as...@apache.org>.
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-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org