[windup-dev] Asciidoc - lists

Thu Sep 11 07:13:53 EDT 2014

Hi Ondra,

Of course! As I said on IRC, what ever is easiest for you is fine by me. :-)

Thanks,
Sande

On 09/10/2014 11:04 PM, Ondrej Zizka wrote:
> Okay, in that case, let's do AsciiDoc, except for the few pages where 
> I am just storing temp info before converting to a real page, mostly 
> "Dev:", because that's changing often, shouldn't go to any official 
> docs, and I edit faster in Markdown. These pages will have "Draft" at 
> the top. But I'll update the existing pages in AsciiDoc.
>
> Will that work fine?
>
> Regards,
> Ondra
>
>
>
> On 10.9.2014 13:44, Sande Gilda wrote:
>> Coming into this late....
>>
>> I agree with Pete. I think the Wiki is a temporary container for the 
>> documentation. As Pete said, we may embed the docs into the web site 
>> or it may be published to the Customer Portal. Similar to the other 
>> documentation, we may also eventually need more complex structures 
>> like tables and graphs and I'm pretty sure we will want to publish 
>> PDFs. I hate to tie ourselves to something that can't grow with us. 
>> The syntax for AsciiDoc is very similar and I don't find it any more 
>> difficult to work with than Markdown.
>>
>> I do think we need to be consistent with the documentation and use 
>> the same tooling for all the pages. However, Ondra, if you feel more 
>> comfortable and productive working with Markdown, please continue to 
>> use it as you are doing an amazing job creating documentation! When 
>> you think a page is ready, I am happy to convert it to AsciiDoc for 
>> you.  :-)
>>
>> On 09/10/2014 06:12 AM, Pete Muir wrote:
>>> I doubt that the github wiki will be our target output platform. 
>>> We'll likely want to embed them in to the website.
>>>
>>> On 9 Sep 2014, at 23:24, Ondrej Zizka <ozizka at redhat.com 
>>> <mailto:ozizka at redhat.com>> wrote:
>>>
>>>> Other issues might be GitHub's translator. But IDK what's the main 
>>>> target medium for our docs. Is that GitHub wiki?
>>>>
>>>> Ondra
>>>>
>>>>
>>>> On 9.9.2014 13:45, Sande Gilda wrote:
>>>>> One of Ondra's complaints is the way lists seem to display an 
>>>>> extra paragraph between the items.  Take a look at the home page 
>>>>> here: https://github.com/windup/windup/wiki
>>>>>
>>>>> Note that the list items are spaced far apart. I search for a 
>>>>> solution, and the only thing I could find was mention of using 
>>>>> |[options="compact"], |but it didn't seem to work.
>>>>>
>>>>> Ondra, what other issues did you have.
>>>>>
>>>>>
>>>>> On 09/09/2014 06:39 AM, Pete Muir wrote:
>>>>>> The big advantages of asciidoc are:
>>>>>>
>>>>>> * more comprehensive markup (e.g. tables, definition lists are supported as standard)
>>>>>> * 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.
>>>>>>
>>>>>> 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.
>>>>>>
>>>>>> 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
>>>>
>>>> _______________________________________________
>>>> windup-dev mailing list
>>>> windup-dev at lists.jboss.org <mailto: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/20140911/2aea5ade/attachment-0001.html 