[windup-dev] Asciidoc - lists

Fri Sep 12 12:56:24 EDT 2014

Ok, if that works for you two, that's fine with me.

On Fri, Sep 12, 2014 at 11:46 AM, Sande Gilda <sgilda at redhat.com> wrote:

>  Hi Lincoln,
>
> The plan is definitely to make them all Asciidoc format. Ondra writes a
> lot of doc and if he feels more productive using Markdown when creating a
> new document, that's fine by me. When he's finished with a topic, I will
> convert it to Asciidoc. Then he will have to make any updates using the
> Asciidoc format. So everything will be Asciidoc.
>
> Thanks,
> Sande
>
>
> On 09/12/2014 11:30 AM, Lincoln Baxter, III wrote:
>
> Coming in to this late, I'd prefer to stick with one format, and it seems
> like we (as JBoss) are moving toward asciidoc, so I think we should stick
> with that (for all of the previously stated reasons.)
>
> On Thu, Sep 11, 2014 at 7:13 AM, Sande Gilda <sgilda at redhat.com> wrote:
>
>>  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> 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> <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> <ozizka at redhat.com>
>> To: "Sande Gilda" <sgilda at redhat.com> <sgilda at redhat.com>, "Windup-dev List" <windup-dev at lists.jboss.org> <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 listwindup-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/windup-dev
>>
>>  _______________________________________________
>> windup-dev mailing listwindup-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/windup-dev
>>
>>  _______________________________________________
>> windup-dev mailing listwindup-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/windup-dev
>>
>>
>>
>>
>> _______________________________________________
>> windup-dev mailing listwindup-dev at lists.jboss.orghttps://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 listwindup-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/windup-dev
>>
>>
>>
>>
>> _______________________________________________
>> windup-dev mailing listwindup-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/windup-dev
>>
>>
>>
>>
>> _______________________________________________
>> windup-dev mailing listwindup-dev at lists.jboss.orghttps://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
>>
>
>
>
>  --
> Lincoln Baxter, III
> http://ocpsoft.org
> "Simpler is better."
>
>
> _______________________________________________
> windup-dev mailing listwindup-dev at lists.jboss.orghttps://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
>

-- 
Lincoln Baxter, III
http://ocpsoft.org
"Simpler is better."
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/windup-dev/attachments/20140912/8ab8f956/attachment-0001.html 