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

Add glossary #210

Merged
merged 5 commits into from
Nov 19, 2023
Merged

Add glossary #210

merged 5 commits into from
Nov 19, 2023

Conversation

jngrad
Copy link
Collaborator

@jngrad jngrad commented Nov 18, 2023

Add a glossary for:

  • acronyms (HPC, STEM, FAIR, ...)
  • skill codes (DOCBB, SWREPOS, ...)
  • technical terms (COBOL, GitHub, SysOp, design pattern, ...)

Comment on lines +41 to +45
- \newglossary[skills.glg]{skills}{skills.gls}{skills.glo}{Skill codes}
- \makeglossaries
- \input{glossary.tex}
- \newglossaryentry{DOCBB}{name={DOCBB},type={skills},description={Creating documented code building blocks}}
- \newglossaryentry{LIBS}{name={LIBS},type={skills},description={Building distributable libraries}}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: I'm defining these acronyms here, because they have a type, and thus require a \newglossary call that declares a new skills namespace with file extension .skills.*. By keeping these terms separate from the terms defined in glossary.tex, it is possible to re-use glossary.tex in the other manuscripts.

@@ -23,12 +24,18 @@ all: $(objects)
-M pdfa-$(MAKE_PDFA)=1 \
-M date="`date "+%B %e, %Y"`" \
-M datexmp="`date "+%F"`" \
-M linkcolor=darkgray \
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This color is almost black, so that acronyms and terms do not attract too much attention, while still being perceptible as links. One could also make this color black, then the terms (and links to figures/tables) would be indistinguishable from the regular text.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened in on my home pc with Adobe Acrobat and since it does not give a 'hover preview' I think it makes sense to keep the color as darkgray.

@jngrad
Copy link
Collaborator Author

jngrad commented Nov 18, 2023

@CaptainSifff, @jpthiele, @MakisH Here is a proof-of-concept for a glossary, as discussed earlier today in the Zoom call. Let me know if this is desirable. If not, no hard feelings; I'll recycle this work in my personal LaTeX guidebook anyway. 😃

I opted not to use tomncooper/pandoc-gls, because it is less flexible, the syntax is cryptic to novice users, and it doesn't work inside LaTeX environments. Instead the glossaries package is used. Maybe it can be used with tooltips (#158)?

Many thanks to @ljgarcia for identifying acronyms in #205, this helped me speed up the process a lot.

@jngrad jngrad mentioned this pull request Nov 18, 2023
@CaptainSifff
Copy link
Collaborator

@jngrad Have you thought about presenting your guidebook at deRSE24?

@CaptainSifff
Copy link
Collaborator

CaptainSifff commented Nov 18, 2023

It looks nice! Do you think, that the abbreviations are complete?

Copy link
Collaborator

@MakisH MakisH left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice! Works nicely in Okular and Evince. Some minor suggestions to consider.

Closes #158 (which was previously closed as not planned).

competencies.md Outdated Show resolved Hide resolved
glossary.tex Outdated Show resolved Hide resolved
glossary.tex Outdated Show resolved Hide resolved
competencies.md Outdated Show resolved Hide resolved
@jpthiele
Copy link
Collaborator

I agree with Gerasimos points.
Although the first one should only be addressed if technically easy to change, no need for another LaTeX rabbit hole :)

On a side note: Adobe Acrobat explicitly tells me the PDF is PDF/A compatible, which is nice!

@jngrad jngrad marked this pull request as ready for review November 19, 2023 16:43
Copy link
Collaborator

@MakisH MakisH left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the two-columns is tricky. Looks already very good!

Tiny suggestion (I cannot make it in GitHub):

- static analysis automated procedure to detect software bugs in source code without actually executing the code.
+ static analysis automated procedure to detect software bugs in source code without executing the code.

to save a "useless" new line that only has the page number "9":

Screenshot from 2023-11-19 19-28-48

Edit: Edited the file directly, to help merging it faster.

@CaptainSifff CaptainSifff merged commit ff10286 into main Nov 19, 2023
3 checks passed
@jngrad jngrad deleted the glossary branch November 19, 2023 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants