On 24 Jan 2013, at 04:32, Dan Allen wrote:
> One more thing I want to mention because it's an important difference from
AsciiDoc.
>
> For consistency, flexibility and speed, Asciidoctor enforces that start delimiters
match end delimiters around blocks. For instance, the following would not work:
>
> ====
> example block
> ===============
>
> So if the document totally loses all processing after a certain point, that could be
the culprit.
>
> I also noticed in the Ticket Monster tutorial that tabs are littered in a lot of
places. I strongly recommend against mixing spaces and tabs for indenting. Asciidoctor can
handle it, but I don't normalize tabs to spaces so you could get misalignment in
literal blocks in the output.
We should definitely normalize this in the sources. I blame the authors (me, Burr, Marius
;-).
Rafael, could you pick this one up?
Sure!
Dan, do I need to update the jdf-site to use asciidoctor or is it
embedded to awestruct 0.4.8 ?
> -Dan
>
> On Thu, Jan 24, 2013 at 3:18 AM, Dan Allen<dan.j.allen(a)gmail.com> wrote:
> Oh yeah, I almost forgot. These feedback comes with a pull request :)
>
>
https://github.com/jboss-jdf/jboss-as-quickstart/pull/412
>
> -Dan
>
>
> On Thu, Jan 24, 2013 at 3:15 AM, Dan Allen<dan.j.allen(a)gmail.com> wrote:
> Pete,
>
> I head from Jason that you're experimenting with using Asciidoctor to generate
the HTML for some of the guides. I'm thrilled to here that. It also prompted me to
review how Asciidoctor handles these documents. I processed the following guide:
>
>
https://github.com/jboss-jdf/jboss-as-quickstart/tree/master/guide
>
> I've come up with some observations and recommendations. But first, some general
advice for using Asciidoctor.
>
> If you are using Asciidoctor view the API, you'll want to disable SafeMode (since
that's not relevant for builds) and enable full document output:
>
> Asciidoctor.render_file('guide.asciidoc', :safe =>
Asciidoctor::SafeMode::UNSAFE, :header_footer => true, :in_place => true)
>
> The :in_place option mimics the behavior of AsciiDoc of rendering to file w/ the same
basename as the source file.
>
> Coming in 0.1.0 is a cli, named asciidoctor. You'll be able to use that as a
drop-in replacement for the asciidoc command.
>
> Moving on to the feedback.
>
> * AsciiDoc clips the label of the following xref (because of the comma in the label),
whereas Asciidoctor gets it right:
>
> <<GettingStarted-on_linux, Installing and starting the JBoss server on
Linux, Unix or Mac OS X>>
>
> * Asciidoctor does not process the anchor:name[] macro, use [[name]] instead (best is
to put it above a section title)
> * Asciidoctor does not render callout numbers as icons (I recommend we use
FontAwesome or CSS to accomplish this markup)
> * Use a conditional block to setup the source-highlighter when using Asciidoctor:
>
> ifdef::asciidoctor[]
> :source-highlighter: highlightjs
> :highlightjs-theme: github
> endif::asciidoctor[]
>
> Another option for source highlighting is CodeRay, which is more or less like
Pygments in that it formats the code directly. You'll need to gem install coderay,
then:
>
> ifdef::asciidoctor[]
> :source-highlighter: coderay
> endif::asciidoctor[]
>
> I noticed a couple of places where Asciidoctor was incorrectly parsing the text. I
fixed them and pushed the changes. They will likely make it into 0.1.0.
>
> If you have any questions, or have any features you'd like to see, let me know or
just post the feedback in the Asciidoctor issue tracker [1].
>
> Cheers!
>
> -Dan
>
> [1]
https://github.com/erebor/asciidoctor/issues?state=open
>
> --
> Dan Allen
> Principal Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597
>
>
http://google.com/profiles/dan.j.allen
>
http://mojavelinux.com
>
http://mojavelinux.com/seaminaction
>
>
>
> --
> Dan Allen
> Principal Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597
>
>
http://google.com/profiles/dan.j.allen
>
http://mojavelinux.com
>
http://mojavelinux.com/seaminaction
>
>
>
> --
> Dan Allen
> Principal Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597
>
>
http://google.com/profiles/dan.j.allen
>
http://mojavelinux.com
>
http://mojavelinux.com/seaminaction
> _______________________________________________
> jdf-dev mailing list
> jdf-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/jdf-dev
_______________________________________________
jdf-dev mailing list
jdf-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jdf-dev