Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
[suggestion] Control leveloffset with include indent level? #1616
I've been experimenting a lot today with http://asciidoctor.org/docs/user-manual/#relative-leveloffset and it's fantastic that you can keep all your .adoc files at Section 1 level and include them wherever you want in the document.
One thing that has caused me some difficulty today is getting the attribute level attached to the include directive correct.
I wonder if it would be possible to have Asciidoctor process leveloffset implicitly based on the indent level of includes in the parent document.
The way I've set up my docs repo is to set all .adoc topics as Sect 1 heading types. This lets me reliably include them and know the leveloffset I need to specify to have them include correctly.
Is this type of logic something that Asciidoctor could employ, to make using a common repository of topics as reusable chunks in, and across, documents?
There would, of course, need to be standards set about what does "indent" look like. Two spaces? Four spaces? Once that requirement has been set, you could implement the solution around that understanding.
By "indent", do you mean indenting the include directive from the left margin? If that's what you mean, I would say we don't want to do that. I believe one of the key strong points of the AsciiDoc syntax is that it is left aligned. This makes it easier to understand and saves you from having to waste time banging away at the space bar and counting spaces.
With that said, I do like the idea that leveloffset is associated with some semantic information in the document. One possible way to do this is to link leveloffset to the folder depth of the included document. This could be implemented using an IncludeProcessor extension, which takes over the responsibility of handling the include directive.
...but this also brings us back to a long-running discussion in Asciidoctor that an include is not a subdocument. It's very clear from past discussion that we need a subdocument macro that is used for combining documents in a semantic way. The include directive has no idea about the structure of the document because it is processed before the syntax is parsed. It is quite literally a coalescer and nothing more. See #894.
On Tue, 15 Dec 2015 at 10:16 Dan Allen email@example.com wrote:
With that said, I do like the idea that leveloffset is associated with some
A good question to ask would be how folder depth plays a part in this
Using a folder nesting strategy would potentially work, but you would need
I may be venturing into functionality outside of what the toolchain was
The ability for Asciidoctor to pull from a /topics folder with topics all
Sent from Mobile.
The beauty of the extension mechanism is that you get to decide what determines hierarchy in your system. So a given CMS could document an implicit hierarchy and then implement that using a custom IncludeProcessor. Granted, that does couple the content to the system, but if the content is designed to be managed by that system, then it is a reasonable tradeoff.
Basically what I'm saying is that the implicit hierarchy can be defined however you want to define it thanks to the IncludeProcessor. All core needs to do, which is does, it provide this hook.
...not outside the toolchain, but rather via the extension mechanism.
Btw, instead of indenting the include, you can provide an indent property on the include directive. This preserves the left aligned syntax while communicating the same intent.
...though this isn't much different than relative leveloffset to be honest.
Yep, you're right. This is basically the same as [leveloffset].
On Wed, 16 Dec 2015 at 10:58 Dan Allen firstname.lastname@example.org wrote:
Sent from Mobile.