Asciidoctor :: Discussion

multiple tags

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

Hedgehog

multiple tags

Hi,
I'm exploring Asciidoctor as a possible solution for documentation where a section of text (multiple paragraphs diagrams, formulas, tables etc) need to be included in multiple documents.

Context:
sec1 is included in doc1, doc2, doc3
sec2 is included in doc1, doc2
sec3 is included in doc1

I see the "include directive supports multiple tagged selection":
https://github.com/asciidoctor/asciidoctor/blob/master/test/reader_test.rb#L712

However I'm wondering if there is a more succinct syntax for tagging, say, sec1 than this (Ruby):
http://asciidoctor.org/docs/user-manual/#by-tagged-regions

#tag::doc1[]
#tag::doc2[]
#tag::doc3[]

Shared section 1 content here 

#end::doc1[]
#end::doc2[]
#end::doc3[]

this gets very painful for large amounts of documents.
Based on POLS I'd expect something like (Ruby):

#tags[doc1;doc2;doc3]

Shared section 1 content here 

#end[doc1;doc2;doc3]

Appreciate any suggestions or tips
Kind regards
Hedge

mojavelinux

Re: multiple tags

Administrator

Hedge,

I see from your message that there is a tagging case that we've overlooked. It would be nice to be able to assign multiple labels to a tagged region marker. However, the syntax a recommend would align with the conditional preprocessor directive. For example:

// tag::doc1,doc2[]

shared section

// end::doc1,doc2[]

We could even end it at different locations:

// tag::doc1,doc2[]

shared section

// end::doc1[]

not shared section

// end::doc2[]

I'm definitely willing to consider adding that to Asciidoctor if you file an issue.

Now, I'd like to suggest another approach to what you are trying to do. Instead of labeling the regions by which document they are included in, it would be more semantically correct to label the shared sections by what they are, then itemize which of those semantic regions you want to include in each document. For example:

// tag::intro[]

introduction content

// end::intro[]

// tag::background[]

background content

// end::background[]

// tag::sect1[]

first section

// end::sect1[]

Then, in doc1.adoc, you'd use:

include::shared.adoc[tags=intro,sect1]

If we added support for attribute interpolation in the include directive, then you could even make this list an attribute reference:

:doc1-tags: intro,sect1

include::shared.adoc[tags={doc1-tags}]

However, that example doesn't work atm.

Cheers,

-Dan

On Wed, Nov 12, 2014 at 5:33 PM, Hedgehog [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,
I'm exploring Asciidoctor as a possible solution for documentation where a section of text (multiple paragraphs diagrams, formulas, tables etc) need to be included in multiple documents.

Context:
sec1 is included in doc1, doc2, doc3
sec2 is included in doc1, doc2
sec3 is included in doc1

I see the "include directive supports multiple tagged selection":
https://github.com/asciidoctor/asciidoctor/blob/master/test/reader_test.rb#L712

However I'm wondering if there is a more succinct syntax for tagging, say, sec1 than this (Ruby):
http://asciidoctor.org/docs/user-manual/#by-tagged-regions
#tag::doc1[]
#tag::doc2[]
#tag::doc3[]

Shared section 1 content here 

#end::doc1[]
#end::doc2[]
#end::doc3[]
this gets very painful for large amounts of documents.
Based on POLS I'd expect something like (Ruby):
#tags[doc1;doc2;doc3]

Shared section 1 content here 

#end[doc1;doc2;doc3]
Appreciate any suggestions or tips
Kind regards
Hedge

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/multiple-tags-tp2451.html

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

Dan Allen | http://google.com/profiles/dan.j.allen

Hedgehog

Re: multiple tags

Hi,
Many thanks for the feedback and suggestions. Apologies for the long response.....
I'll think over the suggestion to use a more semantically correct approach.

Accepting that I'll use your suggestion for the current state of asciidoctor.... the following is to shed light on the use case, and why I's prefer to avoid attribute interpolation in the include directives (I think the current tags facility is sufficient), attributes referencing a list of tags.

The use case is to generate data dictionary/documentation *and* avoid having to maintain two mappings/indexes:
1). mapping each dictionary/document element/definition to the documents it is included in.
2). mapping documents to the various elements/definitions that are included in it.

In this use case, (or generally?) it makes more sense from a analyst/business PoV to choose 1). the reason I say this is that when writing the content I have in mind - where (in what context) is this being read. Hence it feels more natural to tag the content with the document it is to be used in.

If I understand your suggested (semantically correct) approach, I still need to maintain 2) above, or as you say " itemize which of those semantic regions you want to include in each document".

It is important to note that I agree one does need a listing(s) of what is included in a document.
However to my mind this is is the benefit of acsiidoctor.... it generates that for me in the form the ToC, index and glossary, etc.

Of course I accept a data dictionary is a specialized use case and writing asciidoctor to handle all the corner cases might eliminate its elegance/parsimony.
However, I do wonder: If I aim to write a asciidoctor document with something *for the content* that is much more than

\<various front matter directives\> 
include::shared.adoc[tags=doc1]
\<various end matter directives\>

is this a doumentation version of a code smell?

I intended that the question: "Is the right content in right document?" is handled by writing Cucumber features that verify the ToC, Glossary, Index, etc. (in the generated documents) contain what they should.
That is, I trust asciidoctor to include/generate what it has been instructed to (i.e. if not, it's a bug that needs to be reported).
This way my parent document.adoc keeps content related directives to a minimum and concentrates on non-content related directives.

Does that sound sane? Or am I going to be bitten a little later?

The suggested syntax

# tag::a,b,c[]

seems reasonable. While I don't yet understand the implenettaion choices, and whether this is feasible I do think

#tags[a;b;c]

is intuitive. Can tags not be ended with

#end[a;b]

?

Kind regards
Hedge

mojavelinux

Re: multiple tags

Administrator

Hedge,

In reading your explanation, I now realize that these two approaches for marking content for inclusion are equally correct in terms of semantics. It's not always the parent (i.e., master) document's responsibility to know what it is including. In certain use case, such as the data dictionary you have cited, it's more correct to "push" the content into the parent instead of have it explicitly pull the content.

So long as you are aware of the relationship between the parent document and included content, and choose the labeling system appropriately, I don't think you'll be bitten later.

I was biased towards maintaining the include list in the parent document because that's the solution that fits best in the use cases I frequently see in tech. Now I'm aware of my bias there.

What's important is that Asciidoctor does not dictate one solution over the other. That is definitely your choice to make as an author, and rightfully so.

Technically, you could implement the tag directives as you have proposed them today in Asciidoctor. You simply have to write a custom IncludeProcessor extension and handle the include processing logic. The downside to this approach is that it's all or nothing currently, meaning you have to handle all aspects of processing the include directive (tags, line offsets, etc). The upside is that you get full control :)

The reason we prefer the tag::a,b,c[] directive over tag::[a;b;c] is because the former follows the macro pattern used elsewhere in AsciiDoc (<name>::<target>[<attributes>]). One of the strengths of AsciiDoc is the consistency of the syntax, so we want to honor that as much as possible to get the most knowledge reuse. (Of course, if you implement your own IncludeProcessor, you have the choice to implement it however you want).

Would you like to follow-up by filing an issue to allow an include region to be marked with multiple tags?

Cheers,

-Dan

On Sun, Nov 16, 2014 at 4:13 PM, Hedgehog [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,
Many thanks for the feedback and suggestions. Apologies for the long response.....
I'll think over the suggestion to use a more semantically correct approach.

Accepting that I'll use your suggestion for the current state of asciidoctor.... the following is to shed light on the use case, and why I's prefer to avoid attribute interpolation in the include directives (I think the current tags facility is sufficient), attributes referencing a list of tags.

The use case is to generate data dictionary/documentation *and* avoid having to maintain two mappings/indexes:
1). mapping each dictionary/document element/definition to the documents it is included in.
2). mapping documents to the various elements/definitions that are included in it.

In this use case, (or generally?) it makes more sense from a analyst/business PoV to choose 1). the reason I say this is that when writing the content I have in mind - where (in what context) is this being read. Hence it feels more natural to tag the content with the document it is to be used in.

If I understand your suggested (semantically correct) approach, I still need to maintain 2) above, or as you say " itemize which of those semantic regions you want to include in each document".

It is important to note that I agree one does need a listing(s) of what is included in a document.
However to my mind this is is the benefit of acsiidoctor.... it generates that for me in the form the ToC, index and glossary, etc.

Of course I accept a data dictionary is a specialized use case and writing asciidoctor to handle all the corner cases might eliminate its elegance/parsimony.
However, I do wonder: If I aim to write a asciidoctor document with something *for the content* that is much more than
\<various front matter directives\> 
include::shared.adoc[tags=doc1]
\<various end matter directives\>
is this a doumentation version of a code smell?

I intended that the question: "Is the right content in right document?" is handled by writing Cucumber features that verify the ToC, Glossary, Index, etc. (in the generated documents) contain what they should.
That is, I trust asciidoctor to include/generate what it has been instructed to (i.e. if not, it's a bug that needs to be reported).
This way my parent document.adoc keeps content related directives to a minimum and concentrates on non-content related directives.

Does that sound sane? Or am I going to be bitten a little later?

The suggested syntax
# tag::a,b,c[]
seems reasonable. While I don't yet understand the implenettaion choices, and whether this is feasible I do think
#tags[a;b;c]
is intuitive. Can tags not be ended with
#end[a;b]
?

Kind regards
Hedge

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/multiple-tags-tp2451p2467.html

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

Dan Allen | http://google.com/profiles/dan.j.allen

Hedgehog

Re: multiple tags

Hi Dan,
Thanks for the feedback.

My reflex is to agree that we should follow the macro pattern used elsewhere in AsciiDoc (<name>::<target>[<attributes>]).

I'll mull over this discussion for a while, and try to ingest some of the asciidoctor codebase before framing an issue/feature request.

Kind regards
Hedge