Subtopics/chapters in separate files?

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Subtopics/chapters in separate files?

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

Re: Subtopics/chapters in separate files?

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

Re: Subtopics/chapters in separate files?

ramendik
Thanks!
Reply | Threaded
Open this post in threaded view
|

Re: Subtopics/chapters in separate files?

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

Re: Subtopics/chapters in separate files?

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


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

Re: Subtopics/chapters in separate files?

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


(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



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Subtopics/chapters in separate files?

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

Re: Subtopics/chapters in separate files?

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

Re: Subtopics/chapters in separate files?

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