glossary conundrum

Hey, Asciidoc community! I'm a tech writer who is new to Asciidoc and find it so refreshingly clean, simple to learn, and fairly comprehensive. Thank you!

We are in the process of creating glossaries. The current opinion is a few separate glossaries geared toward the level of knowledge of the user. My preference, however, is one glossary that can be manipulated.

Let's say you have 3 distinct groups of potential readers and 50 terms to define. 20 terms apply to most readers. Then, there are 10 terms that apply only to Group 1, 10 for Group 2, and 10 for Group 3. Is there a way to have all 50 terms in one glossary, tagging the 10 terms each as Group 1, Group 2, and Group 3 respectively, and tagging the 20 terms as Groups 1, 2, & 3? And then readers could filter by group?

Thank you!

My understanding of css is limited, but I think you can do this by assigning styles to the terms and then adjusting the visibility with css and javascript.

You could also have a look at a https://asciidoctor.org/docs/user-manual/#include-partial.
You may need to enclose each term with as many tags as groups see it.

Another option is enclose each term with it's onwn unique tag, then have a doc for each group including only the ones you need. But with this approach you will end up with a very loooong include line.

I like this!  IIUC, this solution will statically generate 3 versions of your glossary, and not need any runtime modification through css or javascript.  My solution would generate 1 glossary page and (theoretically) allow multiple “runtime” views of it.

Thank you! I'll play around with it and report back if needed. :)

Thank you! I'll play around with it and report back if needed. :)

Hi Team,

Based on Abel's post I started to explore the partial includes for the purpose of including (parts of) other asciidoc files, but came up with a question.

Assume I have the following document called myfile.adoc:

== Title

General information that applies to everyone.

// tag::group1[]
This only applies to group 1.
// end::group1[]

// tag::group2[]
This only applies to group 2.
// end::group2[]

More general information that applies to everyone.

The question is: how do I include all text and the text that belongs to a specific tag? For example, the output I am looking for when (somehow) specifying the group1 tag would look like this:

Title

General information that applies to everyone.

This only applies to group 1.

More general information that applies to everyone.

I have tried various combinations of the wildcards and tag names, but seem to be unable to include everything that is untagged and selected parts that are tagged.

Further to this, I would like to be able to select multiple tags for inclusion. Let's say my example document had a total of 5 tags (group1...group5), then would it be possible to do something like

include::myfile.adoc[tags=**;group1;group4;group5]

...to end up with a document that includes all non-tagged text and the text for group1, 4 and 5?

I am running asciidoctor 2.0.10.

Thank you.

Marc.

I know this does not match what you want to do Marc, but in your case I'd would go for a different organization that offers the same final result.

For the sake of simplicity and ease of manteninance I would avoid having untagged and tagget sections in the included content.
I'd have a file with all the grouped terms defined by tag like the one below. But I would avoid using "all" unless you have lots of group, just add all related tags like in the third element.

// tag::group1[]
* This only applies to group 1.
// end::group1[]

// tag::group2[]
* This only applies to group 2.
// end::group2[]

// tag::group2[]
// tag::group1[]
* This only applies to group 1 or 2.
// end::group1[]
// end::group2[]

// tag::all[]
* This is some geenral term for everyone.
// end::all[]

... [show rest of quote]

Then from the files that are actualy renders just import what you need.

= Title

== General terms

include::glossary.adoc[tag=all]

== Terms for Group 1

include::glossary.adoc[tag=group1]

== Terms for Group 2

include::glossary.adoc[tag=group2]

== Terms for both (Group1 OR Group2)

include::glossary.adoc[tags=group1;group2]

... [show rest of quote]

That way you keep the access to contents in a separate file with single consistent way of tagging. And then you control what and how you want to show the info in another.

PS: I don't knwo if it's possible to tell to include tags matching all groups (and AND)

To achieve

Title

General information that applies to everyone.

This only applies to group 1.

More general information that applies to everyone.

you'll need to write an include like this:

include::tags.adoc[tags=**;!*;group1]

Adding "!*" to exclude all tagged content first is the key. You can then re-add all the groups you want to see one by one. See https://asciidoctor.org/docs/user-manual/#tag-filtering the documentation.

Alexander,

Thank you very much that works.

Prior to posting the question I had read the piece about tag filtering in the user manual. For "**", it states:

Select all the lines in the document except for lines with an include tag/end directive. Use this symbol if you want to include a file that has tag/end directives, but you want to ignore all those lines.

I therefore used that, followed by the tags I wanted to include.

A bit further down in the documentation it explains "**" as:

selects all the lines in the document; matches the default behavior of the include directive, except lines containing a tag directive; shorthand for **;* when used alone

These two descriptions seem to conflict with each other.

Based on my observations made by your solution, I would say that the second description matches the behavior.

Thanks again!

Marc.

Hello Marc,

I'm glad that I could help here.

It seems to me that the writer of the docs considered "lines with an include tag/end directive" only the lined starting and ending the snippet, but not the lined in between.

The docs are on GitHub. How would you describe it in your own words? Could you provide a pull request?

Cheers!

Alexander,

I have been thinking about this for a bit, wrapping my head around what "**" actually does, but I find it difficult to come up with a concise description.

My understanding of the "**" filter is that it will include the entire document, except individual lines containing a tag/end tag directive. This means that the text between the start and end of the tag directives is also included with this filter applied.

My initial understanding was that because the tag directives were excluded, so was the content between them. That's where I went wrong.

To clarify your solution

include::tags.adoc[tags=**;!*;group1]

"**" includes the entire document (minus individual lines that say things like // tag::group1[] and // end::group1[])
"!*" gets rid of all text between // tag and // end.
"group1" then includes the individual group.

For the benefit of others, you can also use an attribute that resolves to a tag name inside your include line.

For example:

:mygroup: group1
include::tags.adoc[tags=**;!*;{mygroup}]

Marc.