[windup-dev] Asciidoc - lists

Wed Sep 10 06:12:17 EDT 2014

On 9 Sep 2014, at 23:19, Ondrej Zizka <ozizka at 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 at 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 at redhat.com | c: 980.226.7865 | http://www.redhat.com
>>>> 
>>>> 
>>>> ----- Original Message -----
>>>> From: "Ondrej Zizka" <ozizka at redhat.com>
>>>> To: "Sande Gilda" <sgilda at redhat.com>, "Windup-dev List" <windup-dev at 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 at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/windup-dev
>>> _______________________________________________
>>> windup-dev mailing list
>>> windup-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/windup-dev
>> 
>> _______________________________________________
>> windup-dev mailing list
>> windup-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/windup-dev
> 
> _______________________________________________
> windup-dev mailing list
> windup-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/windup-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/windup-dev/attachments/20140910/a664e6fa/attachment-0001.html 