/packages/tex/support/makeglossariesgui/src/doc/makeglossariesgui-en.xml on ftp.icm.edu.pl

<?xml version="1.0" encoding="UTF-8"?>
<manual fontenc="T1">
 <preambleDefault handler: 
>
 <title>
 User Manual for
 <dict tag="appname"/>
 version
 <nbsp/>
 <dict tag="appversion"/>
 </title>
 <author>
 Nicola L. C. Talbot
 
 <url www="www.dickimaw-books.com"/>
 </author>
Default handler: 
 <date>
 <dict tag="appdate"/>
 </date>
Default handler: 
 <newacro short="GUI" long="graphical user interface" tag="gui"/>
Default handler: 
 <newterm tag="makeglossaries" text="makeglossaries" fmt="tt" description="a Perl script provided with the glossaries package which runs either makeindex or xindy, depending on the settings in the .aux file"/>
 <newterm tag="makeglossarieslite" text="makeglossaries-lite.lua" fmt="tt" description="a Lua script provided with the glossaries package as a light-weight alternative to makeglossaries (the .lua extension may be omitted or replaced with .exe, according to the TeX distribution)"/>
 <newterm tag="bib2gls" text="bib2gls" fmt="tt" description="an indexing application designed specifically for use with glossaries-extra.sty"/>
 <newterm tag="makeindex" text="makeindex" fmt="tt" description="an indexing application"/>
 <newterm tag="xindy" text="xindy" fmt="tt" description="an indexing application written in Perl"/>
 <newterm tag="lookandfeel" text="Look and Feel" description="the appearance (look) of Java applications and how the widgets behave (feel)"/>
 </preamble>
 <document>
 <node tag="introduction" type="chapter" title="Introduction">
 
 The
 <latex/>
 <sty>
 glossaries
 </sty>
 package has three methods of generating a glossary (list of abbreviations, terms or symbols): directly using
 <latex/>
 , using
 <term tag="makeindex"/>
 or using
 <term tag="xindy"/>
 . The first option requires two
 <latex/>
 runs (as with cross-references), the last two options requires a
 <latex/>
 run followed by running the indexing application (
 <term hyper="false" tag="makeindex"/>
 or
 <term hyper="false" tag="xindy"/>
 ), followed by another
 <latex/>
 run. The
 <sty>
 glossaries-extra
 </sty>
 package provides two more methods (just using
 <cs tag="printunsrtglossary"/>
 or using
 <cs tag="printunsrtglossary"/>
 with
 <term tag="bib2gls"/>
 ). These last two methods aren't supported by
 <app/>
 (although it will flag documents that require
 <term tag="bib2gls"/>
 if detected, as part of its diagnostics). Your document may require additional applications, such as bibtex, but that's outside of the scope of
 <app/>
 .
 
 
 The
 <sty>
 glossaries
 </sty>
 package provides a Perl script called
 <term tag="makeglossaries"/>
 that's intended to simplify this step for options 2 and 3. However, sometimes things can go wrong and users may not be able to work out why. The
 <term hyper="false" tag="makeglossaries"/>
 script tries to diagnose problems, but not everyone wants to install Perl for some reason (which is a shame, as there are some useful
 <tex/>
 -related Perl scripts, including
 <term tag="xindy"/>
 ). The
 <sty>
 glossaries
 </sty>
 package also provides a light-weight Lua alternative,
 <term tag="makeglossarieslite"/>
 , but that doesn't provide any diagnostics.
 <app/>
 is a Java application that (when run in batch mode) can be used instead of
 <term hyper="false" tag="makeglossaries"/>
 or
 <term hyper="false" tag="makeglossarieslite"/>
 however its primary purpose is a
 <acr tag="gui"/>
 tool for determining what's gone wrong when the glossary doesn't appear or is incomplete.
 
 
 Since
 <app/>
 is written in Java, you'll need the Java Runtime Environment installed. If your document build process supports the conditional execution of commands, then you can test if
 <app/>
 ,
 <term tag="makeglossaries"/>
 or
 <term tag="makeglossarieslite"/>
 are required by searching the log file for the presence of the command
 <cs tag="@istfilename"/>
 . (The argument is the style file. The extension determines whether
 <term tag="makeindex"/>
 or
 <term tag="xindy"/>
 is required.)
 
 
 The
 <app/>
 application runs in
 <acr tag="gui"/>
 mode by default, but can be run in batch mode using the
 <opt tag="batch"/>
 command line option. Command line invocation:
 
 
 <code>
 makeglossariesgui
 </code>
 [
 <meta>
 options
 </meta>
 ] [
 <meta>
 filename
 </meta>
 ]
 
 
 The
 <meta>
 filename
 </meta>
 must be supplied when run in batch mode (the
 <file>
 .aux
 </file>
 extension may be omitted), but is optional in
 <acr tag="gui"/>
 mode. The
 <meta>
 filename
 </meta>
 should be the auxiliary file produced by the
 <latex/>
 run, but may also be the
 <file>
 .tex
 </file>
 or
 <file>
 .log
 </file>
 file if it has the same basename as the auxiliary file and is located in the same directory. Unlike
 <term tag="makeglossaries"/>
 and
 <term tag="makeglossarieslite"/>
 ,
 <meta>
 filename
 </meta>
 may include the directory path.
 
 
 Available options:
 <dl>
 <dt>
 <opt tag="batch"/>
 (or
 <code>
 -b
 </code>
 )
 </dt>
 <dd>
 Invoke
 <app/>
 in batch mode (
 <meta>
 filename
 </meta>
 must be supplied). Note that the extra checks that parse the log file aren't performed in batch mode.
 </dd>
 <dt>
 <opt tag="gui"/>
 </dt>
 <dd>
 Invoke
 <app/>
 in
 <acr tag="gui"/>
 mode (default).
 </dd>
 <dt>
 <opt tag="quiet"/>
 </dt>
 <dd>
 Suppress (non-error) messages that would otherwise have been written to STDOUT.
 </dd>
 <dt>
 <opt tag="dry-run"/>
 (or
 <code>
 -n
 </code>
 )
 </dt>
 <dd>
 Dry run mode (don't run the indexing application).
 </dd>
 <dt>
 <opt tag="nodry-run"/>
 </dt>
 <dd>
 Not dry run mode (default).
 </dd>
 <dt>
 <opt tag="debug"/>
 </dt>
 <dd>
 Print debug messages to STDOUT.
 </dd>
 <dt>
 <opt tag="version"/>
 (or
 <code>
 -v
 </code>
 )
 </dt>
 <dd>
 Print the version details to STDOUT and exit.
 </dd>
 <dt>
 <opt tag="help"/>
 (or
 <code>
 -h
 </code>
 )
 </dt>
 <dd>
 Print a brief summary of available options to STDOUT and exit.
 </dd>
 </dl>
 
 
 When run in batch mode,
 <app/>
 behaves much like
 <term tag="makeglossaries"/>
 . It reads the auxiliary file to determine whether to use
 <term tag="makeindex"/>
 or
 <term tag="xindy"/>
 and what options to pass to them. The
 <acr tag="gui"/>
 <ref text="settings" tag="properties"/>
 will be honoured.
 
 </node>
 <node type="chapter" tag="main" title="Basic Use (GUI Mode)">
 
 A file can be loaded from the command line invocation (see
 <ref tag="introduction"/>
 ) or in the
 <acr tag="gui"/>
 using the
 <menu tag="file.open"/>
 menu item. You can also use the load file button on the toolbar or (if permitted by your operating system) drag and drop the file onto the main window. The input file should be the
 <file>
 .aux
 </file>
 file created by
 <latex/>
 , but if you try to load the main document
 <file>
 .tex
 </file>
 file or the
 <file>
 .log
 </file>
 transcript file,
 <app/>
 will assume you meant the associated
 <file>
 .aux
 </file>
 file. (If you have used
 <latex/>
 's
 <file>
 -jobname
 </file>
 or
 <file>
 -output-directory
 </file>
 options, then you won't be able to use the
 <file>
 .tex
 </file>
 file and will have to use either the
 <file>
 .aux
 </file>
 or
 <file>
 .log
 </file>
 file.)
 
 <example>
 
 Suppose you have the following document (called, say,
 <file>
 basic-sample.tex
 </file>
 ):
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makeglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A \gls{sample} document. \printglossaries \end{document}
 </pre>
 
 First run
 <latex/>
 the usual way. This should create the auxiliary file
 <file>
 basic-sample.aux
 </file>
 as well as some other files including
 <file>
 basic-sample.glo
 </file>
 and
 <file>
 basic-sample.ist
 </file>
 . Now load the auxiliary file (
 <file>
 basic-sample.aux
 </file>
 ) into
 <app/>
 . (Since the main
 <file>
 .tex
 </file>
 file has the same basename as the
 <file>
 .aux
 </file>
 file, you can also use that, as mentioned above.)
 
 
 Once
 <app/>
 has successfully loaded the
 <file>
 .aux
 </file>
 file, it will run
 <term tag="makeindex"/>
 on the associated
 <file>
 .glo
 </file>
 file (with the
 <file>
 .ist
 </file>
 file as the style). In this case, there are no problems with the document and the
 <file>
 .tex
 </file>
 file is now ready for another
 <latex/>
 run. The general information panel (
 <ref tag="basicsample"/>
 ) shows a summary of the document glossaries. In this case, there's only one glossary (the
 <file>
 main
 </file>
 one). If you edit the document source code (
 <file>
 .tex
 </file>
 file) you can use the
 <menu tag="file.reload"/>
 menu item to reload the updated
 <file>
 .aux
 </file>
 file in
 <app/>
 .
 
 
 <float type="figure" tag="basicsample" caption="General Information Panel (Basic Sample)" pos="htbp">
 <image src="images/basic-sample.png" scale="0.8" alt="image of general information panel"/>
 </float>
 
 
 In this example, only one entry has been indexed in the
 <file>
 main
 </file>
 glossary. You can find out more information by clicking on the
 <dq>
 Details
 </dq>
 link, which will open the window shown in
 <ref tag="basicsampledetails"/>
 .
 
 
 <float type="figure" tag="basicsampledetails" caption="Entry Details (Basic Sample)" pos="tbp">
 <image src="images/basic-sample-details.png" alt="image of details window"/>
 </float>
 
 
 Since only one entry has been used, there's only one row. The first column lists the entry's label, the second column lists the entry's sort field and the third column shows the number of times that entry was indexed in the document. If you have a long list of entries, you can use the search box to find an entry according to its
 
 label
 
 . (The sort column isn't searched.) Regular expressions are permitted.
 
 
 The
 <button tag="diagnostics.title"/>
 tab (
 <ref tag="basicsamplediagnostics"/>
 ) provides information, warnings and suggestions. In this example, there are no errors detected, so it just provides suggestions and some links on how to incorporate
 <term tag="makeglossaries"/>
 into your document build process. There are also two buttons provided to test the
 <term tag="makeglossaries"/>
 and
 <term tag="makeglossarieslite"/>
 scripts. In the first case, the action will also test if Perl is installed.
 
 
 <float type="figure" tag="basicsamplediagnostics" caption="Diagnostics Tab (Basic Sample)" pos="tbp">
 <image scale="0.75" src="images/basic-sample-diagnostics.png" alt="image of diagnostics window"/>
 </float>
 
 </example>
 
 If you have defined an entry in your document, but it's not listed in the details window for the relevant glossary, then it hasn't been indexed in your document. Remember that the commands described in section
 <nbsp/>
 9 (
 <dq>
 Using Glossary Terms Without Links
 </dq>
 ) of the
 <sty>
 glossaries
 </sty>
 manual don't index the terms. These essentially are all the commands in the form
 <backslash/>
 <file>
 glsentry
 </file>
 <meta>
 field
 </meta>
 or
 <backslash/>
 <file>
 glossentryname
 </file>
 <meta>
 field
 </meta>
 , such as
 <cs tag="glsentrytext"/>
 ,
 <cs tag="glsentryshort"/>
 ,
 <cs tag="glsentrylong"/>
 or
 <cs tag="glossentryname"/>
 , and their case-changing variants. Also
 <cs tag="glsentrytitlecase"/>
 and
 <cs tag="glshyperlink"/>
 .
 
 
 If you're using the
 <sty>
 glossaries-extra
 </sty>
 package, remember that the
 <file>
 noindex
 </file>
 option will suppress indexing.
 
 <example>
 
 Now let's consider the following document (called, say,
 <file>
 missing-sort.tex
 </file>
 ):
 
 <pre>
 \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[xindy]{glossaries} \makeglossaries \newglossaryentry{S}{name={\S}, description={section symbol}} \newglossaryentry{alpha}{name={\ensuremath{\alpha}}, description={alpha}} \newglossaryentry{beta}{name={$\beta$},text={\beta}, description={beta}} \begin{document} Test: \gls{S}, $\gls{alpha}$, $\gls{beta}$. \printglossaries \end{document}
 </pre>
 
 As before, run
 <latex/>
 as usual on this document. Since the
 <file>
 xindy
 </file>
 package option has been used, this will create a
 <file>
 .xdy
 </file>
 file instead of a
 <file>
 .ist
 </file>
 file and the
 <file>
 .glo
 </file>
 file is now in
 <term tag="xindy"/>
 's format. There are, however, problems with this document. The
 <sty>
 glossaries
 </sty>
 manual advises using the
 <file>
 sort
 </file>
 key for entries that contain special characters or commands in the entry's name. This document hasn't followed that advice, and xindy will complain. The
 <file>
 S
 </file>
 entry just causes a warning:
 
 <blockquote>
 Would replace complete index key with empty string, ignoring
 </blockquote>
 
 and the
 <file>
 S
 </file>
 entry is ignored. The
 <file>
 alpha
 </file>
 and
 <file>
 beta
 </file>
 entries cause an error:
 
 <blockquote>
 index 0 should be less than the length of the string
 </blockquote>
 
 Again the entries are ignored, but the message is fairly cryptic. If we load the auxiliary file (
 <file>
 missing-sort.aux
 </file>
 ) into
 <app/>
 , these problems are detected, and the following error message is displayed:
 
 <blockquote>
 Xindy has ignored one or more entries with empty sort strings. Xindy failed with exit code 1.
 </blockquote>
 
 Once this error message has been dismissed, the
 <button tag="diagnostics.title"/>
 tab should automatically be selected (see
 <ref tag="missingsortdiagnostics"/>
 ). This identifies the problem entries and recommends a solution, in this case, add the
 <file>
 sort
 </file>
 key to the entry definition. The actual warning and error message reported by
 <term tag="xindy"/>
 are shown at the end. (You can adjust the font used by these messages if you like, see
 <ref tag="properties"/>
 .)
 
 
 <float type="figure" tag="missingsortdiagnostics" caption="Diagnostics Panel" pos="tbp">
 <image src="images/missing-sort-diagnostics.png" scale="0.8" alt="image of diagnostics panel"/>
 </float>
 
 
 In the
 <button tag="main.title"/>
 panel, the
 <dq>
 Details
 </dq>
 link can again be used to view the list of indexed entries, but now the problematic entries are shown in red (see
 <ref tag="missingsortdetails"/>
 ).
 
 
 <float type="figure" tag="missingsortdetails" caption="Entry Details (Problematic Entries)" pos="htbp">
 <image src="images/missing-sort-details.png" alt="image of details window with rows displayed in red"/>
 </float>
 
 </example>
 
 <app/>
 actually performs more problem-checking than
 <term tag="makeglossaries"/>
 as it also tries to parse the log file for certain messages (but only in
 <acr tag="gui"/>
 mode). This is illustrated in the next example, which won't generate any error messages from
 <term tag="makeglossaries"/>
 .
 
 <example>
 
 Spot what's wrong with the following document:
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makeglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A \gls{sample} document. \printglossary[type=acronym] \end{document}
 </pre>
 
 If you use the normal method of
 <latex/>
 ,
 <term tag="makeglossaries"/>
 ,
 <latex/>
 , you won't get any error messages, but the glossary won't be displayed. Why not? If we switch from
 
 <pre>
 \usepackage{glossaries}
 </pre>
 
 to
 
 <pre>
 \usepackage{glossaries-extra}
 </pre>
 
 then we do finally get an error:
 
 <blockquote>
 ! Package glossaries-extra Error: Glossary type
 <sq>
 acronym
 </sq>
 doesn't exist.
 </blockquote>
 
 The
 <sty>
 glossaries-extra
 </sty>
 package is stricter than the base
 <sty>
 glossaries
 </sty>
 package. The problem here is that I've used
 <file>
 type=acronym
 </file>
 , but there's no glossary with that label. (I haven't used the
 <file>
 acronym
 </file>
 option.) If you're not using the extension package, this is harder to pick up, but
 <app/>
 will notify you of the problem. This example document will trigger the error
 
 <blockquote>
 No glossary
 <sq>
 acronym
 </sq>
 .
 </blockquote>
 
 and the diagnostics panel will show the message:
 
 <blockquote>
 It looks as though you might have done something like
 <code>
 <cs tag="printglossary"/>
 [type=
 <marg>
 acronym
 </marg>
 ]
 </code>
 , but there's no
 <file>
 acronym
 </file>
 glossary.
 </blockquote>
 
 If you switch to the
 <button tag="main.title"/>
 panel, the labels for the glossaries defined in the document are listed next to
 <dq>
 <dict tag="main.list"/>
 </dq>
 so you can check the indicated type against it. In this example, the list has only the single label
 <dq>
 main
 </dq>
 .
 
 </example>
 
 Remember that you not only have to define your entries, but you also have to index them if you want them to appear in the glossary. The
 <sty>
 glossaries
 </sty>
 package provides many commands that index entries, the most commonly used one being
 <cs tag="gls"/>
 , which displays the text associated with the entry, indexes the entry, marks it as having been used and (if the
 <sty>
 hyperref
 </sty>
 package has been loaded) also creates a link to the definition in the glossary. Other commands provide variations, such as displaying different text or not changing the
 <dq>
 first use flag
 </dq>
 . In particular, the
 <cs tag="glsadd"/>
 command only indexes the entry without displaying any text.
 
 <example>
 
 In the sample document below, I've defined an entry but it hasn't been indexed anywhere in the document.
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makeglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A sample document. \printglossaries \end{document}
 </pre>
 
 My first step, as usual, is to run
 <latex/>
 on this document, which will create the
 <file>
 .aux
 </file>
 file. Now if I try loading this file into
 <app/>
 I get the error message:
 
 <blockquote>
 No entries were found for glossary
 <sq>
 main
 </sq>
 .
 </blockquote>
 
 The diagnostics panel shows the following message:
 
 <blockquote>
 There were no entries listed for the
 <file>
 main
 </file>
 glossary. Remember that you must index entries for them to appear in the glossary using the commands provided by the glossaries package. Entries that have been defined but not indexed won't be listed. If you don't want to use this glossary, add the
 <file>
 nomain
 </file>
 package option to your document. Check the following:
 <ul>
 <li>
 Have you used commands like
 <cs tag="gls"/>
 or
 <cs tag="glsadd"/>
 in the document? (If you haven't, you need to add them.)
 </li>
 <li>
 If you have used commands like
 <cs tag="glsadd"/>
 or
 <cs tag="glsaddall"/>
 in the preamble, have you remembered to put them
 
 after
 
 <cs tag="makeglossaries"/>
 </li>
 <li>
 If you have at least version 4.24 of the glossaries package, have you used the debug option? (That might provide some more information for me to analyse.)
 </li>
 </ul>
 </blockquote>
 
 (The sentence referencing
 <file>
 nomain
 </file>
 only appears if there are no entries for the
 <file>
 main
 </file>
 glossary, but not for any other glossaries.)
 
 </example>
 
 Remember that if you use
 <cs tag="makenoidxglossaries"/>
 , you don't need
 <term tag="makeindex"/>
 or
 <term tag="xindy"/>
 .
 
 <example>
 
 Consider the following document:
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makenoidxglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A \gls{sample} document. \printnoidxglossaries \end{document}
 </pre>
 
 If I load the
 <file>
 .aux
 </file>
 file for this document into
 <app/>
 , I get the following message in the diagnostics panel:
 
 <blockquote>
 It seems you've used
 <cs tag="makenoidxglossaries"/>
 , which means you don't need xindy or makeindex, you just need a second LaTeX run to get the glossary up to date.
 </blockquote>
 
 Note that
 <app/>
 can still provide some limited diagnostics even when
 <cs tag="makenoidxglossaries"/>
 has been used. To illustrate this, if we modify the above sample document slightly, introducing an error:
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makenoidxglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A \gls{sample} document. \printnoidxglossary[type=acronym] \end{document}
 </pre>
 
 This provides some additional information in the diagnostics panel:
 
 <blockquote>
 
 Package glossaries Warning: Empty glossary for
 <code>
 <cs tag="printnoidxglossary"/>
 [type=
 <marg>
 acronym
 </marg>
 ]
 </code>
 Rerun may be required (or you may have forgotten to use commands like
 <cs tag="gls"/>
 ) on input line 13.
 
 
 It looks as though you might have done something like
 <code>
 <cs tag="printnoidxglossary"/>
 [type=
 <marg>
 acronym
 </marg>
 ]
 </code>
 , but there's no
 <file>
 acronym
 </file>
 glossary.
 
 </blockquote>
 
 So
 <app/>
 picks up the error.
 
 </example>
 
 Note that
 <app/>
 also looks for warnings from the
 <sty>
 glossaries
 </sty>
 package, so if you are encountering any problems, make sure you haven't suppressed the warnings with the
 <file>
 nowarn
 </file>
 package option.
 
 <example>
 
 In this example I've omitted
 <cs tag="printglossary"/>
 from the document:
 
 <pre>
 \documentclass{article} \usepackage{glossaries} \makeglossaries \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} A \gls{sample} document. \end{document}
 </pre>
 
 This doesn't cause any problems for
 <term tag="makeindex"/>
 as all the associated files have been created correctly. The document simply doesn't load the file generated by
 <term tag="makeindex"/>
 as there's no
 <cs tag="printglossary"/>
 (or
 <cs tag="printglossaries"/>
 ). However the
 <sty>
 glossaries
 </sty>
 package does generate a warning, and this warning is picked up by
 <app/>
 and displayed in the diagnostics panel:
 
 <blockquote>
 Package glossaries Warning: No
 <cs tag="printglossary"/>
 or
 <cs tag="printglossaries"/>
 found. (Remove
 <cs tag="makeglossaries"/>
 if you don't want any glossaries.) This document will not have a glossary.
 </blockquote>
 
 If you suppress these warnings then
 <app/>
 can't help.
 
 </example>
 
 Sometimes things can go so badly wrong that
 <latex/>
 doesn't even generate an auxiliary file. In this case you can load the
 <file>
 .log
 </file>
 file instead. (You'll need to change the file selector filter to show all files.)
 <app/>
 will parse the log file to see if it recognises any of the error messages. Some
 <latex/>
 error messages can be quite crytic so there's no guarantee that
 <app/>
 will be able to help, but it might detect something useful. Note that this option is only available in
 <acr tag="gui"/>
 mode.
 
 <example>
 
 Consider the following document:
 
 <pre>
 \batchmode \documentclass{beamer} \usepackage{glossaries} \makeglossaries \newglossaryentry{sample}{name=sample,first={\textit{sample}}, description={an example}} \begin{document} \begin{frame} \gls{sample} \end{frame} \begin{frame} \printglossary \end{frame} \end{document}
 </pre>
 
 This document goes badly wrong. The first error message is:
 
 <pre>
 ! Undefined control sequence. \in@ #1#2->\begingroup \def \in@@
 </pre>
 
 If I load the log file into
 <app/>
 , the diagnostic panel displays the following:
 
 <blockquote>
 
 Since the aux file doesn't exist, there's not much I can do to help, but I'll parse the log file in case there are any clues there.
 
 
 It's possible that there's an expansion issue involving a fragile command. Things to check for:
 
 <ul>
 <li>
 Have you used a class like
 <file>
 beamer
 </file>
 that doesn't make common formatting commands like
 <cs tag="textit"/>
 robust?
 </li>
 <li>
 Have you tried using
 <cs tag="protect"/>
 in front of fragile commands contained within your entry definitions?
 </li>
 <li>
 Have you tried switching off the expansion using commands like
 <cs tag="glsnoexpandfields"/>
 ? (See section 4.6 Expansion in the
 <file>
 glossaries
 </file>
 user manual.)
 </li>
 </ul>
 </blockquote>
 
 The problem here is that a fragile command has been used in the entry definition. The problematic command in this example is
 <cs tag="textit"/>
 , which is normally robust, but it happens to be fragile with the
 <file>
 beamer
 </file>
 class. The solution is to either protect the problematic command with
 <cs tag="protect"/>
 or use
 <cs tag="glsnoexpandfields"/>
 before you define the entries. For example:
 
 <pre>
 \documentclass{beamer} \usepackage{glossaries} \makeglossaries \glsnoexpandfields \newglossaryentry{sample}{name=sample,first={\textit{sample}}, description={an example}} \begin{document} \begin{frame} \gls{sample} \end{frame} \begin{frame} \printglossary \end{frame} \end{document}
 </pre>
 </example>
 
 The main panel shows the character encoding that
 <app/>
 believes is being used by the indexing application and, if detected, the document input encoding. Since
 <term tag="makeindex"/>
 only supports characters in the range 1 to 255,
 <app/>
 assumes ISO-8859-1 (Latin-1) for
 <term tag="makeindex"/>
 and will add an advisory note if the document class uses a different encoding.
 
 <example>
 
 Consider the following example:
 
 <pre>
 \documentclass{article} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage[style=indexgroup]{glossaries} \makeglossaries \newglossaryentry{elite}{name={
 élite},description={select group}} \begin{document} \gls{elite} \printglossary \end{document}
 </pre>
 
 This document is saved as UTF-8 and has a term where the sort value starts with an extended character. This doesn't work as
 <term tag="makeindex"/>
 treats the UTF-8 letter as two separate characters form from the two octets. This not only affects the sorting but also causes a problem for the
 <file>
 indexgroup
 </file>
 style.
 
 
 <float type="figure" tag="unsupportedencdiagnostics" caption="Encoding Problems (Diagnostics Panel)" pos="htbp">
 <image src="images/unsupported-enc-diagnostics.png" alt="image of diagnostics panel" scale="0.75"/>
 </float>
 
 
 The first message in the diagnostics panel (see
 <ref tag="unsupportedencdiagnostics"/>
 ) is only picked up after you rerun
 <latex/>
 and reload the file in
 <app/>
 , as it's only after the glossary file has been created by
 <term tag="makeindex"/>
 that the
 <latex/>
 call fails. The failure is caused by the first octet appearing in the argument of
 <cs tag="glsgroupheading"/>
 . This causes two problems: the argument of this command is a label so special or active characters will break it, and the
 <sty>
 inputenc
 </sty>
 package makes the first octet active, requiring the second octet as the argument. The message reads:
 
 <blockquote>
 
 There seems to be a problem with the letter group label
 Ã. The label is used to construct a command name, so it can't contain any special characters. (This includes extended characters if you're using inputenc.sty.)
 
 <pre>
 l.3 \glsgroupheading{
 Ã}
 </pre>
 
 You may want to consider using xindy with a LaTeX engine that has native Unicode support (XeLaTeX or LuaLaTeX) or use bib2gls instead.
 
 </blockquote>
 
 This message doesn't show up when you first attempt to create the glossary files with
 <app/>
 . However, there's advisory message than points to a problem:
 
 <blockquote>
 The indexer encoding
 <sq>
 ISO-8859-1
 </sq>
 doesn't seem to match the document encoding (utf8). This may not be a problem if you aren't using extended characters in the sort values.
 </blockquote>
 
 In this case it is a problem. The two different encodings are also shown in
 <ref tag="unsupportedencdiagnostics"/>
 . The indexer encoding is listed as ISO-8859-1, and the document encoding is listed as utf8.
 
 
 <float type="figure" tag="unsupportedencsummary" caption="Encoding Problems (General Information Panel)" pos="htbp">
 <image src="images/unsupported-enc-summary.png" alt="image of general information panel" scale="0.75"/>
 </float>
 
 
 The problem shows up more clearly in the
 <dq>
 Details
 </dq>
 window (see
 <ref tag="unsupportedencdetails"/>
 ), which uses the indexer's encoding and so displays the sort value as
 Ã©lite instead of élite.
 
 
 <float type="figure" tag="unsupportedencdetails" caption="Encoding Problems (Details Window)" pos="htbp">
 <image src="images/unsupported-enc-details.png" alt="image of the details window" scale="0.75"/>
 </float>
 
 </example>
 </node>
 <node type="chapter" tag="properties" title="Settings">
 
 The application settings can be adjusted through the
 <menu tag="settings"/>
 menu. This has menu items for increasing or decreasing the font size (
 <menu tag="settings.incsize"/>
 or
 <menu tag="settings.decsize"/>
 ), setting the dry run mode (
 <menu tag="settings.dryrun"/>
 ) or open the
 <button tag="properties.title"/>
 dialog window (
 <menu tag="settings.editproperties"/>
 ). Note that the dry run mode is the only setting that isn't remembered the next time you run
 <app/>
 .
 
 
 The
 <button tag="properties.title"/>
 dialog has four tabs:
 <button tag="properties.start_dir"/>
 ,
 <button tag="properties.diagnostics"/>
 ,
 <button tag="properties.applications"/>
 and
 <button tag="properties.gui"/>
 .
 
 </node>
 <node type="section" tag="startdirtab" title="Start Up Directory">
 
 <float type="figure" tag="propertiesdialog-startdir" caption="Properties Dialog (Start Up Directory)" pos="htbp">
 <image src="images/properties-startdir.png" alt="image of properties dialog with start up tab selected" scale="0.8"/>
 </float>
 
 
 The
 <button tag="properties.start_dir"/>
 (
 <ref tag="propertiesdialog-startdir"/>
 ) tab allows you to select the directory to use on start up. This is the directory the file chooser will be set to initially.
 
 </node>
 <node type="section" tag="diagnosticstab" title="Diagnostic Settings">
 
 <float type="figure" tag="propertiesdialog-diagnostics" caption="Properties Dialog (Diagnostics)" pos="htbp">
 <image src="images/properties-diagnostics.png" alt="image of properties dialog with diagnostics tab selected" scale="0.8"/>
 </float>
 
 
 <app/>
 will try to determine if you have defined any entries within the
 <env tag="document"/>
 environment. Although the
 <sty>
 glossaries
 </sty>
 package allows document definitions, the manual encourages defining entries in the preamble, see section
 <nbsp/>
 4.10 of the
 <sty>
 glossaries
 </sty>
 user manual (
 <dq>
 Drawbacks With Defining Entries in the Document Environment
 </dq>
 ). If you want to skip this check, deselect the
 <button tag="properties.docdefcheck"/>
 check box.
 
 
 There's also a check to see if the
 <sty>
 glossaries
 </sty>
 package has complained about missing language modules. Not all languages are supported and, for those languages that are supported, the appropriate module must be installed in addition to installing the
 <sty>
 glossaries
 </sty>
 package. If the required language support is missing, the glossary files can still be built, you'll just have to manually change the fixed text for the title following the instructions in section
 <nbsp/>
 1.3 (
 <dq>
 Multi-Lingual Support
 </dq>
 ) of the
 <sty>
 glossaries
 </sty>
 user manual. If you want to skip this check, deselect the
 <button tag="properties.langcheck"/>
 check box.
 
 </node>
 <node type="section" tag="applicationstab" title="Indexing Applications">
 
 <float type="figure" tag="propertiesdialog-applications" caption="Properties Dialog (Applications)" pos="htbp">
 <image src="images/properties-applications.png" alt="image of properties dialog with applications tab selected" scale="0.8"/>
 </float>
 
 
 The
 <button tag="properties.applications"/>
 tab lists the paths to
 <term tag="makeindex"/>
 and
 <term tag="xindy"/>
 .
 <app/>
 will attempt to locate them on your system's path, but if they can't be detected, you'll need to specify the correct location. You can omit the location for an unrequired application.
 
 
 <app/>
 will try to determine the language and input encoding from the
 <file>
 .aux
 </file>
 file to pass to
 <term tag="xindy"/>
 , but you can override this if you want to. Make sure that the
 <button tag="properties.override"/>
 check box is selected, and change the language and encoding as appropriate. Note that the batch mode will also use these settings, although they can only be adjusted in the
 <acr tag="gui"/>
 mode.
 
 </node>
 <node type="section" tag="guitab" title="GUI Preferences">
 
 <float type="figure" tag="propertiesdialog-gui-metal" caption="GUI Preferences (Metal Look and Feel)" pos="htbp">
 <image src="images/properties-gui-metal.png" alt="image of properties dialog with GUI tab selected (Metal Look and Feel)" scale="0.8"/>
 </float>
 
 
 The font used in the
 <button tag="main.title"/>
 and
 <button tag="diagnostics.title"/>
 panels can be set in the
 <button tag="properties.gui"/>
 tab. In addition to adjusting the font size through the
 <menu tag="settings.incsize"/>
 or
 <menu tag="settings.decsize"/>
 menu items, you can also set the required font size in this tab.
 
 
 The
 <term tag="lookandfeel"/>
 can be set by selecting the required option in the
 <button tag="properties.look_and_feel"/>
 drop-down menu. Note that a restart is required as the Look and Feel is set on start up. The title bar appearance is governed by your usual operating system preference. The Look and Feel changes the way the window elements are displayed.
 <ref tag="propertiesdialog-gui-metal"/>
 shows the
 <dq>
 Metal
 </dq>
 Look and Feel.
 <ref tag="propertiesdialog-gui-nimbus"/>
 shows the
 <dq>
 Nimbus
 </dq>
 Look and Feel.
 <ref tag="propertiesdialog-gui-cde"/>
 shows the
 <dq>
 CDE/Motif
 </dq>
 Look and Feel.
 <ref tag="propertiesdialog-gui-gtk"/>
 shows the
 <dq>
 GTK+
 </dq>
 Look and Feel. You may not have all these options on your system or you may have additional options, depending on your Java installation.
 
 
 <float type="figure" tag="propertiesdialog-gui-nimbus" caption="GUI Preferences (Nimbus Look and Feel)" pos="htbp">
 <image src="images/properties-gui-nimbus.png" alt="image of properties dialog with GUI tab selected (Nimbus Look and Feel)" scale="0.8"/>
 </float>
 <float type="figure" tag="propertiesdialog-gui-cde" caption="GUI Preferences (CDE/Motif Look and Feel)" pos="htbp">
 <image src="images/properties-gui-cde.png" alt="image of properties dialog with GUI tab selected (Cde/motif Look and Feel)" scale="0.8"/>
 </float>
 <float type="figure" tag="propertiesdialog-gui-gtk" caption="GUI Preferences (GTK+ Look and Feel)" pos="htbp">
 <image src="images/properties-gui-gtk.png" alt="image of properties dialog with GUI tab selected (GTK+ Look and Feel)" scale="0.8"/>
 </float>
 
 </node>
 <node type="chapter" tag="licence" title="Licence">
 
 <app/>
 is licensed under the terms of the GNU General Public License.
 <app/>
 depends on the following third party libraries whose jar files are in the
 <file>
 lib
 </file>
 directory: Java Help (
 <url www="https://javahelp.java.net/"/>
 ) and the Java Look and Feel Graphics Repository (
 <url www="http://www.oracle.com/technetwork/java/index-138612.html"/>
 ).
 
 <verbtabinput src="LICENSE"/>
 </node>
 <printglossary/>
 <printindex/>
 </document>
</manual>