Improve doc and backward compatibility

src/Makefile

@@ -84,6 +84,10 @@ latex-make_MAIN=latex-make.dtx
 figlatex_MAIN=figlatex.dtx
 texdepends_MAIN=texdepends.dtx
 
+# use local files by default
+export TEXINPUTS:=.$(addprefix :,$(TEXINPUTS))::
+export TEXMFSCRIPTS:=.$(addprefix :,$(TEXMFSCRIPTS))::
+
 #LATEX=latex -v
 
 # Force using local LaTeX.mk and not system-wide LaTeX.mk if already installed

src/latex-make.dtx

@@ -2,7 +2,7 @@
 %
 %<*dtx>
           \ProvidesFile{latex-make.dtx}
-[2018/09/04 v2.2.5 fix output format of figdepth.py]
+[2018/10/17 v2.3.0 handle TDS for local install]
 %</dtx>
 %    \fi
 % \iffalse
@@ -30,7 +30,7 @@
 \g@addto@macro{\IndexParms}{\hbadness=10000}
 \g@addto@macro{\GlossaryParms}{\hbadness=10000}
 \makeatother
-\newenvironment{source}[1][.8\linewidth]{%
+\newenvironment{source}[1][.9\linewidth]{%
   \begin{center}%
     \begin{boxedminipage}[c]{#1}\tt%
       \vspace{1em}%
@@ -101,7 +101,7 @@
 % documents with the help of a Makefile. Dependencies are
 % automatically tracked with the help of the |texdepends.sty| package.
 % \end{abstract}
-% \CheckSum{332}
+% \CheckSum{344}
 %
 % \changes{v2.0.0}{2006/03/09}{First autocommented version}
 % \changes{v2.1.0}{2008/01/28}{That's the question}
@@ -113,6 +113,8 @@
 % \changes{v2.2.3}{2017/01/08}{Add LuaLaTeX support}
 % \changes{v2.2.4}{2018/05/29}{Fix directory permissions on install}
 % \changes{v2.2.5}{2018/09/04}{fix output format of figdepth.py}
+% \changes{v2.3.0}{2018/10/17}{Add DEPENDS-EXCLUDE, add doc and
+% support for local texmf tree}
 %
 % \makeatletter
 % \def\SpecialOptionIndex#1{\@bsphack
@@ -222,17 +224,65 @@
 % If you work with other people that do not have installed (and do not
 % want to install) \LaTeX-Make, you can use the
 % |LaTeX-Make-local-install| target in |LaTeX.mk| to install required
-% files locally in the current directory. You can them commit these
-% files into your control version system so all co-authors will be
-% able to use \LaTeX-Make without installing it.
-% However, note that:
+% files in a local TEXMF tree. You can them commit this
+% tree into your control version system. Then, in your |Makefile|,
+% replace the single line\par
+% \begin{source}
+%     include LaTeX.mk
+% \end{source}
+% with something like\par
+% \begin{source}\small
+%     export TEXMFHOME:=\$(CURDIR)/relpath/to/local/tree/texmf\\
+%     include \$(shell env TEXMFHOME=\$(TEXMFHOME) $\backslash$\\
+%     \hspace*{12ex}kpsewhich -format texmfscripts LaTeX.mk)
+% \end{source}
+% If you have a previous value for |TEXMFHOME| that you do not want to
+% override, you can use the following (more complexe) snipset\par
+% \begin{source}\small
+%     \# Adapt the following line to find the local texmf tree\\
+%     LOCAL\_TEXMF:=\$(CURDIR)/\$(firstword \$(wildcard texmf $\backslash$\\
+%     \hspace*{16ex}../texmf ../../texmf ../../../texmf))\\
+%     \# Get the old TEXMFHOME value\\
+%     TEXMFHOME:=\$(shell kpsewhich -var-value TEXMFHOME)\\
+%     \# If the new tree is already in it, do nothing, else add it\\
+%     ifeq (\$(filter \$(LOCAL\_TEXMF)//%,\$(TEXMFHOME)),)\\
+%     TEXMFHOME := \$(LOCAL\_TEXMF)\$(addprefix :,\$(TEXMFHOME))\\
+%     \# display info so that users know what to define in order to\\
+%     \# compile documents directly with (pdf)latex\\
+%     \$(warning export TEXMFHOME=\$(TEXMFHOME))\\
+%     export TEXMFHOME\\
+%     endif\\
+%     ~\\
+%     include \$(shell env TEXMFHOME=\$(TEXMFHOME) $\backslash$\\
+%     \hspace*{12ex}kpsewhich -format texmfscripts LaTeX.mk)
+% \end{source}
+% Doing so, all co-authors will be able to use \LaTeX-Make without
+% installing it.  However, note that:
 % \begin{itemize}
 % \item you wont beneficit of an update of \LaTeX-Make in your system
-%   (you will continue to use the locally installed files)
+%   (you will continue to use the locally installed files) ;
 % \item there is no support for upgrading locally installed files (but
 %   reexecuting the installation should do a correct upgrade most of
-%   the time)
+%   the time) ;
+% \item  if a user tries to compile the \LaTeX{} source code directly
+% with |[pdf]latex|, he must before either have LaTeX-Make installed
+% or define and export |TEXMFHOME|.
 % \end{itemize}
+%
+% Another possibility is to install package files (|*.sty|) into a
+% directory pointed by |TEXINPUTS|, scripts files (|*.py|) into a
+% directory pointed bt |TEXMFSCRIPTS|, and to directly include
+% |LaTeX.mk|. For example:
+% \begin{source}\small
+%     \# use local files by default\\
+%     \# packages in sty/ subdir and scripts in bin/\\
+%     TEXINPUTS:=sty\$(addprefix :,\$(TEXINPUTS))::\\
+%     TEXMFSCRIPTS:=bin\$(addprefix :,\$(TEXMFSCRIPTS))::\\
+%     export TEXINPUTS\\
+%     export TEXMFSCRIPTS\\
+%     \# Force using local LaTeX.mk and not system-wide LaTeX.mk if available\\
+%     include \$(CURDIR)/LaTeX.mk
+% \end{source}
 % \subsection{Customization}
 % Of course, lots of things can be customized. Here are the most
 % useful ones. Look at the section \ref{sec:reference} for more detailed
@@ -1122,19 +1172,36 @@ $(eval $(call lu-setvar-global,FIG2DEV,fig2dev))
 $(eval $(call lu-setvar-global,EPSTOPDF,epstopdf))
 $(eval $(call lu-setvar-global,MAKEINDEX,makeindex))
 
-# Look for local version, then texmfscript, then in PATH of our program
+# workaround the fact that $(shell ...) ignore locally exported variables
+# get only the variables with plain names
+_LU_MAKE_ENV := $(shell echo '$(.VARIABLES)' | awk -v RS=' ' '/^[a-zA-Z0-9]+$$/')
+_LU_SHELL_EXPORT := $(foreach v,$(_LU_MAKE_ENV),$(v)='$($(v))')
+_lu_run_kpsewhich=$(shell $(_LU_SHELL_EXPORT) kpsewhich -format $1 $2)
+
+# Look first into the TDS (texmfscripts), then in PATH for our program
 # At each location, we prefer with suffix than without
 define _lu_which # VARNAME progname
  ifeq ($(origin _LU_$(1)_DEFAULT), undefined)
  _LU_$(1)_DEFAULT := $$(firstword $$(wildcard \
-        $$(addprefix bin/,$(2) $$(basename $(2))) \
-        $$(addprefix ./,$(2) $$(basename $(2))) \
-	$$(shell kpsewhich -format texmfscripts $(2)) \
-	$$(shell kpsewhich -format texmfscripts $$(basename $(2))) \
+	$$(call _lu_run_kpsewhich,texmfscripts,$(2)) \
+	$$(call _lu_run_kpsewhich,texmfscripts,$$(basename $(2))) \
 	$$(foreach dir,$$(subst :, ,$$(PATH)), \
 		$$(dir)/$(2) $$(dir)/$$(basename $(2))) \
 	) $(2))
  export _LU_$(1)_DEFAULT
+ _LU_$(1)_DEFAULT_OLD := $$(firstword $$(wildcard \
+     $$(addprefix bin/,$(2) $$(basename $(2))) \
+     $$(addprefix ./,$(2) $$(basename $(2)))))
+ $$(if $$(filter-out $$(_LU_$(1)_DEFAULT), $$(_LU_$(1)_DEFAULT_OLD)),\
+   $$(if $$(_lu_scripts_warnings),, \
+     $$(eval _lu_scripts_warnings:=done) \
+     $$(warning By default, this version of LaTeX-Make do not use \
+     scripts in $$(dir $$(_LU_$(1)_DEFAULT_OLD)) anymore.) \
+     $$(warning For example $$(_LU_$(1)_DEFAULT) is used instead of $$(_LU_$(1)_DEFAULT_OLD))\
+     $$(warning If you want to keep the old behavior, add into your \
+     Makefile something like:)\
+     $$(warning export TEXMFSCRIPTS:=$$(dir $$(_LU_$(1)_DEFAULT_OLD))$$$$(addprefix :,$$$$(TEXMFSCRIPTS))::)))
+ #$$(warning _LU_$(1)_DEFAULT=$$(_LU_$(1)_DEFAULT))
  endif
  $$(eval $$(call lu-setvar-global,$(1),$$(_LU_$(1)_DEFAULT)))
 endef