You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@logging.apache.org by Ralph Goers <ra...@dslextreme.com> on 2019/04/29 15:34:23 UTC
Asciidoc for site documents
The master branch was converted to use AsciiDoctor. To be honest, I don’t remember why. But after trying to create a new page with it I discovered that AsciiDoctor simply doesn’t work properly with the Maven Site Plugin. See https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As such I believe the site documents in Master need to be converted back to Markdown.
Ralph
Re: Asciidoc for site documents
Posted by Matt Sicker <bo...@gmail.com>.
On Mon, 29 Apr 2019 at 13:53, Ralph Goers <ra...@dslextreme.com> wrote:
> The proposal wasn’t to go back to xdoc but to switch everything to Markdown. To be honest I’m still not sure why asciidoc is better than Markdown. What syntactical features?
I don't remember if I brought this up back when I was converting the
docs, but asciidoc had far more formatting-related features that
seemed optimized for technical documentation compared to markdown
which seems to be optimized for README files and reddit comments.
However, I most likely tried converting everything to markdown first
before choosing asciidoc. I'll need to do some digging to find that
info again.
--
Matt Sicker <bo...@gmail.com>
Re: Asciidoc for site documents
Posted by Gary Gregory <ga...@gmail.com>.
On Mon, Apr 29, 2019 at 2:53 PM Ralph Goers <ra...@dslextreme.com>
wrote:
> The proposal wasn’t to go back to xdoc but to switch everything to
> Markdown. To be honest I’m still not sure why asciidoc is better than
> Markdown. What syntactical features?
>
I won't oppose any shuffling around but I think it would be nice in a FOSS
way to give the opportunity to the asciidoc community to fix or update
their plugin.
Gary
>
> Ralph
>
> > On Apr 29, 2019, at 10:14 AM, Matt Sicker <bo...@gmail.com> wrote:
> >
> > Oh, the maven plugin seems to be a different project than what I was
> > referencing.
> >
> > So is this just not possible to fix? I'd really hate to have to go back
> to xdoc.
> >
> > On Mon, 29 Apr 2019 at 11:48, Ralph Goers <ra...@dslextreme.com>
> wrote:
> >>
> >> The issue isn’t marked as fixed. The problem I am having is that
> tables are rendered without borders. This is because asciidoc doesn’t
> include its css file when building the site because the “normal” asciidoc
> css would break the site. Asciidoc generates tables with css class names to
> generate the borders and grids. According to the Jira issue other markup
> has the same issue.
> >>
> >> Ralph
> >>
> >>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> >>>
> >>> I had converted them to asciidoc a while back because it provided more
> >>> syntactical features than markdown. Many of the files I converted
> >>> weren't markdown but xdoc.
> >>>
> >>> Also, there was a new asciidoctor release just the other day. Unsure
> >>> if it's related.
> >>>
> >>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
> wrote:
> >>>>
> >>>> The master branch was converted to use AsciiDoctor. To be honest, I
> don’t remember why. But after trying to create a new page with it I
> discovered that AsciiDoctor simply doesn’t work properly with the Maven
> Site Plugin. See
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
> such I believe the site documents in Master need to be converted back to
> Markdown.
> >>>>
> >>>> Ralph
> >>>
> >>>
> >>>
> >>> --
> >>> Matt Sicker <bo...@gmail.com>
> >>>
> >>
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
> >
>
>
>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
The proposal wasn’t to go back to xdoc but to switch everything to Markdown. To be honest I’m still not sure why asciidoc is better than Markdown. What syntactical features?
Ralph
> On Apr 29, 2019, at 10:14 AM, Matt Sicker <bo...@gmail.com> wrote:
>
> Oh, the maven plugin seems to be a different project than what I was
> referencing.
>
> So is this just not possible to fix? I'd really hate to have to go back to xdoc.
>
> On Mon, 29 Apr 2019 at 11:48, Ralph Goers <ra...@dslextreme.com> wrote:
>>
>> The issue isn’t marked as fixed. The problem I am having is that tables are rendered without borders. This is because asciidoc doesn’t include its css file when building the site because the “normal” asciidoc css would break the site. Asciidoc generates tables with css class names to generate the borders and grids. According to the Jira issue other markup has the same issue.
>>
>> Ralph
>>
>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>
>>> I had converted them to asciidoc a while back because it provided more
>>> syntactical features than markdown. Many of the files I converted
>>> weren't markdown but xdoc.
>>>
>>> Also, there was a new asciidoctor release just the other day. Unsure
>>> if it's related.
>>>
>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com> wrote:
>>>>
>>>> The master branch was converted to use AsciiDoctor. To be honest, I don’t remember why. But after trying to create a new page with it I discovered that AsciiDoctor simply doesn’t work properly with the Maven Site Plugin. See https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As such I believe the site documents in Master need to be converted back to Markdown.
>>>>
>>>> Ralph
>>>
>>>
>>>
>>> --
>>> Matt Sicker <bo...@gmail.com>
>>>
>>
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
>
Re: Asciidoc for site documents
Posted by Matt Sicker <bo...@gmail.com>.
Oh, the maven plugin seems to be a different project than what I was
referencing.
So is this just not possible to fix? I'd really hate to have to go back to xdoc.
On Mon, 29 Apr 2019 at 11:48, Ralph Goers <ra...@dslextreme.com> wrote:
>
> The issue isn’t marked as fixed. The problem I am having is that tables are rendered without borders. This is because asciidoc doesn’t include its css file when building the site because the “normal” asciidoc css would break the site. Asciidoc generates tables with css class names to generate the borders and grids. According to the Jira issue other markup has the same issue.
>
> Ralph
>
> > On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> >
> > I had converted them to asciidoc a while back because it provided more
> > syntactical features than markdown. Many of the files I converted
> > weren't markdown but xdoc.
> >
> > Also, there was a new asciidoctor release just the other day. Unsure
> > if it's related.
> >
> > On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com> wrote:
> >>
> >> The master branch was converted to use AsciiDoctor. To be honest, I don’t remember why. But after trying to create a new page with it I discovered that AsciiDoctor simply doesn’t work properly with the Maven Site Plugin. See https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As such I believe the site documents in Master need to be converted back to Markdown.
> >>
> >> Ralph
> >
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
> >
>
>
--
Matt Sicker <bo...@gmail.com>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
Remember, if you use AsciiDoctor without the site plugin it could work just fine. But yes, the Log4J site has a lot of content. Also, we automatically convert the “manual” section of the site into a pdf book.
Ralph
> On Apr 29, 2019, at 6:36 PM, Remko Popma <re...@gmail.com> wrote:
>
> Yes, I like AsciiDoc. It is much richer than MarkDown.
> The picocli site is much simpler than the Log4j site though.
>
> Looking at
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166, it
> seems that the AsciiDoctor maintainers are taking the issue seriously so
> that gives hope that they will be able to help come up with a solution.
>
>> On Tue, Apr 30, 2019 at 9:04 AM Matt Sicker <bo...@gmail.com> wrote:
>>
>> The CMS seems even harder to use. I think Remko uses Asciidoc for his
>> picocli site.
>>
>> On Mon, Apr 29, 2019 at 18:55, Ralph Goers <ra...@dslextreme.com>
>> wrote:
>>
>>> The alternative would be to not use Maven at all to build the web site,
>> or
>>> at least not the majority of the site. It is possible we could use it to
>>> create the javadoc and a few other things, but there are other
>> alternatives
>>> for many of the site reports. Theoretically, we could just have the
>> whole
>>> site managed by the ASF CMS at https://cms.apache.org/logging/ <
>>> https://cms.apache.org/logging/>, although I am not a fan of that at
>> all.
>>>
>>> Ralph
>>>
>>>> On Apr 29, 2019, at 1:53 PM, Matt Sicker <bo...@gmail.com> wrote:
>>>>
>>>> I haven't exactly seen a better alternative to maven-site-plugin for
>>> maven.
>>>>
>>>> On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com>
>>> wrote:
>>>>>
>>>>> Gary, if you want to contribute patches for AsciiDoctor go for it. I
>>> simply don’t have time. They have basically admitted that when generating
>>> the body AsciiDoctor ignores the Maven Site theme, which is the root of
>> the
>>> problem. I’m not even sure that their proposed solution of using an
>>> AsciiDoctor extension would work since the site plugin uses Doxia which,
>> as
>>> I understand it, is requires Doxia modules to provide unrendered data to
>> it
>>> so that all the HTML is really being generated by Doxia.
>>>>>
>>>>> At this point I am convinced we have to switch back to Markdown or
>> xdoc
>>> where Markdown doesn’t work. Either that or we abandon the site plugin to
>>> generate the Log4j web site.
>>>>>
>>>>> Ralph
>>>>>
>>>>>> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com>
>>> wrote:
>>>>>>
>>>>>> Based on the reply to my comment I just saw on the github page for
>> the
>>>>>> issue, it seems like the developer is willing to help, we just need
>> to
>>>>>> provide PRs or a description of what we'd like to change...
>>>>>>
>>>>>> Gary
>>>>>>
>>>>>> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <
>>> ralph.goers@dslextreme.com>
>>>>>> wrote:
>>>>>>
>>>>>>> The issue isn’t marked as fixed. The problem I am having is that
>>> tables
>>>>>>> are rendered without borders. This is because asciidoc doesn’t
>>> include its
>>>>>>> css file when building the site because the “normal” asciidoc css
>>> would
>>>>>>> break the site. Asciidoc generates tables with css class names to
>>> generate
>>>>>>> the borders and grids. According to the Jira issue other markup has
>>> the
>>>>>>> same issue.
>>>>>>>
>>>>>>> Ralph
>>>>>>>
>>>>>>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>>>>>>
>>>>>>>> I had converted them to asciidoc a while back because it provided
>>> more
>>>>>>>> syntactical features than markdown. Many of the files I converted
>>>>>>>> weren't markdown but xdoc.
>>>>>>>>
>>>>>>>> Also, there was a new asciidoctor release just the other day.
>> Unsure
>>>>>>>> if it's related.
>>>>>>>>
>>>>>>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <
>>> ralph.goers@dslextreme.com>
>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>> The master branch was converted to use AsciiDoctor. To be honest,
>> I
>>>>>>> don’t remember why. But after trying to create a new page with it I
>>>>>>> discovered that AsciiDoctor simply doesn’t work properly with the
>>> Maven
>>>>>>> Site Plugin. See
>>>>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
>> <
>>>>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
>>> .
>>> As
>>>>>>> such I believe the site documents in Master need to be converted
>> back
>>> to
>>>>>>> Markdown.
>>>>>>>>>
>>>>>>>>> Ralph
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Matt Sicker <bo...@gmail.com>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> Matt Sicker <bo...@gmail.com>
>>>>
>>>
>>> --
>> Matt Sicker <bo...@gmail.com>
>>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
Although they seem to take it seriously I doubt that the solution will work seamlessly with the site plugin. Since AsciiDoctor is not interacting with Doxia in the way Doxia modules are supposed to, and since their proposals so far show no indication they plan to address that, I have to assume their plan is to create templates or css that emulate the default maven site theme. However, that would require that they also provide emulation for other maven site themes to be complete. Since we have customized our theme with definitions in the site.css, those would also have to be modified to match whatever AsciiDoctor does.
In short, I am not optimistic of a favorable outcome.
Ralph
> On Apr 29, 2019, at 6:36 PM, Remko Popma <re...@gmail.com> wrote:
>
> Yes, I like AsciiDoc. It is much richer than MarkDown.
> The picocli site is much simpler than the Log4j site though.
>
> Looking at
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166, it
> seems that the AsciiDoctor maintainers are taking the issue seriously so
> that gives hope that they will be able to help come up with a solution.
>
> On Tue, Apr 30, 2019 at 9:04 AM Matt Sicker <bo...@gmail.com> wrote:
>
>> The CMS seems even harder to use. I think Remko uses Asciidoc for his
>> picocli site.
>>
>> On Mon, Apr 29, 2019 at 18:55, Ralph Goers <ra...@dslextreme.com>
>> wrote:
>>
>>> The alternative would be to not use Maven at all to build the web site,
>> or
>>> at least not the majority of the site. It is possible we could use it to
>>> create the javadoc and a few other things, but there are other
>> alternatives
>>> for many of the site reports. Theoretically, we could just have the
>> whole
>>> site managed by the ASF CMS at https://cms.apache.org/logging/ <
>>> https://cms.apache.org/logging/>, although I am not a fan of that at
>> all.
>>>
>>> Ralph
>>>
>>>> On Apr 29, 2019, at 1:53 PM, Matt Sicker <bo...@gmail.com> wrote:
>>>>
>>>> I haven't exactly seen a better alternative to maven-site-plugin for
>>> maven.
>>>>
>>>> On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com>
>>> wrote:
>>>>>
>>>>> Gary, if you want to contribute patches for AsciiDoctor go for it. I
>>> simply don’t have time. They have basically admitted that when generating
>>> the body AsciiDoctor ignores the Maven Site theme, which is the root of
>> the
>>> problem. I’m not even sure that their proposed solution of using an
>>> AsciiDoctor extension would work since the site plugin uses Doxia which,
>> as
>>> I understand it, is requires Doxia modules to provide unrendered data to
>> it
>>> so that all the HTML is really being generated by Doxia.
>>>>>
>>>>> At this point I am convinced we have to switch back to Markdown or
>> xdoc
>>> where Markdown doesn’t work. Either that or we abandon the site plugin to
>>> generate the Log4j web site.
>>>>>
>>>>> Ralph
>>>>>
>>>>>> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com>
>>> wrote:
>>>>>>
>>>>>> Based on the reply to my comment I just saw on the github page for
>> the
>>>>>> issue, it seems like the developer is willing to help, we just need
>> to
>>>>>> provide PRs or a description of what we'd like to change...
>>>>>>
>>>>>> Gary
>>>>>>
>>>>>> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <
>>> ralph.goers@dslextreme.com>
>>>>>> wrote:
>>>>>>
>>>>>>> The issue isn’t marked as fixed. The problem I am having is that
>>> tables
>>>>>>> are rendered without borders. This is because asciidoc doesn’t
>>> include its
>>>>>>> css file when building the site because the “normal” asciidoc css
>>> would
>>>>>>> break the site. Asciidoc generates tables with css class names to
>>> generate
>>>>>>> the borders and grids. According to the Jira issue other markup has
>>> the
>>>>>>> same issue.
>>>>>>>
>>>>>>> Ralph
>>>>>>>
>>>>>>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>>>>>>
>>>>>>>> I had converted them to asciidoc a while back because it provided
>>> more
>>>>>>>> syntactical features than markdown. Many of the files I converted
>>>>>>>> weren't markdown but xdoc.
>>>>>>>>
>>>>>>>> Also, there was a new asciidoctor release just the other day.
>> Unsure
>>>>>>>> if it's related.
>>>>>>>>
>>>>>>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <
>>> ralph.goers@dslextreme.com>
>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>> The master branch was converted to use AsciiDoctor. To be honest,
>> I
>>>>>>> don’t remember why. But after trying to create a new page with it I
>>>>>>> discovered that AsciiDoctor simply doesn’t work properly with the
>>> Maven
>>>>>>> Site Plugin. See
>>>>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
>> <
>>>>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
>>> .
>>> As
>>>>>>> such I believe the site documents in Master need to be converted
>> back
>>> to
>>>>>>> Markdown.
>>>>>>>>>
>>>>>>>>> Ralph
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Matt Sicker <bo...@gmail.com>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> Matt Sicker <bo...@gmail.com>
>>>>
>>>
>>> --
>> Matt Sicker <bo...@gmail.com>
>>
Re: Asciidoc for site documents
Posted by Remko Popma <re...@gmail.com>.
Yes, I like AsciiDoc. It is much richer than MarkDown.
The picocli site is much simpler than the Log4j site though.
Looking at
https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166, it
seems that the AsciiDoctor maintainers are taking the issue seriously so
that gives hope that they will be able to help come up with a solution.
On Tue, Apr 30, 2019 at 9:04 AM Matt Sicker <bo...@gmail.com> wrote:
> The CMS seems even harder to use. I think Remko uses Asciidoc for his
> picocli site.
>
> On Mon, Apr 29, 2019 at 18:55, Ralph Goers <ra...@dslextreme.com>
> wrote:
>
> > The alternative would be to not use Maven at all to build the web site,
> or
> > at least not the majority of the site. It is possible we could use it to
> > create the javadoc and a few other things, but there are other
> alternatives
> > for many of the site reports. Theoretically, we could just have the
> whole
> > site managed by the ASF CMS at https://cms.apache.org/logging/ <
> > https://cms.apache.org/logging/>, although I am not a fan of that at
> all.
> >
> > Ralph
> >
> > > On Apr 29, 2019, at 1:53 PM, Matt Sicker <bo...@gmail.com> wrote:
> > >
> > > I haven't exactly seen a better alternative to maven-site-plugin for
> > maven.
> > >
> > > On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com>
> > wrote:
> > >>
> > >> Gary, if you want to contribute patches for AsciiDoctor go for it. I
> > simply don’t have time. They have basically admitted that when generating
> > the body AsciiDoctor ignores the Maven Site theme, which is the root of
> the
> > problem. I’m not even sure that their proposed solution of using an
> > AsciiDoctor extension would work since the site plugin uses Doxia which,
> as
> > I understand it, is requires Doxia modules to provide unrendered data to
> it
> > so that all the HTML is really being generated by Doxia.
> > >>
> > >> At this point I am convinced we have to switch back to Markdown or
> xdoc
> > where Markdown doesn’t work. Either that or we abandon the site plugin to
> > generate the Log4j web site.
> > >>
> > >> Ralph
> > >>
> > >>> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com>
> > wrote:
> > >>>
> > >>> Based on the reply to my comment I just saw on the github page for
> the
> > >>> issue, it seems like the developer is willing to help, we just need
> to
> > >>> provide PRs or a description of what we'd like to change...
> > >>>
> > >>> Gary
> > >>>
> > >>> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <
> > ralph.goers@dslextreme.com>
> > >>> wrote:
> > >>>
> > >>>> The issue isn’t marked as fixed. The problem I am having is that
> > tables
> > >>>> are rendered without borders. This is because asciidoc doesn’t
> > include its
> > >>>> css file when building the site because the “normal” asciidoc css
> > would
> > >>>> break the site. Asciidoc generates tables with css class names to
> > generate
> > >>>> the borders and grids. According to the Jira issue other markup has
> > the
> > >>>> same issue.
> > >>>>
> > >>>> Ralph
> > >>>>
> > >>>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> > >>>>>
> > >>>>> I had converted them to asciidoc a while back because it provided
> > more
> > >>>>> syntactical features than markdown. Many of the files I converted
> > >>>>> weren't markdown but xdoc.
> > >>>>>
> > >>>>> Also, there was a new asciidoctor release just the other day.
> Unsure
> > >>>>> if it's related.
> > >>>>>
> > >>>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <
> > ralph.goers@dslextreme.com>
> > >>>> wrote:
> > >>>>>>
> > >>>>>> The master branch was converted to use AsciiDoctor. To be honest,
> I
> > >>>> don’t remember why. But after trying to create a new page with it I
> > >>>> discovered that AsciiDoctor simply doesn’t work properly with the
> > Maven
> > >>>> Site Plugin. See
> > >>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
> <
> > >>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166
> >.
> > As
> > >>>> such I believe the site documents in Master need to be converted
> back
> > to
> > >>>> Markdown.
> > >>>>>>
> > >>>>>> Ralph
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> --
> > >>>>> Matt Sicker <bo...@gmail.com>
> > >>>>>
> > >>>>
> > >>>>
> > >>>>
> > >>
> > >>
> > >
> > >
> > > --
> > > Matt Sicker <bo...@gmail.com>
> > >
> >
> > --
> Matt Sicker <bo...@gmail.com>
>
Re: Asciidoc for site documents
Posted by Matt Sicker <bo...@gmail.com>.
The CMS seems even harder to use. I think Remko uses Asciidoc for his
picocli site.
On Mon, Apr 29, 2019 at 18:55, Ralph Goers <ra...@dslextreme.com>
wrote:
> The alternative would be to not use Maven at all to build the web site, or
> at least not the majority of the site. It is possible we could use it to
> create the javadoc and a few other things, but there are other alternatives
> for many of the site reports. Theoretically, we could just have the whole
> site managed by the ASF CMS at https://cms.apache.org/logging/ <
> https://cms.apache.org/logging/>, although I am not a fan of that at all.
>
> Ralph
>
> > On Apr 29, 2019, at 1:53 PM, Matt Sicker <bo...@gmail.com> wrote:
> >
> > I haven't exactly seen a better alternative to maven-site-plugin for
> maven.
> >
> > On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com>
> wrote:
> >>
> >> Gary, if you want to contribute patches for AsciiDoctor go for it. I
> simply don’t have time. They have basically admitted that when generating
> the body AsciiDoctor ignores the Maven Site theme, which is the root of the
> problem. I’m not even sure that their proposed solution of using an
> AsciiDoctor extension would work since the site plugin uses Doxia which, as
> I understand it, is requires Doxia modules to provide unrendered data to it
> so that all the HTML is really being generated by Doxia.
> >>
> >> At this point I am convinced we have to switch back to Markdown or xdoc
> where Markdown doesn’t work. Either that or we abandon the site plugin to
> generate the Log4j web site.
> >>
> >> Ralph
> >>
> >>> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com>
> wrote:
> >>>
> >>> Based on the reply to my comment I just saw on the github page for the
> >>> issue, it seems like the developer is willing to help, we just need to
> >>> provide PRs or a description of what we'd like to change...
> >>>
> >>> Gary
> >>>
> >>> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <
> ralph.goers@dslextreme.com>
> >>> wrote:
> >>>
> >>>> The issue isn’t marked as fixed. The problem I am having is that
> tables
> >>>> are rendered without borders. This is because asciidoc doesn’t
> include its
> >>>> css file when building the site because the “normal” asciidoc css
> would
> >>>> break the site. Asciidoc generates tables with css class names to
> generate
> >>>> the borders and grids. According to the Jira issue other markup has
> the
> >>>> same issue.
> >>>>
> >>>> Ralph
> >>>>
> >>>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> >>>>>
> >>>>> I had converted them to asciidoc a while back because it provided
> more
> >>>>> syntactical features than markdown. Many of the files I converted
> >>>>> weren't markdown but xdoc.
> >>>>>
> >>>>> Also, there was a new asciidoctor release just the other day. Unsure
> >>>>> if it's related.
> >>>>>
> >>>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <
> ralph.goers@dslextreme.com>
> >>>> wrote:
> >>>>>>
> >>>>>> The master branch was converted to use AsciiDoctor. To be honest, I
> >>>> don’t remember why. But after trying to create a new page with it I
> >>>> discovered that AsciiDoctor simply doesn’t work properly with the
> Maven
> >>>> Site Plugin. See
> >>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
> >>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>.
> As
> >>>> such I believe the site documents in Master need to be converted back
> to
> >>>> Markdown.
> >>>>>>
> >>>>>> Ralph
> >>>>>
> >>>>>
> >>>>>
> >>>>> --
> >>>>> Matt Sicker <bo...@gmail.com>
> >>>>>
> >>>>
> >>>>
> >>>>
> >>
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
> >
>
> --
Matt Sicker <bo...@gmail.com>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
The alternative would be to not use Maven at all to build the web site, or at least not the majority of the site. It is possible we could use it to create the javadoc and a few other things, but there are other alternatives for many of the site reports. Theoretically, we could just have the whole site managed by the ASF CMS at https://cms.apache.org/logging/ <https://cms.apache.org/logging/>, although I am not a fan of that at all.
Ralph
> On Apr 29, 2019, at 1:53 PM, Matt Sicker <bo...@gmail.com> wrote:
>
> I haven't exactly seen a better alternative to maven-site-plugin for maven.
>
> On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com> wrote:
>>
>> Gary, if you want to contribute patches for AsciiDoctor go for it. I simply don’t have time. They have basically admitted that when generating the body AsciiDoctor ignores the Maven Site theme, which is the root of the problem. I’m not even sure that their proposed solution of using an AsciiDoctor extension would work since the site plugin uses Doxia which, as I understand it, is requires Doxia modules to provide unrendered data to it so that all the HTML is really being generated by Doxia.
>>
>> At this point I am convinced we have to switch back to Markdown or xdoc where Markdown doesn’t work. Either that or we abandon the site plugin to generate the Log4j web site.
>>
>> Ralph
>>
>>> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com> wrote:
>>>
>>> Based on the reply to my comment I just saw on the github page for the
>>> issue, it seems like the developer is willing to help, we just need to
>>> provide PRs or a description of what we'd like to change...
>>>
>>> Gary
>>>
>>> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <ra...@dslextreme.com>
>>> wrote:
>>>
>>>> The issue isn’t marked as fixed. The problem I am having is that tables
>>>> are rendered without borders. This is because asciidoc doesn’t include its
>>>> css file when building the site because the “normal” asciidoc css would
>>>> break the site. Asciidoc generates tables with css class names to generate
>>>> the borders and grids. According to the Jira issue other markup has the
>>>> same issue.
>>>>
>>>> Ralph
>>>>
>>>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>>>
>>>>> I had converted them to asciidoc a while back because it provided more
>>>>> syntactical features than markdown. Many of the files I converted
>>>>> weren't markdown but xdoc.
>>>>>
>>>>> Also, there was a new asciidoctor release just the other day. Unsure
>>>>> if it's related.
>>>>>
>>>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
>>>> wrote:
>>>>>>
>>>>>> The master branch was converted to use AsciiDoctor. To be honest, I
>>>> don’t remember why. But after trying to create a new page with it I
>>>> discovered that AsciiDoctor simply doesn’t work properly with the Maven
>>>> Site Plugin. See
>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
>>>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
>>>> such I believe the site documents in Master need to be converted back to
>>>> Markdown.
>>>>>>
>>>>>> Ralph
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Matt Sicker <bo...@gmail.com>
>>>>>
>>>>
>>>>
>>>>
>>
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
>
Re: Asciidoc for site documents
Posted by Matt Sicker <bo...@gmail.com>.
I haven't exactly seen a better alternative to maven-site-plugin for maven.
On Mon, 29 Apr 2019 at 15:36, Ralph Goers <ra...@dslextreme.com> wrote:
>
> Gary, if you want to contribute patches for AsciiDoctor go for it. I simply don’t have time. They have basically admitted that when generating the body AsciiDoctor ignores the Maven Site theme, which is the root of the problem. I’m not even sure that their proposed solution of using an AsciiDoctor extension would work since the site plugin uses Doxia which, as I understand it, is requires Doxia modules to provide unrendered data to it so that all the HTML is really being generated by Doxia.
>
> At this point I am convinced we have to switch back to Markdown or xdoc where Markdown doesn’t work. Either that or we abandon the site plugin to generate the Log4j web site.
>
> Ralph
>
> > On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com> wrote:
> >
> > Based on the reply to my comment I just saw on the github page for the
> > issue, it seems like the developer is willing to help, we just need to
> > provide PRs or a description of what we'd like to change...
> >
> > Gary
> >
> > On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <ra...@dslextreme.com>
> > wrote:
> >
> >> The issue isn’t marked as fixed. The problem I am having is that tables
> >> are rendered without borders. This is because asciidoc doesn’t include its
> >> css file when building the site because the “normal” asciidoc css would
> >> break the site. Asciidoc generates tables with css class names to generate
> >> the borders and grids. According to the Jira issue other markup has the
> >> same issue.
> >>
> >> Ralph
> >>
> >>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> >>>
> >>> I had converted them to asciidoc a while back because it provided more
> >>> syntactical features than markdown. Many of the files I converted
> >>> weren't markdown but xdoc.
> >>>
> >>> Also, there was a new asciidoctor release just the other day. Unsure
> >>> if it's related.
> >>>
> >>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
> >> wrote:
> >>>>
> >>>> The master branch was converted to use AsciiDoctor. To be honest, I
> >> don’t remember why. But after trying to create a new page with it I
> >> discovered that AsciiDoctor simply doesn’t work properly with the Maven
> >> Site Plugin. See
> >> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
> >> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
> >> such I believe the site documents in Master need to be converted back to
> >> Markdown.
> >>>>
> >>>> Ralph
> >>>
> >>>
> >>>
> >>> --
> >>> Matt Sicker <bo...@gmail.com>
> >>>
> >>
> >>
> >>
>
>
--
Matt Sicker <bo...@gmail.com>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
Gary, if you want to contribute patches for AsciiDoctor go for it. I simply don’t have time. They have basically admitted that when generating the body AsciiDoctor ignores the Maven Site theme, which is the root of the problem. I’m not even sure that their proposed solution of using an AsciiDoctor extension would work since the site plugin uses Doxia which, as I understand it, is requires Doxia modules to provide unrendered data to it so that all the HTML is really being generated by Doxia.
At this point I am convinced we have to switch back to Markdown or xdoc where Markdown doesn’t work. Either that or we abandon the site plugin to generate the Log4j web site.
Ralph
> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com> wrote:
>
> Based on the reply to my comment I just saw on the github page for the
> issue, it seems like the developer is willing to help, we just need to
> provide PRs or a description of what we'd like to change...
>
> Gary
>
> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <ra...@dslextreme.com>
> wrote:
>
>> The issue isn’t marked as fixed. The problem I am having is that tables
>> are rendered without borders. This is because asciidoc doesn’t include its
>> css file when building the site because the “normal” asciidoc css would
>> break the site. Asciidoc generates tables with css class names to generate
>> the borders and grids. According to the Jira issue other markup has the
>> same issue.
>>
>> Ralph
>>
>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>
>>> I had converted them to asciidoc a while back because it provided more
>>> syntactical features than markdown. Many of the files I converted
>>> weren't markdown but xdoc.
>>>
>>> Also, there was a new asciidoctor release just the other day. Unsure
>>> if it's related.
>>>
>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
>> wrote:
>>>>
>>>> The master branch was converted to use AsciiDoctor. To be honest, I
>> don’t remember why. But after trying to create a new page with it I
>> discovered that AsciiDoctor simply doesn’t work properly with the Maven
>> Site Plugin. See
>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
>> such I believe the site documents in Master need to be converted back to
>> Markdown.
>>>>
>>>> Ralph
>>>
>>>
>>>
>>> --
>>> Matt Sicker <bo...@gmail.com>
>>>
>>
>>
>>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
For me, it would be easier to convert the pages to Markdown then write the css to make asciidoc work. I dislike working with css.
As for the description, I provided something but it isn’t particularly specific. I would have expected that if they were going to provide support for the Maven Site Plugin that they would have supplied a css file that makes the generated pages render properly. Without that the Maven Site Plugin isn’t really supported.
Ralph
> On Apr 29, 2019, at 11:25 AM, Gary Gregory <ga...@gmail.com> wrote:
>
> Based on the reply to my comment I just saw on the github page for the
> issue, it seems like the developer is willing to help, we just need to
> provide PRs or a description of what we'd like to change...
>
> Gary
>
> On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <ra...@dslextreme.com>
> wrote:
>
>> The issue isn’t marked as fixed. The problem I am having is that tables
>> are rendered without borders. This is because asciidoc doesn’t include its
>> css file when building the site because the “normal” asciidoc css would
>> break the site. Asciidoc generates tables with css class names to generate
>> the borders and grids. According to the Jira issue other markup has the
>> same issue.
>>
>> Ralph
>>
>>> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>>>
>>> I had converted them to asciidoc a while back because it provided more
>>> syntactical features than markdown. Many of the files I converted
>>> weren't markdown but xdoc.
>>>
>>> Also, there was a new asciidoctor release just the other day. Unsure
>>> if it's related.
>>>
>>> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
>> wrote:
>>>>
>>>> The master branch was converted to use AsciiDoctor. To be honest, I
>> don’t remember why. But after trying to create a new page with it I
>> discovered that AsciiDoctor simply doesn’t work properly with the Maven
>> Site Plugin. See
>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
>> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
>> such I believe the site documents in Master need to be converted back to
>> Markdown.
>>>>
>>>> Ralph
>>>
>>>
>>>
>>> --
>>> Matt Sicker <bo...@gmail.com>
>>>
>>
>>
>>
Re: Asciidoc for site documents
Posted by Gary Gregory <ga...@gmail.com>.
Based on the reply to my comment I just saw on the github page for the
issue, it seems like the developer is willing to help, we just need to
provide PRs or a description of what we'd like to change...
Gary
On Mon, Apr 29, 2019 at 12:48 PM Ralph Goers <ra...@dslextreme.com>
wrote:
> The issue isn’t marked as fixed. The problem I am having is that tables
> are rendered without borders. This is because asciidoc doesn’t include its
> css file when building the site because the “normal” asciidoc css would
> break the site. Asciidoc generates tables with css class names to generate
> the borders and grids. According to the Jira issue other markup has the
> same issue.
>
> Ralph
>
> > On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
> >
> > I had converted them to asciidoc a while back because it provided more
> > syntactical features than markdown. Many of the files I converted
> > weren't markdown but xdoc.
> >
> > Also, there was a new asciidoctor release just the other day. Unsure
> > if it's related.
> >
> > On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com>
> wrote:
> >>
> >> The master branch was converted to use AsciiDoctor. To be honest, I
> don’t remember why. But after trying to create a new page with it I
> discovered that AsciiDoctor simply doesn’t work properly with the Maven
> Site Plugin. See
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <
> https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As
> such I believe the site documents in Master need to be converted back to
> Markdown.
> >>
> >> Ralph
> >
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
> >
>
>
>
Re: Asciidoc for site documents
Posted by Ralph Goers <ra...@dslextreme.com>.
The issue isn’t marked as fixed. The problem I am having is that tables are rendered without borders. This is because asciidoc doesn’t include its css file when building the site because the “normal” asciidoc css would break the site. Asciidoc generates tables with css class names to generate the borders and grids. According to the Jira issue other markup has the same issue.
Ralph
> On Apr 29, 2019, at 8:50 AM, Matt Sicker <bo...@gmail.com> wrote:
>
> I had converted them to asciidoc a while back because it provided more
> syntactical features than markdown. Many of the files I converted
> weren't markdown but xdoc.
>
> Also, there was a new asciidoctor release just the other day. Unsure
> if it's related.
>
> On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com> wrote:
>>
>> The master branch was converted to use AsciiDoctor. To be honest, I don’t remember why. But after trying to create a new page with it I discovered that AsciiDoctor simply doesn’t work properly with the Maven Site Plugin. See https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As such I believe the site documents in Master need to be converted back to Markdown.
>>
>> Ralph
>
>
>
> --
> Matt Sicker <bo...@gmail.com>
>
Re: Asciidoc for site documents
Posted by Matt Sicker <bo...@gmail.com>.
I had converted them to asciidoc a while back because it provided more
syntactical features than markdown. Many of the files I converted
weren't markdown but xdoc.
Also, there was a new asciidoctor release just the other day. Unsure
if it's related.
On Mon, 29 Apr 2019 at 10:34, Ralph Goers <ra...@dslextreme.com> wrote:
>
> The master branch was converted to use AsciiDoctor. To be honest, I don’t remember why. But after trying to create a new page with it I discovered that AsciiDoctor simply doesn’t work properly with the Maven Site Plugin. See https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166 <https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/166>. As such I believe the site documents in Master need to be converted back to Markdown.
>
> Ralph
--
Matt Sicker <bo...@gmail.com>