[windup-dev] Asciidoc - lists
Sande Gilda
sgilda at redhat.com
Fri Sep 12 11:46:11 EDT 2014
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
> <mailto: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
>>>> <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 <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> <mailto: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 <mailto:bdavis at redhat.com> | c:980.226.7865 <tel:980.226.7865> |http://www.redhat.com <http://www.redhat.com/>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> ----- Original Message -----
>>>>>>>>> From: "Ondrej Zizka"<ozizka at redhat.com> <mailto:ozizka at redhat.com>
>>>>>>>>> To: "Sande Gilda"<sgilda at redhat.com> <mailto:sgilda at redhat.com>, "Windup-dev List"<windup-dev at lists.jboss.org> <mailto: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 <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 <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 <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 <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 <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 <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 <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 <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 <mailto: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 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/20140912/df6ef5b1/attachment.html
More information about the windup-dev
mailing list