migration feedback for using Asciidoctor
by Dan Allen
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 …
[View More]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
[View Less]
12 years, 2 months
Quickstarts review
by Rafael Benevides
Hi all,
I was looking at Quickstarts root pom.xml and realized that there are
several Maven properties that I think that should be only on each
project's pom.xml. Is that right ?
If so, I believe that we should remove this properties and leave to the
script/tooling that we're planning, the responsibility of managing this
properties, specially BOMs and plugins versions besides other
verifications.
So I basically want to know if that makes sense, so I can open a pull
request with this …
[View More]properties removed.
Thanks
--
Rafael Benevides | Senior Software Engineer
Red Hat Brazil
+55-61-9269-6576
Better technology. Faster innovation. Powered by community collaboration.
See how it works at redhat.com
[View Less]
12 years, 2 months
Quickstarts - Single or Multiple Projects
by Darran Lofthouse
Hello all,
I have a quick question that I think partly comes down to personal
preference so I wanted to get some feedback on other options.
When developing a quickstart that contains a deployment and a client to
call the deployment is it preferable to contain this within a single
maven artefact or split it out with a common parent?
As an Eclipse user provided the client is simple my preference is to
keep this in a single Maven artefact so when imported into Eclipse it
will be a single …
[View More]project. As a command line user I also prefer this as
I don't need two terminal tabs or a change of working directory to
switch between deploying and running the quickstart.
There a some quickstarts that have to be split up to achieve the
packaging being demonstrated but I think those have a clear
justification for doing so.
I understand for IntelliJ users if split with a common parent the sub
modules are still represented within the parent module so they don't
experience the three project like in Eclipse.
So overall just looking for some feedback on which direction is preferable.
Thanks for your time.
Regards,
Darran Lofthouse.
[View Less]
12 years, 2 months
i18n directions
by Tiago Ferreira
Hello,
i am trying to build a web app to support several users and languages. I
took a look at the kitchensink-ear example and i have some questions.
Is this the best way to i18n a web aplication?
Does the Messages object need to be recreated each time a request is
made from a different locale?
thank you
Tiago
12 years, 2 months
