Oh yeah, I almost forgot. These feedback comes with a pull request :)
-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