<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE manual SYSTEM "makeglossariesgui.dtd">
<manual fontenc="T1">
  <preamble>
    <!-- Document Info -->
    <title>User Manual for <dict tag="appname"/> 
      version<nbsp/><dict tag="appversion" /></title>
    <author>Nicola L. C. Talbot<br/><url www="www.dickimaw-books.com" /></author>
<!--
    <author>Another Author<br />Affliation or URL</author>
    <author>Translated by Some One<br />Affliation or URL</author>
-->
    <date><dict tag="appdate" /></date>
    <!-- Define Acronyms -->
    <newacro short="GUI" long="graphical user interface" tag="gui" />
    <!-- Define Terms. If a description is included it's a glossary
         term otherwise it goes in the index -->
    <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">
     <p>
     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/>.
     </p>
     <p>
     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.
     </p>
     <p>
     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.)
     </p>
     <p>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:
     </p>
     <p align="center">
      <code>makeglossariesgui</code> [<meta>options</meta>] [<meta>filename</meta>]
     </p>
     <p noindent="true">
     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.
     </p>
     <p>
     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>
     </p>
     <p>
     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.
     </p>
   </node>
   <node type="chapter" tag="main" title="Basic Use (GUI Mode)">
   <p>
   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.)
   </p>
   <example>
   <p>
   Suppose you have the following document (called, say, <file>basic-sample.tex</file>):
   </p>
   <pre>
\documentclass{article}

\usepackage{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},
 description={an example}}

\begin{document}
A \gls{sample} document.

\printglossaries

\end{document}
   </pre>
   <p>
   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.)
   </p>
   <p>
   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/>.
   </p>
   <p>
   <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>
   </p>
   <p>
   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"/>.
   </p>
   <p>
   <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>
   </p>
   <p>
   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 <em>label</em>. (The sort column
   isn't searched.) Regular expressions are permitted.
   </p>
   <p>
   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.
   </p>
   <p>
   <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>
   </p>
   </example>
   <p>
   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"/>.
   </p>
   <p>
   If you're using the <sty>glossaries-extra</sty> package, remember that
   the <file>noindex</file> option will suppress indexing.
   </p>
   <example>
   <p>
   Now let's consider the following document (called, say, 
   <file>missing-sort.tex</file>):
   </p>
   <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>
   <p>
   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:
   </p>
<blockquote>
Would replace complete index key with empty string, ignoring
</blockquote>
   <p noindent="true">
   and the <file>S</file> entry is ignored. The <file>alpha</file> and <file>beta</file>
   entries cause an error:
   </p>
<blockquote>
index 0 should be less than the length of the string
</blockquote>
   <p noindent="true">
   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:
   </p>
<blockquote>
Xindy has ignored one or more entries with empty sort strings.
Xindy failed with exit code 1.
</blockquote>
   <p>
   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"/>.)
   </p>
   <p>
   <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>
   </p>
   <p>
   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"/>).
   </p>
   <p>
   <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>
   </p>
   </example>
   <p>
   <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"/>.
   </p>
   <example>
   <p>
   Spot what's wrong with the following document:
   </p>
<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>
   <p>
   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
   </p>
<pre>
\usepackage{glossaries}
</pre>
   <p noindent="true">
   to
   </p>
<pre>
\usepackage{glossaries-extra}
</pre>
   <p noindent="true">
   then we do finally get an error:
   </p>
<blockquote>
! Package glossaries-extra Error: Glossary type <sq>acronym</sq> doesn't exist.
</blockquote>
   <p>
   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
   </p>
<blockquote>
No glossary <sq>acronym</sq>.
</blockquote>
  <p noindent="false">
  and the diagnostics panel will show the message:
  </p>
<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>
   <p>
   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>.
   </p>
   </example>
   <p>
   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.
   </p>
   <example>
   <p>
   In the sample document below, I've defined an entry but it hasn't been 
   indexed anywhere in the document.
   </p>
<pre>
\documentclass{article}

\usepackage{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},
 description={an example}}

\begin{document}
A sample document.

\printglossaries

\end{document}
</pre>
   <p>
   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:
   </p>
   <blockquote>
   No entries were found for glossary <sq>main</sq>.
   </blockquote>
   <p>
   The diagnostics panel shows the following message:
   </p>
   <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 <em>after</em> 
<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>
   <p>
   (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.)
   </p>
   </example>
   <p>
   Remember that if you use <cs tag="makenoidxglossaries"/>, you don't
   need <term tag="makeindex"/> or <term tag="xindy"/>.
   </p>
   <example>
   <p>
   Consider the following document:</p>
<pre>
\documentclass{article}

\usepackage{glossaries}

\makenoidxglossaries

\newglossaryentry{sample}{name={sample},
 description={an example}}

\begin{document}
A \gls{sample} document.

\printnoidxglossaries

\end{document}
</pre>
   <p>
   If I load the <file>.aux</file> file for this document into <app/>, I get
   the following message in the diagnostics panel:
   </p>
   <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>
   <p>
   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:
   </p>
<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>
   <p>
   This provides some additional information in the diagnostics panel:
   </p>
   <blockquote>
<p>
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.
</p>
<p>
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.
</p>
   </blockquote>
   <p>
   So <app/> picks up the error.
   </p>
   </example>
   <p>
   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.
   </p>
   <example>
   <p>
   In this example I've omitted <cs tag="printglossary"/> from the document:
   </p>
<pre>
\documentclass{article}

\usepackage{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},
 description={an example}}

\begin{document}
A \gls{sample} document.

\end{document}
</pre>
   <p>
   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:
   </p>
   <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>
   <p>
   If you suppress these warnings then <app/> can't help.
   </p>
   </example>
   <p>
   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.
   </p>
   <example>
   <p>
   Consider the following document:
   </p>
<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>
   <p>
   This document goes badly wrong. The first error message is:
   </p>
<pre>
! Undefined control sequence.
\in@ #1#2->\begingroup \def \in@@
</pre>
   <p>
   If I load the log file into <app/>, the diagnostic panel displays the
following:
   </p>
<blockquote>
<p>
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.
</p>
<p>
It's possible that there's an expansion issue involving a fragile command. 
Things to check for:
</p>
<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>
   <p>
   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:
   </p>
<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>
   <p>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.</p>
   <example>
   <p>Consider the following example:</p>
<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>
   <p>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.</p>
   <p>
   <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>
   </p>
   <p>
   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:</p>
   <blockquote>
<p>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.)</p>
<pre>l.3 \glsgroupheading{Ã}</pre>
<p>You may want to consider using xindy with a LaTeX engine that has native Unicode support (XeLaTeX or LuaLaTeX) or use bib2gls instead.</p>
   </blockquote>
   <p>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:</p>
   <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>
   <p>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.</p>
   <p>
   <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>
   </p>
   <p>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.
   </p>
   <p>
   <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>
   </p>
   </example>
   </node>
   <node type="chapter" tag="properties" title="Settings" >
   <p>
   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/>.
   </p>
   <p>
   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"/>.
   </p>
   </node>
   <node type="section" tag="startdirtab" title="Start Up Directory">
   <p>
   <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>
   </p>
   <p>
   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.
   </p>
   </node>
   <node type="section" tag="diagnosticstab" title="Diagnostic Settings">
   <p>
   <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>
   </p>
   <p>
   <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.
   </p>
   <p>
   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.
   </p>
   </node>
   <node type="section" tag="applicationstab" title="Indexing Applications">
   <p>
   <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>
   </p>
   <p>
   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.
   </p>
   <p>
   <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.
   </p>
   </node>
   <node type="section" tag="guitab" title="GUI Preferences">
   <p>
   <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>
   </p>
   <p>
   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. 
   </p>
   <p>
   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.
   </p>
   <p>
   <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>
   </p>
   </node>
   <node type="chapter" tag="licence" title="Licence" >
   <p>
   <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"/>).
   </p>
     <verbtabinput src="LICENSE"/>
   </node>
   <printglossary />
   <printindex />
  </document>
</manual>
