summaryrefslogtreecommitdiff
path: root/support
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-02-03 03:02:01 +0000
committerNorbert Preining <norbert@preining.info>2020-02-03 03:02:01 +0000
commit34897eebd22c3de968b64f09bb4a371d96cb0b89 (patch)
tree19a50e54fca63f1f6482d6cb4c2fdee676fd97b1 /support
parente05dc0bb38b16bfb9ba35591285e40af0adaadc4 (diff)
CTAN sync 202002030302
Diffstat (limited to 'support')
-rw-r--r--support/texdoc/NEWS7
-rw-r--r--support/texdoc/README.md4
-rw-r--r--support/texdoc/doc/texdoc-doc.cls236
-rw-r--r--support/texdoc/doc/texdoc.116
-rw-r--r--support/texdoc/doc/texdoc.pdfbin76508 -> 82654 bytes
-rw-r--r--support/texdoc/doc/texdoc.tex1327
-rwxr-xr-xsupport/texdoc/script/texdoc.tlu34
-rw-r--r--support/texdoc/script/texdoclib-alias.tlu4
-rw-r--r--support/texdoc/script/texdoclib-cli.tlu50
-rw-r--r--support/texdoc/script/texdoclib-config.tlu44
-rw-r--r--support/texdoc/script/texdoclib-const.tlu12
-rw-r--r--support/texdoc/script/texdoclib-score.tlu86
-rw-r--r--support/texdoc/script/texdoclib-search.tlu118
-rw-r--r--support/texdoc/script/texdoclib.tlu2
-rw-r--r--support/texdoc/texdoc.cnf60
-rw-r--r--support/texplate/README.md8
-rw-r--r--support/texplate/doc/texplate-manual.pdfbin103717 -> 104886 bytes
-rw-r--r--support/texplate/doc/texplate-manual.tex44
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/Main.java36
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/model/Configuration.java150
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/model/Template.java252
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/model/TemplateProcessing.java391
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/BooleanHandler.java26
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/CSVListHandler.java30
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/util/HandlerUtils.java31
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/util/MergingUtils.java186
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/util/MessageUtils.java84
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/util/PathUtils.java129
-rw-r--r--support/texplate/source/main/java/org/islandoftex/texplate/util/ValidatorUtils.java75
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/Main.kt23
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt228
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidKeySetException.kt (renamed from support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidKeySetException.java)17
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidTemplateException.kt (renamed from support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidTemplateException.java)17
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/TemplateMergingException.kt (renamed from support/texplate/source/main/java/org/islandoftex/texplate/exceptions/TemplateMergingException.java)17
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Configuration.kt67
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Template.kt90
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/BooleanHandler.kt20
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/CSVListHandler.kt22
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/Handler.kt (renamed from support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/Handler.java)8
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt25
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MergingUtils.kt126
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MessageUtils.kt72
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt69
-rw-r--r--support/texplate/source/main/kotlin/org/islandoftex/texplate/util/ValidatorUtils.kt54
-rw-r--r--support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-article.toml (renamed from support/texplate/scripts/templates/texplate-article.toml)0
-rw-r--r--support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-standalone.toml (renamed from support/texplate/scripts/templates/texplate-standalone.toml)0
46 files changed, 2001 insertions, 2296 deletions
diff --git a/support/texdoc/NEWS b/support/texdoc/NEWS
index 430c925d24..aae48497e5 100644
--- a/support/texdoc/NEWS
+++ b/support/texdoc/NEWS
@@ -2,6 +2,13 @@ NEWS for texdoc
===============
(This file public domain.)
+Version 3.2 (TeX Live 2020)
+===========================
+- Improved the scoring scheme to prioritize the latex tree than the latex-dev
+- Support invoking the program with absolute paths
+- The document was entirely rewritten
+- Other small improvements and bug fixes
+
Version 3.1 (TeX Live 2019)
===========================
- New option -c: changing configure temporally
diff --git a/support/texdoc/README.md b/support/texdoc/README.md
index f0da3fc234..b71ab74743 100644
--- a/support/texdoc/README.md
+++ b/support/texdoc/README.md
@@ -1,4 +1,4 @@
-# Texdoc v3.1 (2019-03-28)
+# Texdoc 3.2 (2020-02-02)
[![Build Status](https://travis-ci.org/TeX-Live/texdoc.svg?branch=master)](https://travis-ci.org/TeX-Live/texdoc)
[![Build status](https://ci.appveyor.com/api/projects/status/uq28ms7eba7ns6d3/branch/master?svg=true)](https://ci.appveyor.com/project/wtsnjp/texdoc/branch/master)
@@ -106,7 +106,7 @@ More specific information (e.g., TODO) can be found in the Wiki of our GitHub re
## Copyright and License
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
This package is distributed under the terms of the GNU General Public License as published by the Free Software Foundation, either [version 3](./COPYING) of the License, or (at your option) any later version.
diff --git a/support/texdoc/doc/texdoc-doc.cls b/support/texdoc/doc/texdoc-doc.cls
new file mode 100644
index 0000000000..a9d229b6a7
--- /dev/null
+++ b/support/texdoc/doc/texdoc-doc.cls
@@ -0,0 +1,236 @@
+% Document style for Texdoc user manual
+% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
+% distributed under the terms of GPL v3 or later
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{texdoc-doc}
+ [2020/02/02 Document class for Texdoc user manual]
+
+% class options
+\DeclareOption{draft}{\setlength\overfullrule{5pt}}
+\ProcessOptions\relax
+
+% remove "draft" from global options list
+% (code from https://tex.stackexchange.com/questions/33245/)
+\def\@clearglobaloption#1{%
+ \def\@tempa{#1}%
+ \def\@tempb{\@gobble}%
+ \@for\next:=\@classoptionslist\do
+ {\ifx\next\@tempa
+ \message{Cleared option \next\space from global list}%
+ \else
+ \edef\@tempb{\@tempb,\next}%
+ \fi}%
+ \let\@classoptionslist\@tempb
+ \expandafter\ifx\@tempb\@gobble
+ \let\@classoptionslist\@empty
+ \fi}
+\@clearglobaloption{draft}
+
+% basic dependency
+\LoadClass[a4paper,oneside,parskip=half-]{scrartcl}
+\RequirePackage[british]{babel}
+\RequirePackage{needspace}
+\RequirePackage{xunicode}
+\RequirePackage{fancyvrb}
+\RequirePackage{xparse}
+
+% font settings
+\RequirePackage{fontspec}
+\defaultfontfeatures{Ligatures=TeX}
+\setmainfont{DejaVuSerif}
+\setsansfont{DejaVuSans}
+\setmonofont{DejaVuSansMono}
+\renewcommand{\familydefault}{\sfdefault}
+
+% for math
+%\RequirePackage{unicode-math}
+%\setmathfont[math-style=ISO,bold-style=ISO]{TeX Gyre DejaVu Math}
+
+\setkomafont{title}{}
+\setkomafont{subtitle}{\Large}
+\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
+
+% headers
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.5\baselineskip]{section}
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.3\baselineskip]{subsection}
+
+% colors
+\RequirePackage{xcolor}
+\definecolor{links}{named}{violet}
+\definecolor{special}{rgb}{0,0.5,0}
+\definecolor{code}{rgb}{0,0,0.6}
+
+% list environments
+\RequirePackage{enumitem}
+\newlength\lssep \setlength\lssep{\smallskipamount}
+\setlist{noitemsep, topsep=\lssep, partopsep=\lssep}
+
+% hyperref and bookmark
+\RequirePackage[
+ colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links,
+ bookmarks=true, bookmarksnumbered=true, bookmarksopen=true,
+ bookmarksopenlevel=2]{hyperref}
+\RequirePackage{bookmark}
+
+% text styles
+\DeclareUrlCommand\path{\urlstyle{tt}\color{links}}
+\DeclareTextFontCommand{\emph}{\color{code}}
+
+% for metadata
+\AtBeginDocument{%
+ \bgroup
+ \def\and{, }%
+ \hypersetup{%
+ pdftitle={\@title: \@subtitle},
+ pdfauthor={\@author},
+ pdfsubject={Texdoc's user manual},
+ pdfkeywords={Texdoc, TeX Live, manual, documentation}}
+ \egroup}
+\RequirePackage[yyyymmdd]{datetime}
+\renewcommand{\dateseparator}{-}
+
+% title (overwrite \@maketitle from scrartcl)
+\newcommand*{\pkgurl}[1]{\gdef\@pkgurl{\url{#1}}}
+\renewcommand*{\@maketitle}{%
+ \global\@topnum=\z@
+ \setparsizes{\z@}{\z@}{\z@\@plus 1fil}\par@updaterelative
+ \ifx\@titlehead\@empty \else
+ \begin{minipage}[t]{\textwidth}
+ \usekomafont{titlehead}{\@titlehead\par}%
+ \end{minipage}\par
+ \fi
+ \null
+ \vskip 2em%
+ \begin{center}%
+ \ifx\@subject\@empty \else
+ {\usekomafont{subject}{\@subject \par}}%
+ \vskip 1.5em
+ \fi
+ {\usekomafont{title}{\huge \@title \par}}%
+ \vskip .5em
+ {\ifx\@subtitle\@empty\else\usekomafont{subtitle}\@subtitle\par\fi}%
+ \vskip .1em
+ {\ifx\@pkgurl\@empty\else\usekomafont{subtitle}\@pkgurl\par\fi}%
+ \vskip 1em
+ {%
+ \usekomafont{author}{%
+ \lineskip .5em%
+ \begin{tabular}[t]{c}
+ \@author
+ \end{tabular}\par
+ }%
+ }%
+ \vskip 1em%
+ {\usekomafont{date}{\@date \par}}%
+ \vskip \z@ \@plus 1em
+ {\usekomafont{publishers}{\@publishers \par}}%
+ \ifx\@dedication\@empty \else
+ \vskip 2em
+ {\usekomafont{dedication}{\@dedication \par}}%
+ \fi
+ \end{center}%
+ \par
+ \vskip 2em
+}
+
+% Low layer settings
+\lastlinefit=500 % e-TeX powered
+\catcode`\ 10\relax % take care of non-breakable spaces
+
+% some macros
+\DeclareRobustCommand{\TL}{\texorpdfstring{\TeX\,\,Live}{TeX Live}}
+\newcommand*{\TexdocML}
+ {\href{http://lists.tug.org/texdoc}{mailing list}}
+\newcommand*{\TexdocRepo}
+ {\href{https://github.com/TeX-Live/texdoc}{GitHub repository}}
+\newcommand*{\ie}{i.e.,\,}
+\newcommand*{\eg}{e.g.,\,}
+\newcommand*{\hyph}{-}
+\newcommand*{\meta}[1]{\bgroup
+ \normalfont\color{special}$\langle$\textit{#1}$\rangle$\egroup}
+\newcommand*{\metatab}{\code{\char`\\t}}
+\newcommand*{\choice}[1]{\bgroup
+ \def\@delim{\def\@delim{\space\char`\|\space}}%
+ \normalfont\color{special}%
+ \@for\@item:=#1\do{\@delim\@item}%
+ \egroup}
+\newcommand*{\code}[1]{\bgroup
+ \chardef\_=`\_\code@font #1\egroup}
+\newcommand*{\sopt}[1]{\hyperlink{cl:#1}{\code{\hyph#1}}}
+\newcommand*{\lopt}[1]{\hyperlink{cl:#1}{\code{\hyph{}\hyph#1}}}
+\newcommand*{\ci}[1]{\bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp@hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \hyperlink{\@tmp@hyname}{\code{#1}}}
+
+% verbatim
+\def\code@font{% code
+ \color{code}\normalfont\ttfamily}
+\fvset{%
+ formatcom=\code@font,
+ defineactive=\makeallfancy,
+ commandchars=\\\{\},
+ codes=\fancyactives}
+\newcommand{\fancyactives}{\catcode`\«\active}
+\newcommand{\makeallfancy}{\makefancyog}
+\bgroup
+ \catcode`\«\active
+ \gdef\makefancyog{\def«##1»{\meta{##1}}}
+\egroup
+
+% manual entries
+\newenvironment{manual@entry}{\begin{list}{}{%
+ \setlength{\leftmargin}{2em}%
+ \setlength{\itemindent}{0pt}%
+ \setlength{\itemsep}{0pt}%
+ \setlength{\parsep}{0pt}%
+ \setlength{\rightmargin}{0em}%
+ }\item}{\end{list}}
+
+\NewDocumentEnvironment{clopt}{ m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\sopt##1{\hypertarget{cl:##1}{\code{\hyph##1}}}%
+ \def\lopt##1{\hypertarget{cl:##1}{\code{\hyph{}\hyph##1}}}%
+ \needspace{3ex}\noindent #1\egroup
+ \IfNoValueF{#2}{\hfill (#2)}%
+ \begin{manual@entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual@entry}}
+
+\NewDocumentEnvironment{confitem}{ m m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp@hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \needspace{3ex}\noindent
+ \hypertarget{\@tmp@hyname}{\code{#1 = #2}}%
+ \IfNoValueF{#3}{\hfill (#3)}%
+ \begin{manual@entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual@entry}}
+
+% code in hors-text
+\newenvironment{htcode}
+ {\SaveVerbatim[samepage]{verbmat}}
+ {%
+ \endSaveVerbatim
+ \par\medskip\noindent\hspace*{2em}%
+ \BUseVerbatim{verbmat}%
+ \par\medskip\@endpetrue
+ }
+
+\DefineShortVerb{\|}
+% EOF
diff --git a/support/texdoc/doc/texdoc.1 b/support/texdoc/doc/texdoc.1
index cf072bd5fc..fb2b79f2ec 100644
--- a/support/texdoc/doc/texdoc.1
+++ b/support/texdoc/doc/texdoc.1
@@ -1,16 +1,16 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
-.TH "TEXDOC" "1" "March 2019" "Texdoc 3.1" "Texdoc manual"
+.TH "TEXDOC" "1" "February 2020" "Texdoc 3.2" "Texdoc manual"
.
.SH "NAME"
\fBtexdoc\fR \- find & view documentation in TeX Live
.
.SH "SYNOPSIS"
-\fBtexdoc\fR [OPTION\.\.\.] NAME\.\.\.
+\fBtexdoc\fR [OPTION]\.\.\. NAME\.\.\.
.
.br
-\fBtexdoc\fR [OPTION\.\.\.] ACTION
+\fBtexdoc\fR [OPTION]\.\.\. ACTION
.
.SH "DESCRIPTION"
Try to find appropriate TeX documentation for the specified NAME(s)\. Alternatively, perform the given ACTION and exit\.
@@ -59,10 +59,10 @@ Activate all debug output (equal to "\-\-debug=all")\.
.
.TP
\fB\-d\fR LIST, \fB\-\-debug\fR=LIST
-Activate debug output restricted to the items specified in LIST\.
+Activate debug output restricted to the categories specified in LIST\.
.
.br
-Available items: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\.
+Available categories: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\.
.
.TP
\fB\-c\fR NAME=VALUE
@@ -87,6 +87,7 @@ Print the list of configuration files used\.
Display FILE, given with full path (no searching)\.
.
.SH "ENVIRONMENT"
+The following environment variables can be split by colon and used to set viewers:
.
.TP
\fBBROWSER\fR, \fBBROWSER_texdoc\fR
@@ -112,6 +113,9 @@ Set the command to be used for PDF documents\.
\fBPSVIEWER\fR, \fBPSVIEWER_texdoc\fR
Set the command to be used for PS documents\.
.
+.P
+The following environment variables are also used:
+.
.TP
\fBLANG\fR, \fBLC_ALL\fR and so on
Set the locale (which will influence on the search results)\.
@@ -152,7 +156,7 @@ Texdoc home page: \fIhttp://tug\.org/texdoc/\fR
Source: \fIhttps://github\.com/TeX\-Live/texdoc\fR
.
.SH "COPYRIGHT"
-Copyright 2018 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining\.
+Copyright 2008\-2020 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, the TeX Live Team\.
.
.br
License: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\.
diff --git a/support/texdoc/doc/texdoc.pdf b/support/texdoc/doc/texdoc.pdf
index d897017714..d414706520 100644
--- a/support/texdoc/doc/texdoc.pdf
+++ b/support/texdoc/doc/texdoc.pdf
Binary files differ
diff --git a/support/texdoc/doc/texdoc.tex b/support/texdoc/doc/texdoc.tex
index 37b4460259..e1ab840ace 100644
--- a/support/texdoc/doc/texdoc.tex
+++ b/support/texdoc/doc/texdoc.tex
@@ -1,603 +1,530 @@
%#!xelatex
% Texdoc user manual
-% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
% distributed under the terms of GPL v3 or later
-
-\setlength\overfullrule{5pt}
-
-\documentclass[a4paper,oneside]{scrartcl}
-\usepackage{fontspec}
-\usepackage{xunicode}
-
-\defaultfontfeatures{Ligatures=TeX}
-\setmainfont{DejaVuSerif}
-\setsansfont{DejaVuSans}
-\setmonofont{DejaVuSansMono}
-\renewcommand\familydefault{\sfdefault} \normalfont
-\newcommand\mylangle{$\langle$}
-\newcommand\myrangle{$\rangle$}
-
-\usepackage{xargs,xspace,fancyvrb,xcolor,pifont,calc,ifmtarg,mathstyle}
-
-\usepackage[sf,bf]{titlesec}
-\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
-\titleformat{\subsubsection}[runin]{\itshape}
- {\makebox[0pt][r]{\thetitle\kern1pc}}
- {0pt}{}[\maybedot\space --- \kern0pt]
-\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt}
-
-\usepackage{enumitem}
-\newlength\lssep \setlength\lssep{\smallskipamount}
-\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}
-
-\usepackage[british]{babel}
-\usepackage[bookmarks=true]{hyperref}
-\usepackage{bookmark}
-\hypersetup{%
- bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
- pdftitle={Texdoc: find and view documentation in TeX Live},
- pdfauthor={Manuel Pégourié-Gonnard, Takuto Asakura},
- pdfsubject={Texdoc's user manual},
- pdfkeywords={Texdoc, TeX Live, manual, documentation},
-}
-
-\usepackage[yyyymmdd]{datetime}
-\renewcommand{\dateseparator}{-}
-
-\newcommand\texlive{\TeX~Live\xspace}
-
-\setlength\parindent{\baselineskip}
-
-\lastlinefit=500 % e-TeX powered
-
-\definecolor{links}{named}{violet}
-\definecolor{special}{rgb}{0,0.5,0}
-\definecolor{code}{rgb}{0,0,0.6}
-\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
-
-\newcommand\cofont{% code
- \color{code}\normalfont\ttfamily}
-\newcommand\meta[1]{% meta elements
- {\normalfont\color{special}\mylangle\textit{#1}\myrangle}}
-
-% take care of non-breakable spaces
-\catcode`\ 10\relax
-
-\fvset{%
- formatcom=\cofont,
- defineactive=\makeallfancy,
- codes=\fancyactives,
-}
-\newcommand\fancyactives{\catcode`\«\active}
-\newcommand\makeallfancy{\makefancyog}
-\bgroup
- \catcode`\«\active
- \global\def\makefancyog{\def«##1»{\meta{##1}}}
-\egroup
-
-\newif\ifframed
-\newlength\dec
-\setlength\dec{\heightof{\cofont{texdoc \meta{name}}}}
-
-\makeatletter
-\newenvironment{commandes}[3]{%
- \def\thecmd{\noexpand#1}%
- \def\bmtext{#2}%
- \def\thelabel{#3}%
- \SaveVerbatim[samepage, gobble=2]{verbmat}%
-}{%
- \endSaveVerbatim
- \xdef\sectioncmd{\noexpand\nodotthistime
- \thecmd[\bmtext]{%
- \ifframed
- \unexpanded{\normalsize\normalfont
- \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
- \else
- \unexpanded{\normalsize\normalfont
- \BUseVerbatim{verbmat}}%
- \fi
- \noexpand\label{\thelabel}}}%
- \aftergroup\sectioncmd
-}
-\makeatother
-
-\newcommand\maybedot{.}
-\newcommand\nodotthistime{\renewcommand\maybedot{\global\def\maybedot{.}}}
-
-\newenvironment{cmdsubsec}[2]
- {\framedtrue \commandes\subsection{#1}{#2}}
- {\endcommandes}
-
-\newenvironment{cmdsubsub}[2]
- {\framedfalse \commandes\subsubsection{#1}{#2}}
- {\endcommandes}
-
-\makeatletter
-% code in hors-text
-\newenvironment{htcode}
- {\SaveVerbatim[samepage, gobble=2]{verbmat}}
- {
- \endSaveVerbatim
- \par\medskip\noindent\hspace*{\parindent}%
- \BUseVerbatim{verbmat}%
- \par\medskip\@endpetrue
- }
-\makeatother
-\DefineShortVerb{\|}
-
-\setkomafont{title}{}
-\setkomafont{subtitle}{\Large}
-\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
-
-\newcommand\tdml{\href{http://lists.tug.org/texdoc}{texdoc mailing list}\xspace}
+\documentclass{texdoc-doc}
\title{Texdoc}
-\subtitle{Find \& view documentation in \texlive\\
- \href{https://tug.org/texdoc/}{https://tug.org/texdoc/}}
+\subtitle{Find \& view documentation in \TL}
+\pkgurl{https://tug.org/texdoc/}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
-\date{v3.1\quad \today}
+\date{v3.2\quad \today}
\begin{document}
+
\VerbatimFootnotes
\maketitle
-\section{Quick guide}
-
-\subsection{Basics}
+\section{Quick Guide}
-Texdoc is a command line tool which find and view documentation in \texlive.
-If you type
+Texdoc is a command-line tool to find and view documents in {\TL}. Typing
%
-\begin{quote}
-|texdoc «name»|
-\end{quote}
+\begin{htcode}
+texdoc «name»
+\end{htcode}
%
-in your command line, the documentation of the |«name»| package will pop up. Of
-course, you have to replace |«name»| with the actual name of the package. To
-look up the documentation of more than one package at once, just use multiple
-|«name»|s as arguments.
-
-\subsection{Modes}\label{ss-modes}
-
-Texdoc has different modes that determine how results will be handled. In the
-default, ``view'' mode, it opens the first (supposedly the best) result with a
-suitable viewer. It is rather handy when you know what you want to read, and
-want to access it quickly. On the other hand, there may be other relevant
-documents for the given |«name»|, which are ignored in view mode.
-
-The so-called ``list mode'' makes Texdoc list all relevant documentation and
-ask you which one you want to view. It is useful when there another interesting
-sources of information besides the package's main documentation.
-
-There is also a ``mixed'' mode, intended to combine the best of view mode and
-list mode: if there is only one relevant result, then Texdoc opens it in a
-viewer, else it offers you a menu.
-
-By default, Texdoc hides the results it considers less relevant (unless it
-finds no relevant result at all). In ``showall'' mode, it always shows all
-results.
-
-To select the mode on the command-line, use |texdoc «option» «name»| with one
-of the following options: |-w| or |--view| for view mode, |-m| or |--mixed|
-for mixed mode, |-l| or |--list| for list mode, |-s| or |--showall| for
-showall mode.
-
-If you always (or mostly) use the same mode, you don't want to keep typing the
-same option. The next section describes how to customize Texdoc using
-configurations files.
-
-\subsection{Configuration files}\label{ss-quick-file}
-
-Use |texdoc --files| to know where to put your personal configuration file;
-you'll need to create this file (a possibly some directories) the first time.
-(If you want to know the full list of possible configuration files,
-see~\ref{ss-prec}.)
-
-In order to select you favorite mode, just insert a line |mode = «mode»| in
-this file, where |«mode»| is one of |view|, |mixed|, |list| or |showall|. To
-set your favorite language, use |lang = «2-letter code»|, though it is usually
-detected automatically.
-
-The configuration file can be used to tweak Texdoc in many ways, the most
-useful of which is probably the selection of the viewers for various types of
-documents, explained in the next section.
-
-\subsection{Viewers}\label{ss-viewer}
-
-Texdoc's mechanism for choosing a viewer varies according to your platform.
-On Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
+in your command line, you will see a document of the |«name»| package is popped
+up. Of course, you have to replace |«name»| with the actual name of a package.
+To look up the documentation of more than one packages at once, just give
+multiple |«name»|s as arguments.
+
+\subsection{Modes}
+\label{sec:modes}
+
+Texdoc has several modes that determine how results will be returned. The
+default is \emph{view} mode, which opens the first, that is supposedly the
+best, result with a suitable viewer. It is rather handy when you know what you
+want to read. On the other hand, there may be other relevant documents for the
+given |«name»|, which are ignored in the view mode.
+
+In the \emph{list} mode, Texdoc lists all relevant documentation and ask you
+which one you want to view. This mode is useful when there are other
+interesting sources of information in addition to the main documentation of a
+package.
+
+There is also a \emph{mixed} mode, intended to get the best of the view mode
+and list mode: if there is only one good result, then Texdoc opens it in a
+viewer, like in the view mode. Otherwise, it offers you a menu, like in the
+list mode.
+
+By default, Texdoc hides some results, which expected to be less relevant,
+unless it cannot find any relevant result. In the \emph{showall} mode, Texdoc
+always shows all results, including bad ones.
+
+A couple of command-line options are available for selecting the mode to
+execute: \sopt{w} (\lopt{view}) for the view mode, \sopt{m} (\lopt{mixed}) for
+the mixed mode, \sopt{l} (\lopt{list}) for the list mode, and \sopt{s}
+(\lopt{showall}) for the showall mode.
+
+If you have your favorite mode and always use it, you may not want to keep
+typing the same option. The next section describes how to customize Texdoc
+using its configurations files.
+
+\subsection{Configuration files}
+\label{sec:quick-file}
+
+The configuration file enables you to tweak Texdoc in many ways. You can use
+the \lopt{files} option to know where to put your personal configuration file;
+you may need to create this file, possibly with some parent directories. If you
+want to know the full list of possible configuration files, see
+Section~\ref{sec:prec}.
+
+To set your favorite mode, just insert a line |\ci{mode} = «mode»| in your
+personal configuration file, where |«mode»| is one of |view|, |mixed|, |list|,
+and |showall|. Though your preferred language is usually detected automatically
+by getting the system locale, you can set it explicitly with a line
+|\ci{lang} = «2-letter code»| in the configuration file.
+
+\subsection{Viewers}
+\label{sec:viewer}
+
+The way of Texdoc for choosing a viewer varies according to your platform. On
+Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
associations like when you double-click files in the Explorer, the Finder or
your default file manager (except for the text viewer, which is always a
pager). Otherwise, it tries to find a viewer in the path from a list of
``known'' viewers.
-You may want to select a different viewer for some kind of file. This is
-achieved by setting the various |viewer_«ext»| configuration options, where
-|«ext»| is the extension corresponding to the file type. For example, if you
-want to set xpdf as your default PDF viewer, and run it in the background,
-insert the line |viewer_pdf = xpdf %s &| in your configuration file. Here,
-|%s| stands for the name of the file to view.
-
-\subsection{You can stop reading now}
+You may want to use a different viewer for some types of documents. This can be
+achieved by setting the various \ci{viewer\_\meta{ext}} configuration items,
+where |«ext»| is an extension corresponding to a file type. For example, if
+you want to set \code{xpdf} as your default PDF viewer, and run it in the
+background, insert the line |viewer_pdf = xpdf %s &| in your configuration
+file. Herein, |%s| is a place holder for the name of the file to view.
-Following parts explain Texdoc's mechanisms for finding the best results and
-how to customize them. We have been trying hard to optimize the default
-configuration values so that you normally don't need to fiddle with that, but
-you may be curious or have special needs.
+\subsection*{\underline{You can stop reading now}}
-The final part is a full reference including a few points omitted in the
-present and next parts.
+The following parts explain the mechanisms of Texdoc for finding the best
+results and how to customize them. We have been trying hard to optimize the
+default configuration values so that normal users do not need to fiddle with
+it. Thus, the following parts are useful only when you are curious or have
+special needs.
\clearpage
-\section{File search, aliases, score}
-
-\subsection{An overview of how Texdoc works}
-
-When you type |texdoc «keyword»|, Texdoc first makes a list of files, from two
-sources:
-\begin{enumerate}
- \item In the trees containing documentation (given by the
- \href{https://www.tug.org/kpathsea/} {kpathsea} variable |TEXDOCS|), it
- selects all files containing |«keyword»| in their name (including the
- directory name);
- \item In the \texlive Database, it looks for packages named
- |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be
- |sty| or |cls|, and selects all the documentation files from this package.
-\end{enumerate}
-Files are filtered by extension: only files with known extensions may be
-selected. In case Texdoc cannot find any documentation here, fuzzy search will
-find the closest package name to the |«keyword»| and reselect the files (see
-\ref{ss-fuzzy}).
-
-The selected files are then score according to some simple heuristics. For
-example, a file named |«keyword».pdf|, is good, |«keyword»-«lang».pdf| will
-score higher if your favorite language |«lang»| is detected or configured,
-|«keyword»-doc| will be preferred over |«keyword»whatever|, files in a
-directory named exactly |«keyword»| get a bonus, etc.
-
-Score may also be adjusted base on file extensions or known names (or
-subwords): for example, by default, |Makefile|s get a very bad score since
-they are almost never documentation.\footnote{They often end up in the doc
- tree, since the source of documentation is often in the same directory as
- the documentation itself in \texlive. Other source files are discriminated
- by extension.}
-
-Finally, depending on the mode, the file with the highest score is opened in a
-viewer, or the list of results is shown. Usually, only results with a positive
-score are displayed, except in showall mode. Results with very bad scores
-(-100 and below) are never displayed.
-
-\medskip
-
-This model for searching and scoring is quite efficient, but is unfortunately
-not perfect: Texdoc may sometimes need a hint, either to find a relevant file
-or, more likely, to recognize which of the files found is the most relevant.
-
-For example, assume you are looking for the documentation of the shortvrb
-{\LaTeX} package. Texdoc will find |shortvrb.sty| in the |latex| \texlive
-package, but since this package contains a lot of documentation files, none of
-which contains the string |shortvrb|, it will sort them basically at random.
-
-Here comes the notion of \emph{alias}: in the default configuration file,
-|shortvrb| is aliased to |base/doc|, so that when you type |texdoc shortvrb|,
-Texdoc knows it has to look primarily for |base/doc|. Note that Texdoc will
-also look for the original name, and that a name can be aliased to more than
-one new name.
-
-\medskip
-
-We will soon see how you can configure this, but let's start with a few
-definitions about how a file can match keyword (all matching is
-case-insensitive):
-\begin{enumerate}
- \item The keyword is a substring of the file name.
- \item The keyword is a ``subword'' of the file name; words are defined as
- sequences of alphanumeric characters delimited by punctuation characters
- (there is no space in file names in \texlive) and a subword is a
- substring both ends of which are a word boundary.
- \item The keyword matches ``exactly'' the file name: that is, the file
- name is the keyword, possibly plus an extension.
-\end{enumerate}
-
-\subsection{Alias directives}\label{ss-alias}
-
-\begin{htcode}
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
-\end{htcode}
-
-You can define your own aliases in Texdoc's configuration files
-(see~\ref{ss-quick-file} or \ref{ss-prec}). For example,
-insert\footnote{Actually, you don't need to do this, the default configuration
- file already includes this directive.}
-\begin{htcode}
- alias shortvrb = base/doc
-\end{htcode}
-in order to alias |shortvrb| to |base/doc|. Precisely, it means that files in
-the doc trees matching exactly |base/doc| will be added to the result list
-when you look for |shortvrb|, and get a score of 10 (default score for alias
-results). This is greater than the results of heuristic scoring: it means that
-results found via aliases will always rank before results associated to the
-original keyword.
-
-If you want the results associated to a particular alias to have a custom
-score instead of the default 10, you can use the optional argument to the
-alias directive. This can be useful if you associate many aliases to
-a keyword and want one of them to show up first.
-
-Additionally, starting from with v0.80, aliases for |«keyword»-«lang»|, where
-|«lang»| is your preferred language's 2-letter code (as detected or
-configured, see the |lang| option) are also used for |«keyword»| and get a
-|+1| score upgrade.
-
-You can have a look at the configuration file provided (the last shown by
-|texdoc -f|) for examples. If you feel one of the aliases you defined locally
-should be added to the default configuration, please share it on the \tdml.
-
-Aliases are additive: if you define your own aliases for a keyword in your
-configuration file, and there are also aliases for the same keyword in the
-default configuration, they will add up. To prevent the default aliases
-from being applied for a particular keyword, include |stopalias «keyword»| in
-your personal configuration file. It will preserve the aliases defined before
-this directive (if any) but prevent all further aliasing on this keyword.
-
-\textit{Remark.} Aliasing is case-insensitive, and doesn't cascade:
-only aliases associated to the original keyword are used.
-
-\textbf{Warning.} Results found from aliases always have the score defined by
-the |alias| directive (10 by default), regardless of the adjustments described
-in the next subsections.
-
-\subsection{Score directives}\label{ss-score}
-
-\begin{htcode}
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
-\end{htcode}
+\section{Controlling Texdoc}
-It is possible to adjust the score of results containing some pattern as a
-subword, either globally (for the result of all searches) or only when
-searching with a particular keyword. This is done in a configuration file
-(\ref{ss-quick-file} or \ref{ss-prec}) using the |adjscore| directive. Here are
-a few examples from the default configuration file.
+\subsection{Command-line options}
+\label{sec:cl}
+The full usage of Texdoc can be summarized as follows:
+%
\begin{htcode}
- adjscore /Makefile = -1000
- adjscore /tex-virtual-academy-pl/ = -50
- adjscore(tex) texdoc = -10
+texdoc «names»
+texdoc «options» «names»
+texdoc «action»
+texdoc «options» «action»
\end{htcode}
-All files named |Makefile| (and also files named |Makefile-foo| if there are
-any) are ``killed'' : by adjusting their score with such a large negative
-value, their final score will most probably be less than -100, so they will
-never be displayed. Files from the |tex-virtual-academy-pl| directory, on the
-other hand, are not killed but just get a malus, since they are a common
-source of ``fake'' matches which hide better results (even for the lucky ones
-who can read polish).
-
-The third directive gives a malus for results containing |texdoc| only if the
-search keyword is |tex|. Otherwise, such results would get a high score
-because the heuristic scoring would think |texdoc| is the name of \TeX's
-documentation. The value -10 is enough to ensure that those results will have
-a negative score, so will not be displayed unless ``showall'' mode is active.
-
-\textbf{Warning}: Values of scores (like the default score for aliases, the
-range of heuristic scoring, etc.) may change in a future version of Texdoc.
-So, don't be surprised if you need to adapt your scoring directives after a
-future update of Texdoc. This warning will hopefully disappear at some point.
-
-\subsection{File extensions and names}\label{ss-ext}
-
-The allowed file extensions are defined by the configuration item |ext_list|
-(default: pdf, html, htm, txt, md, ps, dvi, no extension). You can configure it
-with a line |ext_list = «your, list»| in a configuration file. Be aware
-that it will completely override the default list, not add to it. An empty
-string in the list means files without extension (no dot in the name), while a
-star means any extension.
-
-For scoring purposes, there is also a |badext_list| parameter: files whose
-extension is ``bad'' according to this list will get a lesser score (currently
-0).
-
-Unfortunately, sometimes what follows a dot in a file name is not a ``real''
-extension. This often happens with readme files, for example |readme.fr| or
-|readme.texlive|. So, in addition to his list of known extensions, Texdoc has
-a list of known basenames, by default just |readme|.
-
-The corresponding settings are |basename_list| and |badbasename_list|; both
-are similar to |ext_list| and |badext_list|. So, a file will be selected if
-either its extension or its base name is known, and get a lesser score if
-either is known to be ``bad.''
-
-\subsection{Variants}\label{ss-variants}
-
-The documentation for a given package is often found in a file named like
-|«package»-doc|. To handle this properly, Texdoc gives a special score files
-named |«package»«suffix»| where |«suffix»| is one element of the list given by
-the configuration setting |suffix_list|.
-
-To customise this list, add a line with |suffix_list = «your, list»| in a
-configuration file. Be warned, it will replace the default list, no expand
-it. You'll find the default list in the shipped configuration file; feel free
-to suggest additions on the \tdml (with a real-life example).
-
-\subsection{Fuzzy search}\label{ss-fuzzy}
-
-When the normal search can't find any document in {\texlive}, Texdoc will
-execute fuzzy search without user-interactions. The fuzzy search finds the
-closest name of package in {\texlive}\footnote{Note that the feature searches
-only package names at this point. Other objects such as aliases cannot be found
-by the fuzzy search.} to the input |«keyword»|. The results of fuzzy search are
-shown by as an informational message (you can see that with option |-v|).
-
-The default allowance of Levenshtein distance is 5. You can change this default
-value by specifying |fuzzy_level| in your |texdoc.cnf| (see
-\ref{cf-fuzzy_level}). Results of fuzzy search could be irreproducible if
-multiple strings have the same Levenshtein distance.
-
-\clearpage
-
-\section{Full reference}
-
-\subsection{Precedence of configuration sources}\label{ss-prec}
-
-Values for a particular setting can come from several sources. The sources are
-treated in the following order and the first value found is always used:
-\begin{enumerate}
- \item Command-line options.
- \item Environment variables ending with |_texdoc|.
- \item Other environment variables.
- \item Values from configuration files (see below).
- \item Hard-coded defaults that may depend on the current machine.
-\end{enumerate}
-
-The configuration files are found in the directories |TEXMF/texdoc|, where
-|TEXMF| is the kpathsea variable, in the order given by this variable. Inside
-each directory, three files are recognized, in this order:
-\begin{enumerate}
- \item |texdoc-«platform».cnf| where |«platform»| is the name of the current
- platform (defined as the name of the directories where the \texlive
- binaries are located, for example |x86-64-linux|). This may be useful when
- an installation is shared across machines with different architectures
- needing different settings, for example for viewers. Their use is not
- recommended in any other situation.
- \item |texdoc.cnf| is the recommended file for normal use.
- \item |texdoc-dist.cnf| is useful for installing a newer version of texdoc
- (including its default configuration file) in your home while retaining
- the use of the previous file for your personal setting; see
- \href{https://github.com/TeX-Live/texdoc}{our GitHub repository} for
- instructions on running the development version.
-\end{enumerate}
-
-\subsection{Command-line options}\label{ss-cl}
+We have tried to implement a GNU-compatible option parser. Short options, each of
+which consists of a single letter, must start with a single hyphen |-|.
+Multiple short options can be specified with a single hyphen, \eg |-vl| is
+equivalent to |-v -l|. Long options have to be following double hyphens |--|.
+All options must be specified before the first argument. A String beginning
+with a hyphen after the first argument will be treated as an argument starting
+with a hyphen.
-All command-line options (except the first four below) correspond to
-configuration item that can be set in the configuration files: we refer
-the reader to the corresponding section for the meaning of this configuration
-item.
-
-\begin{cmdsubsub}{-h, --help}{cl-h}
- -h, --help
-\end{cmdsubsub}
+Some options are called action options, which can be used for |«action»| in the
+above usage. Four actions are available:
+\begin{clopt}{\sopt{h}, \lopt{help}}
Shows a quick help message (namely a list of command-line options) and exit
successfully.
+\end{clopt}
-\begin{cmdsubsub}{-V, --version}{cl-V}
- -V, --version
-\end{cmdsubsub}
-
+\begin{clopt}{\sopt{V}, \lopt{version}}
Shows the current version of the program and exit successfully.
+\end{clopt}
-\begin{cmdsubsub}{-f, --files}{cl-f}
- -f, --files
-\end{cmdsubsub}
-
+\begin{clopt}{\sopt{f}, \lopt{files}}
Shows the list of configuration files for the current installation and
platform, with their status and exit successfully. Normally, only ``active''
-and ``disabled'' files are shown (see~\ref{cf-lastfile_switch}). To show ``not
-found'' files as well, you can use |--verbose|.
+and ``disabled'' files are shown (see~\ci{lastfile\_switch}). To show ``not
+found'' files as well, you can use \lopt{verbose}.
+\end{clopt}
-\begin{cmdsubsub}{--just-view}{cl-just-view}
- --just-view «file»
-\end{cmdsubsub}
-
-Open «file» in the usual viewer. The file should be given with full path,
+\begin{clopt}{\code{\lopt{just-view} \meta{file}}}
+Open |«file»| in the usual viewer. The file should be given with full path,
absolutely no searching is done. This option is not really meant for users,
but rather intended to be used from another program, like a GUI front-end to
Texdoc.
+\end{clopt}
+
+Some normal options such as \sopt{v} are effective for some actions but note
+that you have to specify such options \emph{before} the action option. Options
+after an action option will be ignored.
+
+The followings are other normal command-line options:
+
+\begin{clopt}{\sopt{w}, \lopt{view}}[default]
+Set \ci{mode} to |view|. Texdoc will open the best results it found by the best
+application it knows. See Section~\ref{sec:modes}.
+\end{clopt}
+
+\begin{clopt}{\sopt{l}, \lopt{list}}
+Set \ci{mode} to |list|. Texdoc will show the lists of all relevant documents
+it found and ask you which to open. When used with the \lopt{nointeract}
+option, Texdoc will just show the lists of documents and exist successfully.
+\end{clopt}
+
+\begin{clopt}{\sopt{m}, \lopt{mixed}}
+Set \ci{mode} to |mixed|. If Texdoc finds only a document for your keyword,
+then it opens it, and if it finds multiple, then it will behave like in the
+|list| mode.
+\end{clopt}
+
+\begin{clopt}{\sopt{s}, \lopt{showall}}
+Set \ci{mode} to |showall|. It also behave like in a |list| mode, but show all
+the documents it found including documents which seem to be not a good result.
+\end{clopt}
+
+\begin{clopt}{\sopt{i}, \lopt{interact}}[default]
+Texdoc may require user reactions, \eg ask you which document to open in the
+|list| mode. Internally, this sets \ci{interact\_switch} to |true|.
+\end{clopt}
+
+\begin{clopt}{\sopt{I}, \lopt{nointeract}}
+If this is specified, Texdoc will never request any input from users.
+Internally, this sets \ci{interact\_switch} to |false|.
+\end{clopt}
+
+\begin{clopt}{\sopt{M}, \lopt{machine}}
+This make the result list of Texdoc machine-readable. Only effective for the
+|list| mode and its friends. This option implies \lopt{nointeract}.
+Internally, this sets \ci{machine\_switch} to |true|.
+\end{clopt}
+
+\begin{clopt}{\sopt{q}, \lopt{quiet}}
+This suppress warnings and most error messages. Internally, this sets
+\ci{verbosity\_level} to minimum.
+\end{clopt}
+
+\begin{clopt}{\sopt{v}, \lopt{verbose}}
+Make Texdoc to print additional information such as viewer commands which are
+invoked by the program. Internally, this sets \ci{verbosity\_level} to maximum.
+\end{clopt}
+
+\begin{clopt}{%
+ \code{\sopt{d} \meta{list}}, \code{\lopt{debug}=\meta{list}},
+ \sopt{D}, \lopt{debug}}
+This sets \ci{debug\_list} to show dubbging information in the specified
+category. You can specify multiple categories with a comma-separated list. If
+you specify |-D| or |--debug| without specifying a list, it activates all
+available debug categories.
+\end{clopt}
+
+\begin{clopt}{\code{\sopt{c} \meta{name}=\meta{value}}}
+This enables you to set arbitrary configuration items |«name»| to |«value»|
+from the command-line. See Section~\ref{sec:conf} for the list of all available
+configuration items.
+\end{clopt}
+
+\subsection{Environment variables}
+\label{sec:envvar}
+
+Some environment variables affect the behavior of Texdoc. The environment
+variables can be roughly categorized into three groups.
+
+First, as well as other programs in {\TL}, searching path for the Texdoc are
+determined with the Kpathsea variables like |TEXMF*|. The mechanism of Kpathsea
+is complex, so please refer to `the {\TL} Guide', which supposed to be open by
+|texdoc texlive|, and the document of Kpathsea for the details. Usually, Texdoc
+searches documents for the |TEXMF| trees including |TEXMFDIST|, |TEXMFLOCAL|,
+and |TEXMFHOME| and trees specified in |TEXDOCS|. It also self-locates its own
+program using |TEXMF| search path. In addition, Texdoc uses |TEXMFROOT| and
+|TEXMFVAR| to look for the tlpdb database and the cache respectively.
+
+Second, the viewers for opening documents can be controlled by some environment
+variables. They all correspond to some \ci{viewer\_\meta{ext}}
+setting.\footnote{Old names of environment variables, namely
+|TEXDOCVIEW_\{html,dvi,md,txt,pdf,ps\}| and
+|TEXDOC_VIEWER_\{HTML,DVI,MD,TXT,PDF,PS\}|, are deprecated but still work.} You
+can append |_texdoc| to every name in the first column: this wins over every
+other name. These variables can be split by colon |:| and the first non-nil
+occurrence is used. If a viewer command contains colon, please specify it by
+\ci{viewer\_\meta{ext}}.
+%
+\begin{center}
+\begin{tabular}{lll}
+Variable & Use for & Configuration item \\ \hline
+|BROWSER| & HTML files & |viewer_html| \\
+|DVIVIEWER| & DVI files & |viewer_dvi| \\
+|MDVIEWER| & Markdown files & |viewer_md| \\
+|PAGER| & Text files & |viewer_txt| \\
+|PDFVIEWER| & PDF files & |viewer_pdf| \\
+|PSVIEWER| & PS files & |viewer_ps| \\
+\end{tabular}
+\end{center}
-\begin{cmdsubsub}{-w, -l, -m, -s, --view, --list, --mixed, --showall}{cl-mode}
- -w, --view, -l, --list, -m, --mixed, -s, --showall
-\end{cmdsubsub}
-
-Set |mode| to the given value, see~\ref{cf-mode}.
-
-\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
- -i, --interact, -I, --nointeract
-\end{cmdsubsub}
+Third, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
+are used for the default value of \ci{lang}.
-Set |interact_switch| to true (or false), see~\ref{cf-interact_switch}.
+\subsection{Precedence of configuration sources}
+\label{sec:prec}
-\begin{cmdsubsub}{-M, --machine}{cl-M}
- -M, --machine
-\end{cmdsubsub}
+Values for a particular setting can come from several sources. The sources are
+looked at in the following order and the first value found is always used:
+%
+\begin{enumerate}
+\item Command-line options.
+\item Environment variables ending with |_texdoc|.
+\item Other environment variables.
+\item Values from configuration files (see below).
+\item Hard-coded defaults that may depend on the current machine.
+\end{enumerate}
-Set |machine_switch| to true, see~\ref{cf-machine_switch}.
+The configuration files are found in the directories \path{TEXMF/texdoc}, where
+\path{TEXMF} is the kpathsea variable, in the order given by this variable.
+Inside each directory, three files are recognized, in this order:
+%
+\begin{enumerate}
+\item |texdoc-«platform».cnf| where |«platform»| is the name of the current
+ platform (defined as the name of the directories where the {\TL}
+ binaries are located, for example |x86-64-linux|). This may be useful when
+ an installation is shared across machines with different architectures
+ needing different settings, for example for viewers. Their use is not
+ recommended in any other situation.
+\item |texdoc.cnf| is the recommended file for normal use.
+\item |texdoc-dist.cnf| is useful for installing a newer version of texdoc
+ (including its default configuration file) in your home while retaining
+ the use of the previous file for your personal setting; see
+ {\TexdocRepo} for instructions on running the development version.
+\end{enumerate}
-\begin{cmdsubsub}{-q, --quiet}{cl-q}
- -q, --quiet
-\end{cmdsubsub}
+\subsection{Exit codes}
+\label{sec:exit}
-Set |verbosity_level| to minimum, see~\ref{cf-verbosity_level}.
+The status of Texdoc, which is whether or not it was successfully executed and
+an expected result was delivered, can be grasped by seeing its exit code. This
+will be useful to manage Texdoc by other programs. The current exit codes of
+Texdoc are:
+%
+\begin{description}[left=2em]
+\item[\code{0}] Success.
+\item[\code{1}] Internal error.
+\item[\code{2}] Usage error.
+\item[\code{3}] No documentation found.
+\end{description}
-\begin{cmdsubsub}{-v, --verbose}{cl-v}
- -v, --verbose
-\end{cmdsubsub}
+\section{Customizing the Search Results}
-Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}.
+\subsection{An overview of how Texdoc works}
-\begin{cmdsubsub}{-d, -D, --debug}{cl-d}
- -d «list», --debug=«list», -D, --debug
-\end{cmdsubsub}
+When you type |texdoc «keyword»|, first filenames related to the |«keyword»|
+are collected from the two following sources.
+%
+\begin{enumerate}
+\item the |TEXMF| trees containing documentation that specified by the
+ \href{https://www.tug.org/kpathsea/}{kpathsea} variable |TEXDOCS|: Texdoc
+ collects all files containing |«keyword»| in their filenames or in the names
+ of their parent directories.
+\item the {\TL} Database (|texlive.tlpdb|): Texdoc searches for packages named
+ |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be |sty|
+ or |cls|, and collects all document files of the found packages.
+\end{enumerate}
-Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug|
-without specifying a list, activates all available debug items.
+Second, the collected filenames are filtered by their extensions. After
+filtering, only files with known extensions (listed in \ci{ext\_list}) remain.
+If Texdoc cannot find any documentation, the fuzzy search will find the closest
+package name to the |«keyword»| and it will recollect document files (see
+Section~\ref{sec:fuzzy}).
+
+Third, the collected filenames are given numeric scores by using some
+heuristics. For example, a filename |«keyword».pdf| is good, and thus gets a
+high score. A name |«keyword»-«lang».pdf| is also good and gets a higher score
+if the |«lang»| is the preferred language code in your configuration. In
+addition, there are several rules such as ``a name |«keyword»-doc| always wins
+over any names |«keyword»whatever|'' and ``files under a directory named
+exactly |«keyword»| get bonuses''. Scores may also be adjusted based on the
+extensions and some known names or subwords. For example, by default,
+|Makefile|s get very low scores because basically they are not
+documents.\footnote{Nevertheless, they often end up in the |doc| trees,
+because in {\TL}, sources of documents are usually in the same directory as the
+documents themselves. Other source files for documents are discriminated by
+their extensions.}
+
+Finally, a file with the highest score is opened with a viewer, or the list
+of results is shown, depending on the current mode. Usually, only results with
+positive scores are displayed, except in the |showall| mode. Results with very
+bad scores, that are lower than |-100|, are never displayed.
+
+This model for searching and scoring is efficient, but unfortunately, it is not
+perfect: Texdoc may sometimes need a hint, either to find a relevant file or,
+more likely, to recognize which of the found files is the best. For example,
+suppose you are looking for a document of the {\LaTeX} package |shortvrb|.
+Texdoc will successfully find |shortvrb.sty| in the {\TL} package |latex|.
+However, Texdoc will not be able to sort a number of documents in the |latex|
+package correctly because none of them contains the string |shortvrb|.
+
+For such cases, \emph{aliases} are useful: in the default configuration file,
+|shortvrb| is aliased to |base/doc|, so that Texdoc primarily look for
+|base/doc| when you type |texdoc shortvrb|. Note that Texdoc will also look for
+the original keyword, and that a name can be aliased to more than one new
+name.
-\begin{cmdsubsub}{-c}{cl-c}
- -c «name»=«value»
-\end{cmdsubsub}
+\subsection{Aliases}
+\label{sec:alias}
-Set configuration item |«name»| to |«value»|. This is a general way to access
-any configuration items listed in \ref{ss-conf} from command line.
+Aliases can be set in configuration files of Texdoc with the following syntax:
+%
+\begin{htcode}
+alias «original keyword» = «name»
+alias(«score») «original keyword» = «name»
+\end{htcode}
+%
+A number of aliases are already set in the default configuration file. You can
+also define your own aliases in your personal configuration files (see
+Section~\ref{sec:quick-file} or \ref{sec:prec} to know where is that). For example,
+you can add a line
+%
+\begin{htcode}
+alias td = texdoc
+\end{htcode}
+%
+to the file to alias |td| to |texdoc|. Then, files in the doc trees matching
+exactly with |texdoc|, \ie this document |texdoc.pdf|, will be added to the
+result list when you search for the keyword |td|.
+
+By default, files match with the aliased name get a score of |10|. This score
+is greater than any result of heuristic scoring. It means that results found
+via aliases will always be ranked higher than results found for the original
+keyword. If you want the results associated with a particular alias to have a
+custom score instead of the default score |10|, you can use the optional
+argument to the |alias| directive. This can be useful if you associate multiple
+aliases to a keyword and want to specify the priorities for them.
+
+In addition, aliases for |«keyword»-«lang»|, where |«lang»| is your preferred
+language's 2-letter code (as detected or configured, see the |lang| option), are
+also used when searching for |«keyword»|. Files match with these language-based
+aliases get additional bonus scores so that they win over the results for
+language-independent aliases.
+
+For concrete examples, please have a look at the default configuration file,
+which can be found in the last line of the output for |texdoc -f|. If you think
+aliases you defined locally should be added to the default configuration,
+please share the idea to the {\TexdocML} or {\TexdocRepo}.
-\subsection{Environment variables}\label{ss-envvar}
+Aliases are additive: if you define your own aliases for a keyword in your
+configuration file, and there are also aliases for the same keyword in the
+default configuration, they will add up. To prevent the default aliases from
+being applied for a particular keyword, add a line |stopalias «keyword»| in
+your personal configuration file. It will preserve the aliases defined before
+this directive if any, but prevent all further aliasing on this keyword.
-They all correspond to some |viewer_«ext»| setting, and the reader is referred
-to~\ref{cf-viewer_*} for details.\footnote{Old names of environment variables,
-namely |TEXDOCVIEW_{html,dvi,md,txt,pdf,ps}| and
-|TEXDOC_VIEWER_{HTML,DVI,MD,TXT,PDF,PS}|, are deprecated but still work.} You can
-append |_texdoc| to every name in the first column: this wins over every other
-name.
+Here are some notes for aliases. First, they are case-insensitive. Second, they
+do not work recursively: only aliases set to the original keyword are used.
+Third, results found for aliases always get the score defined by the |alias|
+directive (|10| by default). The adjustments described in the other subsections
+are not applied to results for aliases.
-\begin{center}
-\begin{tabular}{ll}
-Environment variables & Configuration items \\
-|BROWSER| & |viewer_html| \\
-|DVIVIEWER| & |viewer_dvi| \\
-|MDVIEWER| & |viewer_md| \\
-|PAGER| & |viewer_txt| \\
-|PDFVIEWER| & |viewer_pdf| \\
-|PSVIEWER| & |viewer_ps| \\
-\end{tabular}
-\end{center}
+\subsection{Score adjustments}
+\label{sec:score}
-Also, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
-are used for the default value of |lang|.
+Scores can be arbitrary adjusted by using the |adjscore| directive in the
+configuration files. The adjustment can be done either for global, \ie for any
+keywords, or a particular keyword. The syntax is as follow:
+%
+\begin{htcode}
+adjscore «pattern» = «score adjustment»
+adjscore(«keyword») «pattern» = «score adjustment»
+\end{htcode}
+%
+When the optional argument |«keyword»| is specified, the adjustment will be
+applied only when a user searches for the |«keyword»|. Otherwise, the
+adjustment applied always for the |«pattern»|.
-\subsection{Configuration items}\label{ss-conf}
+Here are a few examples from the default configuration file.
-\subsubsection{Structure of configuration files}\label{sss-sonf-struct}
+\begin{htcode}
+adjscore /Makefile = -1000
+adjscore /tex-virtual-academy-pl/ = -50
+adjscore(tex) texdoc = -10
+\end{htcode}
+%
+Herein, all files named |Makefile|, and those with suffixes, \eg |Makefile.in|,
+will be eliminated from results: by adjusting their score with such a large
+negative value, their final score will be less than |-100|. Which means they
+will never be displayed. Files from the |tex-virtual-academy-pl| directory, on
+the other hand, are not eliminated but get a negative adjustment, since they
+are a common source of ``fake'' matches which hide better results. The third
+line gives a minus adjustment for results containing |texdoc| only when the
+searched keyword is |tex|. Otherwise, such results would get high scores
+because the heuristic scoring would assume |texdoc| is the name of
+documentation for {\TeX} itself. The adjustment value |-10| is enough to ensure
+that those results will have a negative score, so the files containing |texdoc|
+will not be displayed unless |showall| mode is used.
+
+Note that the values of scores, such as the default score for aliases and the
+range of heuristic scores, may be changed in a future version of Texdoc.
+Therefore, you may need to adapt your score adjustments after updating Texdoc
+in the future.
+
+\subsection{Extensions and basenames of files}
+\label{sec:ext}
+
+File extensions regarded as documents by Texdoc can be specified with the
+configuration item \ci{ext\_list}. By default, files with extensions |pdf|,
+|html|, |htm|, |txt|, |md|, |ps|, and |dvi| and files without extension are
+recognized as documents.
+
+During the scoring process, the configuration item |badext_list| is also used:
+files with a ``bad'' extension appearing in this list will get a lesser score.
+
+In the practical filenames, things which are not actually extensions can follow
+dots, \eg |readme.fr| and |readme.texlive|. Thus, in addition to the lists of
+known extensions, Texdoc has lists for known basenames: \ci{basename\_list} and
+\ci{badbasename\_list}. These configuration items are respectively similar to
+\ci{ext\_list} and \ci{badext\_list}. In short, a file will be selected if
+either its extension or its basename is known, and get a lesser score if either
+is known to be ``bad''.
+
+\subsection{Common filenames}
+\label{sec:common-names}
+
+Document filenames of packages are often in the form of |«package»-doc|.
+Respecting this culture in the {\TeX} community, Texdoc gives a special score
+for files named |«package»«suffix»|, where |«suffix»| is an element of the list
+\ci{suffix\_list}. Please refer to the shipped configuration file for the
+default setting. Also, feel free to suggest additional elements for the list to
+the {\TexdocML} with a real-life example.
+
+\subsection{Fuzzy search}
+\label{sec:fuzzy}
+
+When the normal search cannot find any document in {\TL}, Texdoc will execute a
+fuzzy search. The fuzzy search tries to find the closest name of a package in
+{\TL}\footnote{Note that the feature searches only package names at this point.
+Other objects such as aliases cannot be found by the fuzzy search.} to the
+input |«keyword»|. The results of the fuzzy search are shown in an info
+message, which can be seen by using the command-line option |-v|.
+
+The default allowance of Levenshtein distance is |5|. You can change this
+allowance by using the configuration item \ci{fuzzy\_level}. Results of fuzzy
+search could be different among executions if multiple package names have the
+same Levenshtein distance to the input.
+
+\section{Configuration items}
+\label{sec:conf}
Configuration files are line-oriented text files. Comments begin with a |#|
and run to the end of line. Lines containing only space are ignored. Space at
the beginning or end of a line, as well as around an |=| sign, is ignored.
Apart from comments and empty lines, each line must be of one of the following
forms.
-
+%
\begin{htcode}
- «configuration item» = «value»
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
- stopalias «original keyword»
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
+«configuration item» = «value»
+alias «original keyword» = «name»
+alias(«score») «original keyword» = «name»
+stopalias «original keyword»
+adjscore «pattern» = «score adjustment»
+adjscore(«keyword») «pattern» = «score adjustment»
\end{htcode}
We will concentrate on the |«configuration item»| part here, since other
-directives have already been presented (\ref{ss-alias} and \ref{ss-score}).
+directives have already been presented (Section~\ref{sec:alias} and
+\ref{sec:score}).
In the above, |«value»| never needs to be quoted: quotes would be interpreted
as part of the value, not as quotation marks (this also holds for the other
@@ -606,56 +533,48 @@ directives).
Lines which do not obey these rules raise a warning, as well as unrecognised
values of |«configuration item»|. The |«value»| can be an arbitrary string,
except when the name of the |«configuration item»| ends with:
+%
\begin{enumerate}
- \item |_list|, then |«value»| is a coma-separated list of strings. Space
- around commas is ignored. Two consecutive comas or a coma at the beginning
- or end of the list means the empty string at the corresponding place.
- \item |_switch|, then |«value»| must be either |true| or |false|
- (lowercase).
- \item |_level|, then |«value»| is an integer.
+\item |_list|, then |«value»| is a coma-separated list of strings. Spaces
+ around commas are ignored. Two consecutive comas or a coma at the beginning
+ or end of the list means the empty string at the corresponding place.
+\item |_switch|, then |«value»| must be either |true| or |false|
+ (lowercase).
+\item |_level| and |_lines|, then |«value»| is an integer.
\end{enumerate}
+%
In these cases, an improper |«value»| will raise a warning too.
-\begin{cmdsubsub}{mode}{cf-mode}
- mode = «view, list, mixed, showall»
-\end{cmdsubsub}
-Set the mode to the given value. Default is |view|. The various modes
-have been presented in~\ref{ss-modes}.
-
-\begin{cmdsubsub}{interact}{cf-interact_switch}
- interact_switch = «true, false»
-\end{cmdsubsub}
-
-Turn on or off interaction. Default is on. Turning interaction off prevents
-Texdoc from asking you to choose a file to view when there are multiple
-choices, so it just prints the list of files found.
-
-\begin{cmdsubsub}{suffix_list}{cf-suffix_list}
- suffix_list = «list»
-\end{cmdsubsub}
-
-Set the list of known suffixes to |«list»| (see~\ref{ss-variants}). Default is
-the empty list, but see the shipped configuration file for more.
-
-\begin{cmdsubsub}{ext_list}{cf-ext_list}
- ext_list = «list»
-\end{cmdsubsub}
-
-Set the list of recognised extensions to |«list»|. The default value is:
+\begin{confitem}{mode}
+ {\choice{view, list, mixed, showall}}[default: \code{view}]
+Set the mode to the given value. The various modes have been described
+in Section~\ref{sec:modes}.
+\end{confitem}
+
+\begin{confitem}{interact\_switch}{\choice{true, false}}[default: \code{true}]
+Turn on or off interaction. Turning interaction off prevents Texdoc from asking
+you to choose a file to view when there are multiple choices, so it just prints
+the list of files found.
+\end{confitem}
+
+\begin{confitem}{suffix\_list}{\meta{list}}[default: empty]
+Set the list of known suffixes to |«list»| (see
+Section~\ref{sec:common-names}). Default is the empty list, but see the
+shipped configuration file for more.
+\end{confitem}
+
+\begin{confitem}{ext\_list}
+ {\meta{list}}[default: \code{pdf, html, htm, txt, md, dvi, ps,}]
+Set the list of recognised extensions to |«list»|. This list is used to filter
+and sort the results that have the same score (with the default value: pdf
+first, etc). Two special values are recognised:
%
-\begin{htcode}
- pdf, html, htm, txt, md, dvi, ps,
-\end{htcode}
-%
-This list is used to filter and sort the results that have the same
-score (with the default value: pdf first, etc). Two special values are
-recognised:
\begin{itemize}
- \item \emph{The empty element}. This means files without extensions, or more
- precisely without a dot in their name. This is meant for files like
- |README|, etc. The file is assumed to be plain text for viewing purpose.
- \item |*| means any extension. Of course if it is present in the list, it
- can be the only element!
+\item \emph{The empty element}. This means files without extensions, or more
+ precisely without a dot in their name. This is meant for files like
+ |README|, etc. The file is assumed to be plain text for viewing purpose.
+\item |*| means any extension. Of course if it is present in the list, it
+ can be the only element!
\end{itemize}
There is a very special case: if the searched |«name»| has |.sty| extension,
@@ -669,171 +588,150 @@ For each |«ext»| in |ext_list| there should be a corresponding |viewer_«ext»
value set. Defaults are defined corresponding to the default |ext_list|, but
you can add values if you want. For example, if you want Texdoc to be able
to find man pages and display them with the |man| command, you can use
+%
\begin{htcode}
- ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps,
- viewer_1 = man
- viewer_5 = man
+ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps,
+viewer_1 = man
+viewer_5 = man
\end{htcode}
As a special case, if the extension is |sty|, then the |txt| viewer is used;
similarly, if it is |htm| the |html| viewer is used. Otherwise, the |txt|
viewer is used and a warning is issued.
-
-\begin{cmdsubsub}{badext_list}{cf-badext_list}
- badext_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``bad'' extensions to |«list»|. Default is ``|txt,|''. Files
-with those extensions get a malus of |1| on their heuristic score if it was
-previously positive.
-
-\begin{cmdsubsub}{basename_list}{cf-basename_list}
- basename_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``known'' base names to |«list»|. Default is ``|readme|''.
-Files with those base names are selected regardless of their extension. If the
-extension is unknown, the text viewer will be used to view the file.
-
-\begin{cmdsubsub}{badbasename_list}{cf-badbasename_list}
- badbasename_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``bad'' base names to |«list»|. Default is ``|readme|''. Files
-with those names get a malus of |1| on their heuristic score if it was
-previously positive.
-
-\begin{cmdsubsub}{viewer_*}{cf-viewer_*}
- viewer_«ext» = «cmd»
-\end{cmdsubsub}
-
-Set the viewer command for files with extension |«ext»| to |«cmd»|. For files
-without extension, |viewer_txt| is used, and there's no |viewer_| variable.
-In |«cmd»|, |%s| can be used as a placeholder for the file name, which is
-otherwise inserted at the end of the command. The command can be an arbitrary
-shell construct.
-
-\begin{cmdsubsub}{lang}{cf-lang}
- lang = «2-letter code»
-\end{cmdsubsub}
-
-Set you preferred language. Defaults to your system's locale.
-
-\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
- verbosity_level = «n»
-\end{cmdsubsub}
-
-Set the verbosity level to |«n»| (default: 2). At level~3, errors, warnings and
-informational messages will be printed on stderr; 2 means only errors and
-warnings, 1 only errors and 0 nothing except internal errors (obviously not
+\end{confitem}
+
+\begin{confitem}{badext\_list}{\meta{list}}[default: \code{txt}]
+Set the list of ``bad'' extensions to |«list»|. Files with those extensions get
+a malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
+
+\begin{confitem}{basename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
+Set the list of ``known'' base names to |«list»|. Files with those base names
+are selected regardless of their extension. If the extension is unknown, the
+text viewer will be used to view the file.
+\end{confitem}
+
+\begin{confitem}{badbasename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
+
+Set the list of ``bad'' base names to |«list»|. Files with those names get a
+malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
+
+\begin{confitem}{viewer\_\meta{ext}}{\meta{command}}
+Set the viewer command for files with extension |«ext»| to |«command»|. For
+files without an extension, |viewer_txt| is used. Note that there is no
+|viewer_| variable. In |«command»|, |%s| can be used as a placeholder for the
+filename, which is otherwise inserted at the end of the command. The command
+can be an arbitrary shell construct.
+\end{confitem}
+
+\begin{confitem}{lang}{\meta{2-letter code}}
+Set your preferred language. By default, it reflects your system's locale.
+\end{confitem}
+
+\begin{confitem}{verbosity\_level}{\meta{number}}[default: \code{2}]
+Set the verbosity level to |«number»|. At level~|3|, errors, warnings and
+informational messages will be printed on stderr; |2| means only errors and
+warnings, |1| only errors and |0| nothing except internal errors (obviously not
recommended).
+\end{confitem}
-\begin{cmdsubsub}{debug_list}{cf-debug_list}
- debug_list = «list»
-\end{cmdsubsub}
-
-Set the list of activated debug items (default: none). Available debug items
-are |config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|,
-|view|, and |all| to activate all of these. Implies |--verbose|. Debug
-information are printed on standard error.
-
-\begin{cmdsubsub}{max_line}{cf-max_lines}
- max_lines = «number»
-\end{cmdsubsub}
+\begin{confitem}{debug\_list}{\meta{list}}[default: empty]
+Set the list of activated debug categories. Available debug categories are
+|config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|, |view|,
+and |all| to activate all of these. Implies |--verbose|. Debug information are
+printed on standard error.
+\end{confitem}
+\begin{confitem}{max\_lines}{\meta{number}}[default: \code{20}]
Set the maximum number of results to be printed without confirmation in list,
-mixed or showall mode (default: 20). This setting has no effect if interaction
-is disabled.
-
-\begin{cmdsubsub}{machine_switch}{cf-machine_switch}
- machine_switch = «true, false»
-\end{cmdsubsub}
+mixed or showall mode. This setting has no effect if interaction is disabled.
+\end{confitem}
-Turn on or off machine-readable output (default: off). With this option
-active, the value of |interact_switch| is forced to |false|, and each line of
-output is
+\begin{confitem}{machine\_switch}{\choice{true, false}}[default: \code{false}]
+Turn on or off machine-readable output. With this option active, the value of
+|interact_switch| is forced to |false|, and each line of output is
+%
\begin{htcode}
- «argument»\t«score»\t«filename»
+«argument»\metatab«score»\metatab«filename»
\end{htcode}
+%
where |«argument»| is the name of the argument to which the results correspond
-(mainly useful if there were many arguments), |\t| is the tab (ASCII \#9)
+(mainly useful if there were many arguments), {\metatab} is the tab (ASCII \#9)
character, and the other entries are pretty self-explanatory. Nothing else is
printed on stdout, except if an internal error occurs (in which case exit code
will be 1). In the future, more tab-separated fields may be added at the end
of the line, but the first 3 fields will remain unchanged.
Currently, there are two additional fields: a two-letter language code, and an
-unstructured description, both taken from the CTAN catalogue (via the \texlive
+unstructured description, both taken from the CTAN catalogue (via the {\TL}
database). These fields may be empty, and they are not guaranteed to keep the
same meaning in future versions of Texdoc.
-
-\begin{cmdsubsub}{zipext_list}{cf-zipext_list}
- zipext_list = «list»
-\end{cmdsubsub}
-
-List of supported extensions for zipped files (default: empty). Allows
-compressed files with names like |foobar.«zip»|, with |«zip»| in the given
-|«list»|, to be found and unzipped before the viewer is started (the
-temporary file will be destroyed right after).
-
-\textbf{Warning.} Support for zipped documentation is not meant to work on
-windows, a Unix shell is assumed! If you add anything to this list, please make
-sure that you also set a corresponding |unzip=«ext»| value for each |«ext»| in
-the list. At the same time, make sure you are using blocking (i.e., not
-returning immediately) viewers.
-
-\textit{Remark.} \texlive doesn't ship compressed documentation files, so
-this option is mainly useful with re-packaged version of \texlive that do,
-for example in Linux distributions.
-
-\begin{cmdsubsub}{unzip_*}{cf-unzip_star}
- unzip_«zipext» = «command»
-\end{cmdsubsub}
-
-The unzipping command for compressed files with extension |«zipext»| (default:
-none). Define one for each item in |zipext_list|. The command must print
-the result on stdout, like |gzip -d -c| does.
-
-\begin{cmdsubsub}{rm_file, rm_dir}{cf-rm_star}
- rm_file = «command»
- rm_dir = «command»
-\end{cmdsubsub}
-
-Commands for removing files (resp. directories) on your system (defaults:
-|rm -f| and |rmdir|). Only useful for zipped documents (see |zipext_list|).
-
-\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch}
- lastfile_switch = «true, false»
-\end{cmdsubsub}
-
+\end{confitem}
+
+\begin{confitem}{zipext\_list}{\meta{list}}[default: empty]
+List of supported extensions for zipped files. Allows compressed files with
+names like |foobar.«zip»|, with |«zip»| in the given |«list»|, to be found and
+unzipped before the viewer is started (the temporary file will be destroyed
+right after).
+
+Warning: Support for zipped documentation is not meant to work on windows, a
+Unix shell is assumed! If you add anything to this list, please make sure that
+you also set a corresponding |unzip=«ext»| value for each |«ext»| in the list.
+At the same time, make sure you are using blocking (i.e., not returning
+immediately) viewers.
+
+Remark: {\TL} doesn't ship compressed documentation files, so this option is
+mainly useful with re-packaged version of {\TL} that do, for example in Linux
+distributions.
+\end{confitem}
+
+\begin{confitem}{unzip\_\meta{zipext}}{\meta{command}}[no default]
+The unzipping command for compressed files with extension |«zipext»|. Define
+one for each item in \ci{zipext\_list}. The command must print the result on
+stdout, like |gzip -d -c| does.
+\end{confitem}
+
+\begin{confitem}{rm\_file}{\meta{command}}[default: \code{rm -f}]
+Commands for removing files on your system. Only useful for zipped documents
+(see \ci{zipext\_list}).
+\end{confitem}
+
+\begin{confitem}{rm\_dir}{\meta{command}}[default: \code{rmdir}]
+Commands for removing directories on your system. Also only useful for zipped
+documents (see \ci{zipext\_list}).
+\end{confitem}
+
+\begin{confitem}{lastfile\_switch}{\choice{true, false}}[default: \code{false}]
If set to true, prevents Texdoc from reading any other configuration file after
this one (they will be reported as ``disabled'' by |texdoc -f|). Mainly useful
for installing a newer version of Texdoc in your home and preventing the
default configuration file from older versions to be used (see the
\href{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do
so).
+\end{confitem}
-\begin{cmdsubsub}{fuzzy_level}{cf-fuzzy_level}
- fuzzy_level = «n»
-\end{cmdsubsub}
+\begin{confitem}{fuzzy\_level}{\meta{number}}[default: \code{5}]
+Set the allowance of Levenshtein distance to |«number»| for fuzzy search. At
+level~|0|, the fuzzy search feature is disabled.
+\end{confitem}
-Set the allowance of Levenshtein distance to |«n»| for the fuzzy search
-(default: 5). At level 0, the fuzzy search feature is disabled.
+\begin{confitem}{texlive\_tlpdb}{\meta{path}}[no default]
+This enables you to specify the |«path»| for the database |texlive.tlpdb| which
+Texdoc uses for searching documents. By default, Texdoc uses
+\path{TEXMFROOT/tlpkg/texlive.tlpdb}. Usually, you don't have to (or should
+not) set this configuration item. This is only useful when you want to use
+Texdoc within a {\TL}-based {\TeX} distribution which does not ship
+|texlive.tlpdb|.
+\end{confitem}
-\subsection{Exit codes}\label{ss-exit}
-
-The current exit codes are:
-\begin{enumerate}[start=0]
- \item Success.
- \item Internal error.
- \item Usage error.
- \item No documentation found.
-\end{enumerate}
+\section{Licence}
+\label{sec:licence}
-\section{Licence}\label{s-licence}
-
-The current version of Texdoc program and its documentation are copyright 2008
-Manuel Pégourié-Gonnard, Takuto Asakura, and the {\texlive} Team.
+The current version of Texdoc program and its documentation are copyright
+2008--2020 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} Team.
They are free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
@@ -851,17 +749,20 @@ this program. If not, see \url{http://www.gnu.org/licenses/}.
\bigskip
Previous work (Texdoc program) in the public domain:
+%
\begin{itemize}
- \item Contributions from Reinhard Kotucha (2008).
- \item First texlua versions by Frank Küster (2007).
- \item Original shell script by Thomas Esser, David Aspinall, and Simon
- Wilkinson.
+\item Contributions from Reinhard Kotucha (2008).
+\item First texlua versions by Frank K\"uster (2007).
+\item Original shell script version by Thomas Esser, David Aspinall, and Simon
+ Wilkinson.
\end{itemize}
\bigskip
-\begin{center}\Large\bfseries
- Happy {\TeX}ing!
+
+\begin{center}
+\Large\bfseries
+Happy {\TeX}ing!
\end{center}
\end{document}
-% vim: ambiwidth=single spell:
+% vim: set ambiwidth=single spell:
diff --git a/support/texdoc/script/texdoc.tlu b/support/texdoc/script/texdoc.tlu
index b859868236..bc2139435a 100755
--- a/support/texdoc/script/texdoc.tlu
+++ b/support/texdoc/script/texdoc.tlu
@@ -7,11 +7,39 @@
-- Note: we keep this file small as much as possible so that make it easier
-- to install a new version of texdoc in TEXMFHOME.
--- setup the kpse library and load texdoclib
+local lfs = require 'lfs'
+local kpse = require 'kpse'
+
+-- setup kpse library
kpse.set_program_name(arg[-1], 'texdoc')
-local texdoc = require('texdoclib')
--- execute
+-- get realpath of this file
+local function realpath(p)
+ if os.type == 'unix' then
+ local h = io.popen(string.format("realpath '%s'", p))
+ local r = h:read('*a')
+ h:close()
+ return r:gsub('\n$', '')
+ else
+ return ''
+ end
+end
+local file = realpath(arg[0])
+
+-- if the file is not in TEXMFMAIN, set temporal TEXMFAUXTREES and TEXMFDIST
+local texmf = file:match('^(.*/texmf[^/]*)/scripts/texdoc/texdoc.tlu$')
+if texmf ~= nil then
+ if texmf ~= kpse.var_value('TEXMFMAIN') then
+ io.stderr:write('Info: ' ..
+ 'Running Texdoc not installed in the current TEXMFMAIN.\n')
+ os.setenv('TEXMFAUXTREES', texmf .. ',')
+ os.setenv('TEXMFDIST', ',')
+ end
+end
+
+-- load the library and execute
+local texdoc = require 'texdoclib'
+assert(texdoc.cli, 'Internal error: Texdoc is not installed properly.')
texdoc.cli.exec()
-- vim: ft=lua:
diff --git a/support/texdoc/script/texdoclib-alias.tlu b/support/texdoc/script/texdoclib-alias.tlu
index 16c375b3ba..d430623a41 100644
--- a/support/texdoc/script/texdoclib-alias.tlu
+++ b/support/texdoc/script/texdoclib-alias.tlu
@@ -5,7 +5,7 @@
--[[ structure of the alias table
alias = {
- name1 = {<true or nill> stop, <aliasentry> aliasentry1, ...},
+ name1 = {<true or nil> stop, <aliasentry> aliasentry1, ...},
...
}
stop == true means further alias directives should be ignored
@@ -22,7 +22,7 @@ score == nil means to use the default score (defined in texdoclib-score.tlu)
-- dependencies
local texdoc = {
- config = require('texdoclib-config'),
+ config = require 'texdoclib-config',
}
-- shortcuts
diff --git a/support/texdoc/script/texdoclib-cli.tlu b/support/texdoc/script/texdoclib-cli.tlu
index 3de786ef2c..95a43b7ddd 100644
--- a/support/texdoc/script/texdoclib-cli.tlu
+++ b/support/texdoc/script/texdoclib-cli.tlu
@@ -4,11 +4,11 @@
-- dependencies
local texdoc = {
- const = require('texdoclib-const'),
- util = require('texdoclib-util'),
- config = require('texdoclib-config'),
- search = require('texdoclib-search'),
- view = require('texdoclib-view'),
+ const = require 'texdoclib-const',
+ util = require 'texdoclib-util',
+ config = require 'texdoclib-config',
+ search = require 'texdoclib-search',
+ view = require 'texdoclib-view',
}
-- shortcuts
@@ -21,7 +21,7 @@ local err_print = texdoc.util.err_print
-- modified Alternative GetOpt
-- cf. http://lua-users.org/wiki/AlternativeGetOpt
local function getopt(arg, options)
- local tmp
+ local tmp = nil
local tab = {}
local saved_arg = {table.unpack(arg)}
@@ -30,25 +30,36 @@ local function getopt(arg, options)
table.remove(arg, 1)
local x = string.find(v, '=', 1, true)
if x then
- table.insert(tab, {string.sub(v, 3, x-1), string.sub(v, x+1)})
+ table.insert(tab, {string.sub(v, 3, x - 1), string.sub(v, x+1)})
else
table.insert(tab, {string.sub(v, 3), true})
end
+
elseif string.sub(v, 1, 1) == '-' then
table.remove(arg, 1)
local y = 2
local l = string.len(v)
local jopt
+
while (y <= l) do
jopt = string.sub(v, y, y)
+
if string.find(options, jopt, 1, true) then
if y < l then
- tmp = string.sub(v, y+1)
+ tmp = string.sub(v, y + 1)
y = l
else
table.remove(arg, 1)
tmp = saved_arg[k + 1]
end
+
+ -- check the existence of an argument
+ if not tmp then
+ err_print('error',
+ 'Option -%s requires an argument.', jopt)
+ os.exit(C.exit_error)
+ end
+
if string.match(tmp, '^%-') then
table.insert(tab, {jopt, false})
else
@@ -59,6 +70,9 @@ local function getopt(arg, options)
end
y = y + 1
end
+
+ else
+ if tmp then tmp = nil else break end
end
end
@@ -67,7 +81,6 @@ end
local function parse_options()
local curr_arg
- local action = true
local cl_config = {}
local function insert_cl_config(key, val, opt_name)
@@ -87,13 +100,13 @@ local function parse_options()
-- action
if (curr_arg == '-h') or (curr_arg == '--help') then
- action = 'help'
+ return true, 'help', cl_config
elseif (curr_arg == '-V') or (curr_arg == '--version') then
- action = 'version'
+ return true, 'version', cl_config
elseif (curr_arg == '-f') or (curr_arg == '--files') then
- action = 'files'
+ return true, 'files', cl_config
elseif curr_arg == '--just-view' then
- action = 'view'
+ return true, 'view', cl_config
-- mode
elseif (curr_arg == '-w') or (curr_arg == '--view') then
@@ -117,8 +130,7 @@ local function parse_options()
-- config
elseif curr_arg == '-c' then
- local item, value = string.match(v, '^([%a%d_]+)%s*=%s*(.+)')
- insert_cl_config(item, value, curr_arg)
+ insert_cl_config(v, nil, curr_arg)
-- debug
elseif (curr_arg == '-d') or (curr_arg == '--debug') then
@@ -141,7 +153,7 @@ local function parse_options()
end
end
- return action, cl_config
+ return true, action, cl_config
end
-------------------------- process execution --------------------------
@@ -157,7 +169,7 @@ local function do_action(action)
'\n\n' .. C.copyright_msg)
os.exit(C.exit_ok)
elseif action == 'files' then
- print(C.fullname .. ' ' .. C.version)
+ print(texdoc.util.w32_path(C.fullname) .. ' ' .. C.version)
texdoc.config.show_config_files(true)
os.exit(C.exit_ok)
elseif action == 'view' then
@@ -189,9 +201,9 @@ end
function M.exec()
-- parsing command line options
- local action, cl_config = parse_options()
+ local ok, action, cl_config = parse_options()
- if not action then
+ if not ok then
os.exit(C.exit_usage)
end
diff --git a/support/texdoc/script/texdoclib-config.tlu b/support/texdoc/script/texdoclib-config.tlu
index 471fef9fdc..4eb660873f 100644
--- a/support/texdoc/script/texdoclib-config.tlu
+++ b/support/texdoc/script/texdoclib-config.tlu
@@ -2,9 +2,12 @@
--
-- The TeX Live Team, GPLv3, see texdoclib.tlu for details
+-- dependencies
+local lfs = require 'lfs'
+
-- shortcuts
local M = {}
-local C = require('texdoclib-const')
+local C = require 'texdoclib-const'
-- config is local to this file
local config = {}
@@ -172,8 +175,20 @@ end
-- Note: Make sure to set a default value in setup_config_from_defaults()
-- if relevant.
local function setup_config_from_cl(cl_config)
+ local err_print = import_function('util', 'err_print')
+
for _, e in ipairs(cl_config) do
- set_config_element(e[1], e[2], {src='cl', name=e[3]})
+ if e[3] == '-c' then
+ local item, value = string.match(e[1], '^([%a%d_]+)%s*=%s*(.+)')
+ if item and value then
+ set_config_element(item, value, {src='cl', name='-c'})
+ else
+ err_print('warning',
+ 'Invalid argument "%s" for Option -c. Ignoring.', e[1])
+ end
+ else
+ set_config_element(e[1], e[2], {src='cl', name=e[3]})
+ end
end
end
@@ -184,6 +199,7 @@ local function setup_config_from_env()
local function set_config_elt_from_vars(key, vars)
for _, var in ipairs(vars) do
local value = os.getenv(var)
+ value = value and string.gmatch(value, '([^:]+)')()
if value then
set_config_element(key, value, {src='env', name=var})
end
@@ -316,7 +332,7 @@ function M.show_config_files(is_action)
or function(s) dbg_print('files', s) end
-- show the list of configuration files
- print_func('Configuration files are:')
+ print_func('Configuration file(s):')
for i, file in ipairs(config_files) do
-- if not verbose, do not show "not found" files for -f
if file.status ~= "not found"
@@ -329,7 +345,7 @@ function M.show_config_files(is_action)
if is_action then
print_func('Recommended file(s) for personal settings:')
local sep = (os.type == 'windows') and ';' or ':'
- local texmfhomes = string.explode(kpse.var_value('TEXMFHOME'), sep)
+ local texmfhomes = string.explode(kpse.expand_path('$TEXMFHOME'), sep)
for _, home in ipairs(texmfhomes) do
print_func(indent .. w32_path(home .. '/texdoc/texdoc.cnf'))
end
@@ -340,12 +356,20 @@ end -- end scope of config_files
---------------------- config from locale settings -------------------------
+-- set up the locale from the system setting
+-- Note that luatex set the locale to a neutral value for a reason, so we need
+-- to set the locale (for the category 'all') to nil to ignore it.
local function setup_config_from_locale()
- local current = os.setlocale(nil, 'all')
- os.setlocale('', 'all')
- local native = os.setlocale(nil, 'time')
- os.setlocale(current, 'all')
- local lang = string.match(native, '^[a-z][a-z]')
+ local current, native, lang
+ current = os.setlocale(nil, 'all') -- save the default value
+ os.setlocale('', 'all') -- set it to nil temporary
+ native = os.setlocale(nil, 'all') -- get the actual system locale
+ os.setlocale(current, 'all') -- put back the default value
+ if native == 'C' then -- the default C locale is en
+ lang = 'en'
+ else
+ lang = string.match(native, '^[a-z][a-z]')
+ end
if lang then
set_config_element('lang', lang, {src='loc'})
end
@@ -381,6 +405,8 @@ local function desktop_environment_viewer()
end
if os.getenv('GNOME_DESKTOP_SESSION_ID')
or string.match(xdg_current_desktop, '.*GNOME.*') then -- gnome
+ if is_in_path('gio') then return '(gio open %s) &' end
+ -- followings are deplecated commands but keep these for compatibility
if is_in_path('gvfs-open') then return '(gvfs-open %s) &' end
if is_in_path('gnome-open') then return '(gnome-open %s) &' end
end
diff --git a/support/texdoc/script/texdoclib-const.tlu b/support/texdoc/script/texdoclib-const.tlu
index 5d34bed3f6..9562122d38 100644
--- a/support/texdoc/script/texdoclib-const.tlu
+++ b/support/texdoc/script/texdoclib-const.tlu
@@ -4,7 +4,7 @@
-- use an empty environment that will become texdoc_env.C (see EOF)
local constants = {}
-local kpse = kpse
+local kpse = kpse or require 'kpse'
local setfenv = setfenv
local texdoc_env
@@ -21,14 +21,14 @@ end
-- progname and version
fullname = kpse.find_file('texdoc/texdoclib', 'lua')
progname = 'Texdoc'
-version = '3.1'
-release_date = '2019-03-28'
+version = '3.2'
+release_date = '2020-02-02'
-- make sure to update setup_config_from_cl() accordingly
-- and set a default value in setup_config_from_defaults() if relevant
usage_msg = [[
-Usage: texdoc [OPTION...] NAME...
- or: texdoc [OPTION...] ACTION
+Usage: texdoc [OPTION]... NAME...
+ or: texdoc [OPTION]... ACTION
Try to find appropriate TeX documentation for the specified NAME(s).
Alternatively, perform the given ACTION and exit.
@@ -63,7 +63,7 @@ Repository: <https://github.com/TeX-Live/texdoc>
Please email bugs to <texdoc@tug.org>.]]
copyright_msg = [[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.]]
diff --git a/support/texdoc/script/texdoclib-score.tlu b/support/texdoc/script/texdoclib-score.tlu
index 81e1be2a33..fdc2ef3467 100644
--- a/support/texdoc/script/texdoclib-score.tlu
+++ b/support/texdoc/script/texdoclib-score.tlu
@@ -3,14 +3,14 @@
-- The TeX Live Team, GPLv3, see texdoclib.tlu for details
-- dependencies
+local md5 = require 'md5'
local texdoc = {
- util = require('texdoclib-util'),
- config = require('texdoclib-config'),
+ util = require 'texdoclib-util',
+ config = require 'texdoclib-config',
}
-- shortcuts
local M = {}
-local dbg_print = texdoc.util.dbg_print
-- shared variables
local global_adjscore, spec_adjscore = {}, {}
@@ -73,18 +73,19 @@ local function has_bad_basename(file)
end
-- compute a heuristic score -10 <= s < 10
-local function heuristic_score(file, pat)
- dbg_print('score', 'Start heuristic scoring with pattern: ' .. pat)
+local function heuristic_score(file, pat, dbg_score)
+ dbg_score('Start heuristic scoring with pattern: ' .. pat)
+
-- score management
local score = -10
local function upscore(s, reason, force)
if s > score or force then
score = s
- dbg_print('score',
- 'New heuristic score: %.1f. Reason: %s', s, reason)
+ dbg_score('New heuristic score: %.1f. Reason: %s', s, reason)
end
end
local slash = not not string.find(pat, '/', 1, true)
+
-- look for exact or subword match
if M.is_exact_locale(file, pat) then
upscore(5, 'exact match with correct locale')
@@ -93,104 +94,121 @@ local function heuristic_score(file, pat)
elseif is_subword(file, pat) then
upscore(1, 'subword match')
end
+
-- try derivatives unless pat contains a slash
if not slash then
for _, suffix in ipairs(texdoc.config.get_value('suffix_list')) do
- local deriv = pat..suffix
+ local deriv = pat .. suffix
if M.is_exact(file, deriv) then
- upscore(3, 'exact match for derived pattern: ' .. deriv)
+ upscore(4.5, 'exact match for derived pattern: ' .. deriv)
elseif is_subword(file, deriv) then
- upscore(2, 'subword match for derived pattern: ' .. deriv)
+ upscore(3.5, 'subword match for derived pattern: ' .. deriv)
end
end
end
+
-- if extension is bad, score becomes an epsilon
local ext = texdoc.config.get_value('ext_list')[M.ext_pos(file)]
if ext and texdoc.config.get_value('badext_list_inv')[ext] and score > 0 then
upscore(0.1, 'bad extension', true)
end
+
-- if basename is bad, score becomes an epsilon
if has_bad_basename(file) and score > 0 then
upscore(0.1, 'bad basename', true)
end
+
-- bonus for being in the right directory
if string.find('/' .. file, '/' .. pat .. '/', 1, true) and not slash then
upscore(score + 1.5, 'directory bonus')
end
+
-- done
- dbg_print('score', 'Final heuristic score: %.1f', score)
+ dbg_score('Final heuristic score: %.1f', score)
return score
end
-- set the score of a docfile
local function set_score(df, original_kw)
-- scoring is case-insensitive (patterns are already lowercased)
- local name = string.lower(df.shortname)
- dbg_print('score', '----------')
- dbg_print('score', 'Start scoring ' .. df.realpath)
- dbg_print('score', 'Name used: ' .. name)
+ local name = string.lower(df.normname)
+ local df_id = string.sub(md5.sumhexa(name), 1, 7)
+
+ -- special debugging function
+ local function dbg_score(msg, ...)
+ -- add the hash id prefix to make the outputs grep-friendly
+ local msg = string.format('(%s) ', df_id) .. msg
+ texdoc.util.dbg_print('score', msg, ...)
+ end
+
+ dbg_score('Start scoring ' .. df.realpath)
+ dbg_score('Name used: ' .. name)
+
-- get score from patterns
local score = -10
for _, pat in ipairs(df.matches) do
local s = -10
local p = string.lower(pat.name)
- if pat.original then
- s = df.tree > -1 and heuristic_score(name, p) or 1
- elseif M.is_exact(name, p) then
+ if pat.original then -- non-alias
+ s = df.tree > -1 and heuristic_score(name, p, dbg_score) or 1
+ elseif M.is_exact(name, p) then -- alias
local bonus, note = 0, ''
if pat.locale then
bonus, note = 5, ', (language-based)'
end
- s = (pat.score or 10) + bonus -- default alias score is 10
- dbg_print('score',
- 'Matching alias "%s", score: %.1f%s', pat.name, s, note)
+ s = (pat.score or 10) + bonus -- default alias score is 10
+ dbg_score('Matching alias "%s", score: %.1f%s', pat.name, s, note)
end
if s > score then score = s end
end
- dbg_print('score', 'Max pattern score: %.1f', score)
+ dbg_score('Max pattern score: %.1f', score)
+
-- get score from tlp associations
if score == -10 and df.tlptodoc then
score = -1
- dbg_print('score',
- 'New score: %.1f from package name association', score)
+ dbg_score('New score: %.1f from package name association', score)
end
+
if score == -10 and df.runtodoc then
score = -5
- dbg_print('score',
- 'New score: %.1f from sty/cls association', score)
+ dbg_score('New score: %.1f from sty/cls association', score)
end
+
-- bonus for metadata
if df.details then
if string.find(string.lower(df.details), 'readme') then
score = score + 0.1
- dbg_print('score', 'Catalogue "readme" bonus: +0.1')
+ dbg_score('Catalogue "readme" bonus: +0.1')
else
score = score + 1.5
- dbg_print('score', 'Catalogue details bonus: +1.5')
+ dbg_score('Catalogue details bonus: +1.5')
end
end
+
-- adjust from keyword-specific tables
if df.tree > -1 and spec_adjscore[original_kw] then
for pat, val in pairs(spec_adjscore[original_kw]) do
if val and is_subword('/' .. name, pat) then
score = score + val
- dbg_print('score',
- 'Adjust by %.1f from specific pattern "%s"', val, pat)
+ dbg_score('Adjust by %.1f from specific pattern "%s"', val, pat)
end
end
end
+
-- adjust from global tables
if df.tree > -1 then
for pat, val in pairs(global_adjscore) do
if val and is_subword('/' .. name, pat) then
if score > -10 or val < 0 then score = score + val end
- dbg_print('score',
- 'Adjust by %.1f from global pattern "%s"', val, pat)
+ dbg_score('Adjust by %.1f from global pattern "%s"', val, pat)
end
end
end
- dbg_print('score', 'Final score: %.1f', score)
- df.score = score
+
+ dbg_score('Final score: %.1f', score)
+
+ -- the final score should be a float value
+ df.score = score + 0.0
end
-- set the scores for a doclist
diff --git a/support/texdoc/script/texdoclib-search.tlu b/support/texdoc/script/texdoclib-search.tlu
index 1a7270d0b7..addb59a01f 100644
--- a/support/texdoc/script/texdoclib-search.tlu
+++ b/support/texdoc/script/texdoclib-search.tlu
@@ -5,12 +5,14 @@
-- Warning: Some functions here assume that M.init_databases() has been called.
-- dependencies
+local kpse = require 'kpse'
+local lfs = require 'lfs'
local texdoc = {
- const = require('texdoclib-const'),
- util = require('texdoclib-util'),
- alias = require('texdoclib-alias'),
- score = require('texdoclib-score'),
- config = require('texdoclib-config'),
+ const = require 'texdoclib-const',
+ util = require 'texdoclib-util',
+ alias = require 'texdoclib-alias',
+ score = require 'texdoclib-score',
+ config = require 'texdoclib-config',
}
-- shortcuts
@@ -24,11 +26,11 @@ local s_doclist -- the Doclist object to be populated by various functions
local s_meta -- {[normname] = meta, ...} (populated by init_tlp_database)
local vanilla -- is this a vanilla TL or a re-package one without tlpdb?
----------------------------- utility functions -----------------------------
+--------------------------- utility functions ----------------------------
-- find the TeX Live root
local function get_tlroot()
- local tlroot = kpse.var_value('TEXMFROOT')
+ local tlroot = kpse.expand_path('$TEXMFROOT') -- it should be exisitng one
get_tlroot = function() return tlroot end
return tlroot
end
@@ -36,7 +38,7 @@ end
-- says if file has a known extension according to ext_list
-- (or known basename according to basename_list)
local function check_ext(file)
- file = string.lower(file)
+ file = file:lower()
-- remove zipext if applicable
file = texdoc.util.parse_zip(file)
-- then do the normal thing
@@ -44,12 +46,12 @@ local function check_ext(file)
if e == '*' then
return true
elseif (e == '') then
- if not string.find(file, '.', 1, true) then
+ if not file:find('.', 1, true) then
return true
end
else
- local dot_e = '.'..e
- if string.sub(file, -string.len(dot_e)) == dot_e then
+ local dot_e = '.' .. e
+ if file:sub(-#dot_e) == dot_e then
return true
end
end
@@ -63,7 +65,7 @@ local function check_ext(file)
return false
end
------------------------ docfile and doclist objects ------------------------
+---------------------- docfile and doclist objects -----------------------
--[[
doclist = {
@@ -128,7 +130,6 @@ docfile = {
-- those are virtual members, see below
realpath = full path
normname = nomrmalised (path removed up to the 'doc' component)
- shortname = short name used for scoring
basename = basename
lang = language tag from the catalogue metadata
details = details tag from the catalogue metadata
@@ -201,7 +202,7 @@ end
-- normalise a name from the tlpdb (use for s_meta indexes)
local function reloc_tlpdb_path(name)
- return string.gsub(name, '^texmf[^/]*/doc/', '', 1)
+ return name:gsub('^texmf[^/]*/doc/', '')
end
-- return normalised name
@@ -221,16 +222,9 @@ function Docfile:get_details()
return meta and (meta.details or false) or false
end
--- return the short name used for scoring
-function Docfile:get_shortname()
- if self.tree == -1 then return self.name end
- -- remove first component of name if at least two directory levels
- return string.match(self.normname, '^..-/(.+/.+)$') or self.normname
-end
-
-- return the base name
function Docfile:get_basename()
- return string.gsub(self.name, '.*/', '', 1)
+ return self.name:gsub('.*/', '')
end
-- for interface consistency, matches should always be a table, never nil
@@ -246,12 +240,12 @@ function Docfile:get_ext_pos()
return texdoc.score.ext_pos(self.basename)
end
--------------------- select results from TEXDOCS trees ---------------------
+------------------- select results from TEXDOCS trees --------------------
-- says if a file (with its path) matches a pattern
local function matches(pattern, file)
if pattern.original then
- return string.find(file:lower(), pattern.name:lower(), 1, true)
+ return file:lower():find(pattern.name:lower(), 1, true)
else
return texdoc.score.is_exact(file, pattern.name)
end
@@ -296,25 +290,28 @@ local function init_lsr_db(root, shift)
-- scan it
local db = {}
- local maybe_dir, isdoc = true, false
+ local maybe_dir, is_doc = true, false
local current_dir
local l = #shift
while true do
local line = lsr:read('*line')
while line == '' do line, maybe_dir = lsr:read('*line'), true end
if line == nil then break end -- EOF
- local dir_line = maybe_dir and string.match(line, '^%./(.*):$')
+ local dir_line = maybe_dir and line:match('^%./(.*):$')
if dir_line then
maybe_dir = false -- next line may not be a dir
if string.sub(dir_line .. '/', 1, l) == shift then
- isdoc = true
- current_dir = string.sub(dir_line, l+1)
+ is_doc = true
+ current_dir = dir_line:sub(l + 1)
db[current_dir] = nil
- elseif isdoc then
+ elseif is_doc then
break -- we're exiting the ./doc (or shift) dir, so it's over
end
- elseif isdoc then
- local file = (current_dir == '') and line or current_dir .. '/' .. line
+ elseif is_doc then
+ local file = line
+ if current_dir ~= '' then
+ file = current_dir .. '/' .. line
+ end
if check_ext(line) then db[file] = line end
end
end
@@ -361,24 +358,24 @@ init_texdocs_database = function()
local function lsr_root(path)
if not lfs.isdir (path) then return end
local root, shift = path, ''
- if string.sub(root, -1) == '/' then root = string.sub(root, 1, -2) end
- while string.find(root, '/', 1, true) do
+ if root:sub(-1) == '/' then root = root:sub(1, -2) end
+ while root:find('/', 1, true) do
if lfs.isfile(root .. '/ls-R') then
return root, shift
end
- local last_comp = string.match(root, '^.*/(.*)$')
+ local last_comp = root:match('^.*/(.*)$')
-- /!\ cannot put last_comp in a regex: can contain special char
- root = string.sub(root, 1, - (#last_comp + 2))
+ root = root:sub(1, - (#last_comp + 2))
shift = last_comp .. '/' .. shift
end
end
doc_roots = {}
local sep = (os.type == 'windows') and ';' or ':'
- local kpse_texdocs = kpse.expand_var("$TEXDOCS")
+ local kpse_texdocs = kpse.expand_var('$TEXDOCS')
-- expand the path and turn it into a lua list
- local raw_doc_roots = string.explode(kpse.expand_braces(kpse_texdocs), sep)
+ local raw_doc_roots = kpse.expand_braces(kpse_texdocs):explode(sep)
local max = #raw_doc_roots + 1
for j, dir in ipairs(raw_doc_roots) do
@@ -387,9 +384,9 @@ init_texdocs_database = function()
local path, db
-- get path, !! and // values
- dir, n = string.gsub (dir, '//$', '')
+ dir, n = dir:gsub('//$', '')
local recursion_allowed = (n == 1)
- local path, n = string.gsub (dir, '^!!', '')
+ local path, n = dir:gsub('^!!', '')
local index_mandatory = (n == 1)
dbg_print('texdocs',
'texdocs[%d] = %s (index_mandatory=%s, recursion_allowed=%s)',
@@ -426,7 +423,7 @@ end
end -- end scope of doc_roots
----------------------------- look for sty files ----------------------------
+--------------------------- look for sty files ---------------------------
-- add doclist entries for sty files in patlist
local function get_doclist_sty(patlist)
@@ -443,7 +440,7 @@ local function get_doclist_sty(patlist)
end
end
--------------------------------- use tlpdb ---------------------------------
+------------------------------- use tlpdb --------------------------------
-- tlpdb mean TeX Live Package DataBase and tlp means TeX Live Package
@@ -493,23 +490,23 @@ get_tlpinfo_from_tlpdb = function(filename)
local curr_tlp
local state = 'none'
for line in io.lines(filename) do
- if state == 'none' and string.find(line, '^name ') then
+ if state == 'none' and line:find('^name ') then
-- begin a new package
- curr_tlp = string.lower(string.sub(line, 6, -1))
+ curr_tlp = line:sub(6, -1):lower()
tlp_doclist[curr_tlp] = {}
elseif state == 'docfiles' then
- if not string.find(line, '^ ') then
+ if not line:find('^ ') then
state = 'none'
else
- local file = string.match(line, '^ ([^ ]*)')
- local meta = string.match(line, '^ [^ ]* (.+)')
- local basename = string.match(file, '([^/]*)$')
+ local file = line:match('^ ([^ ]*)')
+ local meta = line:match('^ [^ ]* (.+)')
+ local basename = file:match('([^/]*)$')
if check_ext(basename) then
-- we've got a docfile here, add it
table.insert(tlp_doclist[curr_tlp], file)
if meta then
- local details = string.match(meta, 'details="([^"]+)"')
- local lang = string.match(meta, 'language="([^"]+)"')
+ local details = meta:match('details="([^"]+)"')
+ local lang = meta:match('language="([^"]+)"')
s_meta[reloc_tlpdb_path(file)] = {
details = details,
lang = lang,
@@ -518,22 +515,22 @@ get_tlpinfo_from_tlpdb = function(filename)
end
end
elseif state == 'runfiles' then
- if not string.find(line, '^ ') then
+ if not line:find('^ ') then
state = 'none'
else
-- check for interesting runfiles
- local e = string.sub(line, -4, -1)
+ local e = line:sub(-4, -1)
if e == '.tex' or e == '.sty' or e == '.cls' then
- local f = string.match(line, '.*/(.*)%.')
+ local f = line:match('.*/(.*)%.')
tlp_from_runfile[f] = tlp_from_runfile[f] or {}
tlp_from_runfile[f][curr_tlp] = true
end
end
end
-- update state
- if string.find(line, '^docfiles ') then
+ if line:find('^docfiles ') then
state = 'docfiles'
- elseif string.find(line, '^runfiles ') then
+ elseif line:find('^runfiles ') then
state = 'runfiles'
end
end
@@ -658,8 +655,8 @@ end -- end scope of tlpinfo table
-- get tlpinfo tables initialised by whatever mean
local function init_tlp_database()
- local TEXMFVAR = kpse.var_value('TEXMFVAR')
- local cache_file = TEXMFVAR .. '/' .. C.cache_name
+ -- we assume TEXMFVAR always consists of an element
+ local cache_file = kpse.expand_var('$TEXMFVAR/' .. C.cache_name)
-- set vanilla and detect texlive.tlpdb to use
local texlive_tlpdb = get_tlroot() .. '/tlpkg/texlive.tlpdb'
@@ -686,7 +683,8 @@ local function init_tlp_database()
dbg_print('tlpdb', 'Using cached data from ' .. cache_file)
get_tlpinfo_from_cache(cache_file)
else
- dbg_print('tlpdb', 'Getting data from tlpdb file ' .. texlive_tlpdb)
+ dbg_print('tlpdb',
+ 'Getting data from tlpdb file ' .. texlive_tlpdb)
get_tlpinfo_from_tlpdb(texlive_tlpdb)
dbg_print('tlpdb', 'Writing data in cache file ' .. cache_file)
local ok, msg = mkdir_p(texdoc.util.path_parent(cache_file))
@@ -704,7 +702,7 @@ local function init_tlp_database()
end
end
------------------------------- main function -------------------------------
+----------------------------- main function ------------------------------
-- initialise the various databases (must be called first)
function M.init_databases()
@@ -714,11 +712,13 @@ end
-- find docfiles according to pattern
function M.get_doclist(pattern, no_alias)
+ dbg_print('search', 'Searching documents for pattern "%s"', pattern)
+
-- separate sty patterns from the rest
local function normal_vs_sty(list)
local normal, sty = {}, {}
for _, p in ipairs(list) do
- if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then
+ if p.name:lower():match('%.([^/.]*)$') == 'sty' then
table.insert(sty, p)
else
table.insert(normal, p)
diff --git a/support/texdoc/script/texdoclib.tlu b/support/texdoc/script/texdoclib.tlu
index fb85895d37..7c93fba54c 100644
--- a/support/texdoc/script/texdoclib.tlu
+++ b/support/texdoc/script/texdoclib.tlu
@@ -1,7 +1,7 @@
-- texdoclib.tlu: the texdoc library
--[[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
diff --git a/support/texdoc/texdoc.cnf b/support/texdoc/texdoc.cnf
index 5fcb2a5344..b54f56352f 100644
--- a/support/texdoc/texdoc.cnf
+++ b/support/texdoc/texdoc.cnf
@@ -141,6 +141,9 @@ adjscore /demos/ = -1
adjscore /figures/ = -3
adjscore /images/ = -3
+# latex-dev stuff are less important than stable ones
+adjscore /latex-dev/ = -2
+
# readme files usually get negative scores because they have bad extensions,
# but they're still slightly better than other results with negative scores
adjscore readme = +0.1
@@ -165,6 +168,14 @@ adjscore(latex) tufte-latex = -10
adjscore(latex) Content_LaTeX_Package_Demo = -10
adjscore(latex) example_latex = -10
adjscore(latex) test_latex = -10
+# dir names
+adjscore(latex) /latex/ = -4
+adjscore(latex) /latex-dev/ = -5
+adjscore(latex) /generic/ = -5
+
+# prioritize official documents for 'latex'
+adjscore(latex) /latex/base/ = +5
+adjscore(latex) /latex/tools/ = +5
# beamer
adjscore(beamer) beamer-tut-pt/tutorialbeamer = +10
@@ -206,11 +217,47 @@ adjscore(layout) /tools/ = +1
# To override one of the settings below, use the 'noalias' directive in
# your personal configuration file, see the manual for details.
-## Essential documentation
+## TeX Live documentation
-alias live = texlive-en
+# texlive-en for general, but prioritized local version if exists
alias texlive = texlive-en
+alias texlive-cz = texlive-cz
+alias texlive-de = texlive-de
+alias texlive-en = texlive-en
+alias texlive-es = texlive-es
+alias texlive-fr = texlive-fr
+alias texlive-it = texlive-it
+alias texlive-ja = texlive-ja
+alias texlive-pl = texlive-pl
+alias texlive-ru = texlive-ru
+alias texlive-sr = texlive-sr
+alias texlive-zh-cn = texlive-zh-cn
+
+alias live = texlive-en
+alias live-cz = texlive-cz
+alias live-de = texlive-de
+alias live-en = texlive-en
+alias live-es = texlive-es
+alias live-fr = texlive-fr
+alias live-it = texlive-it
+alias live-ja = texlive-ja
+alias live-pl = texlive-pl
+alias live-ru = texlive-ru
+alias live-sr = texlive-sr
+alias live-zh-cn = texlive-zh-cn
+
alias tex-live = texlive-en
+alias tex-live-cz = texlive-cz
+alias tex-live-de = texlive-de
+alias tex-live-en = texlive-en
+alias tex-live-es = texlive-es
+alias tex-live-fr = texlive-fr
+alias tex-live-it = texlive-it
+alias tex-live-ja = texlive-ja
+alias tex-live-pl = texlive-pl
+alias tex-live-ru = texlive-ru
+alias tex-live-sr = texlive-sr
+alias tex-live-zh-cn = texlive-zh-cn
## various stuff
@@ -281,6 +328,10 @@ alias textcomp = source2e
alias tracefnt = source2e
# TODO: try to avoid the huge amount of false positives for `doc' itself.
+# latex-dev instruction
+alias latex-dev = latex/base/ltnews30
+alias(9) latex-dev = latex-dev.man1
+
# latex's required graphics bundle
alias color-dev = color
alias epsfig-dev = epsfig
@@ -374,7 +425,8 @@ alias l3clist = interface3
alias l3prop = interface3
alias l3box = interface3
alias l3coffins = interface3
-alias l3color = interface3
+alias l3color-base = interface3
+alias l3regex = interface3
alias l3msg = interface3
alias l3keys = interface3
alias l3file = interface3
@@ -386,6 +438,8 @@ alias autofe = ucs
alias afoot = arabtex-doc
alias arabicfont = bezos
alias bibtex = btxdoc
+alias btxdoc-ja = jbtxdoc
+alias btxhak-ja = jbtxhak
alias changes = changes.english.pdf
alias cm = cm/README
alias(5) cmsuper = cm-super/FAQ
diff --git a/support/texplate/README.md b/support/texplate/README.md
index 7fea81da09..7428b21519 100644
--- a/support/texplate/README.md
+++ b/support/texplate/README.md
@@ -1,6 +1,8 @@
# TeXplate
-![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square) ![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8.0-blue.svg?style=flat-square) ![Current version: 1.0.1](https://img.shields.io/badge/Current_version-1.0.1-blue.svg?style=flat-square)
+![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square)
+![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8.0-blue.svg?style=flat-square)
+![Current version](https://img.shields.io/badge/dynamic/json.svg?color=blue&label=Latest%20release&query=%24.0.name&url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F13793875%2Frepository%2Ftags&style=flat-square)
TeXplate is a tool for creating document structures based on templates. The application name is a word play on _TeX_ and _template_, so the purpose seems quite obvious: we want to provide an easy and straightforward framework for reducing the typical code boilerplate when writing TeX documents. Also note that one can easily extrapolate the use beyond articles and theses: the application is powerful enough to generate _any_ text-based structure, given that a corresponding template exists.
@@ -20,7 +22,7 @@ $ texplate
\ \_\
\/_/
-TeXplate 1.0.1, a document structure creation tool
+TeXplate 1.0.2, a document structure creation tool
Copyright (c) 2020, Island of TeX
All rights reserved.
@@ -83,7 +85,7 @@ $ texplate -t article -o doc1.tex
\ \_\
\/_/
-TeXplate 1.0.1, a document structure creation tool
+TeXplate 1.0.2, a document structure creation tool
Copyright (c) 2020, Island of TeX
All rights reserved.
diff --git a/support/texplate/doc/texplate-manual.pdf b/support/texplate/doc/texplate-manual.pdf
index 98d06b0ca4..19afbe5c8f 100644
--- a/support/texplate/doc/texplate-manual.pdf
+++ b/support/texplate/doc/texplate-manual.pdf
Binary files differ
diff --git a/support/texplate/doc/texplate-manual.tex b/support/texplate/doc/texplate-manual.tex
index 6fe19fb5e4..56dbe5e5f3 100644
--- a/support/texplate/doc/texplate-manual.tex
+++ b/support/texplate/doc/texplate-manual.tex
@@ -17,7 +17,7 @@
\newcommand{\shortopt}[1]{{\ttfamily-#1}}
\newcommand{\longopt}[1]{{\ttfamily{-}{-}#1}}
\newcommand{\macro}[1]{{\ttfamily\textbackslash#1}}
-\newcommand{\texplateversion}{1.0.1}
+\newcommand{\texplateversion}{1.0.2}
\title{A gentle introduction to \texplate:\\ a document structure creation tool}
\author{Island of \TeX}
@@ -242,7 +242,7 @@ For starters, a template has an identifier, a name that logically represents the
Observe that \texplate's lookup system is case-sensitive, so make sure to always reference the correct name.
\end{disclaimer}
-Although there are no hard limitations on a template name, it is advisable to keep it short and concise, with no spaces whatsoever\footnote{Another Carlislean statement would remind us that people that put spaces in their file names deserve no sympathy. At all.}. As a consequence, potential issues with extended characters in the Unicode range and command line escaping are avoided, and thus our beloved tool might just work as expected.
+Although there are no hard limitations on a template name, it is advisable to keep it short and concise, with no spaces whatsoever\footnote{Another Carlislean statement would remind us that people who put spaces in their file names deserve no sympathy. At all.}. As a consequence, potential issues with extended characters in the Unicode range and command line escaping are avoided, and thus our beloved tool might just work as expected.
\section{Directory lookup}
\label{sec:directorylookup}
@@ -252,7 +252,7 @@ Although there are no hard limitations on a template name, it is advisable to ke
\begin{enumerate}
\item\inline{\textasciitilde/.texplate/templates} which refers to a path structure from the user home directory.
-\item\inline{<APP>/templates} which refers to a path structure from the application directory (with \inline{<APP>} denoting the location where \texplate\ is installed).
+\item The application's resources which refers to a files within the JAR file. You can use a ZIP viewer to look at the templates there.
\end{enumerate}
For instance, as a means to illustrate the concept of directory lookup, consider the following command line command:
@@ -396,7 +396,7 @@ The output (i.e., the template merged with the provided data) will be written to
\item When running \texplate, this is the expected output to be displayed in the command line (note that the layout is slightly modified due to space constraints in this user manual):
\begin{code}
-TeXplate 1.0.1, a document structure creation tool
+TeXplate 1.0.2, a document structure creation tool
Copyright (c) 2020, Island of TeX
All rights reserved.
@@ -597,8 +597,42 @@ gitlab.com/islandoftex/texplate
Happy \TeX ing with \texplate!
-\section*{License}
+\chapter*{License}
\texplate\ is licensed under the New BSD License. Please note that the New BSD License has been verified as a GPL-compatible free software license by the Free Software Foundation, and has been vetted as an open source license by the Open Source Initiative.
+\chapter*{Changelog}
+
+\section*{1.0.2 (current)}
+
+\subsection*{Fixed}
+
+\begin{itemize}
+\item \texplate\ now finds its templates even on Windows.
+\end{itemize}
+
+\subsection*{Changed}
+
+\begin{itemize}
+\item \texplate\ now finishes its transition to Kotlin. We did not change any functionality in the course of this change.
+\item Templates are now provided as resources from the JAR instead of a separate folder on the hard drive.
+\end{itemize}
+
+\section*{1.0.1 (2020-01-17)}
+
+\subsection*{Changed}
+
+\begin{itemize}
+\item \texplate\ will now distribute only non-generic template file names. In the system's template directory, we search for \inline{texplate-<name>.toml} as well.
+\end{itemize}
+
+\section*{1.0.0 (2020-01-15)}
+
+\subsection*{Added}
+
+\begin{itemize}
+\item Base functionality and default templates.
+\item User manual.
+\end{itemize}
+
\end{document}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/Main.java b/support/texplate/source/main/java/org/islandoftex/texplate/Main.java
deleted file mode 100644
index 5c27aab23c..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/Main.java
+++ /dev/null
@@ -1,36 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate;
-
-import org.islandoftex.texplate.model.TemplateProcessing;
-import org.islandoftex.texplate.util.MessageUtils;
-import picocli.CommandLine;
-
-/**
- * The main class. The application logic is enclosed in the template processing
- * class.
- *
- * @version 1.0
- * @since 1.0
- */
-public class Main {
-
- /**
- * Main method. Note that it simply passes the control to the template
- * processing class.
- *
- * @param args The command line arguments.
- */
- public static void main(String[] args) {
-
- // draw the application logo in the
- // terminal (please have fixed fonts
- // in your terminal for a nice display)
- MessageUtils.drawLogo();
-
- // calls the command line processing method
- // and performs the actual application logic
- int exitCode = new CommandLine(new TemplateProcessing()).execute(args);
- System.exit(exitCode);
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/Configuration.java b/support/texplate/source/main/java/org/islandoftex/texplate/model/Configuration.java
deleted file mode 100644
index a0f8e83702..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/Configuration.java
+++ /dev/null
@@ -1,150 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model;
-
-import com.moandjiezana.toml.Toml;
-import io.vavr.control.Try;
-import org.islandoftex.texplate.exceptions.InvalidTemplateException;
-
-import java.nio.file.Path;
-import java.util.Map;
-
-/**
- * The configuration model.
- *
- * @version 1.0
- * @since 1.0
- */
-public class Configuration {
-
- // template of the template
- private String template;
-
- // map of variables for the configuration
- private Map<String, Object> map;
-
- /**
- * Constructor.
- */
- public Configuration() {
- }
-
- /**
- * Constructor.
- *
- * @param template The template.
- * @param map The map.
- */
- public Configuration(String template, Map<String, Object> map) {
- this.template = template;
- this.map = map;
- }
-
- /**
- * Gets the template.
- *
- * @return The template.
- */
- public String getTemplate() {
- return template;
- }
-
- /**
- * Sets the template.
- *
- * @param template The template.
- */
- public void setTemplate(String template) {
- this.template = template;
- }
-
- /**
- * Gets the map.
- *
- * @return The map.
- */
- public Map<String, Object> getMap() {
- return map;
- }
-
- /**
- * Sets the map.
- *
- * @param map The map.
- */
- public void setMap(Map<String, Object> map) {
- this.map = map;
- }
-
- /**
- * Checks whether the configuration is valid.
- *
- * @return A boolean value indicating whether the configuration is valid.
- */
- private boolean isValid() {
- return !(template == null || map == null);
- }
-
- /**
- * Reads the configuration from path.
- *
- * @param path The path.
- * @return Configuration.
- * @throws InvalidTemplateException The configuration is invalid.
- */
- private static Configuration readFromPath(Path path)
- throws InvalidTemplateException {
-
- // the actual configuration
- Configuration configuration;
-
- // the default message
- String message = "The provided configuration file looks invalid. "
- + "Please make sure the configuration has a valid syntax and "
- + "try again. ";
-
- try {
-
- // gets the configuration
- configuration = new Toml().read(path.toFile()).
- to(Configuration.class);
-
- } catch (Exception exception) {
-
- // the configuration
- // seems invalid
- throw new InvalidTemplateException(message + "In this particular "
- + "scenario, there is a possibility that the configuration "
- + "file does not follow the TOML specification. Please "
- + "refer to the user manual for further details and a "
- + "possible fix. Also, the raised exception message can "
- + "give us some hints on what happened.", exception);
- }
-
- // checks whether the
- // configuration is valid
- if (configuration.isValid()) {
-
- // returns the configuration
- return configuration;
- } else {
-
- // the configuration
- // is invalid
- throw new InvalidTemplateException(message + "Specifically, some "
- + "mandatory fields are either absent or empty in the "
- + "configuration file. It is quite important to strictly "
- + "follow the configuration specification, as detailed in "
- + "the user manual, or the tool will not work at all.");
- }
- }
-
- /**
- * Gets the configuration from a path.
- *
- * @param path The path.
- * @return The configuration.
- */
- public static Try<Configuration> of(Path path) {
- return Try.of(() -> readFromPath(path));
- }
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/Template.java b/support/texplate/source/main/java/org/islandoftex/texplate/model/Template.java
deleted file mode 100644
index ca92e04658..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/Template.java
+++ /dev/null
@@ -1,252 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model;
-
-import com.moandjiezana.toml.Toml;
-import io.vavr.control.Try;
-import org.islandoftex.texplate.exceptions.InvalidTemplateException;
-
-import java.nio.file.Path;
-import java.util.List;
-import java.util.Map;
-
-/**
- * The template model.
- *
- * @version 1.0
- * @since 1.0
- */
-public class Template {
-
- // name of the template
- private String name;
-
- // description of the template
- private String description;
-
- // list of authors who wrote the template
- private List<String> authors;
-
- // list of requirements for the template
- private List<String> requirements;
-
- // the document to be configured
- private String document;
-
- // the map handlers
- private Map<String, String> handlers;
-
- /**
- * Constructor.
- */
- public Template() {
- }
-
- /**
- * Constructor.
- *
- * @param name Name of the template.
- * @param description Description of the template.
- * @param authors List of authors of the template.
- * @param requirements List of requirements for the template.
- * @param document The document to be configured.
- * @param handlers The optional map handlers.
- */
- public Template(String name, String description, List<String> authors,
- List<String> requirements, String document,
- Map<String, String> handlers) {
- this.name = name;
- this.description = description;
- this.authors = authors;
- this.requirements = requirements;
- this.document = document;
- this.handlers = handlers;
- }
-
- /**
- * Gets the template name.
- *
- * @return The template name.
- */
- public String getName() {
- return name;
- }
-
- /**
- * Sets the template name.
- *
- * @param name The template name.
- */
- public void setName(String name) {
- this.name = name;
- }
-
- /**
- * Gets the template description.
- *
- * @return The template description.
- */
- public String getDescription() {
- return description;
- }
-
- /**
- * Sets the template description.
- *
- * @param description The template description.
- */
- public void setDescription(String description) {
- this.description = description;
- }
-
- /**
- * Gets the template authors.
- *
- * @return The template authors.
- */
- public List<String> getAuthors() {
- return authors;
- }
-
- /**
- * Sets the template authors.
- *
- * @param authors The template authors.
- */
- public void setAuthors(List<String> authors) {
- this.authors = authors;
- }
-
- /**
- * Gets the template requirements.
- *
- * @return The template requirements.
- */
- public List<String> getRequirements() {
- return requirements;
- }
-
- /**
- * Sets the template requirements.
- *
- * @param requirements The template requirements.
- */
- public void setRequirements(List<String> requirements) {
- this.requirements = requirements;
- }
-
- /**
- * Gets the template document.
- *
- * @return The template document.
- */
- public String getDocument() {
- return document;
- }
-
- /**
- * Sets the template document.
- *
- * @param document The template document.
- */
- public void setDocument(String document) {
- this.document = document;
- }
-
- /**
- * Gets the map handlers.
- *
- * @return The map handlers.
- */
- public Map<String, String> getHandlers() {
- return handlers;
- }
-
- /**
- * Sets the map handlers.
- *
- * @param handlers The map handlers.
- */
- public void setHandlers(Map<String, String> handlers) {
- this.handlers = handlers;
- }
-
- /**
- * Checks whether the template is valid.
- *
- * @return A boolean value indicating whether the template is valid.
- */
- private boolean isValid() {
- return !((name == null) || (description == null)
- || (authors == null) || (requirements == null)
- || (document == null) || name.trim().isEmpty()
- || description.trim().isEmpty() || authors.isEmpty()
- || document.trim().isEmpty());
- }
-
- /**
- * Reads the template from the provided path.
- *
- * @param path The path to the template file.
- * @return The template object from the provided path.
- * @throws InvalidTemplateException The template is invalid.
- */
- private static Template readFromPath(Path path)
- throws InvalidTemplateException {
-
- // the actual template
- Template template;
-
- // the exception message, in case the
- // conversion fails or if there are
- // missing elements from the template
- String message = "The provided template file looks invalid. Please "
- + "make sure the template has a valid syntax and try again. ";
-
- try {
-
- // reads the file and converts
- // the TOML format into the object
- template = new Toml().read(path.toFile()).to(Template.class);
-
- } catch (Exception exception) {
-
- // throws the new exception and
- // attaches the original cause
- throw new InvalidTemplateException(message + "In this particular "
- + "scenario, there is a possibility that the template "
- + "file does not follow the TOML specification. Please "
- + "refer to the user manual for further details and a "
- + "possible fix. Also, the raised exception message can "
- + "give us some hints on what happened.", exception);
- }
-
- // the conversion hasn't failed, but we need
- // to check whether the template is valid
- if (template.isValid()) {
-
- // everything went fine, so
- // simply return the template
- return template;
- } else {
-
- // the template is invalid, so we
- // need to throw an exception
- throw new InvalidTemplateException(message + "Specifically, some "
- + "mandatory fields are either absent or empty in the "
- + "template file. It is quite important to strictly "
- + "follow the template specification, as detailed in the "
- + "user manual, or the tool will not work at all.");
- }
- }
-
- /**
- * Returns the template from the provided path.
- *
- * @param path The path in which the template is retrieved.
- * @return The corresponding template, enclosed in a Try object.
- */
- public static Try<Template> of(Path path) {
- return Try.of(() -> readFromPath(path));
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/TemplateProcessing.java b/support/texplate/source/main/java/org/islandoftex/texplate/model/TemplateProcessing.java
deleted file mode 100644
index eccaf6c732..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/TemplateProcessing.java
+++ /dev/null
@@ -1,391 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model;
-
-import io.vavr.control.Either;
-import org.islandoftex.texplate.util.MergingUtils;
-import org.islandoftex.texplate.util.MessageUtils;
-import org.islandoftex.texplate.util.PathUtils;
-import org.islandoftex.texplate.util.ValidatorUtils;
-import picocli.CommandLine;
-import picocli.CommandLine.Option;
-
-import java.nio.file.Path;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.concurrent.Callable;
-
-/**
- * The template processing class.
- *
- * @version 1.0
- * @since 1.0
- */
-@CommandLine.Command(
- usageHelpWidth = 70,
- name = "texplate"
-)
-public class TemplateProcessing implements Callable<Integer> {
-
- // the file output, which will hold the
- // result of the merging of both template
- // and context data map from command line
- @Option(
- names = {"-o", "--output"},
- description = "The output file in which the chosen "
- + "template will be effectively written. Make sure "
- + "the directory has the correct permissions for "
- + "writing the output file.",
- required = true,
- type = Path.class
- )
- private Path output;
-
- // the template name
- @Option(
- names = {"-t", "--template"},
- description = "The template and. The tool will "
- + "search both user and system locations and set the "
- + "template model accordingly, based on your specs."
- )
- private String template;
-
- // the context data map that holds
- // a set of key/value pairs to be
- // merged with the template
- @Option(
- names = {"-m", "--map"},
- description = "The contextual map that provides the "
- + "data to be merged in the template. This parameter "
- + "can be used multiple times. You can specify a map "
- + "entry with the key=value syntax (mind the entry "
- + "separator).",
- arity = "1..*"
- )
- private Map<String, String> map;
-
- @Option(
- names = {"-c", "--config"},
- description = "The configuration file in which the tool "
- + "can read template data, for automation purposes. Make "
- + "sure to follow the correct specification when writing "
- + "a configuration file.",
- type = Path.class
- )
- private Path configuration;
-
- /**
- * The application logic, enclosed as a call method.
- *
- * @return An integer value denoting the exit status.
- * @throws Exception An exception was raised in the application logic.
- */
- @Override
- public Integer call() throws Exception {
-
- // the exit status, originally
- // set as a valid value
- int exit = 0;
-
- // configuration halt flag, indicating
- // whether the tool has to end earlier
- boolean halt = false;
-
- Map<String, Object> cmap = new HashMap<>();
-
- // ensure the context data map
- // is at least instantiated
- ensureMap();
-
- // there is a configuration file
- // found in the command line
- if (has(configuration)) {
-
- // print the configuration
- // check line for status
- MessageUtils.line("Checking configuration");
-
- // try to read the configuration
- // file into a proper object
- Either<Throwable, Configuration> configChecking = Configuration.
- of(configuration).toEither();
-
- // the configuration file
- // seems to be valid, proceed
- if (configChecking.isRight()) {
-
- // print status line
- MessageUtils.status(true);
-
- // get the configuration file
- Configuration config = configChecking.get();
-
- // check if the configuration
- // has a proper template
- if (has(config.getTemplate())) {
-
- // if so, build the template if, and
- // only if, there's no one already
- // set through command line
- template = ensure(template, config.getTemplate());
- }
-
- // check if the configuration
- // has a proper string/string map
- if (has(config.getMap())) {
-
- // set the main configuration
- // map to be dealt later on
- cmap = config.getMap();
- }
-
- // print header about tidying
- // up configuration variables
- MessageUtils.line("Adjusting variables from file");
- MessageUtils.status(true);
- System.out.println();
-
- } else {
-
- // an error occurred, print it
- // set exit code and halt
- MessageUtils.status(false);
- MessageUtils.error(configChecking.getLeft());
- exit = -1;
- halt = true;
- }
- } else {
-
- // print header regarding
- // no config file found
- MessageUtils.line("Configuration file mode disabled");
- MessageUtils.status(true);
-
- // print a header regarding
- // full command line mode
- MessageUtils.line("Entering full command line mode");
-
- // there's no configuration file, so we
- // need to check whether there is not a
- // pattern set in the command line
- if (!has(template)) {
-
- // print status
- MessageUtils.status(false);
-
- // print message
- MessageUtils.error(new Exception("The template was not set "
- + "in the command line through the -t/--template "
- + "option. If not explicitly specified in a "
- + "configuration file, this option becomes mandatory, "
- + "so make sure to define it either in the command "
- + "line or in a proper configuration file."));
-
- exit = -1;
- halt = true;
-
- } else {
-
- // print status
- MessageUtils.status(true);
- System.out.println();
- }
-
- }
-
- // check whether we should
- // halt prematurely
- if (!halt) {
-
- // initial message, preparing our
- // hearts to the actual merging :)
- System.out.println("Please, wait...");
- System.out.println();
-
- // now we need to obtain the actual
- // template from a file stored either
- // in the user home or in the system
- MessageUtils.line("Obtaining reference");
-
- // let us try to get the corresponding
- // file from the template pattern
- Either<Throwable, Path> fileChecking = PathUtils.
- getTemplatePath(template).toEither();
-
- // the actual template file was
- // found, so we can proceed to
- // the next phase
- if (fileChecking.isRight()) {
-
- // updates the current
- // status accordingly
- MessageUtils.status(true);
-
- // now it's time to compose the template
- // object from its corresponding file
- MessageUtils.line("Composing template");
-
- // attempts to retrieve the template
- // attributes from the referenced file
- // to the actual template object
- Either<Throwable, Template> templateComposition
- = Template.of(fileChecking.get()).toEither();
-
- // the template composition was successful,
- // so we can move on to the next phase
- if (templateComposition.isRight()) {
-
- // updates the current
- // status accordingly
- MessageUtils.status(true);
-
- // once the template object is populated,
- // we need to verify if both template and
- // data map are not somehow conflicting
- MessageUtils.line("Validating data");
- Either<Throwable, Map<String, String>> dataValidation
- = ValidatorUtils.validate(templateComposition.get(),
- map).toEither();
-
- // the data validation was consistent,
- // so now the merging can be applied
- if (dataValidation.isRight()) {
-
- // updates the current
- // status accordingly
- MessageUtils.status(true);
-
- // now it's the final phase, in which
- // both template and data are merged
- MessageUtils.line("Merging template and data");
-
- // merge both template and context data
- // map
- Either<Throwable, Long> merging = MergingUtils.
- merge(templateComposition.get(),
- dataValidation.get(),
- output, cmap).toEither();
-
- // the merging was successful,
- // so now there's nothing else
- // to do, yay!
- if (merging.isRight()) {
-
- // updates the current
- // status accordingly
- MessageUtils.status(true);
-
- // print the final messge and
- // tell the user everything
- // went smooth!
- System.out.println();
- System.out.println("Done! Enjoy your template!");
- System.out.println("Written: "
- + getSize(merging.get()));
- } else {
-
- // updates the current
- // status accordingly
- MessageUtils.status(false);
-
- // the merging failed, so the
- // exception is displayed and
- // the exit status is updated
- MessageUtils.error(merging.getLeft());
- exit = -1;
- }
- } else {
-
- // updates the current
- // status accordingly
- MessageUtils.status(false);
-
- // the data validation failed, so
- // the exception is displayed and
- // the exit status is updated
- MessageUtils.error(dataValidation.getLeft());
- exit = -1;
- }
- } else {
-
- // updates the current
- // status accordingly
- MessageUtils.status(false);
-
- // the template composition failed,
- // so the exception is displayed and
- // the exit status is updated
- MessageUtils.error(templateComposition.getLeft());
- exit = -1;
- }
- } else {
-
- // updates the current
- // status accordingly
- MessageUtils.status(false);
-
- // the file checking failed, so
- // the exception is displayed and
- // the exit status is updated
- MessageUtils.error(fileChecking.getLeft());
- exit = -1;
- }
- }
-
- // the exit status is returned,
- // denoting whether the application
- // was able to merge both template
- // and data accordingly
- return exit;
- }
-
- /**
- * Ensures the data map is never pointed to a null reference.
- */
- private void ensureMap() {
-
- // if the map is null, simply
- // create a new instance
- if (!has(map)) {
- map = new HashMap<>();
- }
- }
-
- /**
- * Gets the file size in a human readable format.
- *
- * @param bytes The file size, in bytes.
- * @return The file size in a human readable format.
- */
- private String getSize(long bytes) {
- if (bytes < 1024) {
- return bytes + " B";
- } else {
- int exponent = (int) (Math.log(bytes) / Math.log(1024));
- return String.format("%.1f %cB", bytes / Math.pow(1024, exponent),
- "KMGTPE".charAt(exponent - 1));
- }
- }
-
- /**
- * Ensures the first parameter is not null, or sets it to the second one.
- *
- * @param <T> The type.
- * @param first First parameter.
- * @param second Second parameter.
- * @return Either the first or the second one.
- */
- private <T> T ensure(T first, T second) {
- return !has(first) ? second : first;
- }
-
- /**
- * Checks whether the object exists.
- *
- * @param object The objects.
- * @return Boolean value indicating whether the object exists.
- */
- private boolean has(Object object) {
- return object != null;
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/BooleanHandler.java b/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/BooleanHandler.java
deleted file mode 100644
index 461b9fd170..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/BooleanHandler.java
+++ /dev/null
@@ -1,26 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model.handlers;
-
-import java.util.Arrays;
-
-/**
- * Implements a boolean handler.
- *
- * @version 1.0
- * @since 1.0
- */
-public class BooleanHandler implements Handler {
-
- /**
- * Applies the conversion to the string.
- *
- * @param string The string.
- * @return A list.
- */
- @Override
- public Object apply(String string) {
- return Arrays.asList("true", "1", "yes")
- .contains(string.toLowerCase());
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/CSVListHandler.java b/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/CSVListHandler.java
deleted file mode 100644
index 4b3d0c2e69..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/CSVListHandler.java
+++ /dev/null
@@ -1,30 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model.handlers;
-
-import java.util.Arrays;
-import java.util.stream.Collectors;
-
-/**
- * Implements a CSV list handler.
- *
- * @version 1.0
- * @since 1.0
- */
-public class CSVListHandler implements Handler {
-
- /**
- * Applies the conversion to the string.
- *
- * @param string The string.
- * @return A list.
- */
- @Override
- public Object apply(String string) {
- return Arrays.stream(string.split(",(?=(?:[^\"]*\""
- + "[^\"]*\")*[^\"]*$)"))
- .map(String::trim)
- .filter(s -> !s.isEmpty())
- .collect(Collectors.toList());
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/util/HandlerUtils.java b/support/texplate/source/main/java/org/islandoftex/texplate/util/HandlerUtils.java
deleted file mode 100644
index 7ab01f7328..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/util/HandlerUtils.java
+++ /dev/null
@@ -1,31 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.util;
-
-import java.util.HashMap;
-import java.util.Map;
-
-import org.islandoftex.texplate.model.handlers.BooleanHandler;
-import org.islandoftex.texplate.model.handlers.CSVListHandler;
-import org.islandoftex.texplate.model.handlers.Handler;
-
-/**
- * Provides the map of handlers.
- *
- * @version 1.0
- * @since 1.0
- */
-public class HandlerUtils {
-
- /**
- * Gets the map of handlers.
- *
- * @return Map of handlers.
- */
- public static Map<String, Handler> getHandlers() {
- Map<String, Handler> handlers = new HashMap<>();
- handlers.put("to-csv-list", new CSVListHandler());
- handlers.put("to-boolean", new BooleanHandler());
- return handlers;
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/util/MergingUtils.java b/support/texplate/source/main/java/org/islandoftex/texplate/util/MergingUtils.java
deleted file mode 100644
index d7ffbddc4d..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/util/MergingUtils.java
+++ /dev/null
@@ -1,186 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.util;
-
-import io.vavr.control.Try;
-import org.apache.velocity.VelocityContext;
-import org.apache.velocity.exception.MethodInvocationException;
-import org.apache.velocity.exception.ParseErrorException;
-import org.apache.velocity.exception.ResourceNotFoundException;
-import org.apache.velocity.exception.TemplateInitException;
-import org.apache.velocity.runtime.RuntimeConstants;
-import org.apache.velocity.runtime.RuntimeServices;
-import org.apache.velocity.runtime.RuntimeSingleton;
-import org.apache.velocity.runtime.parser.ParseException;
-import org.islandoftex.texplate.exceptions.TemplateMergingException;
-import org.islandoftex.texplate.model.Template;
-import org.islandoftex.texplate.model.handlers.Handler;
-import org.slf4j.helpers.NOPLoggerFactory;
-
-import java.io.FileWriter;
-import java.io.IOException;
-import java.io.StringReader;
-import java.io.Writer;
-import java.nio.file.Path;
-import java.util.HashMap;
-import java.util.Map;
-
-/**
- * Merging utilities.
- *
- * @version 1.0
- * @since 1.0
- */
-public class MergingUtils {
-
- /**
- * Merges both template and data.
- *
- * @param template The template object.
- * @param map The data map.
- * @param output The output path.
- * @param cmap The configuration map.
- * @return The length of the generated output.
- * @throws TemplateMergingException The merging failed.
- */
- private static long mergeTemplate(Template template,
- Map<String, String> map, Path output,
- Map<String, Object> cmap)
- throws TemplateMergingException {
-
- // create the context map
- Map<String, Object> context = handle(template, map, cmap);
-
- // create a file writer for
- // the output reference
- try (Writer writer = new FileWriter(output.toFile())) {
-
- // the document is actually read
- // into a string reader
- StringReader reader = new StringReader(template.getDocument());
-
- // load both runtime services and
- // the template model from Velocity
- RuntimeServices services = RuntimeSingleton.getRuntimeServices();
- services.addProperty(RuntimeConstants.RUNTIME_LOG_INSTANCE,
- new NOPLoggerFactory().getLogger(""));
- org.apache.velocity.Template reference
- = new org.apache.velocity.Template();
-
- // set both runtime services
- // and document data into the
- // template document
- reference.setRuntimeServices(services);
- reference.setData(services.parse(reader, reference));
- reference.initDocument();
-
- // create the context based on
- // the data map previously set
- VelocityContext entries = new VelocityContext(context);
-
- // merge both template and data
- // into the file writer
- reference.merge(entries, writer);
-
- } catch (IOException | MethodInvocationException
- | ParseErrorException | ParseException
- | ResourceNotFoundException
- | TemplateInitException exception) {
-
- // an exception has happened, so a
- // new exception is thrown, attaching
- // the original throwable cause
- throw new TemplateMergingException("An error occurred while "
- + "trying to merge the template reference with the "
- + "provided data. Make sure the template is correct "
- + "and try again. The raised exception might give us "
- + "some hints on what exactly happened. Typically, "
- + "make sure the template strictly follows the "
- + "Velocity 2.0 language syntax.", exception);
- }
-
- // simply return the length of
- // the generated output file
- return output.toFile().length();
- }
-
- /**
- * Merges template and data.
- *
- * @param template The template model.
- * @param map The data map.
- * @param output The path reference.
- * @param cmap The configuration map.
- * @return The length of the generated output, enclosed as a Try object.
- */
- public static Try<Long> merge(Template template, Map<String, String> map,
- Path output, Map<String, Object> cmap) {
- return Try.of(() -> mergeTemplate(template, map, output, cmap));
- }
-
- /**
- * Handles the context map.
- *
- * @param template The template model.
- * @param map The context map.
- * @return The new context map.
- */
- private static Map<String, Object> handle(Template template,
- Map<String, String> map,
- Map<String, Object> cmap) {
-
- // no handlers found
- if (template.getHandlers() == null) {
-
- // create a new map from the
- // command line map and put the
- // values from the configuration
- // file, if absent
- Map<String, Object> result = new HashMap<>(map);
- cmap.forEach(result::putIfAbsent);
- return result;
-
- } else {
-
- // get default handlers and
- // set the resulting map
- Map<String, Handler> handlers = HandlerUtils.getHandlers();
- Map<String, Object> result = new HashMap<>();
-
- // check each key from the map
- map.forEach((String key, String value) -> {
-
- // there is a handler for
- // the current key
- if (template.getHandlers().containsKey(key)) {
-
- // the handler seems valid
- if (handlers.containsKey(template.getHandlers().get(key))) {
-
- // apply the handler and
- // store the value in the map
- result.put(key, handlers.get(template.
- getHandlers().get(key)).apply(value));
- } else {
-
- // simply store the value
- result.put(key, value);
- // TODO: should we warn about an invalid handler?
- }
- } else {
-
- // simply store the value
- result.put(key, value);
- }
- });
-
- // put remaining values from
- // the configuration file, if
- // absent
- cmap.forEach(result::putIfAbsent);
-
- // return the map
- return result;
- }
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/util/MessageUtils.java b/support/texplate/source/main/java/org/islandoftex/texplate/util/MessageUtils.java
deleted file mode 100644
index 7649a60e82..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/util/MessageUtils.java
+++ /dev/null
@@ -1,84 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.util;
-
-import org.apache.commons.text.TextStringBuilder;
-import org.apache.commons.text.WordUtils;
-
-import java.time.LocalDate;
-
-/**
- * Message helper methods.
- *
- * @version 1.0
- * @since 1.0
- */
-public class MessageUtils {
-
- // the message width
- private static final int WIDTH = 60;
-
- // the application version
- private static final String VERSION = "1.0.1";
-
- /**
- * Prints a line in the terminal, without a line break.
- *
- * @param message The message to be printed.
- */
- public static void line(String message) {
- System.out.print(new TextStringBuilder()
- .appendFixedWidthPadRight(message.concat(" "), WIDTH - 9, '.')
- .append(" ")
- .toString()
- );
- }
-
- /**
- * Prints the status in the terminal.
- *
- * @param result The boolean value.
- */
- public static void status(boolean result) {
- System.out.println(result ? "[ DONE ]" : "[FAILED]");
- }
-
- /**
- * Prints the error in the terminal.
- *
- * @param throwable The throwable reference.
- */
- public static void error(Throwable throwable) {
- System.out.println(
- new TextStringBuilder("\n")
- .appendFixedWidthPadRight("HOUSTON, WE'VE GOT"
- + " A PROBLEM ", WIDTH, '-')
- .append("\n")
- .appendln(WordUtils.wrap(throwable.getMessage(), WIDTH))
- .appendFixedWidthPadLeft("", WIDTH, '-')
- .append("\n")
- .toString());
- }
-
- /**
- * Prints the application logo in the terminal.
- */
- public static void drawLogo() {
- System.out.println(
- " ______ __ __ ___ __ \n" +
- "/\\__ _\\ /\\ \\ /\\ \\ /\\_ \\ /\\ \\__ \n" +
- "\\/_/\\ \\/ __ \\ `\\`\\/'/' _____\\//\\ \\ __ \\ \\ ,_\\ __ \n" +
- " \\ \\ \\ /'__`\\`\\/ > < /\\ '__`\\\\ \\ \\ /'__`\\ \\ \\ \\/ /'__`\\ \n" +
- " \\ \\ \\/\\ __/ \\/'/\\`\\\\ \\ \\L\\ \\\\_\\ \\_/\\ \\L\\.\\_\\ \\ \\_/\\ __/ \n" +
- " \\ \\_\\ \\____\\ /\\_\\\\ \\_\\ \\ ,__//\\____\\ \\__/.\\_\\\\ \\__\\ \\____\\\n" +
- " \\/_/\\/____/ \\/_/ \\/_/\\ \\ \\/ \\/____/\\/__/\\/_/ \\/__/\\/____/\n" +
- " \\ \\_\\ \n" +
- " \\/_/ \n"
- );
- System.out.println(
- "TeXplate " + VERSION + ", a document structure creation tool\n" +
- "Copyright (c) " + LocalDate.now().getYear() + ", Island of TeX\n" +
- "All rights reserved.\n"
- );
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/util/PathUtils.java b/support/texplate/source/main/java/org/islandoftex/texplate/util/PathUtils.java
deleted file mode 100644
index fa242c4980..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/util/PathUtils.java
+++ /dev/null
@@ -1,129 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.util;
-
-import io.vavr.control.Try;
-import org.islandoftex.texplate.Main;
-
-import java.io.FileNotFoundException;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-
-/**
- * Helper methods for path handling.
- *
- * @version 1.0
- * @since 1.0
- */
-public class PathUtils {
-
- // the templates folder
- private static final String TEMPLATES_FOLDER = "templates";
-
- // the user application folder
- private static final String USER_APPLICATION_FOLDER = ".texplate";
-
- /**
- * Gets the application path.
- *
- * @return The application path.
- */
- private static Path getApplicationPath() {
- return Try.of(() -> Paths.get(Main.class.getProtectionDomain().
- getCodeSource().getLocation().toURI().getPath()).resolve("..").
- normalize()).getOrElse(Paths.get("."));
- }
-
- /**
- * Gets the default template path.
- *
- * @return The default template path.
- */
- private static Path getDefaultTemplatePath() {
- return getApplicationPath().resolve(TEMPLATES_FOLDER);
- }
-
- /**
- * Gets the user template path.
- *
- * @return The user template path.
- */
- private static Path getUserTemplatePath() {
- return Try.of(() -> Paths.get(System.getProperty("user.home"),
- USER_APPLICATION_FOLDER, TEMPLATES_FOLDER)).
- getOrElse(Paths.get("."));
- }
-
- /**
- * Searchs all paths looking for the provided template.
- *
- * @param name The name to be associated to a template file.
- * @return The corresponding template file.
- * @throws FileNotFoundException The template file could not be found.
- */
- private static Path searchTemplatePath(String name)
- throws FileNotFoundException {
- // the file has to be a TOML format,
- // so we add the extension
- name = name.concat(".toml");
-
- // the first reference is based on the
- // user template path resolved with the
- // file name
- Path reference = getUserTemplatePath().resolve(name);
-
- // if the file actually exists,
- // the search is done!
- if (Files.exists(reference)) {
- // return the template
- // file reference
- return reference;
-
- } else {
- // the reference was not found in the
- // user location, so let us try the
- // system counterpart
- reference = getDefaultTemplatePath().resolve(name);
-
- // if the file actually exists,
- // the search is done!
- if (Files.exists(reference)) {
- // return the template
- // file reference
- return reference;
-
- } else {
- // in the system path, look for an `texplate` prefixed
- // version as well
- reference = getDefaultTemplatePath().resolve("texplate-" + name);
-
- if (Files.exists(reference)) {
- // return the template
- // file reference
- return reference;
- } else {
- // the file reference could not be
- // found, so an exception is thrown
- throw new FileNotFoundException("I am sorry, but the template "
- + "file '" + name + "' could not be found in the "
- + "default template locations (system and user). Make "
- + "sure the reference is correct and try again. For "
- + "reference, these are the paths I searched: '"
- + getUserTemplatePath() + "' and '"
- + getDefaultTemplatePath() + "' (in this order).");
- }
- }
- }
- }
-
- /**
- * Gets the template path based on the provided template name.
- *
- * @param name The template name.
- * @return The template path, enclosed in a Try object.
- */
- public static Try<Path> getTemplatePath(String name) {
- return Try.of(() -> searchTemplatePath(name));
- }
-
-}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/util/ValidatorUtils.java b/support/texplate/source/main/java/org/islandoftex/texplate/util/ValidatorUtils.java
deleted file mode 100644
index b400731242..0000000000
--- a/support/texplate/source/main/java/org/islandoftex/texplate/util/ValidatorUtils.java
+++ /dev/null
@@ -1,75 +0,0 @@
-// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.util;
-
-import io.vavr.control.Try;
-import org.islandoftex.texplate.exceptions.InvalidKeySetException;
-import org.islandoftex.texplate.model.Template;
-
-import java.util.Map;
-
-/**
- * Helper methods for validation.
- *
- * @version 1.0
- * @since 1.0
- */
-public class ValidatorUtils {
-
- /**
- * Validates the data map based on the template requirements.
- *
- * @param template The template.
- * @param map The data map.
- * @return A boolean value indicating whether the data map is valid.
- */
- private static boolean validateRequirements(Template template,
- Map<String, String> map) {
- return template.getRequirements().isEmpty() ||
- template.getRequirements().containsAll(map.keySet());
- }
-
- /**
- * Validates the template pattern and the data map and throws an exception
- * in case of failure.
- *
- * @param template The template.
- * @param map The data map.
- * @return The data map.
- * @throws InvalidKeySetException There are invalid keys in the map.
- */
- private static Map<String, String> checkValidation(Template template,
- Map<String, String> map)
- throws InvalidKeySetException {
-
- // for starters, we try to validate
- // the template requirements
- if (validateRequirements(template, map)) {
-
- // everything is validated, so
- // we simply return the map
- return map;
-
- } else {
-
- // the requirements were missing,
- // so an exception is thrown
- throw new InvalidKeySetException("The provided map does not "
- + "contain all the keys required by the chosen "
- + "template. Make sure to define such keys and try "
- + "again. Check the user manual for further details.");
- }
- }
-
- /**
- * Validates the template pattern and the data map.
- *
- * @param template The template.
- * @param map The data map.
- * @return The data map, enclosed in a Try object.
- */
- public static Try<Map<String, String>> validate(Template template,
- Map<String, String> map) {
- return Try.of(() -> checkValidation(template, map));
- }
-
-}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/Main.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/Main.kt
new file mode 100644
index 0000000000..73de15f8c3
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/Main.kt
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate
+
+import kotlin.system.exitProcess
+import org.islandoftex.texplate.util.MessageUtils
+import picocli.CommandLine
+
+/**
+ * Main method. Note that it simply passes the control to the template
+ * processing class.
+ *
+ * @param args The command line arguments.
+ */
+fun main(args: Array<String>) {
+ // draw the application logo in the terminal (please have fixed fonts
+ // in your terminal for a nice display)
+ MessageUtils.drawLogo()
+ // calls the command line processing method and performs the actual
+ // application logic
+ @Suppress("SpreadOperator")
+ val exitCode = CommandLine(TemplateProcessing()).execute(*args)
+ exitProcess(exitCode)
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt
new file mode 100644
index 0000000000..659a0df631
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt
@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate
+
+import java.nio.file.Path
+import java.util.concurrent.Callable
+import kotlin.math.ln
+import kotlin.math.pow
+import org.islandoftex.texplate.exceptions.InvalidTemplateException
+import org.islandoftex.texplate.model.Configuration
+import org.islandoftex.texplate.model.Template
+import org.islandoftex.texplate.util.MergingUtils.mergeTemplate
+import org.islandoftex.texplate.util.MessageUtils.error
+import org.islandoftex.texplate.util.MessageUtils.line
+import org.islandoftex.texplate.util.MessageUtils.status
+import org.islandoftex.texplate.util.PathUtils.getTemplatePath
+import org.islandoftex.texplate.util.ValidatorUtils.validate
+import picocli.CommandLine
+
+/**
+ * The template processing class.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+@CommandLine.Command(usageHelpWidth = 70, name = "texplate")
+class TemplateProcessing : Callable<Int> {
+ // the file output, which will hold the result of the merging of both template
+ // and context data map from command line
+ @CommandLine.Option(
+ names = ["-o", "--output"],
+ description = ["The output file in which the chosen " +
+ "template will be effectively written. Make sure " +
+ "the directory has the correct permissions for " +
+ "writing the output file."],
+ required = true,
+ type = [Path::class]
+ )
+ private val output: Path? = null
+
+ // the template name
+ @CommandLine.Option(
+ names = ["-t", "--template"],
+ description = ["The name of the template. The tool will " +
+ "search both user and system locations and set the " +
+ "template model accordingly, based on your specs."]
+ )
+ private var template: String? = null
+
+ // the context data map that holds a set of key/value pairs to be merged
+ // with the template
+ @CommandLine.Option(
+ names = ["-m", "--map"],
+ description = ["The contextual map that provides the " +
+ "data to be merged in the template. This parameter " +
+ "can be used multiple times. You can specify a map " +
+ "entry with the key=value syntax (mind the entry " +
+ "separator)."],
+ arity = "1..*"
+ )
+ private var map: Map<String, String>? = null
+
+ @CommandLine.Option(
+ names = ["-c", "--config"],
+ description = ["The configuration file in which the tool " +
+ "can read template data, for automation purposes. Make " +
+ "sure to follow the correct specification when writing " +
+ "a configuration file."],
+ type = [Path::class]
+ )
+ private val configuration: Path? = null
+
+ /**
+ * The application logic, enclosed as a call method.
+ *
+ * @return An integer value denoting the exit status.
+ * @throws Exception An exception was raised in the application logic.
+ */
+ @Throws(Exception::class)
+ override fun call(): Int {
+ // the exit status, originally set as a valid value
+ var exit = 0
+ // configuration halt flag, indicating whether the tool has to end earlier
+ var halt = false
+ var cmap: Map<String, Any> = mutableMapOf()
+ // ensure the context data map is at least instantiated
+ ensureMap()
+ // there is a configuration file found in the command line
+ if (has(configuration)) {
+ line("Checking configuration")
+ try {
+ val config = Configuration.fromPath(configuration!!)
+ // the configuration file seems to be valid, proceed
+ status(true)
+ // check if the configuration has a proper template
+ if (has(config.template)) {
+ // if so, build the template if, and only if, there's no one already
+ // set through command line
+ template = ensure(template, config.template)
+ }
+ // check if the configuration has a proper string/string map
+ if (has(config.map)) {
+ // set the main configuration map to be dealt later on
+ cmap = config.map
+ }
+ line("Adjusting variables from file")
+ status(true)
+ println()
+ } catch (e: InvalidTemplateException) {
+ // an error occurred, print it, set exit code and halt
+ status(false)
+ error(e)
+ exit = -1
+ halt = true
+ }
+ } else {
+ line("Configuration file mode disabled")
+ status(true)
+ line("Entering full command line mode")
+ // there's no configuration file, so we need to check whether there is
+ // not a pattern set in the command line
+ if (!has(template)) {
+ status(false)
+ error(Exception("The template was not set " +
+ "in the command line through the -t/--template " +
+ "option. If not explicitly specified in a " +
+ "configuration file, this option becomes mandatory, " +
+ "so make sure to define it either in the command " +
+ "line or in a proper configuration file."))
+ exit = -1
+ halt = true
+ } else {
+ status(true)
+ println()
+ }
+ }
+ // check whether we should halt prematurely
+ if (!halt) {
+ println("Please, wait...")
+ println()
+ // now we need to obtain the actual template from a file stored either
+ // in the user home or in the system
+ line("Obtaining reference")
+ try {
+ // let us try to get the corresponding file from the template pattern
+ val file = getTemplatePath(template!!)
+ // the actual template file was found, so we can proceed to
+ // the next phase
+ status(true)
+ line("Composing template")
+ // attempts to retrieve the template attributes from the referenced file
+ // to the actual template object
+ val template = Template.fromPath(file)
+ // the template composition was successful, so we can move on to the
+ // next phase
+ status(true)
+ // once the template object is populated, we need to verify if both
+ // template and data map are not somehow conflicting
+ line("Validating data")
+ val validatedData = validate(template, map!!)
+ // the data validation was consistent, so now the merging can be
+ // applied
+ status(true)
+ line("Merging template and data")
+ val merged = mergeTemplate(template, validatedData, output!!,
+ cmap)
+ status(true)
+ println()
+ println("Done! Enjoy your template!")
+ println("Written: " + getSize(merged))
+ } catch (e: InvalidTemplateException) {
+ status(false)
+ error(e)
+ exit = -1
+ }
+ }
+ // the exit status is returned, denoting whether the application was able
+ // to merge both template and data accordingly
+ return exit
+ }
+
+ /**
+ * Ensures the data map is never pointed to a null reference.
+ */
+ private fun ensureMap() {
+ if (!has(map)) {
+ map = mutableMapOf()
+ }
+ }
+
+ /**
+ * Gets the file size in a human readable format.
+ *
+ * @param bytes The file size, in bytes.
+ * @return The file size in a human readable format.
+ */
+ @Suppress("MagicNumber")
+ private fun getSize(bytes: Long): String {
+ return if (bytes < 1024) {
+ "$bytes B"
+ } else {
+ val exponent = (ln(bytes.toDouble()) / ln(1024.0)).toInt()
+ "%.1f %cB".format(bytes / 1024.0.pow(exponent.toDouble()),
+ "KMGTPE"[exponent - 1])
+ }
+ }
+
+ /**
+ * Ensures the first parameter is not null, or sets it to the second one.
+ *
+ * @param <T> The type.
+ * @param first First parameter.
+ * @param second Second parameter.
+ * @return Either the first or the second one.
+ </T> */
+ private fun <T> ensure(first: T, second: T): T {
+ return if (!has(first)) second else first
+ }
+
+ /**
+ * Checks whether the object exists.
+ *
+ * @param obj The object.
+ * @return Boolean value indicating whether the object exists.
+ */
+ private fun has(obj: Any?): Boolean {
+ return obj != null
+ }
+}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidKeySetException.java b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidKeySetException.kt
index 3d113a2599..72ff3bcbd4 100644
--- a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidKeySetException.java
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidKeySetException.kt
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.exceptions;
+package org.islandoftex.texplate.exceptions
/**
* Handles exceptions when the context map contains invalid keys.
@@ -7,22 +7,18 @@ package org.islandoftex.texplate.exceptions;
* @version 1.0
* @since 1.0
*/
-public class InvalidKeySetException extends Exception {
-
+class InvalidKeySetException : Exception {
/**
* Constructor.
*/
- public InvalidKeySetException() {
- }
+ constructor()
/**
* Constructor.
*
* @param message Message to be attached to the exception.
*/
- public InvalidKeySetException(String message) {
- super(message);
- }
+ constructor(message: String?) : super(message)
/**
* Constructor.
@@ -30,8 +26,5 @@ public class InvalidKeySetException extends Exception {
* @param message Message to be attached to the exception.
* @param cause The throwable cause to be forwarded.
*/
- public InvalidKeySetException(String message, Throwable cause) {
- super(message, cause);
- }
-
+ constructor(message: String?, cause: Throwable?) : super(message, cause)
}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidTemplateException.java b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidTemplateException.kt
index 73c8276998..678c390055 100644
--- a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/InvalidTemplateException.java
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/InvalidTemplateException.kt
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.exceptions;
+package org.islandoftex.texplate.exceptions
/**
* Handles exceptions when the template is somehow invalid.
@@ -7,19 +7,15 @@ package org.islandoftex.texplate.exceptions;
* @version 1.0
* @since 1.0
*/
-public class InvalidTemplateException extends Exception {
-
- public InvalidTemplateException() {
- }
+class InvalidTemplateException : Exception {
+ constructor()
/**
* Constructor.
*
* @param message Message to be attached to the exception.
*/
- public InvalidTemplateException(String message) {
- super(message);
- }
+ constructor(message: String?) : super(message)
/**
* Constructor.
@@ -27,8 +23,5 @@ public class InvalidTemplateException extends Exception {
* @param message Message to be attached to the exception.
* @param cause The throwable cause to be forwarded.
*/
- public InvalidTemplateException(String message, Throwable cause) {
- super(message, cause);
- }
-
+ constructor(message: String?, cause: Throwable?) : super(message, cause)
}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/TemplateMergingException.java b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/TemplateMergingException.kt
index 86dd99af00..e1760f8732 100644
--- a/support/texplate/source/main/java/org/islandoftex/texplate/exceptions/TemplateMergingException.java
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/exceptions/TemplateMergingException.kt
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.exceptions;
+package org.islandoftex.texplate.exceptions
/**
* Handles exceptions when the template merging failed.
@@ -7,22 +7,18 @@ package org.islandoftex.texplate.exceptions;
* @version 1.0
* @since 1.0
*/
-public class TemplateMergingException extends Exception {
-
+class TemplateMergingException : Exception {
/**
* Constructor.
*/
- public TemplateMergingException() {
- }
+ constructor()
/**
* Constructor.
*
* @param message Message to be attached to the exception.
*/
- public TemplateMergingException(String message) {
- super(message);
- }
+ constructor(message: String?) : super(message)
/**
* Constructor.
@@ -30,8 +26,5 @@ public class TemplateMergingException extends Exception {
* @param message Message to be attached to the exception.
* @param cause The throwable cause to be forwarded.
*/
- public TemplateMergingException(String message, Throwable cause) {
- super(message, cause);
- }
-
+ constructor(message: String?, cause: Throwable?) : super(message, cause)
}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Configuration.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Configuration.kt
new file mode 100644
index 0000000000..8d37cbb39a
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Configuration.kt
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.model
+
+import com.moandjiezana.toml.Toml
+import java.nio.file.Path
+import org.islandoftex.texplate.exceptions.InvalidTemplateException
+
+/**
+ * The configuration model.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+data class Configuration(
+ /**
+ * The template of the template.
+ */
+ val template: String? = null,
+ /**
+ * Map of variables for the configuration.
+ */
+ val map: Map<String, Any> = mapOf()
+) {
+ /**
+ * Whether the configuration is valid.
+ */
+ private val isValid: Boolean
+ get() = template != null
+
+ companion object {
+ /**
+ * Reads the configuration from path.
+ *
+ * @param path The path.
+ * @return Configuration.
+ * @throws InvalidTemplateException The configuration is invalid.
+ */
+ @Throws(InvalidTemplateException::class)
+ fun fromPath(path: Path): Configuration {
+ val configuration: Configuration
+ val message = ("The provided configuration file looks invalid. " +
+ "Please make sure the configuration has a valid syntax and " +
+ "try again. ")
+ configuration = try {
+ // gets the configuration
+ Toml().read(path.toFile()).to(Configuration::class.java)
+ } catch (exception: IllegalStateException) {
+ // the configuration seems invalid
+ throw InvalidTemplateException(message + "In this particular " +
+ "scenario, there is a possibility that the configuration " +
+ "file does not follow the TOML specification. Please " +
+ "refer to the user manual for further details and a " +
+ "possible fix. Also, the raised exception message can " +
+ "give us some hints on what happened.", exception)
+ }
+ return if (configuration.isValid) {
+ configuration
+ } else {
+ throw InvalidTemplateException(message + "Specifically, some " +
+ "mandatory fields are either absent or empty in the " +
+ "configuration file. It is quite important to strictly " +
+ "follow the configuration specification, as detailed in " +
+ "the user manual, or the tool will not work at all.")
+ }
+ }
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Template.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Template.kt
new file mode 100644
index 0000000000..82616242de
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/Template.kt
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.model
+
+import com.moandjiezana.toml.Toml
+import java.nio.file.Path
+import org.islandoftex.texplate.exceptions.InvalidTemplateException
+
+/**
+ * The template model.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+data class Template(
+ /**
+ * Name of the template
+ */
+ val name: String? = null,
+ /**
+ * Description of the template
+ */
+ val description: String? = null,
+ /**
+ * List of authors who wrote the template
+ */
+ val authors: List<String> = listOf(),
+ /**
+ * List of requirements for the template
+ */
+ val requirements: List<String> = listOf(),
+ /**
+ * The document to be configured
+ */
+ val document: String? = null,
+ /**
+ * The map handlers
+ */
+ val handlers: Map<String, String> = mapOf()
+) {
+ /**
+ * Checks whether the template is valid.
+ *
+ * @return A boolean value indicating whether the template is valid.
+ */
+ private val isValid: Boolean
+ get() = !(name == null || description == null ||
+ document == null || name.isBlank() ||
+ description.isBlank() || authors.isEmpty() ||
+ document.isBlank())
+
+ companion object {
+ /**
+ * Reads the template from the provided path.
+ *
+ * @param path The path to the template file.
+ * @return The template object from the provided path.
+ * @throws InvalidTemplateException The template is invalid.
+ */
+ @JvmStatic
+ @Throws(InvalidTemplateException::class)
+ fun fromPath(path: Path): Template {
+ val template: Template
+ // the exception message, in case the conversion fails or if there are
+ // missing elements from the template
+ val message = ("The provided template file looks invalid. Please " +
+ "make sure the template has a valid syntax and try again. ")
+ template = try {
+ Toml().read(path.toFile()).to(Template::class.java)
+ } catch (exception: IllegalStateException) {
+ throw InvalidTemplateException(message + "In this particular " +
+ "scenario, there is a possibility that the template " +
+ "file does not follow the TOML specification. Please " +
+ "refer to the user manual for further details and a " +
+ "possible fix. Also, the raised exception message can " +
+ "give us some hints on what happened.", exception)
+ }
+ // the conversion hasn't failed, but we need to check whether the
+ // template is valid
+ return if (template.isValid) {
+ template
+ } else {
+ throw InvalidTemplateException(message + "Specifically, some " +
+ "mandatory fields are either absent or empty in the " +
+ "template file. It is quite important to strictly " +
+ "follow the template specification, as detailed in the " +
+ "user manual, or the tool will not work at all.")
+ }
+ }
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/BooleanHandler.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/BooleanHandler.kt
new file mode 100644
index 0000000000..cbb74a532f
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/BooleanHandler.kt
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.model.handlers
+
+/**
+ * Implements a boolean handler.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+class BooleanHandler : Handler {
+ /**
+ * Applies the conversion to the string.
+ *
+ * @param string The string.
+ * @return A list.
+ */
+ override fun apply(string: String?): Any? {
+ return listOf("true", "1", "yes").contains(string!!.toLowerCase())
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/CSVListHandler.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/CSVListHandler.kt
new file mode 100644
index 0000000000..77424ed463
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/CSVListHandler.kt
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.model.handlers
+
+/**
+ * Implements a CSV list handler.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+class CSVListHandler : Handler {
+ /**
+ * Applies the conversion to the string.
+ *
+ * @param string The string.
+ * @return A list.
+ */
+ override fun apply(string: String?): Any? {
+ return string?.split(",(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)".toRegex())
+ ?.map { it.trim() }
+ ?.filter { it.isNotEmpty() }
+ }
+}
diff --git a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/Handler.java b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/Handler.kt
index 721224a978..47b59a09a5 100644
--- a/support/texplate/source/main/java/org/islandoftex/texplate/model/handlers/Handler.java
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/Handler.kt
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: BSD-3-Clause
-package org.islandoftex.texplate.model.handlers;
+package org.islandoftex.texplate.model.handlers
/**
* Interface for handlers.
@@ -7,14 +7,12 @@ package org.islandoftex.texplate.model.handlers;
* @version 1.0
* @since 1.0
*/
-public interface Handler {
-
+interface Handler {
/**
* Apply the handler in the string.
*
* @param string The string.
* @return The resulting object.
*/
- Object apply(String string);
-
+ fun apply(string: String?): Any?
}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt
new file mode 100644
index 0000000000..44eebb2b69
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.util
+
+import org.islandoftex.texplate.model.handlers.BooleanHandler
+import org.islandoftex.texplate.model.handlers.CSVListHandler
+import org.islandoftex.texplate.model.handlers.Handler
+
+/**
+ * Provides the map of handlers.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+object HandlerUtils {
+ /**
+ * Gets the map of handlers.
+ *
+ * @return Map of handlers.
+ */
+ @JvmStatic
+ val handlers: Map<String, Handler> = mapOf(
+ "to-csv-list" to CSVListHandler(),
+ "to-boolean" to BooleanHandler()
+ )
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MergingUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MergingUtils.kt
new file mode 100644
index 0000000000..ef02349d5d
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MergingUtils.kt
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.util
+
+import java.io.IOException
+import java.nio.file.Path
+import org.apache.velocity.VelocityContext
+import org.apache.velocity.exception.MethodInvocationException
+import org.apache.velocity.exception.ParseErrorException
+import org.apache.velocity.exception.ResourceNotFoundException
+import org.apache.velocity.exception.TemplateInitException
+import org.apache.velocity.runtime.RuntimeConstants
+import org.apache.velocity.runtime.RuntimeSingleton
+import org.apache.velocity.runtime.parser.ParseException
+import org.islandoftex.texplate.exceptions.TemplateMergingException
+import org.islandoftex.texplate.model.Template
+import org.islandoftex.texplate.util.HandlerUtils.handlers
+import org.slf4j.helpers.NOPLoggerFactory
+
+/**
+ * Merging utilities.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+object MergingUtils {
+ /**
+ * Merges both template and data.
+ *
+ * @param template The template object.
+ * @param map The data map.
+ * @param output The output path.
+ * @param cmap The configuration map.
+ * @return The length of the generated output.
+ * @throws TemplateMergingException The merging failed.
+ */
+ @JvmStatic
+ @Throws(TemplateMergingException::class)
+ @Suppress("TooGenericExceptionCaught")
+ fun mergeTemplate(
+ template: Template,
+ map: Map<String, String?>,
+ output: Path,
+ cmap: Map<String, Any>
+ ): Long {
+ // create the context map
+ val context = handle(template, map, cmap)
+ // create a file writer for the output reference
+ try {
+ output.toFile().writer().use { writer ->
+ // the document is actually read into a string reader
+ val reader = template.document!!.reader()
+ // load both runtime services and the template model from Velocity
+ val services = RuntimeSingleton.getRuntimeServices()
+ services.addProperty(RuntimeConstants.RUNTIME_LOG_INSTANCE,
+ NOPLoggerFactory().getLogger(""))
+ val reference = org.apache.velocity.Template()
+ // set both runtime services and document data into the template document
+ reference.setRuntimeServices(services)
+ reference.data = services.parse(reader, reference)
+ reference.initDocument()
+ // create the context based on the data map previously set
+ val entries = VelocityContext(context)
+ // merge both template and data into the file writer
+ reference.merge(entries, writer)
+ }
+ } catch (exception: Exception) {
+ // TODO: simplify
+ when (exception) {
+ is IOException, is MethodInvocationException, is ParseErrorException,
+ is ParseException, is ResourceNotFoundException, is TemplateInitException ->
+ throw TemplateMergingException("An error occurred while " +
+ "trying to merge the template reference with the " +
+ "provided data. Make sure the template is correct " +
+ "and try again. The raised exception might give us " +
+ "some hints on what exactly happened. Typically, " +
+ "make sure the template strictly follows the " +
+ "Velocity 2.0 language syntax.", exception)
+ else -> throw TemplateMergingException("Fatal error occured. " +
+ "This error should never happen. Please make a detailed " +
+ "report to the developers.")
+ }
+ }
+ // simply return the length of the generated output file
+ return output.toFile().length()
+ }
+
+ /**
+ * Handles the context map.
+ *
+ * @param template The template model.
+ * @param map The context map.
+ * @param configmap The map from a configuration file.
+ * @return The new context map.
+ */
+ private fun handle(
+ template: Template,
+ map: Map<String, String?>,
+ configmap: Map<String, Any>
+ ): Map<String, Any?> {
+ // no handlers found
+ return if (template.handlers.isEmpty()) {
+ // create a new map from the command line map and put the values from
+ // the configuration file cmap, if absent
+ configmap.mapValues { it.value.toString() }.plus(map)
+ } else {
+ // get default handlers and set the resulting map
+ val result: MutableMap<String, Any?> = mutableMapOf()
+ // check each key from the map
+ map.forEach { (key: String, value: String?) ->
+ // there is a handler for the current key
+ if (template.handlers.containsKey(key) &&
+ handlers.containsKey(template.handlers[key])) {
+ // apply the handler and store the value in the map
+ result[key] = handlers[template.handlers[key]]!!.apply(value)
+ } else {
+ // simply store the value
+ result[key] = value
+ // TODO: should we warn about an invalid handler?
+ }
+ }
+
+ // put remaining values from the configuration file, if absent
+ configmap.plus(result)
+ }
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MessageUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MessageUtils.kt
new file mode 100644
index 0000000000..fbb68a819e
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/MessageUtils.kt
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.util
+
+import java.time.LocalDate
+
+/**
+ * Message helper methods.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+object MessageUtils {
+ // the message width
+ private const val WIDTH = 60
+ // the application version
+ private val VERSION = MessageUtils::class.java.`package`.implementationVersion
+ ?: "DEVELOPMENT BUILD"
+
+ /**
+ * Prints a line in the terminal, without a line break.
+ *
+ * @param message The message to be printed.
+ */
+ @JvmStatic
+ fun line(message: String) {
+ print("$message ".padEnd(WIDTH - " [FAILED]".length, '.') + " ")
+ }
+
+ /**
+ * Prints the status in the terminal.
+ *
+ * @param result The boolean value.
+ */
+ @JvmStatic
+ fun status(result: Boolean) {
+ println(if (result) "[ DONE ]" else "[FAILED]")
+ }
+
+ /**
+ * Prints the error in the terminal.
+ *
+ * @param throwable The throwable reference.
+ */
+ @JvmStatic
+ fun error(throwable: Throwable) {
+ println("\n" + "HOUSTON, WE'VE GOT A PROBLEM ".padEnd(WIDTH, '-') +
+ "\n" + throwable.message + "\n" +
+ "".padStart(WIDTH, '-') + "\n")
+ }
+
+ /**
+ * Prints the application logo in the terminal.
+ */
+ fun drawLogo() {
+ println(
+ " ______ __ __ ___ __ \n" +
+ "/\\__ _\\ /\\ \\ /\\ \\ /\\_ \\ /\\ \\__ \n" +
+ "\\/_/\\ \\/ __ \\ `\\`\\/'/' _____\\//\\ \\ __ \\ \\ ,_\\ __ \n" +
+ " \\ \\ \\ /'__`\\`\\/ > < /\\ '__`\\\\ \\ \\ /'__`\\ \\ \\ \\/ /'__`\\ \n" +
+ " \\ \\ \\/\\ __/ \\/'/\\`\\\\ \\ \\L\\ \\\\_\\ \\_/\\ \\L\\.\\_\\ \\ \\_/\\ __/ \n" +
+ " \\ \\_\\ \\____\\ /\\_\\\\ \\_\\ \\ ,__//\\____\\ \\__/.\\_\\\\ \\__\\ \\____\\\n" +
+ " \\/_/\\/____/ \\/_/ \\/_/\\ \\ \\/ \\/____/\\/__/\\/_/ \\/__/\\/____/\n" +
+ " \\ \\_\\ \n" +
+ " \\/_/ \n"
+ )
+ println(
+ "TeXplate $VERSION, a document structure creation tool\n" +
+ "Copyright (c) ${LocalDate.now().year}, Island of TeX\n" +
+ "All rights reserved.\n"
+ )
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt
new file mode 100644
index 0000000000..3a74603557
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.util
+
+import java.io.FileNotFoundException
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.Paths
+
+/**
+ * Helper methods for path handling.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+object PathUtils {
+ // the templates folder
+ private const val TEMPLATES_FOLDER = "templates"
+ // the user application folder
+ private const val USER_APPLICATION_FOLDER = ".texplate"
+
+ /**
+ * The user's template path.
+ */
+ private val userTemplatePath: Path
+ get() = try {
+ Paths.get(System.getProperty("user.home"),
+ USER_APPLICATION_FOLDER, TEMPLATES_FOLDER)
+ } catch (e: RuntimeException) {
+ Paths.get(".")
+ }
+
+ /**
+ * Searches all paths looking for the provided template.
+ *
+ * @param name The name to be associated to a template file.
+ * @return The corresponding template file.
+ * @throws FileNotFoundException The template file could not be found.
+ */
+ @JvmStatic
+ @Throws(FileNotFoundException::class)
+ fun getTemplatePath(name: String): Path {
+ // the file has to be a TOML format, so we add the extension
+ val fullName = "$name.toml"
+ // the first reference is based on the user template path resolved with the
+ // file name
+ val reference = userTemplatePath.resolve(fullName)
+ // if the file actually exists, the search is done!
+ return if (Files.exists(reference)) {
+ reference
+ } else {
+ // the reference was not found in the user location, so let us try the
+ // system counterpart
+ try {
+ val tempFile = Files.createTempFile(null, null)
+ tempFile.toFile().writeText(PathUtils::class.java
+ .getResource("/org/islandoftex/texplate/templates/texplate-$fullName")
+ .readText())
+ tempFile
+ } catch (e: RuntimeException) {
+ throw FileNotFoundException("I am sorry, but the template " +
+ "file '" + fullName + "' could not be found in the " +
+ "default template locations (system and user). Make " +
+ "sure the reference is correct and try again. For " +
+ "reference, these are the paths I searched: '" +
+ userTemplatePath + "'.")
+ }
+ }
+ }
+}
diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/ValidatorUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/ValidatorUtils.kt
new file mode 100644
index 0000000000..ef91a012c1
--- /dev/null
+++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/ValidatorUtils.kt
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: BSD-3-Clause
+package org.islandoftex.texplate.util
+
+import org.islandoftex.texplate.exceptions.InvalidKeySetException
+import org.islandoftex.texplate.model.Template
+
+/**
+ * Helper methods for validation.
+ *
+ * @version 1.0
+ * @since 1.0
+ */
+object ValidatorUtils {
+ /**
+ * Validates the data map based on the template requirements.
+ *
+ * @param template The template.
+ * @param map The data map.
+ * @return A boolean value indicating whether the data map is valid.
+ */
+ private fun validateRequirements(
+ template: Template,
+ map: Map<String, String>
+ ): Boolean {
+ return template.requirements.isNullOrEmpty() ||
+ template.requirements.containsAll(map.keys)
+ }
+
+ /**
+ * Validates the template pattern and the data map and throws an exception
+ * in case of failure.
+ *
+ * @param template The template.
+ * @param map The data map.
+ * @return The data map.
+ * @throws InvalidKeySetException There are invalid keys in the map.
+ */
+ @JvmStatic
+ @Throws(InvalidKeySetException::class)
+ fun validate(
+ template: Template,
+ map: Map<String, String>
+ ): Map<String, String> {
+ // for starters, we try to validate the template requirements
+ return if (validateRequirements(template, map)) {
+ map
+ } else {
+ throw InvalidKeySetException("The provided map does not " +
+ "contain all the keys required by the chosen " +
+ "template. Make sure to define such keys and try " +
+ "again. Check the user manual for further details.")
+ }
+ }
+}
diff --git a/support/texplate/scripts/templates/texplate-article.toml b/support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-article.toml
index 53f7796762..53f7796762 100644
--- a/support/texplate/scripts/templates/texplate-article.toml
+++ b/support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-article.toml
diff --git a/support/texplate/scripts/templates/texplate-standalone.toml b/support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-standalone.toml
index dd8daea65f..dd8daea65f 100644
--- a/support/texplate/scripts/templates/texplate-standalone.toml
+++ b/support/texplate/source/main/resources/org/islandoftex/texplate/templates/texplate-standalone.toml