_    _     _____       _____      __   __ 
               | |  | |   |_   _|     |  __ \     \ \ / / 
               | |__| |___  | |  _ __ | |  | | ___ \ V /  
               |  __  / __| | | | '_ \| |  | |/ _ \ > <   
               | |  | \__ \_| |_| | | | |__| |  __// . \  
               |_|  |_|___/_____|_| |_|_____/ \___/_/ \_\ 
               
  Copyright (c) 2018-2020 Jean-Luc JOULIN <jeanjoux@orange.fr>


HsIndeX is a general purpose index generator for LaTeX and XeTeX. This release contains the binary of version 0.11.1 and this README file



USAGE
=====
The usage of HsIndex is the same as "makeindex", it must be used after the first compilation of you LaTeX documents with "imakeidx" package and before the second pass.

Basic usage
-----------

A english index can be generated with :

>>> hsindex english -i input.idx -o output.ind

A French index can be generated with :

>>> hsindex french -i input.idx -o output.ind


Advanced usage
--------------

A custom style can be provided with:

>>> hsindex english --style="myindexstyle.sty" --input=input.idx --output=output.ind

A custom language definition can be used with:


>>> hsindex custom --def="mylanguage.def" --style="myindexstyle.sty" --input=input.idx --output=output.ind

Successives pages numbers can be converted into ranges with the option --range. 3 or more succesives pages numbers will be converted into a range using a specific delimiter.

>>> hsindex english --range --style="myindexstyle.sty" --input=input.idx --output=output.ind

Style file
==========

A style file is composed with several tags containing the LaTeX commands to be executed at specific locations of the index. The tags are almost the same than the "makeindex" program with a few exceptions.

This is the standard style implemented in the hsindex program.


Tags setting the beginning and the end of the index.

>>> preamble         "\begin{theindex}\\n"
>>> postamble        "\\n\\n\end{theindex}\\n"


Tags setting the first layer letters heading (First letter) The "headings_flag" is a bit different from "makeindex" in the where it can be set to :
 0 or None      : No heading showed 
 1 or UpperCase : First letter in upper case.
-1 or LowerCase : First letter in lower case.

>>> headings_flag    UpperCase
>>> heading_prefix   "{\vspace{1.5cm}\huge{\textbf{"
>>> heading_suffix   "}}\hfill}\\nopagebreak\\n"



Tags setting the second layer letters heading (Two first letters) These tags don't exist with "makeindex":

>>> headings_flag1   None
>>> heading_prefix1  ""
>>> heading_suffix1  ""


Tags to set the title of the Symbol and Number sections:

>>> symhead_positive "Symbols"
>>> numhead_positive "Numbers"

Tags to set the skip between two group of items of the same layer.
The "group_skip1" don't exist in "makeindex":
>>> group_skip       "\\n \indexspace\\n" -- "\\n\\n \indexspace\\n"
>>> group_skip1      ""


The following tags are used to define the LaTeX commands to declare items, subitems and subsubitems:
>>> item_0           "\\n \item "
>>> item_1           "\\n \subitem "
>>> item_2           "\\n \subsubitem "
>>> item_01          "\\n \subitem "
>>> item_12          "\\n \subsubitem "

The following tags are used to define the delimiters betwen items and pages numbers:
>>> delim_0          ", " -- \hfill
>>> delim_1          ", "
>>> delim_2          ", "
>>> delim_n          ", "



Language file
=============

The language file allow the user to define a new language and its custom letters order and substitutions.


The LETTERS section allow the user to give the list of characters considered as letters and their sorting order. This section is mandatory.

>>> LETTERS
>>> abcdefghijklmnopqrstuvwxyz


The NUMBERS section allow the user to give the list of characters considered as numbers and their sorting order. This section is optional.

>>> NUMBERS
>>> 0123456789

The SYMBOLS section allow the user to give the list of characters considered as symbols and their sorting order. This section is optional.

>>> SYMBOLS
>>> ~*@&

The SUBSTITUTIONS section define the characters substitutions to perform. These substitutions are taken into consideration to sort and classify the items. The substituions bellow means that th "œ" character will be replaced by "oe", the accentuated "ê" and "é" will be treated as an "e" and the "_" and "-" will be treated as a space " ".

>>> SUBSTITUTIONS
>>> œ->oe
>>> ê->e
>>> é->e
>>> _-> 
>>> --> 


Feedback and improvement
========================

If you whish to improve this program and add languages or features, this project is available on gitlab :

https://gitlab.com/JeanJouX/hsindex

I hope this program will be usefull for you !