Re: Link versus XRef

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

LightGuardjp
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,

I am still missing something obvious - I have multiple asciidoc files. Within an asciidoc file, I may link to another asciidoc file. This works fine on Github but when converting the asciidoc files to e.g. HTML the links stop working. It looks like the links are not rewritten to end with *.html. For example, I have the following 2 files:

* index.asiidoc
* Creating-a-Source-Module.asciidoc

I have a link in index.asiidoc:

link:Creating-a-Source-Module[Source Modules]

However, the resulting html is:

...Creating-a-Source-Module

Without the html ending appended. Should I rather use xref?

Thanks!

Cheers,

Gunnar


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Link-versus-XRef-tp326.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

mojavelinux
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}]

(outfilesuffix is set automatically based on the backend in use).

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.

-Dan


On Mon, Jun 10, 2013 at 4:57 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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,

I am still missing something obvious - I have multiple asciidoc files. Within an asciidoc file, I may link to another asciidoc file. This works fine on Github but when converting the asciidoc files to e.g. HTML the links stop working. It looks like the links are not rewritten to end with *.html. For example, I have the following 2 files:

* index.asiidoc
* Creating-a-Source-Module.asciidoc

I have a link in index.asiidoc:

link:Creating-a-Source-Module[Source Modules]

However, the resulting html is:

...Creating-a-Source-Module

Without the html ending appended. Should I rather use xref?

Thanks!

Cheers,

Gunnar


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Link-versus-XRef-tp326.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Re-Link-versus-XRef-tp327.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

ghillert
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
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

mojavelinux
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.
 

Are there any indication of when GitHub will upgrade?


I have good reason to believe it will be very soon. I'll stay on it until they do.

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

mojavelinux
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[]

For example:

link:index.html[]

Using the adjustable extension, that would be:

link:index{ext-relative}[]

-Dan


On Mon, Jun 10, 2013 at 11:45 PM, Dan Allen <[hidden email]> wrote:
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.
 

Are there any indication of when GitHub will upgrade?


I have good reason to believe it will be very soon. I'll stay on it until they do.

-Dan



--
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

mojavelinux
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 :)

-Dan


On Mon, Jun 10, 2013 at 11:45 PM, Dan Allen <[hidden email]> wrote:
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.
 

Are there any indication of when GitHub will upgrade?


I have good reason to believe it will be very soon. I'll stay on it until they do.

-Dan



--
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

Eric Bottard
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.
Reply | Threaded
Open this post in threaded view
|

Re: Link versus XRef

mojavelinux
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.

-Dan


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.

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.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Re-Link-versus-XRef-tp327p333.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--