On 9 Sep 2014, at 23:19, Ondrej Zizka <ozizka@redhat.com> wrote:


On 9.9.2014 12:39, Pete Muir wrote:
The big advantages of asciidoc are:

* more comprehensive markup (e.g. tables, definition lists are supported as standard)
That's nice,  but we have 0 tables and just one DL in our docs :)

Understood, this is largely about what you need out of your language. For me tables are essential, as are admonitions and callouts.

* generation of pdf and epub is part of the standard toolchain

Markdown is great for short docs, but I quickly ran in to the limitations when building more complex documents.
Same as above - will we have more complex docs?

I think it’s very likely that we will have what I would class a “complex” document for Windup - yes.

Will we produce PDF? Will users expect a PDF document?

It’s a very commonly requested item. A sizeable majority tend to prefer this.

I don't know 
their customs, but personally I never use PDF docs, except when 
printing, which I never did for anything except Java EE specs / 
tutorials and Spring.

How about keeping MarkDown for short and simple pages, and AsciiDoc 
optionally when needed? One more syntax should not matter.

I would use asciidoc for anything that is going to go in to the docs. For other things, such as READMEs use markdown.

GitHub’s support for asciidoc wasn’t great to start with, but I think the fixed it more recently. Before you abandon it, point me at the problems, I can take a quick look.

I prefer asciidoc links as you just do link:http://redhat.com[Red Hat’s website]. I find this much easier to remember than the weird []() syntax in markdown.
How about this nice paragraph

A 
link:https://maps.google.com/maps?saddr=Hn%C4%9Bvkovsk%C3%A9ho%2FRoute+41&daddr=Kr%C3%B3lewska&hl=en&ie=UTF8&sll=52.229692,21.006203&sspn=0.214911,0.385551&geocode=FW5S7gId0qf9AA%3BFYYeHQMdx6BAAQ&t=h&mra=mift&mrsp=1&sz=12&z=12[way] 
to
link:https://www.google.cz/search?q=poland&client=ubuntu&hs=1q&channel=fs&source=lnms&tbm=isch&sa=X&ei=MHwPVM_jLs7EPJfCgbgL&ved=0CAkQ_AUoAg&biw=1504&bih=1083[Poland].

And now compare with:

A 
"way":https://maps.google.com/maps?saddr=Hn%C4%9Bvkovsk%C3%A9ho%2FRoute+41&daddr=Kr%C3%B3lewska&hl=en&ie=UTF8&sll=52.229692,21.006203&sspn=0.214911,0.385551&geocode=FW5S7gId0qf9AA%3BFYYeHQMdx6BAAQ&t=h&mra=mift&mrsp=1&sz=12&z=12
to 
"Poland":https://www.google.cz/search?q=poland&client=ubuntu&hs=1q&channel=fs&source=lnms&tbm=isch&sa=X&ei=MHwPVM_jLs7EPJfCgbgL&ved=0CAkQ_AUoAg&biw=1504&bih=1083

I personally prefer the first. And the {} attributes syntax doesn't make 
things simpler.

I prefer the first approach too. So a good argument for AsciiDoc then.

Note that the markdown syntax you quote is a github extension I think. This is part of the reason I would pick AsciiDoc - all these things are standard, rather than implementation specific extensions.


my2c.
But as I said - except for this and few other things, AsciiDoc may be 
better, potentially.

Ondra

On 9 Sep 2014, at 01:23, Sande Gilda <sgilda@redhat.com> wrote:

I'll change everything back to Markdown later this week. Ondra, in the
meantime, you can work in Markdown.

On 09/08/2014 08:12 PM, Brad Davis wrote:
I personally leveraged Markdown because it worked.  Asciidoc a while ago did not.  I noticed when things moved to Asciidoc, the images in the docs broke.

Brad Davis
Red Hat Consulting
Email: bdavis@redhat.com | c: 980.226.7865 | http://www.redhat.com


----- Original Message -----
From: "Ondrej Zizka" <ozizka@redhat.com>
To: "Sande Gilda" <sgilda@redhat.com>, "Windup-dev List" <windup-dev@lists.jboss.org>
Sent: Monday, September 8, 2014 7:58:20 PM
Subject: Re: [windup-dev] Asciidoc - lists

For the record: I don't strongly prefer either, only that I only touched
few things in AsciiDoc, and:
  1) certain constructs are quite less readable -> editable in the
source text (e.g. links)
  2) the render results are not satisfactory - things like a bold text
in a lists are not properly implemented on whatever GitHub uses.

Ondra


On 9.9.2014 01:17, Sande Gilda wrote:
Hi all,

Ondra asked me about the advantages of AsciiDoc over Markdown. I
really don't know, but I do remember Pete saying AsciiDoc would be
better for the quickstart README files long ago. And I believe Drupal,
the new host for documentation, supports AsciiDoc.

TBH, I don't feel strongly about sticking with AsciiDoc. If no one can
come up with a good reason for sticking with it, I'm fine with going
back to Markdown if it's easier for everyone.

So, AsciiDoc advocates, please speak up now.

Thanks,
Sande

On 09/08/2014 06:29 PM, Sande Gilda wrote:
Hi Ondra,

You're asking me? ;-)

I'm totally new to asciidoc. I'll research it and see what I can find
out.

Thanks,
Sande

On 09/08/2014 06:13 PM, Ondrej Zizka wrote:
Hi Sande,

is there any way to prevent asciidoc put <p> to each <li>? Makes the
list tall and breaks the whole page layout.

Thanks,
Ondra
_______________________________________________
windup-dev mailing list
windup-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev
_______________________________________________
windup-dev mailing list
windup-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev

_______________________________________________
windup-dev mailing list
windup-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev

_______________________________________________
windup-dev mailing list
windup-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev