md or adoc?

2,652 views
Skip to first unread message

Kevin Sutter

unread,
Jun 7, 2017, 5:06:47 PM6/7/17
to MicroProfile
Have we decided on whether we're using md or adoc for our common files (README, CONTRIBUTING, etc)?  Our evolution-process seems to be using md.  But, I noticed that many of our component repos are using adoc...  Should we focus on just one?  Or, doesn't anybody care?

This came up because I was just initializing my new repo for the "bill of materials"...  By default, Eclipse uses md (README.md), which is consistent with the component proposal I just completed for MP 1.1.  But, I noticed that Config is using adoc (README.adoc).

Thanks, Kevin

Ken Finnigan

unread,
Jun 7, 2017, 5:09:51 PM6/7/17
to MicroProfile
I know I prefer adoc because of its features.

But I don't know if we need to "pick one", though it would make it easier for contributions if we were consistent.

Ken

David Blevins

unread,
Jun 7, 2017, 5:33:18 PM6/7/17
to MicroProfile
+1 for Asciidoc

It can do everything Markdown can, plus a bit more.  There’s also a great toolchain for creating PDFs that Dan Allen maintains.  The MicroProfile.io website content is also in Asciidoc, so anything we create is instantly publishable there (regardless of what repo it lives in, the code that builds the site can pull and publish asciidoc from any git repo).

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/120f7910-9555-40f5-bf85-3cd35e197164%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Kevin Sutter

unread,
Jun 7, 2017, 5:36:42 PM6/7/17
to David Blevins, MicroProfile, Ondrej Mihályi, Heiko Braun
I'm not an expert with either one, so I don't really have a preference.  But, I do think that consistency would be good for our own sanity as well as future contributions.

Let's leave this conversation going for a bit, but it's leaning towards adoc...  Ondrej or Heiko?  Since the evolution-process is slanted towards md...

--  Kevin

On Wed, Jun 7, 2017 at 4:33 PM, David Blevins <dble...@tomitribe.com> wrote:
+1 for Asciidoc

It can do everything Markdown can, plus a bit more.  There’s also a great toolchain for creating PDFs that Dan Allen maintains.  The MicroProfile.io website content is also in Asciidoc, so anything we create is instantly publishable there (regardless of what repo it lives in, the code that builds the site can pull and publish asciidoc from any git repo).

On Jun 7, 2017, at 2:09 PM, Ken Finnigan <k...@kenfinnigan.me> wrote:

I know I prefer adoc because of its features.

But I don't know if we need to "pick one", though it would make it easier for contributions if we were consistent.

Ken

On Wednesday, June 7, 2017 at 5:06:47 PM UTC-4, Kevin Sutter wrote:
Have we decided on whether we're using md or adoc for our common files (README, CONTRIBUTING, etc)?  Our evolution-process seems to be using md.  But, I noticed that many of our component repos are using adoc...  Should we focus on just one?  Or, doesn't anybody care?

This came up because I was just initializing my new repo for the "bill of materials"...  By default, Eclipse uses md (README.md), which is consistent with the component proposal I just completed for MP 1.1.  But, I noticed that Config is using adoc (README.adoc).

Thanks, Kevin

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/120f7910-9555-40f5-bf85-3cd35e197164%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/wuF8zAr1rnk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/B75229D4-4EFA-4A24-A5C6-42DED46F7C52%40tomitribe.com.

Alasdair Nottingham

unread,
Jun 7, 2017, 5:39:11 PM6/7/17
to Kevin Sutter, David Blevins, MicroProfile, Ondrej Mihályi, Heiko Braun
For reading it doesn’t matter, for authoring md is still more widely understood, so likely has a lower barrier of entry. I quite like asciidoc though.


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

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

ondrej....@gmail.com

unread,
Jun 7, 2017, 7:05:05 PM6/7/17
to Kevin Sutter, David Blevins, MicroProfile, Heiko Braun

I prefer adoc.

 

It's much more powerful than MD.

 

For simple documents it doesn't matter but it makes sense to avoid mixing 2 formats. The evolution repo is one of the oldest and I guess MD was chosen just because the author knew it better or the original content was already in MD. With revising the evolution process, I would convert it to adoc.


--Ondro

+1 for Asciidoc

 

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

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/wuF8zAr1rnk/unsubscribe.

To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.

ondrej....@gmail.com

unread,
Jun 7, 2017, 7:08:55 PM6/7/17
to Kevin Sutter, David Blevins, MicroProfile, Heiko Braun

Just a small example why adoc is better – md doesn't support nested lists while adoc supports multilevel nested lists. And much more.

 

Ondro

John Clingan

unread,
Jun 7, 2017, 8:55:38 PM6/7/17
to MicroProfile
Like Kevin, I don't really have skin in this game because I'll just go with what others decide here. Since its looking like adoc is winning here, what content creation tools are available for adoc besides AsciidocFX? I'm asking because I may be having to write more asciidoc :-)


On Wednesday, June 7, 2017 at 2:33:18 PM UTC-7, David Blevins wrote:
+1 for Asciidoc

It can do everything Markdown can, plus a bit more.  There’s also a great toolchain for creating PDFs that Dan Allen maintains.  The MicroProfile.io website content is also in Asciidoc, so anything we create is instantly publishable there (regardless of what repo it lives in, the code that builds the site can pull and publish asciidoc from any git repo).

On Jun 7, 2017, at 2:09 PM, Ken Finnigan <k...@kenfinnigan.me> wrote:

I know I prefer adoc because of its features.

But I don't know if we need to "pick one", though it would make it easier for contributions if we were consistent.

Ken

On Wednesday, June 7, 2017 at 5:06:47 PM UTC-4, Kevin Sutter wrote:
Have we decided on whether we're using md or adoc for our common files (README, CONTRIBUTING, etc)?  Our evolution-process seems to be using md.  But, I noticed that many of our component repos are using adoc...  Should we focus on just one?  Or, doesn't anybody care?

This came up because I was just initializing my new repo for the "bill of materials"...  By default, Eclipse uses md (README.md), which is consistent with the component proposal I just completed for MP 1.1.  But, I noticed that Config is using adoc (README.adoc).

Thanks, Kevin

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

Alasdair Nottingham

unread,
Jun 7, 2017, 9:07:32 PM6/7/17
to John Clingan, MicroProfile
I find vi works really well ;)

Alasdair Nottingham
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

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

Rahman USTA

unread,
Jun 8, 2017, 12:41:44 AM6/8/17
to Alasdair Nottingham, MicroProfile, John Clingan
I suggest anybody using AsciidocFX editor but it doesn't matter which text editor you use. Asciidoc is best for documentation and I wonder why people still use Markdown :)

8 Haz 2017 04:07 tarihinde "Alasdair Nottingham" <alasdair....@gmail.com> yazdı:

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/AEEEC19D-481B-4B0F-A65C-F65BD639EE6F%40gmail.com.

Heiko Braun

unread,
Jun 8, 2017, 2:33:36 AM6/8/17
to MicroProfile, kwsu...@gmail.com, dble...@tomitribe.com, ondrej....@gmail.com, ike....@googlemail.com
+1 on adoc


On Wednesday, 7 June 2017 23:39:11 UTC+2, Alasdair Nottingham wrote:
For reading it doesn’t matter, for authoring md is still more widely understood, so likely has a lower barrier of entry. I quite like asciidoc though.

On Jun 7, 2017, at 5:36 PM, Kevin Sutter <kwsu...@gmail.com> wrote:

I'm not an expert with either one, so I don't really have a preference.  But, I do think that consistency would be good for our own sanity as well as future contributions.

Let's leave this conversation going for a bit, but it's leaning towards adoc...  Ondrej or Heiko?  Since the evolution-process is slanted towards md...

--  Kevin
On Wed, Jun 7, 2017 at 4:33 PM, David Blevins <dble...@tomitribe.com> wrote:
+1 for Asciidoc

It can do everything Markdown can, plus a bit more.  There’s also a great toolchain for creating PDFs that Dan Allen maintains.  The MicroProfile.io website content is also in Asciidoc, so anything we create is instantly publishable there (regardless of what repo it lives in, the code that builds the site can pull and publish asciidoc from any git repo).

On Jun 7, 2017, at 2:09 PM, Ken Finnigan <k...@kenfinnigan.me> wrote:

I know I prefer adoc because of its features.

But I don't know if we need to "pick one", though it would make it easier for contributions if we were consistent.

Ken

On Wednesday, June 7, 2017 at 5:06:47 PM UTC-4, Kevin Sutter wrote:
Have we decided on whether we're using md or adoc for our common files (README, CONTRIBUTING, etc)?  Our evolution-process seems to be using md.  But, I noticed that many of our component repos are using adoc...  Should we focus on just one?  Or, doesn't anybody care?

This came up because I was just initializing my new repo for the "bill of materials"...  By default, Eclipse uses md (README.md), which is consistent with the component proposal I just completed for MP 1.1.  But, I noticed that Config is using adoc (README.adoc).

Thanks, Kevin

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

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

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/wuF8zAr1rnk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.

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

Mike Croft

unread,
Jun 8, 2017, 3:32:17 AM6/8/17
to MicroProfile, kwsu...@gmail.com, dble...@tomitribe.com, ondrej....@gmail.com, ike....@googlemail.com
+1 for adoc.

Alasdair already mentioned the slightly higher friction for new users of Asciidoc, but I've found it's worth it. The pain of later finding out that MD isn't good enough and converting to Asciidoc is *large*. There's support in lots of editors, AsciidocFX and Atom will both give live rendered previews, or there are are browser plugins which would work very well for Vi/Vim users ;-)

http://asciidoctor.org/docs/editing-asciidoc-with-live-preview

Antoine Sabot-Durand

unread,
Jun 8, 2017, 8:22:08 AM6/8/17
to MicroProfile
+1 for adoc: richer and more versatile format without complexity addition (compared to md)

Antoine
--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.

Kevin Sutter

unread,
Jun 8, 2017, 11:49:41 AM6/8/17
to Antoine Sabot-Durand, MicroProfile
I'll leave this "vote" open for at least 24 hours, but it's looking like asciidoc is the clear winner...  Thanks!

--  Kevin

On Thu, Jun 8, 2017 at 7:21 AM, 'Antoine Sabot-Durand' via MicroProfile <microp...@googlegroups.com> wrote:
+1 for adoc: richer and more versatile format without complexity addition (compared to md)

Antoine

On 8 juin 2017 à 09:32 +0200, Mike Croft <backtoth...@gmail.com>, wrote:
+1 for adoc.

Alasdair already mentioned the slightly higher friction for new users of Asciidoc, but I've found it's worth it. The pain of later finding out that MD isn't good enough and converting to Asciidoc is *large*. There's support in lots of editors, AsciidocFX and Atom will both give live rendered previews, or there are are browser plugins which would work very well for Vi/Vim users ;-)

http://asciidoctor.org/docs/editing-asciidoc-with-live-preview
--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/fcc56ab3-f72a-4307-a6be-6280b96b5295%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/wuF8zAr1rnk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/6ef009c2-6586-491d-9113-cb4d9a3bf161%40Spark.

Kevin Sutter

unread,
Jun 13, 2017, 9:57:04 AM6/13/17
to MicroProfile
Okay, I think I've left this vote/discussion open long enough...  AsciiDoc is the clear winner.  Please ensure that your documentation (proposals, readmes, specs, etc) are all in AsciiDoc (.adoc) format.  As previously discussed, there are several tools to help you out .  Personally, I use the AsciiDoc plugin for Atom and it works quite nice to preview the updates real time.

Thanks!
Kevin

Emily Jiang

unread,
Jun 13, 2017, 6:09:57 PM6/13/17
to MicroProfile
Kevin,
Can you log the vote result on our wiki page (guideline for contributing) so that we can easily refer to it?

Emily


On Tuesday, June 13, 2017 at 2:57:04 PM UTC+1, Kevin Sutter wrote:
Okay, I think I've left this vote/discussion open long enough...  AsciiDoc is the clear winner.  Please ensure that your documentation (proposals, readmes, specs, etc) are all in AsciiDoc (.adoc) format.  As previously discussed, there are several tools to help you out .  Personally, I use the AsciiDoc plugin for Atom and it works quite nice to preview the updates real time.

Thanks!
Kevin

On Thursday, June 8, 2017 at 10:49:41 AM UTC-5, Kevin Sutter wrote:
I'll leave this "vote" open for at least 24 hours, but it's looking like asciidoc is the clear winner...  Thanks!

--  Kevin
On Thu, Jun 8, 2017 at 7:21 AM, 'Antoine Sabot-Durand' via MicroProfile <microp...@googlegroups.com> wrote:
+1 for adoc: richer and more versatile format without complexity addition (compared to md)

Antoine

On 8 juin 2017 à 09:32 +0200, Mike Croft <backtoth...@gmail.com>, wrote:
+1 for adoc.

Alasdair already mentioned the slightly higher friction for new users of Asciidoc, but I've found it's worth it. The pain of later finding out that MD isn't good enough and converting to Asciidoc is *large*. There's support in lots of editors, AsciidocFX and Atom will both give live rendered previews, or there are are browser plugins which would work very well for Vi/Vim users ;-)

http://asciidoctor.org/docs/editing-asciidoc-with-live-preview
--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/fcc56ab3-f72a-4307-a6be-6280b96b5295%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/wuF8zAr1rnk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile...@googlegroups.com.

Kevin Sutter

unread,
Jun 14, 2017, 3:37:23 PM6/14/17
to MicroProfile
Done.  Thanks for the nudge.

--  Kevin

Emily Jiang

unread,
Jun 14, 2017, 4:08:23 PM6/14/17
to MicroProfile
Thanks Kevin!
Emily
Reply all
Reply to author
Forward
0 new messages