Re: [windup-dev] Asciidoc - lists

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