Package: knowledge-clustering
knowledge-clusteringCommand-line tool to help with the use of theknowledge LaTeX package.
A tutorial on how to use bothknowledgeandknowledge-clusteringcan be foundhere.PrincipleThe goal ofknowledge-clusteringis to help the user write a LaTeX document with
theknowledge package.
It has three features:Clustering: provide suggestions to the user of what notions should be grouped together.Add quotes: find where you might have missed some quotes in your document.Anchor points: find where you might have missed anchor points in your document.Theclusteringalgorithm is meant to be used while writing your document, while the last two tools
should be used when your document is (nearly) ready to be published, to check if everything is right.InstallationTo install (or upgrade)knowledge-clustering, you need to have Python 3.9 (or a more recent version), and then runpip3 install --upgrade knowledge-clusteringand thenknowledge initTo check if you have the latest version ofknowledge-clustering, you can runknowledge --versionClustering notionsSyntaxUsage: knowledge cluster [OPTIONS]

  Defines, as a comment and in the knowledge files, all the knowledges
  occuring in the file.

Options:
  -k, --knowledge FILE        File containing the knowledges that are already
                              defined. Multiple files are allowed; new
                              knowledges will be written in the last one. If
                              the option is not specified, all .kl file in the
                              current directory (and subdirectory,
                              recursively) will be taken. If there are
                              multiple files, exactly one of them must end
                              with `default.kl`.
  -d, --diagnose FILE         Diagnose file produced by LaTeX. If the option
                              is not specified, the unique .diagnose file in
                              the current directory (and subdirectory,
                              recursively) is taken instead.
  -l, --lang [en|fr]          Language of your TeX document.
  -S, --scope / --no-scope    Print the scopes defined in the knowledge file
                              and print the possible meaning of those scope
                              inferred by knowledge-clustering.
  -N, --no-update / --update  Don't look on PyPI if a newer version of
                              knowledge-clustering is available.
  -c, --config-file TEXT      Specify the configuration file. By default the
                              configuration file in the folder
                              /Users/rmorvan/knowledge-
                              clustering/knowledge_clustering/data
                              corresponding to your language is used.
  --help                      Show this message and exit.ExampleExample files can be found in theexamples/folder.While writing some document, you have defined some knowledges in a file calledpreservation.kl(distinct
from your mainLaTeX).
You continued writing yourLaTeXdocument (not provided in theexamples/folder)
for some time, and used some knowledges that were undefined.
When compiling,LaTeXand theknowledge packagegives you a warning
and writes in a.diagnosefile some information explaining what went wrong. This.diagnosefile contains
a section called "Undefined knowledges" containing all knowledges used in your mainLaTeXfile but not
defined inpreservation.kl. We reproduced this section
in thepreservation.diagnosefile.Normally, you would add every undefined knowledge, one after the other, in yourpreservation.kl. This is quite burdensome and can
largely be automated. This is precisely whatknowledge-clusteringdoes: after runningknowledge cluster -k preservation.kl -d preservation.diagnoseyour filepreservation.diagnoseis left unchanged
butpreservation.klis updated with comments.Theclustercommand is optional: you can also writeknowledge -k preservation.kl -d preservation.diagnose.Now you simply have to check that the recommendations ofknowledge-clusteringare
correct, and uncomment those lines.AutofinderIf the current directory (and its recursive subdirectories) contains
a unique.diagnosefile and a unique.klfile,
you can simply writeknowledge cluster(orknowledge): the files will be automatically found.Multiple knowledge filesIf you havemultiple knowledge files, you can use the-koption multiple times.
For instance, you could write:knowledge cluster -k 1.kl -k 2.kl -d ordinal.diagnoseSynonyms of knowledges defined in1.kl(resp.2.kl) will be defined, as comments,
in1.kl(resp.2.kl). New knowledges will always be added, as comments, to the last
file, which is2.klin the example.You can also use the autofinder in this case, usingknowledge clusterorknowledge: if multiple.klfiles are present in the current directory (and
its recursive subdirectories), exactly one of them must end withdefault.kl—this is
where new knowledges will be put.Adding quotes/!\ This feature is somewhat experimental.Usage: knowledge addquotes [OPTIONS]

  Finds knowledges defined in the knowledge files that appear in tex file
  without quote symbols. Proposes to add quotes around them.

Options:
  -t, --tex FILE              Your TeX file.  [required]
  -k, --knowledge FILE        File containing the knowledges that are already
                              defined. Multiple files are allowed; new
                              knowledges will be written in the last one. If
                              the option is not specified, all .kl file in the
                              current directory (and subdirectory,
                              recursively) will be taken. If there are
                              multiple files, exactly one of them must end
                              with `default.kl`.
  -p, --print INTEGER         When finding a match, number of lines (preceding
                              the match) that are printed in the prompt to the
                              user.
  -N, --no-update / --update
  --help                      Show this message and exit.After runningknowledge addquotes -t mydocument.tex -k knowledges1.kl -k knowledges2.klyour prompt will propose to add quotes around defined knowledges,
and to define synonyms of knowledges that occur in your TeX file. For instance, if
"algorithm" is a defined knowledge and "algorithms" occurs in your TeX file, then
it will propose to you to define "algorithms" as a synonym of the knowledge "algorithm",
and to add a pair of quotes around the string "algorithms" that occurs in your TeX file.Whenever the algorithm finds a match for a knowledge, it will print the line of
the document where it found the match, and emphasize the string corresponding to the knowledge.
If you want to print more than one line, you can use the-p(or--print) option
to print more than one line.Finding missing anchor pointsUsage: knowledge anchor [OPTIONS]

  Prints warning when a knowledge is introduced but is not preceded by an
  anchor point.

Options:
  -t, --tex FILE              Your TeX file.  [required]
  -s, --space INTEGER         Number of characters tolerated between an anchor
                              point and the introduction of a knowledge.
                              (Default value: 200)
  -N, --no-update / --update
  --help                      Show this message and exit.When one runsknowledge anchor -t mydocument.texthe tool will print the lines of the document containing the
introduction of a knowledge that is not preceded by an anchor point.
The tolerance on how far away the anchor point can be from the
introduction of a knowledge can be changed with the-s(or--space)
option. The default value is 150 characters (corresponding to 2-3 lines in a
TeX document).Devel using virtualenvUsingvenvand the--editableoption frompip3allows for an easy
setup of a development environment that will match a future user install without
the hassle.For bash and Zsh userspython3-mvenvkl.venvsource./kl.venv/bin/activate
pip3install--editable.For fish userspython3 -m venv kl.venvsource./kl.venv/bin/activate.fish
pip3 install --editable .FAQknowledge: command not foundafter installingknowledge-clusteringMake sure you have Python>=3.9.When runningknowledge, I obtain a long message error indicating "Resource punkt not found."Runknowledge init.My shell doesn't autocomplete the commandknowledge.Depending on whether you usezshorbashwriteeval "`pip completion --<shellname>`"(where<shellname>is eitherzshorbash)
in your.zshrc(or.bashrc) file and then,
either launch a new terminal or runsource ~/.zshrc(orsource ~/.bashrc).Error: Got unexpected extra argumentwhen using multiple knowledge files.You should use the option-kbeforeeveryknowledge file, like inknowledge cluster -k 1.kl -k 2.kl -d blabla.diagnoseI've updatedknowledge-clusteringbut I still don't have the last version (which can be checked usingknowledge --version):
This can happen if you have multiple versions ofpython(and multiple versions
ofknowledge-clustering).Typewhere python3, and uninstallknowledge-clusteringfrom everywhere (using<path>/python3 -m pip uninstall knowledge-clustering)
except your main version of python. Try to then upgradeknowledge-clusteringby runningpip3 install --upgrade knowledge-clustering.