Oh yes, and the underlines for the section titles must be within +/- 1 of
the length of the title.
For instance, this won't work
Section Title
---------
It needs to match up (if this were monospaced font, it would)
Section Title
-------------
But I strongly urge you to prefer the single-line syntax:
= Section Title
It's so much simpler. Plus, the number of equal signs is the section level
(easy to remember), whereas I can never remember which symbol to use for a
given level using the underlines.
-Dan
On Thu, Jan 24, 2013 at 3:32 AM, Dan Allen <dan.j.allen(a)gmail.com> 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.
-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
--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597