APT vs Markdown formats for site docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

APT vs Markdown formats for site docs

Artem Krosheninnikov
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.
Reply | Threaded
Open this post in threaded view
|

Re: APT vs Markdown formats for site docs

Paul Hammant-3
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.
>
> ---
>
Reply | Threaded
Open this post in threaded view
|

Re: APT vs Markdown formats for site docs

Andres Almiray
In reply to this post by Artem Krosheninnikov
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 <
[hidden email]> 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 <[hidden email]>:
>
> > 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.
>
Reply | Threaded
Open this post in threaded view
|

Re: APT vs Markdown formats for site docs

Ralph Goers
In reply to this post by Artem Krosheninnikov
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 <[hidden email]> wrote:
>
> FYI, over at Log4j, we switched to Asciidoc.
>
> Gary
>
> On Mon, Feb 1, 2021, 05:19 Artem Krosheninnikov <
> [hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: APT vs Markdown formats for site docs

David Jencks-4
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 <[hidden email]> 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 <[hidden email]> wrote:
>>
>> FYI, over at Log4j, we switched to Asciidoc.
>>
>> Gary
>>
>> On Mon, Feb 1, 2021, 05:19 Artem Krosheninnikov <
>> [hidden email]> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]