Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
I believe an xref is the correct way to do this. A link is for linking to sections or anchors you create, I believe. Sorry for the uncertainly, this isn't something I typically do. On Mon, Jun 10, 2013 at 3:52 PM, ghillert [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi, ... [show rest of quote] |
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
|
This is use case that can be satisfied once GitHub upgrades to Asciidoctor 0.1.3. The reason we can't solve it now is because Asciidoctor 0.1.0 (currently on GitHub) didn't have enough tools to be able do the solution. So here's the solution: In the header, you define an attribute for the extension of relative documents, guarded by the environment in which the document is being viewed. Something like: ifdef::host-github[:ext-relative: .asciidoc] ifndef::host-github[:ext-relative: {outfilesuffix}]Then you create your relative links like: * index{ext-relative} * Creating-a-Source-Module{ext-relative} I'm really itching to be able to use this setup because we need it for the asciidoctor.org site as well. I'll add this to the wiki as a tip, but it's not available for use just yet. Btw, there are other ways to check for the host environment...but again, you can't do those types of conditionals until Asciidoctor is upgraded on GitHub. On Mon, Jun 10, 2013 at 4:57 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
... [show rest of quote] -- 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 |
Thanks for the answers. This blows though - It kind of breaks our tool-chain. I totally did not expect that links are not rendered with the proper extension (depending on the selected backend)
Are there any indication of when GitHub will upgrade? Thanks! Cheers, Gunnar |
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
|
On Mon, Jun 10, 2013 at 9:55 PM, ghillert [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks for the answers. This blows though - It kind of breaks our tool-chain. I totally did not expect that links are not rendered with the proper extension (depending on the selected backend) Actually, this can be solved with the toolchain as is. Go ahead and set the following attribute in the header of the document: :relative-ext: .asciidoc
And reference in as follows: * link:other-doc{relative-ext} That will work on GitHub. When you run Asciidoctor, whether it's part of your build or invoking asciidoctor directly, just override this attribute using: asciidoc -a relative-ext .html ... or asciidoc -a relative-ext .xml ... depending on the backend (I'm still thinking how to do it dynamically in this scenario). Speaking about the feature in general, the issue isn't that AsciiDoc/Asciidoctor doesn't render with the proper extension, it's that it doesn't interfere with the target of links as written. ...however, this is an excellent opportunity for Asciidoctor to move AsciiDoc forward. We need to decide what we want it to do and when that behavior should kick in. The best way to get that going is to create an issue. https://github.com/asciidoctor/asciidoctor/issues/417 Should we activate the feature when the extension of the link is a known AsciiDoc extension? Or should we require a special attribute on the link macro (inside the square brackets?) If we can sort it out in the next week or so, we'll make it part of 0.1.4.
I have good reason to believe it will be very soon. I'll stay on it until they do. -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
|
In reply to this post by ghillert
Just in case it wasn't clear, to create a link to a relative document (regardless of which extension it has) you need to use the link macro: link:target[]Using the adjustable extension, that would be: link:index{ext-relative}[]
On Mon, Jun 10, 2013 at 11:45 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] -- 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
|
In reply to this post by ghillert
The important message here is that there is a way to solve this problem today and there could be a better way to solve it in the future(s) (i.e., GitHub upgrade, Asciidoctor 0.1.4, etc).
The important thing is to make sure you have something that is going to work for you today, then let's design the future we want :)
On Mon, Jun 10, 2013 at 11:45 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Hi, working with Gunnar on the very same issue.
The problem is even more complicated and I guess has been encountered by many, but I did not find a solution for it. The thing is, we use several asciidoc documents included together to generate a full guide. So basically, what we'd need is some macro that behaves like a link: when documents are separated, and like an xref (<<anchor>>) when they've been concatenated together. At first, I thought about redefining the link: macro for the html and docbook backend to capture the anchor part (in link:document#anchor[Label]) together with the template for it (to render eg. Label in the html backend) but sadly, macro definitions don't seem to work in our toolchain (gradle plugin). I'm curious, what is the usual solution to this, as I'm sure people have encountered that? PS: One other option, and I guess I'll try that now, would be to rewrite links at the source level (ie. sed equivalent) before processing with asciidoctor. |
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
|
Eric, Your post triggered an idea in my mind about how to solve this.As you pointed out, we actually have two use cases here: 1. Link to a standalone document 2. Link to section in the final document that is stored in source form in a separate document The second use case has provided clarity for the first. If you are willing to follow two conventions (one which is required anyway) we can make this work simply by modifying the backend templates (which make the HTML / DocBook). Here are those assumptions: 1. Section ids (and other anchors) are globally unique in the final document (Asciidoctor enforces this by appending counters if there is a conflict, but they need to be globally unique in the source documents for this to work cleanly) 2. The name of the document must match the id generated from the section title for any document that gets included in the master document (this is the default on GitHub anyway...don't worry about case, we can handle that) Now, the reason this is going to work is because Asciidoctor builds a collection of all the ids in the document during parsing. Therefore, you can check if a cross reference is available in the final document. If so, we can make a xref link. If the id is not present, we assume we still have to link to the other document. Here's how the syntax will work. First, the target of the link will be the AsciiDoc source document. We can recognize known AsciiDoc extensions to understand when we are dealing with this type of link in the renderer. link:other-document.adoc[] But that's not enough, because there may be a case when you want to link to the AsciiDoc document directly. So, we add one more requirement. You must specify an anchor on the target. If you want to reference the top-most heading, just append a hash: link:other-document.adoc#[] If you want to reference a section within that document: link:other-document.adoc#example-section[] Here are the rules for how the information from the macro is processed in the renderer. 1. Check if the target has a known AsciiDoc source extension (.ad, .adoc, .asciidoc, etc), then strip it from the target 2. If an anchor value is given (value after the hash), look for that id in the @document.references[:ids] table 2a. If found, create an cross-reference to that section /END 2b. If not found, use the target and anchor to create an external link to that document and section (e.g., <a href="other-document.html#example-section">...</a>) /END 3. If an anchor value is not given, look for the target in the @document.references[:ids] table 3a. If found, create a cross-reference to that section /END 3b. If not found, use the target to create an external link to the top of that document (e.g., <a href="other-document.html">...</a>) Voila! I'll follow up with an example to show how this will work. I just wanted to share that I had come up with a possible scenario. NOTE: The tricky part is going to be making this work for links that have no file extension, like on the GitHub wiki. We could detect the 'wiki/' prefix, we could add an attribute to the link macro, or we can find some other way to hint to apply this logic. On Tue, Jun 11, 2013 at 2:06 AM, Eric Bottard [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi, working with Gunnar on the very same issue. ... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Free forum by Nabble | Edit this page |