Link to an other document

Assuming I have something like this:

\---docs
        +--- example-manual.adoc
        \---page2.adoc

With the page2.adoc being something like:

[source,asciidoc]
----
Second page of the user manual.

[[chap2]]
== Second page chapter

This project does something.
We just haven't decided what that is yet.
----

Now in the example-manual.adoc, I want to make a link to the page 2. According to the Links to relative files section in the writers guide.

I should be able to do something like that:

[source,asciidoc]
----
link:page2[Go to the second page]

link:page2/#chap2[LiveReload]
----

But both solutions are not working.

The only way I managed to do this, is to make the assumption that I will get HTML document, and to use something like that:

[source,asciidoc]
----
link:page2.html[Go to the second page]

link:page2.html#chap2[check this section]
----

Is the documentation wrong?
Did I miss something?

Making the assumption on the output format is in my opinion not really a good idea. The file I want to link is page2.adoc and not page2.html (which exist only after the build with the HTML backend).

Having a link to the html page means, this will not work:
* in a preview context like with the chrome extension
* on a GitHub page when you browse the source tree
=> in those cases the link is really to the adoc file and not to a the html file.

What is your opinion?

I just spoke with Dan Allen at the JavaLandConf.

The new way to do it goes like that:

<<page2.adoc#,Smart Link to page 2>>

<<page2.adoc#intro2,Smart Link to the chap2 section in an other doc>>

I will try to udpate the documentation.

I tested the behavior. It works to convert the file extension ".adoc" or ".txt" to ".html"

<<page2.adoc#,Smart Link to page 2>>
or
<<page2.txt#,Smart Link to page 2>>

both renders as a link

href="page2.html"

My question is why can't Asciidoctor convert the file extension with this style?
link:page2.adoc[Link to page 2]

Dan told me this was introduced with 1.5.0 version of Asciidoctor, because they reconized that this was needed.
The "cross references" syntax  is working and the "link:" macro syntax is not working.

Maybe you will find an answer in the Inter-document cross references section.

The "AsciiDoc Syntax Quick Reference" already contains an example: check the "Inter-document cross references (Asciidoctor only)" example at the end of the links section of the "AsciiDoc Syntax Quick Reference"

For the "AsciiDoc Writer’s Guide" check my pull request:
https://github.com/asciidoctor/asciidoctor.org/pull/368