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

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 >

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(a)redhat.com | c: 980.226.7865 | http://www.redhat.com ----- Original Message ----- From: "Ondrej Zizka" <ozizka(a)redhat.com&gt; To: "Sande Gilda" <sgilda(a)redhat.com&gt;, "Windup-dev List" <windup-dev(a)lists.jboss.org&gt; 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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com&gt; 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(a)redhat.com | c: 980.226.7865 | http://www.redhat.com >> >> >> ----- Original Message ----- >> From: "Ondrej Zizka" <ozizka(a)redhat.com&gt; >> To: "Sande Gilda" <sgilda(a)redhat.com&gt;, "Windup-dev List" <windup-dev(a)lists.jboss.org&gt; >> 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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/windup-dev > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

I took a look at this, and it looks like a problem with the github css for the output. I think you could file a bug with them about it.

I guess a good question here is whether the wiki is just for editing, OR if it’s actually how we will present this stuff?

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

Ondra, it looks like Markdown has the same problem rendering lists. See: https://github.com/jboss-developer/jboss-eap-quickstarts/blob/6.4.x-devel... On 09/09/2014 10:18 AM, Pete Muir wrote: > I took a look at this, and it looks like a problem with the github css for the output. I think you could file a bug with them about it. > > I guess a good question here is whether the wiki is just for editing, OR if it’s actually how we will present this stuff? > > On 9 Sep 2014, at 12:45, Sande Gilda <sgilda(a)redhat.com&gt; 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(a)redhat.com&gt; >>> 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(a)redhat.com | c: 980.226.7865 | http://www.redhat.com >>>>> >>>>> >>>>> >>>>> ----- Original Message ----- >>>>> From: "Ondrej Zizka" >>>>> <ozizka(a)redhat.com&gt; >>>>> >>>>> To: "Sande Gilda" >>>>> <sgilda(a)redhat.com&gt;, "Windup-dev List" <windup-dev(a)lists.jboss.org&gt; >>>>> >>>>> 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(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>> _______________________________________________ >>>> windup-dev mailing list >>>> >>>> windup-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>> _______________________________________________ >>> windup-dev mailing list >>> >>> windup-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/windup-dev >> _______________________________________________ >> windup-dev mailing list >> windup-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/windup-dev > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com&gt; 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(a)redhat.com | c: 980.226.7865 | http://www.redhat.com >>>> >>>> >>>> ----- Original Message ----- >>>> From: "Ondrej Zizka" <ozizka(a)redhat.com&gt; >>>> To: "Sande Gilda" <sgilda(a)redhat.com&gt;, "Windup-dev List" <windup-dev(a)lists.jboss.org&gt; >>>> 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(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>> _______________________________________________ >>> windup-dev mailing list >>> windup-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/windup-dev >> _______________________________________________ >> windup-dev mailing list >> windup-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/windup-dev > > > > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com > <mailto:ozizka@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&lt;sgilda(a)redhat.com&gt; 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&quot;&lt;ozizka(a)redhat.com&gt; >>>>>> To: "Sande Gilda&quot;&lt;sgilda(a)redhat.com&gt;, "Windup-dev List&quot;&lt;windup-dev(a)lists.jboss.org&gt; >>>>>> 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(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>> _______________________________________________ >>>>> windup-dev mailing list >>>>> windup-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>> _______________________________________________ >>>> windup-dev mailing list >>>> windup-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>> >>> >>> >>> _______________________________________________ >>> windup-dev mailing list >>> windup-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/windup-dev >> >> _______________________________________________ >> windup-dev mailing list >> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >> https://lists.jboss.org/mailman/listinfo/windup-dev > > > > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com >> <mailto:ozizka@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&lt;sgilda(a)redhat.com&gt; 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&quot;&lt;ozizka(a)redhat.com&gt; >>>>>>> To: "Sande Gilda&quot;&lt;sgilda(a)redhat.com&gt;, "Windup-dev List&quot;&lt;windup-dev(a)lists.jboss.org&gt; >>>>>>> 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(a)lists.jboss.org >>>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>>> _______________________________________________ >>>>>> windup-dev mailing list >>>>>> windup-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>> _______________________________________________ >>>>> windup-dev mailing list >>>>> windup-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>> >>>> >>>> >>>> _______________________________________________ >>>> windup-dev mailing list >>>> windup-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>> >>> _______________________________________________ >>> windup-dev mailing list >>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>> https://lists.jboss.org/mailman/listinfo/windup-dev >> >> >> >> _______________________________________________ >> windup-dev mailing list >> windup-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/windup-dev > > > > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com <mailto:sgilda@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(a)redhat.com >>> <mailto:ozizka@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&lt;sgilda(a)redhat.com&gt; <mailto: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 <mailto:bdavis@redhat.com> | c:980.226.7865 <tel:980.226.7865> |http://www.redhat.com <http://www.redhat.com/> >>>>>>>> >>>>>>>> >>>>>>>> ----- Original Message ----- >>>>>>>> From: "Ondrej Zizka&quot;&lt;ozizka(a)redhat.com&gt; <mailto:ozizka@redhat.com> >>>>>>>> To: "Sande Gilda&quot;&lt;sgilda(a)redhat.com&gt; <mailto:sgilda@redhat.com>, "Windup-dev List&quot;&lt;windup-dev(a)lists.jboss.org&gt; <mailto: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(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>>>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>>>> _______________________________________________ >>>>>>> windup-dev mailing list >>>>>>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>>> _______________________________________________ >>>>>> windup-dev mailing list >>>>>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>>> >>>>> >>>>> >>>>> _______________________________________________ >>>>> windup-dev mailing list >>>>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>>> >>>> _______________________________________________ >>>> windup-dev mailing list >>>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>>> https://lists.jboss.org/mailman/listinfo/windup-dev >>> >>> >>> >>> _______________________________________________ >>> windup-dev mailing list >>> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >>> https://lists.jboss.org/mailman/listinfo/windup-dev >> >> >> >> _______________________________________________ >> windup-dev mailing list >> windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> >> https://lists.jboss.org/mailman/listinfo/windup-dev > > > > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org <mailto:windup-dev@lists.jboss.org> > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org <mailto:windup-dev@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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev

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(a)redhat.com&gt; 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(a)redhat.com | c: 980.226.7865 | http://www.redhat.com >> >> >> ----- Original Message ----- >> From: "Ondrej Zizka" <ozizka(a)redhat.com&gt; >> To: "Sande Gilda" <sgilda(a)redhat.com&gt;, "Windup-dev List" <windup-dev(a)lists.jboss.org&gt; >> 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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/windup-dev > _______________________________________________ > windup-dev mailing list > windup-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/windup-dev _______________________________________________ windup-dev mailing list windup-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/windup-dev