optexcount (2jul21)

git-svn-id: svn://tug.org/texlive/trunk@59817 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 271 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/support/optexcount/LICENSE b/Master/texmf-dist/doc/support/optexcount/LICENSE
new file mode 100644
index 00000000000..d8ed525c9c6
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Richard Hartmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/Master/texmf-dist/doc/support/optexcount/README.md b/Master/texmf-dist/doc/support/optexcount/README.md
new file mode 100644
index 00000000000..70d104c414e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/README.md
@@ -0,0 +1,7 @@
+# OpTeXcount
+
+What is OpTeXcount? It is a basic python script that analyzes OpTeX source code and counts words in specific categories. For more information about this tool read `optexcount-doc.pdf`.
+### How to install OpTeXcount?
+Run: `sudo ./install.sh`
+### Usage
+Run: `optexcount [-h] [-v] [-s SET_VERBCHAR] [--version] filename`, where `filename` is the name of our OpTeX code file. What does the optional argument `-v/--verbose`? It prints the entire source code with colored words according to their categories. `-s SET_VERBCHAR` or `--set-verbchar SET_VERBCHAR` sets the implicit inline verbatim character to `SET_VERBCHAR` character.
diff --git a/Master/texmf-dist/doc/support/optexcount/example_01.tex b/Master/texmf-dist/doc/support/optexcount/example_01.tex
new file mode 100644
index 00000000000..77a79f8a761
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/example_01.tex
@@ -0,0 +1,146 @@
+% This optex source code is partialy copied from http://petr.olsak.net/tat/priklad-optex.tex
+% text words:  221
+% header words: 15
+% caption words: 14
+
+
+\chyph                      % české vzory dělení slov
+\fontfam[Schola]            % fontová rodina TeXGyre Schola
+\margins/1 a4 (3,3,3,3)cm   % okraje 3cm ze všech stran pro stranu A4
+\typosize[11/13]            % velikost písma 11pt na 13pt řádkování
+\activettchar"              % znak " bude ohraničovat řádkový verbatim
+\hyperlinks\Blue\Green      % interní odkazy modré, webové odkazy zelené
+\outlines0                  % klikací obsah po straně PDF prohlížeče
+
+\def\center{\noindent\hfil} % zkratka pro centrování
+
+\tit Ukázka \OpTeX u
+
+\sec Základní struktura
+
+Dokument se skládá z odstavců (ve zdrojovém textu jsou odděleny prázdnými řádky)
+a dále z kapitol, sekcí a podsekcí.
+
+\secc Výčty
+
+V textu můžeme používat výčty:
+
+\begitems
+* první
+* druhý
+\enditems
+
+
+Někdy mohou být výčty vnořeny:
+
+\begitems
+* První
+* Druhý.
+  \begitems \style a
+  * Podproblém,
+  * ještě jeden podproblém,
+  * poslední podproblém.
+  \enditems
+* Třetí.
+* Poslední.
+\enditems
+ 
+
+\secc Vyznačování
+
+Text můžeme zdůraznit {\it kurzívou}, nebo {\bf tučně}. 
+
+\secc[poznamky]  Poznámky
+
+Poznámka pod čarou\fnote{Vypadá takto.} je automaticky číslovaná.
+Může jich být více\fnote{Druhá poznámka.}.
+
+
+\sec[dalsi] Další sekce
+
+\secc Verbatim text
+
+Vložíme {\it verbatim text}, tedy text \uv{tak jak je} bez interpretace
+\TeX{}em:
+
+Výčet:
+\begtt
+\begitems
+* První
+* Druhý.
+\enditems
+\endtt
+
+Kromě toho je možné psát "#kusy {kódů}" přímo v textu odstavce.
+
+\secc Obrázky
+
+Obrázky se do odborného textu obvykle vkládají včetně popisku.
+
+\midinsert \label[ptacek]
+  \center \picw=7cm \inspic final_bird.png
+  \medskip
+  \caption/f Hlavní textura hry Flappy Bird
+\endinsert
+
+
+\secc Odkazy
+
+Na automaticky číslované objekty je možné odkazovat. Ve zdrojovém dokumentu
+je třeba použít {\it lejblík} v místě cíle a stejný lejblík v místě odkazu.
+Odkazy vypadají například takto: viz sekci~\ref[dalsi] na
+straně~\pgref[dalsi], dále v podsekci~\ref[poznamky] je zmínka o poznámkách
+pod čarou a rovnice~\ref[rce] na straně~\pgref[rce] uvádí zajímavou
+matematickou myšlenku. Každý jistě poznal, že na obrázku~\ref[ptacek] se
+nachází karikatura ptáčka.
+
+Vnější odkazy směřují obvykle na webové stránky, 
+např.~\url{http://petr.olsak.net/opmac.html}.
+
+\secc Tabulky
+
+Na tabulky se používá "\hbox" / "\vbox" aritmetika.
+
+\bigskip
+\center\table{||l|cc||}{\crl \tskip.5ex
+           & \multispan2 \hfil počet \qquad\hfil\vrule\kern\vvkern\vrule\strut\cr
+   makro             & řádků kódu & stran dokumentace \crli \tskip.5ex
+   plain             &    1241 & 100 \cr
+   OPmac             &    1600 &  19 \crli \tskip.5ex
+   \LaTeX{} (jádro)  &    8000 & 240 \cr
+   hyperref          &   24773 & 423 \cr
+   color + graphics  &    2469 &  81 \crli \tskip.5ex
+   Ti{\it k}Z        & 1\,634\,882 & 726 \crli \tskip.5ex
+   Con\TeX{}t        & 1\,155\,673 & 547 \crl
+ } 
+\nobreak\medskip
+\caption/t Makra a jejich rámcový rozsah
+\bigskip
+
+V tabulce ve zdrojovém textu je jednak záhlaví s pravidlem, jak mají být
+formátována jednotlivá pole tabulky, a dále data oddělená od sebe smluvenými
+oddělovači.
+
+\secc Matematika
+
+V řádku se píše matematika mezi dolary: $a^2+b^2=c^2$. Nebo je možno sestavit
+samostatnou rovnici obklopenou dvojicí dolarů:
+
+\label[rce]
+$$
+  \int x^\alpha {\rm d}x = \cases {
+     x^{\alpha+1} \over \alpha+1 & pro $\alpha\not=-1$ \cr \noalign{\medskip}
+     \ln x                       & pro $\alpha=-1 $
+  }
+  \eqmark
+$$ 
+Vzorce se zapisují zhruba tak, jak bychom je anglicky přečetli.
+
+
+
+$$
+  {\bbchar A} = \pmatrix{ a & b & c \cr d & e & f \cr g & h & i}.
+$$
+Toť na úvod vše.
+
+\bye
diff --git a/Master/texmf-dist/doc/support/optexcount/final_bird.png b/Master/texmf-dist/doc/support/optexcount/final_bird.png
new file mode 100644
index 00000000000..889d3d12d30
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/final_bird.png
diff --git a/Master/texmf-dist/doc/support/optexcount/optexcount-doc.pdf b/Master/texmf-dist/doc/support/optexcount/optexcount-doc.pdf
new file mode 100644
index 00000000000..8a838fa803a
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/optexcount-doc.pdf
diff --git a/Master/texmf-dist/doc/support/optexcount/optexcount-doc.tex b/Master/texmf-dist/doc/support/optexcount/optexcount-doc.tex
new file mode 100644
index 00000000000..764c1c527bd
--- /dev/null
+++ b/Master/texmf-dist/doc/support/optexcount/optexcount-doc.tex
@@ -0,0 +1,97 @@
+
+\fontfam[Termes]
+\margins/1 a4 (3,3,3,3)cm
+\typosize[11/13.5]
+\verbchar`
+
+\def\title{\OpTeX count}
+\def\desc{Python script for counting words in \OpTeX/ documents}
+\def\version{Version 1.1}
+\def\author{Richard Hartmann}
+
+\def\maketitle {\vbox to 9\baselineskip{
+    \parindent=0pt
+    \leftskip=0pt plus 1fill \rightskip=0pt plus 1fill
+    {\parskip=14pt \typoscale[2000/]\bf \title \par}
+    {\parskip=19pt \typoscale[1200/]\desc \par}
+    {\parskip=10pt \version \par}
+    {\parskip=10pt \it \author \par}
+    {\parskip=8pt \the\day.\,\the\month.\,\the\year \par}
+}}
+
+\maketitle
+
+
+\sec Functionality and Usage
+
+\OpTeX count is a basic python utility that analyzes \OpTeX source code. It is inspired by already existing \TeX count for \LaTeX. The functionality is really lightweight and basic.
+It counts words and other elements of \OpTeX/ document and sorts them out into individual categories. These categories are inspired by \TeX count.
+
+\begitems
+\typosize[11.5/16]
+\style N \bf
+* Regular text words count
+* Header words count
+* Caption words count
+* Header count
+* Figures/Tables count
+* Inline formulae
+* Displayed math formulae
+\enditems
+
+Regular text words are words that occur in the main text.
+Header words are introduced using these particular keywords: {\Blue `\tit`}, {\Blue `\chap`}, {\Blue `\sec`} and {\Blue `\secc`}.
+Caption words take into account captions of tables and figures, i.e., {\Blue `\caption/t`} and {\Blue `\caption/f`}, footnotes({\Blue `\fnote`} or {\Blue `\fnotetext`}) and marginal notes({\Blue `\mnote`}).
+Header count is the number of all headers in our document.
+Figures/Tables count counts all tables and figures which occur in the document.
+Inline formulae are introduced using {\Blue `$`\dots`$`} and displayed formulae are introduced using {\Blue `$$`\dots`$$`}.
+
+If there is a verbatim text in some category, its words are counted too.
+
+Alongside above mentioned statistics, all individual sections are printed separately with particular word counts.
+
+To get this utility running, you need to install it using basic bash script.
+Use command {\Blue `sudo ./install.sh`}.
+Installation requires `python3` and `zip` utility running.
+Then user can run this utility by command:
+
+\begtt
+optexcount [-h] [-v] [-s SET_VERBCHAR] [--version] filename
+\endtt
+
+Use {\Blue `-h`} or {\Blue `--help`} specifier for the help message.
+User can also use two optional specifiers: {\Blue `-v`}~/~{\Blue `--verbose`} and {\Blue -s SET_VERBCHAR}~/~{\Blue --set-verbchar SET_VERBCHAR}.
+When the utility is ran in verbose mode, it prints the source code on the screen with colored words, so user can easily see, what is considered as text word, header word, caption word or keyword.
+Character {\Blue `SET_VERBCHAR`} sets implicit verbatim inline character.
+This can be useful when the specific verbatim character is used in the file but not explicitely set in the file.
+The situation may occur for example when user wants to count words in file, that is read by different main file.
+The verbatim character is set in the main file, but not in the file we want to analyze.
+
+In case you don't want to install this software you can run python script {\Blue `src/optexcount.py`} with {\Blue `python3`} command explicitly.
+
+\sec A Brief Implementation Description
+
+\OpTeX count uses regular expressions to separate individual words, to identify keywords, brackets, math formulae etc.
+These preprocessed words are sequentially loaded into counter that decides how to treat with the word.
+
+If some specific keyword occurs, that is not known by this utility, it is skipped.
+Problem may occur, if an unknown keyword has got some arguments, the utility could count these arguments as individual words.
+Therefore, most common keywords with arguments are listed in `src/keywords.py`, so the utility can load successfully these arguments.
+If there is some important keyword missing, feel free to modify this file, to add this keyword\dots
+
+In case of some keyword, that is important for the utility to identify, for example {\Blue `\sec`} or {\Blue `\fnote`}, special handler routine is ran, to manage this particular keyword.
+The place, from which we process the word also determines the category of the word, in what color should be this word highlighted in verbose mode etc.
+
+
+\sec Utility Limitations
+
+The results are pretty precise when the most basic \OpTeX/ constructions are used.
+As It has been already mentioned above, it is really basic and lightweight utility.
+When user uses some more advanced \TeX/ constructions, problems may occur, and the counts may be imprecise.
+It doesn't take into account macro expansion, self defined rules etc\dots When using this utility, a valid \OpTeX/ source code should be passed.
+If the file contains some errors(for example unterminated inline verbatim), utility terminates the process and won't provide much information about the problem.
+This utility only works with one particular file so it doesn't count included files as well.
+
+Beside above mentioned limitations of this utility, it could be very useful for the analysis of basic \OpTeX/ documents(such as the exemplary document {\Blue `examples/example_01.tex`}).
+
+\bye