You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Artem Krosheninnikov <ar...@gmail.com> on 2021/02/01 10:18:56 UTC
APT vs Markdown formats for site docs
Hello there, whilst looking at some docs in maven-enforcer-plugin, I found
.apt.vm format not very convenient and developer-friendly, especially for a
newcomer.
Is it a standard for all maven plugins or were there any discussions on
using another format? I see that maven-parent-34 has several modules for
other formats like markdown or fml.
--
Sincerely yours,
Krosheninnikov Artem.
Re: APT vs Markdown formats for site docs
Posted by David Jencks <da...@gmail.com>.
Asciidoctor Maven Tools is the more supported way of using Asciidoctor from maven, either directly or through Doxia.
https://docs.asciidoctor.org/maven-tools/latest/ <https://docs.asciidoctor.org/maven-tools/latest/> (docs)
https://github.com/asciidoctor/asciidoctor-maven-plugin <https://github.com/asciidoctor/asciidoctor-maven-plugin> (GitHub)
AsciiDoc support in Jekyll using jekyll-asciidoc is quite good, and GitHub is rather jekyll-friendly. You do have to build the site yourself, GitHub’s built in AsciiDoc rendering is somewhat crippled for incomprehensible reasons. I’m now the primary maintainer of jekyll-asciidoc so issues may receive prompt attention.
I think Antora is incomparable, and would certainly produce fabulous results properly used for maven documentation, but with the investment in Doxia organization that may be a better choice.
David Jencks
> On Feb 1, 2021, at 3:34 AM, Andres Almiray <aa...@gmail.com> wrote:
>
> FWIW Doxia supports Asciidoc pretty well. You just have to add an extra
> dependency for it to find Asciidoctorj, as demonstrated at
>
> https://github.com/kordamp/pomchecker/blob/master/pom.xml#L200-L227
>
> You can mix all kind of supported formats if needed. Or use only asciidoc,
> the choice is yours ;-)
>
> Cheers,
> Andres
>
> -------------------------------------------
> Java Champion; Groovy Enthusiast
> http://andresalmiray.com
> http://www.linkedin.com/in/aalmiray
> --
> What goes up, must come down. Ask any system administrator.
> There are 10 types of people in the world: Those who understand binary, and
> those who don't.
> To understand recursion, we must first understand recursion.
>
>
> On Mon, Feb 1, 2021 at 12:29 PM Artem Krosheninnikov <
> artem.krosheninnikov@gmail.com> wrote:
>
>> I agree that there are several implementations thus it may be not a good
>> choice.
>>
>> FML looks very ancient from my point of view but asciidoc is more or less a
>> standard format in docops community.
>>
>> It's not that everything should be immediately converted to another format,
>> just trying to understand whether apt is convenient for all and is a
>> standard for all maven projects.
>>
>> пн, 1 февр. 2021 г. в 13:32, Benjamin Marwell <bm...@apache.org>:
>>
>>> Markdown is not a "standard" or "standardized".
>>> Even worse, different implementations have different feature sets.
>>> Thus my -1 for md.
>>>
>>> But another format might be feasible, really. fml looks verbose.
>>>
>>> Asciidoc might be a sane choice here. It was specially designed for
>>> technical documentation and
>>> has neat features which are handy for exactly those cases.
>>> Besides, it is also supported on GitHub.
>>>
>>> ---
>>>
>>> A quick check revealed there was no such discussion in the last 12
>>> months on the mailing list.
>>>
>>> - Ben
>>>
>>>
>>
>> --
>> Sincerely yours,
>> Krosheninnikov Artem.
>>
Re: APT vs Markdown formats for site docs
Posted by Andres Almiray <aa...@gmail.com>.
FWIW Doxia supports Asciidoc pretty well. You just have to add an extra
dependency for it to find Asciidoctorj, as demonstrated at
https://github.com/kordamp/pomchecker/blob/master/pom.xml#L200-L227
You can mix all kind of supported formats if needed. Or use only asciidoc,
the choice is yours ;-)
Cheers,
Andres
-------------------------------------------
Java Champion; Groovy Enthusiast
http://andresalmiray.com
http://www.linkedin.com/in/aalmiray
--
What goes up, must come down. Ask any system administrator.
There are 10 types of people in the world: Those who understand binary, and
those who don't.
To understand recursion, we must first understand recursion.
On Mon, Feb 1, 2021 at 12:29 PM Artem Krosheninnikov <
artem.krosheninnikov@gmail.com> wrote:
> I agree that there are several implementations thus it may be not a good
> choice.
>
> FML looks very ancient from my point of view but asciidoc is more or less a
> standard format in docops community.
>
> It's not that everything should be immediately converted to another format,
> just trying to understand whether apt is convenient for all and is a
> standard for all maven projects.
>
> пн, 1 февр. 2021 г. в 13:32, Benjamin Marwell <bm...@apache.org>:
>
> > Markdown is not a "standard" or "standardized".
> > Even worse, different implementations have different feature sets.
> > Thus my -1 for md.
> >
> > But another format might be feasible, really. fml looks verbose.
> >
> > Asciidoc might be a sane choice here. It was specially designed for
> > technical documentation and
> > has neat features which are handy for exactly those cases.
> > Besides, it is also supported on GitHub.
> >
> > ---
> >
> > A quick check revealed there was no such discussion in the last 12
> > months on the mailing list.
> >
> > - Ben
> >
> >
>
> --
> Sincerely yours,
> Krosheninnikov Artem.
>
Re: APT vs Markdown formats for site docs
Posted by Artem Krosheninnikov <ar...@gmail.com>.
I agree that there are several implementations thus it may be not a good
choice.
FML looks very ancient from my point of view but asciidoc is more or less a
standard format in docops community.
It's not that everything should be immediately converted to another format,
just trying to understand whether apt is convenient for all and is a
standard for all maven projects.
пн, 1 февр. 2021 г. в 13:32, Benjamin Marwell <bm...@apache.org>:
> Markdown is not a "standard" or "standardized".
> Even worse, different implementations have different feature sets.
> Thus my -1 for md.
>
> But another format might be feasible, really. fml looks verbose.
>
> Asciidoc might be a sane choice here. It was specially designed for
> technical documentation and
> has neat features which are handy for exactly those cases.
> Besides, it is also supported on GitHub.
>
> ---
>
> A quick check revealed there was no such discussion in the last 12
> months on the mailing list.
>
> - Ben
>
>
--
Sincerely yours,
Krosheninnikov Artem.
Re: APT vs Markdown formats for site docs
Posted by Paul Hammant <pa...@hammant.org.INVALID>.
https://github.com/asciidoctor/jekyll-asciidoc-quickstart .. find “GitHub
pages” in page.
My blog used to be in textile - overnight GHP dropped support so I had to
batch convert hundreds to markdown. That was years back. I might have
preferred asciidoc, and if it is supported that’s great, but I don’t think
it is.
> Asciidoc might be a sane choice here. It was specially designed for
> technical documentation and
> has neat features which are handy for exactly those cases.
> Besides, it is also supported on GitHub.
>
> ---
>
Re: APT vs Markdown formats for site docs
Posted by Benjamin Marwell <bm...@apache.org>.
Markdown is not a "standard" or "standardized".
Even worse, different implementations have different feature sets.
Thus my -1 for md.
But another format might be feasible, really. fml looks verbose.
Asciidoc might be a sane choice here. It was specially designed for
technical documentation and
has neat features which are handy for exactly those cases.
Besides, it is also supported on GitHub.
---
A quick check revealed there was no such discussion in the last 12
months on the mailing list.
- Ben
Am Mo., 1. Feb. 2021 um 11:19 Uhr schrieb Artem Krosheninnikov
<ar...@gmail.com>:
>
> Hello there, whilst looking at some docs in maven-enforcer-plugin, I found
> .apt.vm format not very convenient and developer-friendly, especially for a
> newcomer.
>
> Is it a standard for all maven plugins or were there any discussions on
> using another format? I see that maven-parent-34 has several modules for
> other formats like markdown or fml.
> --
> Sincerely yours,
> Krosheninnikov Artem.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: APT vs Markdown formats for site docs
Posted by David Jencks <da...@gmail.com>.
I looked for a few minutes at https://github.com/apache/logging-log4j2 and found 3 or 4 markdown pages under site that didn’t appear to have anything that would be hard to write in AsciiDoc.
The root level pages such as README.md, if written in (limited) AsciiDoc, will display nicely at GitHub.
David Jencks
> On Feb 1, 2021, at 7:24 AM, Ralph Goers <ra...@dslextreme.com> wrote:
>
> Log4j didn’t switch everything. A couple pages had to be left as Markdown for things AsciiDoc doesn’t support, although at the moment I don’t remember what those things were at the moment.
>
> Ralph
>
>> On Feb 1, 2021, at 6:30 AM, Gary Gregory <ga...@gmail.com> wrote:
>>
>> FYI, over at Log4j, we switched to Asciidoc.
>>
>> Gary
>>
>> On Mon, Feb 1, 2021, 05:19 Artem Krosheninnikov <
>> artem.krosheninnikov@gmail.com> wrote:
>>
>>> Hello there, whilst looking at some docs in maven-enforcer-plugin, I found
>>> .apt.vm format not very convenient and developer-friendly, especially for a
>>> newcomer.
>>>
>>> Is it a standard for all maven plugins or were there any discussions on
>>> using another format? I see that maven-parent-34 has several modules for
>>> other formats like markdown or fml.
>>> --
>>> Sincerely yours,
>>> Krosheninnikov Artem.
>>>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: APT vs Markdown formats for site docs
Posted by Ralph Goers <ra...@dslextreme.com>.
Log4j didn’t switch everything. A couple pages had to be left as Markdown for things AsciiDoc doesn’t support, although at the moment I don’t remember what those things were at the moment.
Ralph
> On Feb 1, 2021, at 6:30 AM, Gary Gregory <ga...@gmail.com> wrote:
>
> FYI, over at Log4j, we switched to Asciidoc.
>
> Gary
>
> On Mon, Feb 1, 2021, 05:19 Artem Krosheninnikov <
> artem.krosheninnikov@gmail.com> wrote:
>
>> Hello there, whilst looking at some docs in maven-enforcer-plugin, I found
>> .apt.vm format not very convenient and developer-friendly, especially for a
>> newcomer.
>>
>> Is it a standard for all maven plugins or were there any discussions on
>> using another format? I see that maven-parent-34 has several modules for
>> other formats like markdown or fml.
>> --
>> Sincerely yours,
>> Krosheninnikov Artem.
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: APT vs Markdown formats for site docs
Posted by Gary Gregory <ga...@gmail.com>.
FYI, over at Log4j, we switched to Asciidoc.
Gary
On Mon, Feb 1, 2021, 05:19 Artem Krosheninnikov <
artem.krosheninnikov@gmail.com> wrote:
> Hello there, whilst looking at some docs in maven-enforcer-plugin, I found
> .apt.vm format not very convenient and developer-friendly, especially for a
> newcomer.
>
> Is it a standard for all maven plugins or were there any discussions on
> using another format? I see that maven-parent-34 has several modules for
> other formats like markdown or fml.
> --
> Sincerely yours,
> Krosheninnikov Artem.
>