summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/toptesi/toptesi.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/toptesi/toptesi.dtx')
-rw-r--r--Master/texmf-dist/source/latex/toptesi/toptesi.dtx217
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.