"Include directive" topic is included twice :)

[ggrossetie]

Chapter 31 and chapter 51:

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

Not sure if this is intended but we have id duplication on section titles include-partitioning, include-nonasciidoc...

[mojavelinux]

Uh oh. That was probably as a result of an improperly resolved merge conflict. Of course, that raises the question, where should it go. Surprisingly, I think the answer is neither of those locations. I think the most logic place for it is in the part "Structuring, Navigating, and Referencing Your Content".

Want to do a PR?

[ggrossetie]

Sure, I think the related PR is #506 but I didn't understand exactly the goal so I wasn't sure that this was intended or not...

[mojavelinux]

Definitely an accident. We had quite a few merge conflicts in that series of changes, so it's understandable why it happened.

[ggrossetie]

Definitely an accident. We had quite a few merge conflicts in that series of changes, so it's understandable why it happened.

Ok.

I think the most logic place for it is in the part "Structuring, Navigating, and Referencing Your Content".

I agree but as the the time we should introduce the include macro before: http://asciidoctor.org/docs/user-manual/#include-partial (30.4).

Section is an excellent reference, in that it gives all the information you could possibly need, but:
For an essential topic, it is introduced quite late in the guide (section 50)
It dives straight into the detail without demonstrating how it 'just works' for the most common use case of a document divided into chapter files
It references the Asciidoc manual
@rockyallen about Include directive in #506

I think "Basics", "File resolution" and maybe "AsciiDoc vs non-AsciiDoc files" should go before "30.4. Select Portions of a Document to Include".
Having said that, IMO "30.4. Select Portions of a Document to Include" is a specific topic and may be introduce later.

"Partitioning large documents and using leveloffset" could go in the part "Structuring, Navigating, and Referencing Your Content".

@mojavelinux @rockyallen What do you think ?

[rockyallen]

As of today it looks like:

31. Include Directive
    31.1. Basics
    31.2. File resolution
    31.3. Partitioning large documents and using leveloffset
    31.4. AsciiDoc vs non-AsciiDoc files
    31.5. Select Portions of a Document to Include
    31.6. Normalize Block Indentation
    31.7. Include Content from a URI
    31.8. Caching URI Content
    31.9. Include a File Multiple Times in the Same Document

Agreed that 31.3, 31.5 and 31.9 are all about organizing content in large documents, but I think they should be kept with the include topic if possible. Maybe regroup as:

31. Include Directive
    31.1. Basics
      31.1.1. File resolution
      31.1.2. AsciiDoc vs non-AsciiDoc files
      31.1.3. Normalize Block Indentation
      31.1.4. Include Content from a URI
      31.1.5. Caching URI Content
    31.2 Using include for Modular Documents
      31.2.1. Select Portions of a Document to Include
      31.2.2. Partitioning large documents and using leveloffset
      31.2.3. Include a File Multiple Times in the Same Document

?

[mojavelinux]

The duplicate has been removed. However, we haven't done any restructuring. Should we still do that?