Asciidoctor :: Discussion - Re: Links to relative files by an anchor

Re: Links to relative files by an anchor

Posted by mojavelinux on
URL: https://discuss.asciidoctor.org/Links-to-relative-files-by-an-anchor-tp354p471.html

Alex,

Several variations of this requirement have been raised recently and it's definitely something important to address. I believe the core functionality you need is captured by issue #417 (https://github.com/asciidoctor/asciidoctor/issues/417). After an explanation, I'll present your example using the change I've proposed in the attached pull request.

The feature that appears to be missing from the AsciiDoc syntax is a means of creating an inter-document cross-reference. Until now, we've been viewing these as links. However, it's incorrect to encode them as links since the references could end up in the same document if both the source and destination get included in a master document. If there are written as cross-references, then Asciidoctor can intelligently wire them together appropriately since it has visibility into the full context of the document.

The proposed change enhances the existing xref macro from a simple id reference with an optional label:

<<id,label>>

to a compound reference that encodes the source document and id.

<<doc.ad#id,label>>

In fact, the AsciiDoc extension is optional.

<<doc#id,label>>

If the reference target is included in the same document as the reference source, the document (e.g., doc) is dropped. Thus, that reference may produce either one of these HTML elements:

<a href="#id">label</a>

<a href="doc.html#id">label</a>

Notice the .html is automatically added, since Asciidoctor knows what type of output it is producing.

Here's your example:

srs.ad

= Software Requirement Specifications

...

== Persistence

* In order to meet <<prs#PRS-1>>, we are going to use MongoDB.

If the document is rendered together as a book, the link in the last sentence would be represented as:

If the documents are rendered separately, the link would be represented as:

(you can provide an explicit label if you don't like the one that is auto-generated). Feedback welcome as well.

NOTE: We're assuming (for now) that reference ids are globally unique within a document set.

-Dan

On Thu, Jun 27, 2013 at 12:56 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

Today I have been thinking about one requirement that maybe could be fit un AsciiDoc format, but I think it will require some changes, or maybe I am wrong and it is already supported. I am thinking about linking to relative file, by instead of linking to section by using #<nameofsection> for example link:editing-asciidoc-with-live-preview/#livereload[LiveReload], we could do the same but to a special point without being a section.

I am thinking in next scenario:

I have got a document where I write all my Product Requirement Specifications which looks something like:

= Product Requirement Specifications

...

== Physical System Requirements

[cols="1,3"]
.Physical Requirements
|===
|PRS -1
|system should .....

|PRS-2
|system should ...
|===

But then in another document for example in Software Requirements document I want to link to an exact point of the document, for example:

= Software Requirement Specifications

...

== Persistence

* In order to meet PRS-1, we are going to use MongoDB.

The problem is that because PRS-1 is not a section I cannot do a link like:

link:prs/#PRS-1[PRS-1]

So maybe would be interesting to have a special character to enclose a word, which means that will be rendered as a link on original document so can be referenced from other document.

Maybe something like shown in AsciiDoc documentation:

[cols="1,3"]
.Physical Requirements
|===
|anchor:PRS-1[]PRS-1
|system should .....

I have seen that in Asciidoctor you can create links to blocks with identifiers, but I have not seen if there is a way to create links to a any part of the document.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Links-to-relative-files-by-an-anchor-tp354.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen