html2index -s input.html [-o output.html] [-t template.html] [-c config] [-d]
html2index -v
html2index -h
The program identifies in an HTML source all expressions which need to be copied to the generated index and searches given dictionaries on the Web for an explanation of each expression.
The resulting glossary is written to a new HTML-file or its HTML-code printed to STDOUT.
NOTE: The default dictionaries are French: Larousse and JargonF. Non-French speakers MUST define the dictionary by editing the configuration file ~/.config/HTML2Index/config as described under Configuration below.
-d, --debug: | Be verbose |
---|---|
-s, --source=SOURCE: | |
Source is the the original html-file which contains marked expressions (see Preparations, below). | |
-o, --out=GLOSSARY: | |
Glossary is the generated file in HTML-format. | |
-t, --template=TEMPLATE: | |
A html file containing placeholders for the references to the dictionaries used and the generated glossary. The placeholders are currently defined as %=dict_list=% and %=glossary=%. You can set different field-delimiters and names in the configuration-file. See below under EXAMPLE-Template for a rudimentary example. | |
-c, --config=CONFIG: | |
Configuration-file. Command-line arguments override the settings in this file. You find a functional configuration after the first program-execution in ~/.config/HTML2Index. The file is commented and can immediately be adapted to your needs. |
-h, --help Show this message
-v, --version Show program version
Here is a html-page containing instructions on how to enable and disable a touchpad using the xinput command (or any other HTML-file) in the French (or any other) language.
touchpad_fr.html
Executing HTML2Index with the -s argument and the HTML-file as its value, like this:
:~$ html2index -s /[path]/touchpad_fr.html
will produce output like this with expressions from the HTML-file explained in the French language :
vi (JargonF): 1. [Unix]. « Visual Interface » (littéralement, « interface visuelle », ça ne s'invente pas !) éditeur de texte du pléistocène codé par Bill Joy, aussi fondateur de Sun. Des aficionados d'Unix s'en servent encore, même s'il est très concurrencé par Emacs. Son principal avantage est que quel que soit l'état de votre système (par exemple complètement déglingué ou allégé) il a de fortes chances de fonctionner encore correctement. La version la plus répandue est vim. 2. [nom de domaine]. Nom de domaine de premier niveau des îles Vierges étasuniennes. ------------------------------------------------------------ xinput (JargonF): commande. [X11] Utilitaire facilitant la gestion des périphériques X Window d'entrée. Il peut en fournir la liste, détailler leurs propriétés et modifier celles qui peuvent l'être. http://www.souris-libre.fr/savoir_faire/touchpad/touchpad_fr.html Exemple d'utilisation: désactivation et activation rapide du pavé tactile.
If you name an output file with the -o option, html2index will direct its output in HTML-format to this file.
In the source-code of the original HTML- page, expressions for the future glossary are marked by means of
By default, the span-tag with an attribute lang="fy" is used, 'fy' meaning Frisian, a language which is rarely used on the Web.., I venture.
Example:
<span lang="fy" xml:lang="fy">pavé tactile</span>
You can, though, define your own tag, attribute and attribute-value, if you prefer to mark expressions in your original html-file differently, like in
Example:
<em class="expression">Tripane</em>
Remember that you can combine css classes and thus economize on html-elements, if you use them anyway to style your html-content. This would complicate the task for html2index only a little bit, as we will see further below.
Apart from the way that expressions are marked in the original html, you can prepare a few settings for HTML2Index, which influence its behaviour. Command-line options override the values stored in the configuration-file.
A default configuration will be stored in the file ~/.config/HTML2Index/config the first time that you run html2index. It should be sufficiently commented to allow you to comprehend and alter any values in the file.
However, an explanation of each one of the available variables follows:
debug: | Does the same as the command-line options '-d' or '--debug'. Accepts the values false or true or can be left empty. If set to true, this setting causes html2index to be very verbose. Usually, you do not need to change the default value to this variable, which is false. |
||||||||
---|---|---|---|---|---|---|---|---|---|
dictionaries: | Here, you HAVE to define the online-dictionaries to consult, if you do not want to stick with the defaults, which are Larousse and JargonF, two French speaking sites, which also provide explanations in the French language only. The dictionaries are defined with four variables, each: name, url, xpath, color. Each dictionary-definition must start with a dash, followed by a white-space, then the first variable. Each variable-name must be enclosed by colons (see comments in the config-file).
|
||||||||
template: | An HTML-file which contains placeholders. Two placeholders are needed at the time of this writing, one to name the dictionaries which are used to look-up definitions, another one to locate the spot where the new glossary will be written. See below under EXAMPLE-Template for a rudimentary example. The default template is internally defined. |
||||||||
fdelim: | A character sequence which is used to mark placeholders in the HTML-template file. The default is '%-', meaning that a percent-symbol followed by a dash marks the beginning, a dash followed by a percent-symbol the end of a placeholder, like in %-dict-list-% for the placeholder named 'dict-list'. |
||||||||
placeholders: | A list of placeholder names. Currently, there are only two placeholders recognized by Html2Index: dict_list and glossary. As the value to these two variables, note the name that you chose for the placeholders in your HTML-template. The defaults are dict_list for dict_list and index for glossary. |
||||||||
html_tag: | This is the tag which encloses marked expressions in the original HTML-page (the source-file). Default is span |
||||||||
html_attribute: | An attribute of the html_tag which encloses marked expressions in the original HTML-page (the source-file). Default is lang. |
||||||||
html_value: | The value of an attribute of the html_tag which encloses marked expressions in the original HTML-page (the source-file). Default is fy. |
Assuming that the defaults are used, the following could be a working HTML-template to use with HTML2Index:
<html> <head><title>Glossary</title></head> <body> <h1>Glossary</h1> <h2>Dictionaries used to produce this glossary</h2> <!-- will be replaced by an unnumbered list <ul><li> ... </li></ul> --> %-dict_list-% <h2>Definitions</h2> <!-- will be replaced by a definition list <dl><dt><dd>... </dd></dt></dl> --> %-glossary-% </body> </html>
html2index warns you if the output-file exists and asks you if you want to replace it with a new version.
The program also tries to determine the file-type of the input (HTML) file and gives out a warning if the file is considered unsuitable.
Each time, that an expression cannot be found in one of the targeted dictionaries, a warning is given. All these problematic expressions will be listed in a temporary file, which is named after html2index has terminated.
html2index is developed in Ruby and can be installed as a Ruby-Gem. As Ruby is an interpreter-language, the source-code of the installed version is always accessible. You can also decompress the gem-file to take a look at the code.
AUTHOR: | Michael Uplawski <michael[dot]uplawski[at]uplawski[dot]eu> |
---|