Asciidoctor :: Discussion

Subtopics/chapters in separate files?

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

9 messages Options

ramendik

Oct 13, 2017; 4:23pm

Subtopics/chapters in separate files?

8 posts

Hello,

I am a bit uncomfortable with keeping an entire book in a huge plain-text file. Coming form a DITA background, I would be much more comfortable if I could keep pieces of the document (chapters, subtopics, what not) in separate files. This provides for easier collaborative editing, easier lookups, easier linking, and also VERY MUCH easier reordering of parts of the document.

Does AsciiDoc support anything like this?

abelsromero

Oct 13, 2017; 4:37pm

Re: Subtopics/chapters in separate files?

242 posts

Welcome to the forums,

You can split a document into different files and then assemble them using the include directive like this:

include::path/file.adoc[]

or if everything is in the same folder

include::file.adoc[]

Full details: http://asciidoctor.org/docs/user-manual/#include-directive.

ramendik

Oct 13, 2017; 8:22pm

Re: Subtopics/chapters in separate files?

8 posts

Thanks!

ramendik

Oct 13, 2017; 8:46pm

Re: Subtopics/chapters in separate files?

8 posts

In reply to this post by abelsromero

I have reviewed the include documentation and it looks like it covers much of what I want for topic-based documentation, especially because of the leveloffset attribute. There is one question. however, that remains unclear.

is it possible to link from one included file to another by referencing the file name? Or does one have to have a unified anchoring system throughout the document, so one has to look up the name of the particular anchor that might be placed in that file?

(Of course it would be a trivial task to script adding filename-based anchors at the start of every file, but if Asciidoctorcan do it itself that would be a big bonus.).

mojavelinux

Oct 13, 2017; 9:13pm

Re: Subtopics/chapters in separate files?

Administrator

2681 posts

> is it possible to link from one included file to another by referencing the file name?

Yes. That's the inter-document xref feature, which is a source-to-source link.

See http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

(I'll admit that section could be clearer).

-Dan

On Fri, Oct 13, 2017 at 2:46 PM, ramendik [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I have reviewed the include documentation and it looks like it covers much of what I want for topic-based documentation, especially because of the leveloffset attribute. There is one question. however, that remains unclear.

is it possible to link from one included file to another by referencing the file name? Or does one have to have a unified anchoring system throughout the document, so one has to look up the name of the particular anchor that might be placed in that file?

(Of course it would be a trivial task to script adding filename-based anchors at the start of every file, but if Asciidoctorcan do it itself that would be a big bonus.).

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Subtopics-chapters-in-separate-files-tp5968p5973.html

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

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Oct 13, 2017; 9:14pm

Re: Subtopics/chapters in separate files?

Administrator

2681 posts

In reply to this post by ramendik

To be clear, it's as simple as:

xref:chapter-a.adoc#[Chapter A]

As of 1.5.7, the trailing '#' will no longer be required as it will recognize the .adoc extension by itself.

-Dan

On Fri, Oct 13, 2017 at 3:13 PM, Dan Allen <[hidden email]> wrote:

> is it possible to link from one included file to another by referencing the file name?

Yes. That's the inter-document xref feature, which is a source-to-source link.

See http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

(I'll admit that section could be clearer).

-Dan

On Fri, Oct 13, 2017 at 2:46 PM, ramendik [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I have reviewed the include documentation and it looks like it covers much of what I want for topic-based documentation, especially because of the leveloffset attribute. There is one question. however, that remains unclear.

is it possible to link from one included file to another by referencing the file name? Or does one have to have a unified anchoring system throughout the document, so one has to look up the name of the particular anchor that might be placed in that file?

(Of course it would be a trivial task to script adding filename-based anchors at the start of every file, but if Asciidoctorcan do it itself that would be a big bonus.).

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Subtopics-chapters-in-separate-files-tp5968p5973.html

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

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

ramendik

Oct 13, 2017; 9:23pm

Re: Subtopics/chapters in separate files?

8 posts

So if I use an inter-document link and then actually include the linked file and the file where the link is in the same document (using include statements), then the inter-document link will function as an intra-document link in that big document?

mojavelinux

Oct 13, 2017; 9:57pm

Re: Subtopics/chapters in separate files?

Administrator

2681 posts

Correct.

-Dan

On Fri, Oct 13, 2017 at 3:23 PM, ramendik [via Asciidoctor :: Discussion] <[hidden email]> wrote:

So if I use an inter-document link and then actually include the linked file and the file where the link is in the same document (using include statements), then the inter-document link will function as an intra-document link in that big document?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Subtopics-chapters-in-separate-files-tp5968p5977.html

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

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

ramendik

Oct 13, 2017; 10:21pm

Re: Subtopics/chapters in separate files?

8 posts

Thanks. This is perfect.

The context of my two threads is that I am coming in from DITA (not DocBook) and trying to get similar functionality for topic-based documentation. It looks like I can already have DITA-style topic files, maps, and links with the include stuff.