glossary conundrum

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

glossary conundrum

coley
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!
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

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

https://asciidoctor.org/docs/user-manual/#custom-styling-with-attributes explains how to apply custom styles.  IIUC, you could say

[.group1]#Term1 means Foo!#
[.group2]#Term2 means Bar!#

Hope this helps!
David Jencks

On Feb 6, 2020, at 7:44 AM, coley [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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!


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/glossary-conundrum-tp7578.html
To start a new topic under Asciidoctor :: Discussion, [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

abelsromero
In reply to this post by coley
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.
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

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

David Jencks

On Feb 6, 2020, at 8:26 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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.


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/glossary-conundrum-tp7578p7580.html
To start a new topic under Asciidoctor :: Discussion, [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

coley
In reply to this post by abelsromero
Thank you! I'll play around with it and report back if needed. :)
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

coley
In reply to this post by David Jencks
Thank you! I'll play around with it and report back if needed. :)
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

1marc1
In reply to this post by abelsromero
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.
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

abelsromero
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[]

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]

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)
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

Alexander Schwartz
In reply to this post by 1marc1
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 Schwartz (alexander.schwartz@gmx.net)
https://www.ahus1.de
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

1marc1
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.
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

Alexander Schwartz
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 Schwartz (alexander.schwartz@gmx.net)
https://www.ahus1.de
Reply | Threaded
Open this post in threaded view
|

Re: glossary conundrum

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