doclicense (11jul21)

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

2 files changed, 169 insertions, 69 deletions

diff --git a/Master/texmf-dist/source/latex/doclicense/Makefile b/Master/texmf-dist/source/latex/doclicense/Makefile
index 62eb5c63ca6..bfa65debc3f 100644
--- a/Master/texmf-dist/source/latex/doclicense/Makefile
+++ b/Master/texmf-dist/source/latex/doclicense/Makefile
@@ -6,25 +6,35 @@
 # For more details about the licensing, refer to the README.md file.
 
 TEXMFHOME ?= $(shell kpsewhich -var-value TEXMFHOME)
+SHELL := /bin/bash -o nounset -o pipefail -o errexit
 
-all: install build manifest.txt
+.PHONY: all
+all: install build
 
-build: check-quick doclicense.sty doclicense.pdf
+.PHONY: build
+build: manifest.txt doclicense.sty doclicense.pdf
 
+.PHONY: ci
+ci: lint build
+
+.PHONY: install
 install:
 	mkdir --parents "$(TEXMFHOME)/tex/latex/"
 	test -L "$(TEXMFHOME)/tex/latex/doclicense" || ln --no-target-directory --symbolic "$$PWD" "$(TEXMFHOME)/tex/latex/doclicense"
 
-check-quick: doclicense.dtx
-	chktex "$<"
-
+# Run before release.
+.PHONY: check
 check: run_tests doclicense.sty lint
 	./"$<"
 
-lint:
+.PHONY: lint
+lint: doclicense.dtx
+	chktex "$<"
 	find -regextype posix-egrep -iregex '.*\.(tex|ldf)' -and -not -iname '*-plaintext.tex' -print0 | xargs --null chktex
+	[[ -z "$(shell lacheck "$<" *.ldf | grep 'possible unwanted space')" ]]
 	reuse lint
 
+.PHONY: clean
 clean:
 	rm -rf *.sty *.pdf *.aux *.out *.glo *.gls *.hd *.idx *.ilg *.ind *.log *.toc
 
diff --git a/Master/texmf-dist/source/latex/doclicense/doclicense.dtx b/Master/texmf-dist/source/latex/doclicense/doclicense.dtx
index 5932dabaa47..e6520b4d80d 100644
--- a/Master/texmf-dist/source/latex/doclicense/doclicense.dtx
+++ b/Master/texmf-dist/source/latex/doclicense/doclicense.dtx
@@ -24,7 +24,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1998/12/01]
 %<package>\ProvidesPackage{doclicense}
 %<*package>
-    [2021/03/13 v2.3.0 Support for putting documents under a license]
+    [2021/07/11 v3.0.0 Support for putting documents under a license]
 %</package>
 %
 %<*driver>
@@ -44,7 +44,7 @@
   obeyspaces,
   spaces,
 ]{url}
-\usepackage{
+\usepackage{%
   babel,
   csquotes,
   xcolor,
@@ -63,7 +63,7 @@
   hyphenation={RaggedRight},
 ]{doclicense}
 \GetFileInfo{doclicense.dtx}
-\hypersetup{
+\hypersetup{%
   pdftitle={A manual for \PackageName},
   pdfauthor={\PackageAuthor{} <\PackageAuthorEmail>},
   pdfsubject={\fileinfo},
@@ -136,10 +136,9 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % \changes{2.2.0}{2020/09/18}{Add Japanese and Bulgarian translation. Add hint how to use Chinese to docs. Load hyperxmp by default when it is installed. Before, doclicense just suggested to load it and made use of the package when the user did.}
 % \changes{2.2.1}{2020/09/25}{Fix compatibility issue with newer versions of hyperxmp (bug confirmed with Tex Live 2020) resulting in an compile error by loading hyperxmp and hyperref in the order the packages expect it.}
 % \changes{2.3.0}{2021/03/13}{Add option to disable the use of hyperxmp and add compatibility for pdfx. Use \url{https://reuse.software/} for the doclicense source code itself.}
+% \changes{3.0.0}{2021/07/11}{Breaking change: Hard require package options "type", "modifier" and "version" now after one year in soft require migration period. Add Croatian translation. Add sections to docs about choosing a license and the REUSE specification. Update Spanish translation to match Creative Commons website. Add note to README that CC license texts and images are licensed themselves under CC0-1.0. Load csquotes after hyperref to avoid hyperref warning. Do not load the hyperxmp package if the silence package is loaded to avoid an endless loop. Improve warning messages generated by the package. Add "Dependency packages and load order" section to docs.}
 %
 %
-
-%
 % ^^A nag warned about the center environment and it really messes up spacing.
 %
 % \DoNotIndex{\RequirePackage, \DeclareOption, \ProcessOptions}
@@ -174,20 +173,19 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % package is designed to handle all kinds of licenses. See \nameref{sec:contributing}.
 %
 % \section{Usage}
-% Just load the package by placing something like this:
+% The package can be used like in this mini working example:
 %
 % \begin{quote}
-%   |\usepackage{| \\
-%   |  babel,| \\
-%   |}| \\
+%   |\documentclass[english]{article}| \\
 %   |\usepackage[| \\
 %   |  type={CC},| \\
 %   |  modifier={by-sa},| \\
 %   |  version={4.0},| \\
-%   |]{doclicense}|
+%   |]{doclicense}| \\
+%   |\begin{document}| \\
+%   |\doclicenseThis%| \\
+%   |\end{document}|
 % \end{quote}
-% in the preamble of your \LaTeXe{} source file and change the package options
-% to the license you want to put the document under.
 %
 % This will explicitly set the license to \doclicenseNameRef.
 %
@@ -200,13 +198,48 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % \enquote{Document License} tab under \enquote{Properties}. You may check
 % this manual for how your PDF reader handles such metadata.
 %
-% In case you are using other package to manipulate the metadata which is
+% In case you are using other packages to manipulate the metadata which is
 % incompatible to the use of hyperxmp, e.\,g. \PrintPackage{pdfx} you can use
-% the \PrintOptionF{hyperxmp=false} to disable this automatism. If
+% the \PrintOptionF{hyperxmp=false} option to disable this automatism. If
 % \PrintPackage{pdfx} is loaded before \PrintPackage{doclicense} or if
 % \PrintPackage{hyperxmp} is not installed this automatism is disabled.
-% In these cases a warning is emitted to inform you about the reasons.
-% The warning will not show up if \PrintOptionF{hyperxmp} is set to false.
+% In these cases a warning is emitted to inform you about the reason.
+% The warning will not show up if \PrintOptionF{hyperxmp} is set to
+% \PrintOptionF{false}.
+%
+% Also note that \PrintPackage{hyperxmp} is not loaded when
+% \PrintPackage{silence} was loaded. This is because when both of those
+% packages are loaded, compilation runs into an endless loop.
+%
+% \section{Dependency packages and load order}
+%
+% \PackageName{} will ensure that the following packages are loaded by default.
+% You don't need to do anything extra as long as you are fine with the default options
+% of those packages:
+%
+% \begin{eqlist}
+%   \item[\PrintPackage{ccicons}] To typeset icon versions of the Creative Commons licenses.
+%   \item[\PrintPackage{graphicx}] To include images/buttons of the Creative Commons licenses.
+%   \item[\PrintPackage{hyperxmp}] To write license information into the metadata section of the generated PDF.
+%   \item[\PrintPackage{hyperref}] To typeset hyperlinks/URLs that are clickable.
+%   \item[\PrintPackage{csquotes}] To offload localization of quotes depending on document language.
+% \end{eqlist}
+%
+% Load order is important for some of those packages.
+% Here are the constraints that you will need to consider when you decide to
+% load the packages yourself or other packages that you use load them:
+%
+% \begin{itemize}
+%   \item \PrintPackage{hyperxmp} should be loaded before the setup of \PrintPackage{hyperref} is called.
+%   \item \PrintPackage{csquotes} should be loaded before
+%     \PrintPackage{biblatex} because otherwise \PrintPackage{biblatex} will
+%     define the \cmd{\enquote} in a way that is not compatible with
+%     \PackageName{}.
+%   \item The position of loading \PackageName{} is decoupled from the load
+%     order because interaction and loading of dependency packages is done via a
+%     hook at the end of the preamble.
+% \end{itemize}
+%
 %
 % \section{Package options}
 %
@@ -214,13 +247,16 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % Like in the previous example, the type can be
 % \enquote{CC} to cover all the \doclicenseLongType licenses.
 % Please make sure that the type is all uppercase. See the \nameref{sec:supported-licenses} section for a complete list.
+% This is a required option since v2.0.0.
 %
 % Allows to \DescribePara{modifier}
 % select different subclasses of a license. In the
 % example it is \enquote{by-sa}.
 % Please make sure that the type is all lowercase. See the \nameref{sec:supported-licenses} section for a complete list.
+% This is a required option since v2.0.0.
 %
 % As \DescribePara{version} there can be more than one version of a license, the version also needs to be set.
+% This is a required option since v2.0.0.
 %
 % This package can output some texts like the long license name.
 % \DescribePara{lang}
@@ -236,6 +272,7 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 %   \item Bulgarian
 %   \item Catalan
 %   \item Chinese: Note that you might need to pass \verb+lang={chinese-utf8}+ or \verb+chinese-gbk+.
+%   \item Croatian
 %   \item English
 %   \item French
 %   \item Galician
@@ -513,6 +550,32 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % \end{eqlist}
 % \makeatother
 %
+% \section{What license to choose for the document?}
+%
+% The list of available licenses is long (see
+% \href{https://spdx.org/licenses/}{SPDX License List}). Only a (small) subset
+% of them are a good choice for documentation. The \doclicenseLongType family
+% seem to be a common choice as contributions to this package have shown. This
+% package was translated to 15+ languages but no other license families have
+% been added yet. With that, a link to
+% \href{https://creativecommons.org/choose/}{Creative Commons: Choose a
+% License} is probably justified if you have not done that already.
+%
+% \section{REUSE Specification}
+%
+% That clarifies the question under which license you want to put the document
+% under, but in practice it might not be as easy as that.
+% Under what license are the artifacts (images/figures/tables/source code
+% listings) you are including? It would probably be useful to track such
+% metadata along with the files. For this, the \href{REUSE
+% Specification}{https://reuse.software/} can be used.
+%
+% The REUSE Specification is independed of \LaTeXe{} and more \enquote{low
+% level} than this package.
+% \PackageName{} might integrate with the REUSE Specification at a later point.
+% Refer to \url{https://github.com/ypid/latex-packages/issues/72} for
+% discussion how such an integration could look like.
+%
 % \section{Contributing}
 % \label{sec:contributing}
 % This package is being developed on GitHub: \url{\PackageURL}. When you want
@@ -532,6 +595,15 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % via Email or preferably by opening a pull request on GitHub so that I can
 % include them in the next release.
 %
+% Note that the following development conventions are used for the package:
+%
+% \begin{itemize}
+%   \item \href{https://reuse.software/spec/}{REUSE Specification 3.0}
+%   \item \href{https://www.conventionalcommits.org/en/v1.0.0/}{Conventional Commits 1.0.0}
+%   \item \href{https://semver.org/spec/v2.0.0.html}{Semantic Versioning 2.0.0}
+%   \item CI tests using GitHub Actions
+% \end{itemize}
+%
 % \section{Plaintext license text}
 % \label{sec:plain_license_text}
 %
@@ -596,7 +668,7 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
     \renewcommand{\labelenumiv}{(\roman{enumiv})}%
 }{\end{enumerate}}
 
-\ifthenelse{
+\ifthenelse{%
   \equal{\doclicense@hyphenation}{}
 }{}{%
   \RequirePackage{ragged2e}
@@ -607,35 +679,35 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
   }
 }
 \AtEndPreamble{%
-  \@ifpackageloaded{csquotes}{
+  \@ifpackageloaded{ccicons}{}{\RequirePackage{ccicons}}
+    % For \doclicenseIcon
+  \@ifpackageloaded{graphicx}{}{\RequirePackage{graphicx}}
+    % For \doclicenseImage
+  \@ifpackageloaded{hyperref}{}{\RequirePackage{hyperref}}
+  \@ifpackageloaded{csquotes}{%
     % csquotes has already been loaded so we are fine.
-  }{
-    \ifcsdef{enquote}{
+  }{%
+    \ifcsdef{enquote}{%
       % \enquote is defined but not by csquotes.
-      \@ifpackageloaded{biblatex}{
+      \@ifpackageloaded{biblatex}{%
         \PackageError{doclicense}{The enquote macro is defined by biblatex}
           {This package assumes that the enquote macro is defined by the
             csquotes package. Please load csquotes before you load biblatex so
             that biblatex does not define enquote instead.}%
-      }{
-        \PackageError{doclicense}{The enquote macro is defined by unknown package}
+      }{%
+        \PackageError{doclicense}{The enquote macro is defined by an unknown package}
           {This package assumes that the enquote macro is defined by the
             csquotes package. Please check why enquote is defined without
             csquotes being loaded. Maybe try loading csquotes early so that it
             can define the enquote macro instead.}%
       }
-    }{
+    }{%
       \RequirePackage{csquotes}
     }
   }
-  \@ifpackageloaded{ccicons}{}{\RequirePackage{ccicons}}
-    % For \doclicenseIcon
-  \@ifpackageloaded{graphicx}{}{\RequirePackage{graphicx}}
-    % For \doclicenseImage
-  \@ifpackageloaded{hyperref}{}{\RequirePackage{hyperref}}
-  \@ifpackageloaded{hyperxmp}{
+  \@ifpackageloaded{hyperxmp}{%
     % The following options are only defined when the hyperxmp package was loaded.
-    \hypersetup{
+    \hypersetup{%
       pdfcopyright  = {\doclicenseLongText},
       pdflicenseurl = {\doclicenseURL},
     }
@@ -644,17 +716,33 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 \ifdoclicense@hyperxmp
   \@ifpackageloaded{pdfx}{%
     \PackageWarning{doclicense}{%
-    The pdfx package was detected. Therefore the mechanism to add license
-    metadata won't work. Ensure to setup \string\Copyright\space and
-    corresponding settings to your xmpdata-file.
-  }
-  }{
-    \IfFileExists{hyperxmp.sty}{
-      \@ifpackageloaded{hyperxmp}{}{\RequirePackage{hyperxmp}}
-    }{
+      The pdfx package was detected. Therefore the mechanism to add license
+      metadata won't work. Ensure to setup \string\Copyright\space%
+      and corresponding settings to your xmpdata-file.
+    }
+  }{%
+    \@ifpackageloaded{silence}{%
       \PackageWarning{doclicense}{%
-        The hyperxmp package is missing so no license metadata can be embedded
-        into the PDF. Consider installing hyperxmp.% chktex 13
+        The silence package was detected. hyperxmp and silence are not% chktex 12
+        compatible with each other so doclicense will not load hyperxmp as long
+        as you load silence. Therefore the mechanism to add license metadata
+        won't work.  Consider to compile the final version of your document
+        without silence so that you can benefit from hyperxmp while still being
+        able to filter log messages for your draft versions.
+      }
+      \@ifpackageloaded{hyperxmp}{%
+        \PackageError{doclicense}{silence and hyperxmp were manually loaded together}{%
+          Error out because those packages together result in an endless loop.
+        }%
+      }{}
+    }{%
+      \IfFileExists{hyperxmp.sty}{%
+        \@ifpackageloaded{hyperxmp}{}{\RequirePackage{hyperxmp}}
+      }{%
+        \PackageWarning{doclicense}{%
+          The hyperxmp package is missing so no license metadata can be embedded
+          into the PDF. Consider installing hyperxmp.% chktex 13
+        }
       }
     }
   }
@@ -665,35 +753,30 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 % \subsection{Deprecation handling}
 %    \begin{macrocode}
 % Deprecation handling (((
-\ifthenelse{
+\ifthenelse{%
   \equal{\doclicense@type}{}
-}{
-  \PackageWarning{doclicense}{%
-    "type" package option missing. % chktex 18
+}{%
+  \PackageError{doclicense}{"type" package option missing}{% chktex 18
     This option is now required and the fallback to "CC" is deprecated. % chktex 18
     In an upcoming major version of doclicense, this will be a package error.
     Please explicitly pick a license of your choosing.
   }
-  \renewcommand{\doclicense@type}{CC}
 }{}
 
-\ifthenelse{
+\ifthenelse{%
   \equal{\doclicense@modifier}{}
-}{
-  \PackageWarning{doclicense}{%
-    "modifier" package option missing. % chktex 18
+}{%
+  \PackageError{doclicense}{"modifier" package option missing}{% chktex 18
     This option is now required and the fallback to "by-sa" is deprecated. % chktex 18
     In an upcoming major version of doclicense, this will be a package error.
     Please explicitly pick a license of your choosing.
   }
-  \renewcommand{\doclicense@modifier}{by-sa}
 }{}
 
-\ifthenelse{
+\ifthenelse{%
   \equal{\doclicense@version}{}
-}{
-  \PackageWarning{doclicense}{%
-    "version" package option missing. % chktex 18
+}{%
+  \PackageError{doclicense}{"version" package option missing}{% chktex 18
     This option is now required and the fallback is deprecated. % chktex 18
     In an upcoming major version of doclicense, this will be a package error.
     Please explicitly pick a license of your choosing.
@@ -828,9 +911,16 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
 \IfFileExists{doclicense-\doclicense@lang.ldf}{%
   \input{doclicense-\doclicense@lang.ldf}% chktex 27
 }{%
-  \PackageWarning{doclicense}{%
-    No language definition for \doclicense@lang found.
-    Please add one and submit a patch. Using English as fallback.
+  \ifthenelse{\equal{\doclicense@lang}{nil}}{%
+    \PackageWarning{doclicense}{%
+      The language of your document is not defined. Please refer to the babel or polyglossia
+      package to see how to define it. Using English as fallback.
+    }
+  }{%
+    \PackageWarning{doclicense}{%
+      No language definition for \doclicense@lang\space
+      found.  Consider adding one and submit it to doclicense. Using English as fallback.
+    }
   }
   \renewcommand{\doclicense@lang}{english}
   \input{doclicense-\doclicense@lang.ldf}% chktex 27
@@ -898,7 +988,7 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
         \renewcommand{\doclicense@imagemodifier}{-88x31}% chktex 29
       }{}
     }{}
-    \ifthenelse{\equal{\doclicense@modifier}{by-nc-sa}}{
+    \ifthenelse{\equal{\doclicense@modifier}{by-nc-sa}}{%
       \renewcommand{\doclicense@icon}{\ccbyncsa}
       \IfBeginWith{\doclicense@imagemodifier}{-eu}{%
         \renewcommand{\doclicense@icon}{\ccbyncsaeu}
@@ -908,7 +998,7 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
         \renewcommand{\doclicense@imagemodifier}{-88x31}% chktex 29
       }{}
     }{}
-    \ifthenelse{\equal{\doclicense@modifier}{by-nc-nd}}{
+    \ifthenelse{\equal{\doclicense@modifier}{by-nc-nd}}{%
       \renewcommand{\doclicense@icon}{\ccbyncnd}
       \IfBeginWith{\doclicense@imagemodifier}{-jp}{%
         \renewcommand{\doclicense@icon}{\ccbyncndjp}
@@ -924,13 +1014,13 @@ corresponds to \PackageName\nobreakspace\fileversion, dated \printdateTeX{\filed
         \doclicense@modifier/%
         \doclicense@versionUsed\doclicense@UrlLangPart}
     }{}
-    \ifthenelse{\equal{\doclicense@modifier}{pd}}{
-      \PackageError{doclicense}{CC PD license removed as of version 2.0.0}{
+    \ifthenelse{\equal{\doclicense@modifier}{pd}}{%
+      \PackageError{doclicense}{CC PD license removed as of version 2.0.0}{%
         Creative Commons PD has been replaced by CC-zero.
         Please update your license choice.
       }%
     }{}
-    \IfSubStr{\doclicense@modifier}{nc}{}{
+    \IfSubStr{\doclicense@modifier}{nc}{}{%
       % eu (Euro) does only exist for nc (non commercial) so if not nc then reset -eu.
       \IfBeginWith{\doclicense@imagemodifier}{-eu}{%
         \renewcommand{\doclicense@imagemodifier}{-88x31}% chktex 29