Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
23 posts
|
Hi all,
I'm using Asciidoctor through the Asciidoctor Gradle plugin. I was using version 0.5.0 of the plugin which used the previous version of Asciidoctor, but I decided to try the latest version, 0.6.0, that Andrés has just released, and which is using Asciidoctor 0.1.4. There are a few very interesting features I'm longing to try and integration for the Groovy documentation :-) But alas, I'm encountering some issues... In a nutshell, here's the log of my build after the upgrade: http://rifers.org/paste/show/2350 The tons of warnings seem to be related to includes. It seems somehow the default base path, or something like that, has changed? Or is it something specific to the Gradle plugin? I'm using includes like this: [source,groovy] ---- include::../test/SyntaxTest.groovy[tags=hexadecimal_literal_example,indent=0] ---- Basically, it's a relative path, ie. relative to my core-syntax.adoc file doing the above include. But instead of resolving the fully qualified path to: /Users/glaforge/Projects/groovy/groovy-git/src/spec/test/SyntaxTest.groovy It's resolved instead to : /Users/glaforge/Projects/groovy/test/SyntaxTest.groovy So it seems somehow now that the relative path is resolved against the root of the project, rather than relative to the document. Issue with Asciidoctor or with the plugin? And the other issue I'm seeing in the build log is this serialization issue with JRuby: java.io.NotSerializableException: org.jruby.Ruby It's the big stacktrace at the end of the logs. It might also be related to the Gradle plugin though, as it seems that it's Gradle trying to somehow serialize it: org.gradle.api.UncheckedIOException: Could not add entry ':asciidoctor' to cache taskArtifacts.bin (/Users/glaforge/Projects/groovy/groovy-git/.gradle/1.7/taskArtifacts/taskArtifacts.bin). Any hint will be most welcome :-) Guillaume |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
23 posts
|
At least for the problem with the includes, it's related to that change:
https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/19 Which is the fact the relative path is now resolved against the project's path, and not the document's path, which I guess makes more sense anyway. Now... onto the Gradle related problem... |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
31 posts
|
This is indeed the case. Previous to 0.6.0 the base_dir property was not set by the gradle plugin, thus leaving it open for aSciidoctor to figure out. This omission caused no trouble in single project build but created problems in a multi project build as it was automatically set to the root project's dir, no matter if the asciidcotor task was being executed in a subproject. From now on, the base_dir property will be set to the current project's directory, so paths should always be relative to the project where the asciidoctor task is being applied.
The gradle problem might be caused by an attempt to serialize (by the Gradle daemon) an error caused by the non-relative paths in order to cache tasks outputs. Further investigation is needed. Cheers, Andres |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
298 posts
|
Hello, we can talk tomorrow about exactly the problem of serialization, but before that let me show you the code that deals with HashMap to RubyHash:
This method is called when you want to render something (in this case an string). The Map (the one you had send as argument) is received as argument and is converted to RubyHash by using RubyHashUtil. public String render(String content, Map<String, Object> options) { this.rubyGemsPreloader.preloadRequiredLibraries(options); addRubyRuntimeAsAttribute(options); RubyHash rubyHash = RubyHashUtil.convertMapToRubyHashWithSymbols( rubyRuntime, options); Object object = this.asciidoctorModule.render(content, rubyHash); return returnExpectedValue(object); } Note that a new instance of hash is created, and then for each element, the key is converted to a Ruby symbol, and the value to a Ruby object calling toRubyObject. public static RubyHash convertMapToRubyHashWithSymbols(Ruby rubyRuntime, Map<String, Object> options) { RubyHash rubyHash = new RubyHash(rubyRuntime); Set<Entry<String, Object>> optionsSet = options.entrySet(); for (Entry<String, Object> entry : optionsSet) { String key = entry.getKey(); Object value = entry.getValue(); RubySymbol newSymbol = RubyUtils.toSymbol(rubyRuntime, key); IRubyObject iRubyValue = toRubyObject(rubyRuntime, value); rubyHash.put(newSymbol, iRubyValue); } return rubyHash; } private static IRubyObject toRubyObject(Ruby rubyRuntime, Object value) { if (value instanceof List) { return toRubyArray(rubyRuntime, (List |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by aalmiray
On Tue, Oct 8, 2013 at 5:17 AM, aalmiray [via Asciidoctor :: Discussion] <[hidden email]> wrote:
This is indeed the case. Previous to 0.6.0 the base_dir property was not set by the gradle plugin, thus leaving it open for aSciidoctor to figure out. This omission caused no trouble in single project build but created problems in a multi project build as it was automatically set to the root project's dir, no matter if the asciidcotor task was being executed in a subproject. From now on, the base_dir property will be set to the current project's directory, so paths should always be relative to the project where the asciidoctor task is being applied. +1 I believe this change is also being made to the Maven plugin as well so we're consistent. Another thing that changed in Asciidoctor 0.1.4 (which may need to be tested in the context of the Gradle plugin) is how the path of an include directive that appears within a file included from a subdirectory is resolved (e.g., a.adoc includes "subdir/b.adoc" and b.adoc includes "c.adoc", how is "c.adoc" resolved?). The path is now resolved relative to the file which contains the include directive (e.g., "c.adoc" resolves to subdir/c.adoc).
I've tested this behavior with the Gradle plugin and what I've discovered is that when base_dir is set, "c.adoc" is still resolved relative to b.adoc and it gets included, but a warning is issued that says the file cannot be found. Hmm.
The rules for resolving include paths needs to be better clarified in Asciidoctor, and then in the plugins. I have filed an issue against Asciidoctor 1.5.0 [1].
Keep in mind that you can access the path of the master file (the file at the top of the include stack) using the attribute reference {docdir} (read "docdir" as "master document directory"). Thus, to resolve c.adoc in theory, you might use:
include::{docdir}/asciidoc/subdir/c.adoc[] However, I'm noticing that there is an issue resolving this path as well, likely due to a conflict with base_dir. The best strategy at this point may be to chart it out so that we can determine what we expect in each case and try to get the behavior to match it. (Paths are such a nightmare :))
Andres, I wonder if for this release, a better solution is to set the attribute "projectdir" so it resolves to the project directory, then let this be used by authors like:
include::{projectdir}/src/java/org/example/Sample.java[] Then we can resolve the issues with base_dir such that if we set it in the future, this include would work the same with or without the {projectdir} segment. wdyt?
-Dan p.s. I want to point out that a major part of the Asciidoctor 1.5.0 release is a proper user guide, which is being drafted by Sarah as we speak. A key focus of that guide is to sort out the confusion about how certain features like path resolution work so that a) we can understand them and b) we can change the behavior to make it more intuitive. The AsciiDoc (Python) user guide leaves *a lot* of gray area in places like this. We're going to make it right.
Dan Allen | http://google.com/profiles/dan.j.allen
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
31 posts
|
OK, if I understood correctly the gradle plugin should set projectdir and leave base_dir without value (unless it was specified?) Conceptually speaking, what's the difference between base_dir and projectdir? Specially in the context of a multi project build. Cheers, Andres |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
23 posts
|
In reply to this post by mojavelinux
On Tue, Oct 8, 2013 at 11:51 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Also, a comprehensive overview of all the possible elements of syntax, etc. Including all those changes / improvements / new features that have been listed in the release notes, and so on.
I really miss a one stop shop where I can find everything :-) |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by aalmiray
On Oct 9, 2013 2:49 AM, "aalmiray [via Asciidoctor :: Discussion]" <[hidden email]> wrote: Correct. We would basically be leaving this up to the user to set for now. I'm assuming there's some variable in Gradle that has this information, so it's easy to set. > Conceptually speaking, what's the difference between base_dir and projectdir? Specially in the context of a multi project build. Right now it's because base_dir has affects on the internal behavior of Asciidoctor. base_dir is a jail path. For some reason, the various conceptual roots in a Gradle project (project root, module root, docs dir root, source dir root and pwd) are confusing the logic of how base_dir is factored in. The projectdir (if you think that's the right name) should be an absolute path. That way, when prepended to a relative include path without base_dir set should resolve to exactly where you intend it to resolve. We then have time to think about exactly how we want base_dir to affect path resolution in this environment and enable it in the next release. Sound reasonable? -Dan p.s. I think projectdir is generally useful to have, as would moduledir, hence why I think adding them now makes sense anyway. |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by glaforge
On Oct 9, 2013 2:35 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote: That's exactly the plan. It's a living working draft, btw: http://asciidoctor.org/docs/user-manual Note that not all the information in there is accurate yet (but certainly a majority of it is). I still need to do a full technical review. Anyone else is welcome to as well. Just keep in mind, if you see something that doesn't seem right, just speak up. -Dan |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
31 posts
|
In reply to this post by mojavelinux
Should this new attribute be named project_dir in order to be consistent with other dir like attribute names?
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
31 posts
|
In reply to this post by asotobu
I've traced the API call that injects Ruby into the options Map set from AsciidoctorTask, it's this one
Caused by: java.lang.UnsupportedOperationException at org.asciidoctor.internal.JRubyAsciidoctor.addRubyRuntimeAsAttribute(JRubyAsciidoctor.java:171) at org.asciidoctor.internal.JRubyAsciidoctor.renderFile(JRubyAsciidoctor.java:158) at org.asciidoctor.Asciidoctor$renderFile.call(Unknown Source) at org.asciidoctor.gradle.AsciidoctorTask$_processAllDocuments_closure1.doCall(AsciidoctorTask.groovy:123) at org.asciidoctor.gradle.AsciidoctorTask.processAllDocuments(AsciidoctorTask.groovy:114) ... 88 more I found out by wrapping the options/attributes map with an immutable one. So anyway, our current fix (defensive copying of options/attributes) works just fine as Gradle will keep the original maps for caching and asciidoctor-java modifies its copy to its heart's content. Cheers, Andres |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
31 posts
|
In reply to this post by aalmiray
Another thing wrt setting a value for base_dir automagically, even if asiidoctor-gradle sets projectDir (or project_dir) it looks like some properties would still resolve to the rootProject's directory rather than the current child directory as explained in https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/19
Setting base_dir to the current project's directory solves the problem (see options.templates_dir and options.attributes.imagesdir). I'm leaning towards defining a value for attributes.projectdir (I see now that in attributes the *dir suffix is preferred over *_dir) to be equal to base_dir for the time being. wdyt? |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
On Wed, Oct 9, 2013 at 1:17 PM, aalmiray [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Another thing wrt setting a value for base_dir automagically, even if asiidoctor-gradle sets projectDir (or project_dir) it looks like some properties would still resolve to the rootProject's directory rather than the current child directory as explained in https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/19 I'll review those scenarios, then cast my vote once a have a more solid understanding of the implications.
Agreed. Speaking of attribute name consistency, AsciiDoc isn't very consistent in this area. Generally, though, the nameswithnospaces is used. For instance, docdir, docfile, imagesdir, stylesdir, etc.
In contrast, options always use the underscore_separated syntax. For instance, base_dir, in_place, template_dirs, etc. Options are confined to the API, which is why we were able to make the change w/o impacting AsciiDoc compatibility. base_dir lives outside the document. The document isn't able to see this value (as part of the security requirements).
Attribute naming conventions is a topic I'd like to discuss in a separate thread in the near future. My idea is to allow attributes to be entered using names_separated_by_underscores but then store and resolve them with the underscores removed. That way, the style is up to the author. In order to do that, however, I need to switch to the new attribute manager I've been prototyping so that the logic for storage and lookup is encapsulated.
-Dan Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by aalmiray
On Wed, Oct 9, 2013 at 2:04 PM, Dan Allen <[hidden email]> wrote:
I'm sure Guillaume would agree that we are creeping into the realm of language design here. That's one of the reasons I'm so thrilled that Guillaume is part of this community. Guillaume, your expertise on language design will no doubt prove central to the evolution of this syntax!
-Dan Dan Allen | http://google.com/profiles/dan.j.allen
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
298 posts
|
In reply to this post by mojavelinux
Andres thanks for the stacktrace now I see the problem. This will change for next version so you don t have to clone the map. In fact it will be not necessary to clone nothing because I am going to create a context environment to get the Ruby environment for extensions instead of using as attribute which throws this exception in Gradle
El dimecres 9 d’octubre de 2013, mojavelinux [via Asciidoctor :: Discussion] ha escrit:
... [show rest of quote] -- Enviat amb Gmail Mobile |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
23 posts
|
In reply to this post by mojavelinux
On Wed, Oct 9, 2013 at 10:09 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Oh flattery :-) Consistency is of course very important. The problem seems that AsciiDoc itself hasn't been all that consistent in the first place, so I guess it puts Asciidoctor in a problematic situation with regards compatibility.
If there's no interference with and without underscores, I would argue that supporting both the way you mention (through underscore removal basically) is a good compromise. Users not remembering if there's an underscore or not won't be bothered if they make a typo :-) It's quite forgiving! And it's pragmatic.
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
23 posts
|
In reply to this post by mojavelinux
[...]
An example I didn't find in the user guide (and had difficulties finding in AsciiDoc's documentation) was how to use unicode escape characters. Say, you want the Euro symbol... I tried \u20AC like in programming languages... but it didn't work.
AsciiDoc(tor) actually use the entities notation like in HTML, ie. AC; I was searching for "unicode escape sequence" and such, but didn't find anything... until somehow I stumbled upon the entities notation :-)
Anyhow, the user guide has nicely evolved over time already, and is becoming more and more comprehensive! That's really very useful! |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by glaforge
On Thu, Oct 10, 2013 at 1:25 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
;) Oh, but it's more than that. I'm glad just to get to know you and to give you something in return for your hard work.
In the short term, yes. Once Asciidoctor reaches a point where it's the most widely adopted implementation, hands down, the plan is to start _defining_ compatibility. I'm already taking a lot of notes for what we'll want to add, improve or drop when we're ready to make a formal specification, based on the experiences flowing through this community.
Exactly. Thanks for sharing that insight. I'll put it on the roadmap then. -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by glaforge
On Thu, Oct 10, 2013 at 1:31 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
... [show rest of quote] Thanks for pointing that out. That's exactly the type of feedback I'm hoping for. I'll make sure that phrasing gets included.
That's good to hear. We have a lot more coming, including new content, clarifications and more examples. When we're "done", the AsciiDoc User Guide will be nothing more than a relic :) -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Administrator
2681 posts
|
In reply to this post by asotobu
On Wed, Oct 9, 2013 at 11:30 PM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Andres thanks for the stacktrace now I see the problem. This will change for next version so you don t have to clone the map. In fact it will be not necessary to clone nothing because I am going to create a context environment to get the Ruby environment for extensions instead of using as attribute which throws this exception in Gradle That's great news, Alex! The cleaner the integration, the more comfortable users will feel about the use of JRuby. -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
Free forum by Nabble | Edit this page |