toptesi (21nov18)

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

1 files changed, 198 insertions, 19 deletions

diff --git a/Master/texmf-dist/source/latex/toptesi/toptesi.dtx b/Master/texmf-dist/source/latex/toptesi/toptesi.dtx
index 9ca4fb8afba..266f5a105b0 100644
--- a/Master/texmf-dist/source/latex/toptesi/toptesi.dtx
+++ b/Master/texmf-dist/source/latex/toptesi/toptesi.dtx
@@ -24,6 +24,9 @@ Distributable under the LaTeX Project Public License,
 version 1.3c or higher (your choice). The latest version of
 this license is at: http://www.latex-project.org/lppl.txt
 
+For important further details see the English or the Italian 
+documentation.
+
 This work is "author-maintained"
 
 This work consists of this file toptesi.dtx, a README file
@@ -139,7 +142,7 @@ School of Turin.
 %<topmag>\ProvidesPackage{toptesi-magistrale}[%
 %<topdoc>\ProvidesPackage{toptesi-dottorale}[%
 %<*driver,class,topsty,topcmn,topfrn,topscu,topmon,topsss,topmag,topdoc>
-2018/10/30 v.~6.2.05 
+2018/11/20 v.6.2.09 
 %<class>Class for typesetting university theses]
 %<topsty>Extension for toptesi.cls]
 %<topcmn>Additional commands for the TOPtesi bundle]
@@ -253,10 +256,10 @@ School of Turin.
 %</driver>
 % \fi
 %
-% \CheckSum{7540}
+% \CheckSum{7600}
 %
 % \begin{abstract}
-% This file describes the TOPtesi bundle; it is a set of files
+% This file describes the TOPtesi bundle; it consists of a set of files
 % designed to typeset  a university final report that in Italian
 % is generally called “tesi”; it was originally developed at
 % the Technical University of Turin (Politecnico di Torino) but
@@ -299,6 +302,12 @@ School of Turin.
 % author, and to other programmers and/or curious users.
 % The “normal” user should not spend his/her time to read
 % unnecessary information.
+%
+% \textcolor{red}{This bundle is distributed under the \LaTeX\ Project
+% Public Licence (LPPL) which is appended to the Italian documentation
+% file \texttt{toptesi-it.pdf} included in this bundle; personal
+% customisation of parts of this bundle are discouraged but are
+% permitted only in conformance with the LPPL. See also section~\ref{sec:LPPL}.}
 % \end{abstract}
 %
 % \section{History}
@@ -2410,35 +2419,57 @@ School of Turin.
 %
 % \item
 % In the 2018 version of \TeXLive, with the upgrade of |pdfx|
-% a glitch emerged due to licence questions; the |sRGB.icc| distributed with earlier versions was under a limited licence that is not  compliant with the free nature of the \TeX\ system. The maintainers are aware of this problem ad while they are further upgrading the |pdfx| file, suggest a work-around (the will be described below); it is possible that when you read this documentations the work-around is not necessary any more. Nevertheless belod the work-around is described.
+% a glitch emerged due to licence questions; the |sRGB.icc| distributed
+% with earlier versions was under a limited licence that is not 
+% compliant with the free nature of the \TeX\ system. The maintainers
+% are aware of this problem and, while they are further upgrading the
+% |pdfx| file, they suggest a work-around (that will be described below);
+% it is possible that when you read this documentations the work-around
+% is not necessary any more. Nevertheless the work-around is
+% described.
 %
 % \item
 % If your thesis main file, the one you run your typesetting
 % program on, is named, say, \texttt{JohnSmithMasterThesis.tex},
 % prepare in the same directory another file named
 % \texttt{JohnSmithMasterThesis.xmpdata} that contains the
-% \emph{metadata} relative to the thesis; pay attention
-% to follow the stringent syntax described and exemplified
-% in the \textsf{pdfx} documentation. A minimal example set of
-% \emph{metadata} would be the following one:
+% \emph{metadata} relative to the thesis. 
+% Pay attention to follow the stringent metadata syntax described
+% and exemplified in the \textsf{pdfx} documentation. A minimal 
+% example set of \emph{metadata} would be the following one:
 % \begin{verbatim}
 % \Title{Experiments in Trichotetratomy}
 % \Author{John Smith}
 % \end{verbatim}
 % The keyword list requires a specific format that can be
-% examined in the package documentation. The best way to
+% examined in the |pdfx| package documentation. The best way to
 % be sure that this file accompanies the thesis main file,
-% is to put its contents in a \env{filecontents*} environment
-% before the |\documentclass| declaration. The details are
-% in the documentation of the \pack{pdfx} package and examples
-% are shown in the Italian documentation of |TOPtesi|.
+% is to put its contents in a \env{filecontents*} environment.
+% The details are in the documentation of the \pack{pdfx} package and
+% examples are shown in the Italian documentation of |TOPtesi|.
+% In order to override the constraints of the \LaTeX\ kernel 
+% |filecontents| environment, TOPtesi loads the package |filecontents|
+% that% eliminates the mentioned constraints, but requires that the
+% environment be used within the preamble, in any case before
+% loading the |pdfx| package. Actually this does not forbid to use the
+% environment before the |\documentclass| statement, as it was in the
+% previous versions of TOPtesi. The new version is backwards compatible with the previous nes with this simple difference: when the environment
+% is used before the |\documentclass| statement, any modification of
+% its contents does not take place unless the previous |xmpdata| file
+% is deleted, because the kernel environment does not overwrite existing
+% files; on the opposite, if the environment is used after the
+% |\documentclass| statement ,the |xmpdata| file is simply overwritten
+% without the need to delete a previous version.
 %
 % The work-around mentioned above consists in adding another line 
-% at the very end of the metadata file that looks like this:
+% at the very end of the metadata file; it looks like this:
 %\begin{verbatim}
 %\setRGBcolorprofile{sRGB.icc}{sRGB}{Argyll CMS, sRGB color profile}%
 %{https://www.argyllcms.com/}
 %\end{verbatim}
+% Thanks to the |filecontents| functionalities there is no need
+% to delete a previous |.xmpdata| file.
+%
 % This work-around is required if you get an error message that
 % refers to line 1084 of the |pdfx.sty| file; if you don't patch
 % the metadata file and you do not get the above error, it means
@@ -2525,6 +2556,85 @@ School of Turin.
 % or ttf fonts and use this version of the TOPtesi bundle
 % you should be able to avoid most problems.
 %
+% \section{Customisation}\label{sec:LPPL}
+% Customisation of parts of this bundle is discouraged, but is not
+% forbidden, provided that it is done according to the \LaTeX\ Project
+% Public Licence (LPPL). The full text of this licence is contained at the
+% end of the Italian documentation file \texttt{toptesi-it.pdf},
+% besides being available from the \sigla{ctan} web site.
+%
+% The parts of this bundle already contain several customising
+% commands and environments; other parts are not directly
+% customisable; for example the geometry of the page; the various
+% standard title pages (where the \texttt{tipotesi=custom} option
+% already allows complete customisation of the title page); the
+% super sectioning of the final document by means of |\frontmatter|,
+% |\mainmatter|, and |\backmatter|; what appears in the table of
+% contents; and so on.
+%
+% Nevertheless, in spite of being discouraged,  some user might
+% want to customise some details. There are several ways to do
+% such customisation that conform the LPPL. 
+%
+% \textcolor{red}{The main restriction set by the LPPL is that
+% the bundle files may be modified, but their names must be changed,
+% although the original author and licence are maintained in their
+% initial comments, and that the file maintainer name is changed so
+% that any user of the modified version knows to whom address
+% him/herself in case of need; the original author  is not responsible
+% of any modified file.}
+%
+% \paragraph{Direct modification}
+% In order to make a direct modification to any original file, first
+% duplicate the original file and change name to the duplicated file;
+% the modify this copy name and make the changes that are deemed
+% necessary, without forgetting to delete my name as the maintainer
+% while adding your name; it would be useful if some comments are
+% added so as to describe what has benne modified, why and how.
+%
+% Remember to change accordingly the references to the modified
+% file(s) in the other bundle files; this implies that all the
+% bundle files get modified and that their names must be changed
+% accordingly while modifying the initial  comment lines so as to
+% delete my name as the maintainer.
+%
+% \paragraph{Modification of single commands and/or environments}
+% Another way to perform some customisation that does not infringe
+% the LPPL licence is the following.
+%
+% In facts a simpler way to customise some commands and or
+% environments is to copy their code from the original bundle
+% files, and paste it  into a personal \texttt{.sty} file to be
+% input with a |\usepackage| command inside the argument of
+% another |\AtBeginDocument| command; modify your personal file
+% the way you like, and test the result.
+
+% If your modifications do not produce any difference in the 
+% output PDF file, then you have to load your modified file after
+% the |\begin{document}| line. In this case you have to change
+% your file extension from \texttt{.sty} to \texttt{.tex}, and 
+% you probably have to start your file with a |\makeatletter| and
+% finish it with a |\makeatother| commands, since many macros
+% used inside the original code are “protected” with an |@| sign
+% with its category code changed to “letter”. Needless to say that
+% in order to suse thei |.tex| file, the |\input| command must be
+% used in place of the |\usepackage| one.
+%
+% \paragraph{Command patching}
+% A third way to modify some commands and/or environments is to
+% patch their definitions by means of the patching commands provided
+% by the |etoolbox| package, that is already loaded by this bundle.
+% Such |etoolbox| commands allow to add or to append some code to
+% selected macros; other |etoolbox| commands allow to insert some code
+% in the middle of a replacement text of selected macros or to replace
+% some code in any position of its replacement text.
+%
+% The use of these patching commands requires some attention and
+% is not recommended for \LaTeX\ beginners; nevertheless it is the
+% best way to apply personal modifications to existing commands.
+% The details of this procedure must be examined in the |etoolbox|
+% documentation.
+%
 % \StopEventually{}
 %
 % \newpage
@@ -2542,7 +2652,7 @@ School of Turin.
 % \fi
 %
 % The class itself is very simple since it loads just the
-% \texttt{report} document class and some packages with some
+% \texttt{report} document class and some packages with a few
 % default options. All options specified to the \texttt{toptesi}
 % class are passed on to the \texttt{report} class; the
 % |a4paper| option is made the default, but the user can invoke
@@ -2550,12 +2660,15 @@ School of Turin.
 % \LaTeX\ and |xkeyval| machinery of option passing, the |\ExecuteOptionX|
 % command assures that |a4paper| is the default size, but it
 % is not used if another paper size code is specified to the class.
+%
 % The same holds true for the other class options, except for
-% the encoding string because their passing machinery does
+% the encoding string because their option passing machinery does
 % not hold true for the \pack{inputenc} package; therefore this
 % package is not loaded any more as it was in previous versions
 % of the class\footnote{Thanks to Enrico Gregorio who pointed
-% out this feature.}. On the opposite, while typesetting with
+% out this feature.}. 
+%
+% On the opposite, while typesetting with
 % |pdfLaTeX|, if another language is specified in the list of
 % \pack{toptesi} class options this language is appended to the
 % \pack{babel} package default options and, beware!, it would
@@ -2564,6 +2677,36 @@ School of Turin.
 % specifying languages; with these programs other languages must
 % be specified with their |\setotherlanguage| or |\setotherlanguages|
 % commands which do not change the preset main language.
+%
+% The |filecontents| package is loaded: it removes the constraints
+% the original kernel environment |filecontents|, with or without
+% the asterisk, sets up for its use. In particular that what is
+% contained in the environment gets saved in the named file, only
+% if the named file does not exist. This implies that if some
+% changes are introduced in the environment contents, such changes
+% do not get saved in the named file unless a pre\-existing file is
+% deleted.
+%
+% Another piece of code follows in order to abort the job if the
+% |toptesi| date, contained in it |\ProvidePacckage| argument is
+% older than the class date. Should this happen, the job is aborted
+% with a strong message on the console. In order to work properly
+% the |toptesi| package is loaded and its date is fetched by means
+% of the defined |\GetFileInfo|macro. This macro is almost identical
+% to the one that is available when this documented file is processed;
+% it simply differs in the sense that the |v.| prefix to the file
+% version number is taken as a separator; should be necessary to
+% compare also the version number, the |\fileversion| macro gets
+% defined properly without any prefix. The |\@parse@version| macro
+% is a \LaTeX\ kernel one; in spite spite of its name, it extracts
+% from the first macro token the data in a form suitable for comparison
+% with the second macro token, so that a numerical test can be performed
+% without the intervention of non digit symbols. The prominent class
+% error message is output only if the numerical value of the package
+% date is strictly lower than the class date. This version control was
+% necessary because apparently there are some vintage versions still
+% on the web, and some newbie \TeX{}ies fetch them instead of using
+% the most recent \TeX\ system complete and updated installation.
 %    \begin{macrocode}
 \usepackage{trace}
 \RequirePackage{xkeyval}
@@ -2587,7 +2730,37 @@ School of Turin.
   \expandafter\@firstoftwo\else
   \expandafter\@secondoftwo\fi}
 \fi
+\RequirePackage{filecontents}
+\providecommand\GetFileInfo[1]{%
+  \def\filename{#1}%
+  \def\@tempb##1 v.##2 ##3\relax##4\relax{%
+    \def\filedate{##1}%
+    \def\fileversion{##2}%
+    \def\fileinfo{##3}}%
+  \edef\@tempa{\csname ver@#1\endcsname}%
+  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
+
 \usepackage{toptesi}
+\GetFileInfo{toptesi.sty}\let\stydate\filedate
+\GetFileInfo{toptesi.cls}\let\classdate\filedate
+
+  \ifnum\expandafter\@parse@version\stydate//00\@nil<%
+        \expandafter\@parse@version\classdate//00\@nil
+    \ClassError{toptesi}{\MessageBreak
+      ******************\MessageBreak
+      This class requires a sty file not older than the class\MessageBreak
+      This class has a date of \classdate\space while\MessageBreak
+      the sty file you are using  has a date of \stydate\MessageBreak
+      \MessageBreak
+      This job is therefore aborted\MessageBreak\@gobble
+      ******************\MessageBreak
+      \MessageBreak
+      Update your TeX system installation and/or \MessageBreak
+      avoid using vintage toptesi.sty files%
+    }{%
+    }
+    \expandafter\stop
+  \fi
 %
 %    \end{macrocode}
 % \iffalse
@@ -8621,6 +8794,12 @@ Anno scolastico \@annoscolastico}}
 %    to the report/book/article class can be used (this required a loto
 %    of thought, because the xkeyval package documentations require
 %    thoughtful interpretation.
-
-
+%%%% (version 6.2.07 of 2018/11/12) Added checks in order to avoid loading
+%    an older toptesi.sty package compared to the toptesi.cls. It avoids
+%    any possible conflict with hacked toptesi.sty files, or even with
+%    such obsolete versions, still going around in Internet, that date back
+%    to the old times when the toptesi.cls file did not yet exist (versions
+%    2.xxxx or older).
+%%%% (version 6.2.09 of 2-18/11/20) Loaded the filecontents package in oder
+%    to allow overwriting of the metadata file needed for PDF/A compliance.