[discussion] AsciiDoc instead of Markdown?

[Jörg Hohwiller]

Hi there,

I migrated my personal OSS projects entirely from Markdown to AsciiDoc. AsciiDoc is way superior to Markdown.
For some projects I do create entire PDF books as documentation from Github Wikis with hundreds of pages using asciidoctor-maven-plugin.

Therefore I just wanted to ask if other users think the same and would welcome to use *.adoc in advance to *.md on github (e.g. Readme.md, Contributing.md as well as in wikis).
Otherwise I am fine with staying as is.

Best regards
  Jörg

[Baptiste Mathus]

I'm totally fine with this. I think Markdown becomes unusable/cumbersome for anything more than a small README.

--
You received this message because you are subscribed to the Google Groups "mojohaus-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mojohaus-dev+unsubscribe@googlegroups.com.
To post to this group, send email to mojoha...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/mojohaus-dev/15dc6352-bd37-4361-b61e-1a4bab3a542a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Hervé Boutemy]

can you give us a pointer to your projects, to see what a complete migration

looks like?

+1 to add asciidoc to other formats and make a test

Regards,

Hervé

To view this discussion on the web visit https://groups.google.com/d/msgid/mojohaus-dev/CANWgJS7proNAQvScAhn-s76upoX3fECgUg5BqQXDZR6_cV87LQ%40mail.gmail.com.

[Jörg Hohwiller]

Hi Hervé,

README and CONTRIBUTING are easy. For an example look here:
https://github.com/m-m-m/util

For a fairly bigger use of AsciiDoc on github where I was involved see:
https://github.com/oasp/oasp4j/wiki/OASP4J
https://oasp.github.io/assets/PDF/OASP4J.pdf
If interested see also here:
https://github.com/oasp/oasp-docgen/wiki
(build has meanwhile replaced with asciidoctor-maven-plugin making all the XSLT and other stuff obsolete and the build simple and portable via parent POM).
All free OSS for share and reuse.

Cheers
  Jörg

Am Montag, 25. September 2017 22:49:52 UTC+2 schrieb Hervé Boutemy:

can you give us a pointer to your projects, to see what a complete migration

looks like?

+1 to add asciidoc to other formats and make a test

Regards,

Hervé

2017-09-24 23:00 GMT+02:00 Baptiste Mathus <m...@batmat.net>:

I'm totally fine with this. I think Markdown becomes unusable/cumbersome for anything more than a small README.

2017-09-21 18:50 GMT+02:00 'Jörg Hohwiller' via mojohaus-dev <mojoha...@googlegroups.com>:

Hi there,

I migrated my personal OSS projects entirely from Markdown to AsciiDoc. AsciiDoc is way superior to Markdown.
For some projects I do create entire PDF books as documentation from Github Wikis with hundreds of pages using asciidoctor-maven-plugin.

Therefore I just wanted to ask if other users think the same and would welcome to use *.adoc in advance to *.md on github (e.g. Readme.md, Contributing.md as well as in wikis).
Otherwise I am fine with staying as is.

Best regards
  Jörg

--
You received this message because you are subscribed to the Google Groups "mojohaus-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to mojohaus-dev...@googlegroups.com.

To post to this group, send email to mojoha...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/mojohaus-dev/15dc6352-bd37-4361-b61e-1a4bab3a542a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "mojohaus-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to mojohaus-dev...@googlegroups.com.

To post to this group, send email to mojoha...@googlegroups.com.

[Mirko Friedenhagen]

+1 from me as well for ASCIIDOC, I really like the Maven plugin.
Regards Mirko
--
http://illegalstateexception.blogspot.com/
https://github.com/mfriedenhagen/
https://bitbucket.org/mfriedenhagen/

> https://groups.google.com/d/msgid/mojohaus-dev/a3bdeb12-ab82-4582-80b4-114b44024128%40googlegroups.com.

[Jochen Wiedmann]

On Thu, Sep 21, 2017 at 6:50 PM, 'Jörg Hohwiller' via mojohaus-dev
<mojoha...@googlegroups.com> wrote:

> Therefore I just wanted to ask if other users think the same and would
> welcome to use *.adoc in advance to *.md on github (e.g. Readme.md,
> Contributing.md as well as in wikis).
> Otherwise I am fine with staying as is.

Question: Does Doxia support adoc?

jochen


--
The next time you hear: "Don't reinvent the wheel!"

http://www.keystonedevelopment.co.uk/wp-content/uploads/2014/10/evolution-of-the-wheel-300x85.jpg

[Manfred Moser]

Well the Maven plugin works with asciidoc... I use it for the complete site of the Android Maven Plugin

http://simpligility.github.io/android-maven-plugin/

And github supports it for readme and such as well.

And if you want to do a full site and esp towards pdf output it is generally better (a bit anyway). But for most simple use cases markdown is just fine and better known.Tooling is maybe a bit more common for markdown but there is plenty for asciidoc around as well.

So my vote is +- 0 ;-) 

manfred

--
You received this message because you are subscribed to the Google Groups "mojohaus-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to mojohaus-dev+unsubscribe@googlegroups.com.

To post to this group, send email to mojoha...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/mojohaus-dev/CAF8HOZL10R4tyD3R0SRYqa05rd0QGR4uLHRnt8%3Dc7H68kLKudg%40mail.gmail.com.

[Hervé Boutemy]

Thank you Manfred: this is exactly the type of example I wanted to see.

Good news, it can be used as an additional source markup format to maven-site-plugin (see http://asciidoctor.org/docs/asciidoctor-maven-plugin/#maven-site-integration for reference documentation on this scenario)

So, yes, the maven plugin adds asciidoc support to Doxia (see https://github.com/asciidoctor/asciidoctor-maven-plugin/tree/master/src/main/java/org/asciidoctor/maven/site for the integration code)

and full +1 for me if anybody wants to add some pages in src/site/asciidoc: we'll see later if we really migrate existing content from other source formats.

After some successful test in on Mojohaus plugin, we could add the configuration of this new format in parent pom.

I think I'll open a PR to improve the explanations about this scenario: in this scenario, the "asciidoctor-maven-plugin" artifact is not used as a Maven plugin but as a Doxia module. That's where the explanation is confusing for some people who better know the internals of maven-site-plugin vs Doxia... :)

Regards,

Hervé

To view this discussion on the web visit https://groups.google.com/d/msgid/mojohaus-dev/CABffhO4no9r%3D%3DXh0ei%3DkJHtN0%2B79R%2BcSjkK0-%3DGd-cosCr%3Dobw%40mail.gmail.com.

[Hervé Boutemy]

first PR is online: https://github.com/asciidoctor/asciidoctor-maven-plugin
explanations about the 2 ways of using asciidoctor (as an independant plugin or as a Maven site integration) should be easier to understand
feedback welcome

I'll see how to have the changes also in http://asciidoctor.org/docs/asciidoctor-maven-plugin/


Then: if anybody want to add asciidoc as additionnal Markup language in MojoHaus parent pom, or any plugin, I think you can do it.

Regards,

Hervé