Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[suggestion] Control leveloffset with include indent level? #1616

Open
jaredmorgs opened this issue Dec 14, 2015 · 6 comments

Comments

Projects
None yet
2 participants
@jaredmorgs
Copy link
Member

commented Dec 14, 2015

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.

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Dec 15, 2015

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.

@mojavelinux mojavelinux added this to the discussion milestone Dec 15, 2015

@jaredmorgs

This comment has been minimized.

Copy link
Member Author

commented Dec 16, 2015

On Tue, 15 Dec 2015 at 10:16 Dan Allen notifications@github.com wrote:

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.

Yep, that is what I meant. Thanks for clarifying direction about that
aspect of the RFE.

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.

I'm thinking to the future where Asciidoctor could be used as a backend for
CCMS implementations where folder order holds no semantic meaning.

A good question to ask would be how folder depth plays a part in this
scenario if the content for the CCMS was stored in a single folder, with
the top-level element in each .adoc topic set to == Sect 1?.

/topics

Using a folder nesting strategy would potentially work, but you would need
to know where topics were stored to be able to reuse them easily.

/user_guide
/developer_guide
/reference_guide

I may be venturing into functionality outside of what the toolchain was
originally designed for, and it may be that a CCMS implementation would
just implement this functionality outside the toolchain when content was
built.

The ability for Asciidoctor to pull from a /topics folder with topics all
at the == Sect 1 level and let the root .adoc file act as a content spec

...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
#894.

Sounds like a good enhancement to strive for, however I do understand this
is non-trivial and would require significant scoping to ensure requirements
are fit for purpose.


Reply to this email directly or view it on GitHub
#1616 (comment)
.

Sent from Mobile.

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Dec 16, 2015

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.

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Dec 16, 2015

it may be that a CCMS implementation would just implement this functionality outside the toolchain when content was built.

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

include::another-file.adoc[indent=4]

...though this isn't much different than relative leveloffset to be honest.

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Dec 16, 2015

The ability for Asciidoctor to pull from a /topics folder with topics all at the == Sect 1 level and let the root .adoc file act as a content spec

That's precisely the design of the relative level offset.

@jaredmorgs

This comment has been minimized.

Copy link
Member Author

commented Dec 16, 2015

Yep, you're right. This is basically the same as [leveloffset].

On Wed, 16 Dec 2015 at 10:58 Dan Allen notifications@github.com wrote:

it may be that a CCMS implementation would just implement this
functionality outside the toolchain when content was built.

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

include::another-file.adoc[indent=4]

...though this isn't much different than relative leveloffset to be honest.


Reply to this email directly or view it on GitHub
#1616 (comment)
.

Sent from Mobile.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.