morehype (23oct11)

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

1 files changed, 143 insertions, 69 deletions

diff --git a/Master/texmf-dist/tex/latex/morehype/texlinks.sty b/Master/texmf-dist/tex/latex/morehype/texlinks.sty
index 9423dfef4df..ac546b89f67 100644
--- a/Master/texmf-dist/tex/latex/morehype/texlinks.sty
+++ b/Master/texmf-dist/tex/latex/morehype/texlinks.sty
@@ -1,5 +1,5 @@
 \NeedsTeXFormat{LaTeX2e}[1994/12/01] %% \newcommand* etc. 
-\ProvidesPackage{texlinks}[2011/10/10 v0.41 TeX-related links (UL)] 
+\ProvidesPackage{texlinks}[2011/10/21 v0.5 TeX-related links (UL)] 
 %% copyright (C) 2011 Uwe Lueck, 
 %% http://www.contact-ednotes.sty.de.vu 
 %% -- author-maintained in the sense of LPPL below.
@@ -15,19 +15,19 @@
 %% 
 %%   http://www.contact-ednotes.sty.de.vu 
 %%
-%% == Outline ==
+%% == Outline                               ==
 %% % Almost                             %% 2011/07/23
 %% % all the            %% including https 2011/08/27
 %% The link macros of 'texlinks' are based on macros 
 %% |\httpref| and |\httpsref|. For use of 'texlinks' with 'blog.sty', 
 %% the latter provides definitions of `\httpref' and `\httpsref'
-%% suitable for \acro{HTML}, where a choice of opening a new 
+%% suitable for \HTML, where a choice of opening a new 
 %% tab or window---or not---is relevant.
 %%
 %% For use with 'hyperref' (or ...?), 'texlinks' may 
 %% provide definitions of `\httpref' and `\httpsref' 
 %% based on `\href'. The decision to do so or not may happen at 
-%% `\begin{document}'. 'blog.sty' generates \acro{HTML} without 
+%% `\begin{document}'. 'blog.sty' generates \HTML\ without 
 %% using the `{document}' environment, so we might assume 
 %% that when `\begin{document}' is found, we are running
 %% 'hyperref', or just \emph{something} that provides a 
@@ -36,12 +36,12 @@
 %% 
 %% Moreover, a \acro{PDF} file with links may be \emph{printed}, 
 %% and klicking the links on the paper may fail. 
-%% \acro{URL}s in main text, on the other hand, sometimes are 
+%% \URL s in main text, on the other hand, sometimes are 
 %% troublesome. I consider it a good idea to present 
-%% links with their \acro{URL} as the displayed text in \emph{footnotes}
-%% (or endnotes). It may even be useful with \acro{HTML} to present 
-%% the \acro{URL}s displayed in some 
-%% 2011/01/27:
+%% links with their \URL\ as the displayed text in \emph{footnotes}
+%% (or endnotes). It may even be useful with \HTML\ to present 
+%% the \URL s displayed in some 
+%% %% 2011/01/27:               %% rm. 2011/10/20
 %% ``appendix."---This idea has been resumed in v0.2 only, 
 %% |\urlfoot|.
 %% %
@@ -49,7 +49,7 @@
 %% % package option forcing `\httpref' to use this style. 
 %% % Well, better \emph{not today} ... [2011/01/24, TODO]
 %%
-%% == Package Options       ==
+%% == Package Options                       ==
 %% Somebody may want to suppress a definition of `\httpref'
 %% at `\begin{document}' ... [2011/01/24, TODO]
 %% %% 2011/02/10:
@@ -61,7 +61,49 @@
 %% useful for different purposes than running 'blog.sty'.
 \ProcessOptions
 %%
-%%    \pagebreak 
+%% == Fonts for \URL s and File/Package Names ==
+%% %% ** Fonts for \URL s, File Names, and Package Names **
+%% %% new 2011/10/19, TODO: `meansltx'? vgl. `makedoc.cfg'
+%% This section ``provides" markup for displaying \URL s (|\urlfmt|), 
+%% file names (|\filenamefmt|---thinking of single files 
+%% that may be found in the internet or on your computer---, 
+%% and ``packages" (|\pkgnamefmt|). 
+%% For the latter two, in certain files I use shorthands 
+%% |\file| and |\pkg|, resp., ... 
+%% (Not sure about `\providecommand' TODO ...)
+%% %% TODO "fallback" with 'provlast'
+%% 
+%% It is usual to use `\texttt' for formatting \TeX\ code 
+%% (``verbatim", `\verb' etc.). It may also be common to use 
+%% `\texttt' for file names, perhaps even for \URL s. 
+%% Therefore we provide |\urlfmt{<url>}| as follows: 
+\providecommand*{\urlfmt}{\texttt}
+%% The file name format |\filenamefmt{<file-name>}|
+%% may differ from the format for \URL s---if somebody 
+%% wants/adjusts it, \emph{here} it is the \emph{same:}
+\providecommand*{\filenamefmt}{\texttt}
+%% ... 
+%% I favour `\code' over `\texttt' as ``logical markup," 
+%% inspired by the \xmltagcode{code} element in \HTML, 
+%% but it is too difficult to provide this right now here ...
+%% 
+%% %% Instead of |\pkgnamefmt{<pack-name>}|, 
+%% %% 'blog.sty' had `\pkg{<pack-name>}',      %% was `prg' 2011/10/20
+%% %% without a proper implementation. 
+%% |\pkgnamefmt{<package-name>}| displays the name of a ``package". 
+%% Using `\textsf' for `\pkgnamefmt' 
+%% seems to conform to common practice today---implemented here. 
+%% The following code may later be suppressed at some package options, 
+%% as with the choice for `\httpref':   %% TODO 2011/01/24
+% \@ifdefinable\pkgnamefmt {\let\pkgnamefmt\@firstofone}
+% \AtBeginDocument         {\let\pkgnamefmt\textsf}
+%% <- This was here until v0.61, makes a difference for \acro{PDF}
+%% vs.\ 'blog' \HTML. Now we choose the same as with `\urlfmt':
+\providecommand*{\pkgnamefmt}{\textsf}
+%% Indeed, the same day we are providing `\textsf' in 'blog.sty'.
+%% However, the rationale of the earlier solution was 
+%% that web pages use sans-serif as the \emph{normal} font ...
+%%
 %% %% moving \httpsref 2011/08/27:
 %% == Providing &\httpref\ and   &\httpsref ==
 %%                             %% rm. \kern-\baselineskip 2011/10/10
@@ -69,7 +111,7 @@
 %% should display <text> 
 %% as a link to `http://<host-path[#frag]>'; 
 %% \[|\httpsref{<host-path[#frag]>}{<text>}|\]
-%% is the obvious analogue for `https:' \acro{URL}s. 
+%% is the obvious analogue for `https:' \URL s. 
 %% In case `\begin{document}' is found with a definition of 
 %% `\href' present, we provide definitions of `\httpref'
 %% and `\httpsref' in terms of `\href' there:
@@ -86,14 +128,21 @@
 \AtBeginDocument{%% TODO: options, guarded \let (mine, HO)
     \@ifdefinable\NormalHTTPref{\let\NormalHTTPref\httpref}} 
 %% |\ithttpref{<url>}{<text>}| displays <text> in italics:
-\newcommand*{\ithttpref}[2]{\NormalHTTPref{#1}{\textit{#2}}}
-%% === \acro{URL}s as Links ===
-%% With |\urlhttpref{<url>}|, that \acro{URL} <url> is displayed:
+% \newcommand*{\ithttpref}[2]{\NormalHTTPref{#1}{\textit{#2}}}
+%% However, I seem never to have used it. And I would now 
+%% prefer |\metahttpref| TODO ...
+%%
+%% === \URL s as Links ===
+%% With |\urlhttpref{<url>}|, that \URL\ <url> is displayed:
 \newcommand*{\urlhttpref}[1]{%
     \NormalHTTPref{#1}{\urlfmt{\httpprefix#1}}} 
+%% %% moved up here 2011/10/20
+%% In 'blog.sty' (as of 2010/05/26), there was a command 
+%% `\urlref' instead of `\urlhttpref'. It did not provide `\urlfmt'.
+%%
 %% |\httpprefix| is an idea that was missing in 'blog.sty' up to v0.3. 
 %% It may be used to determine generally whether a display of an 
-%% \acro{URL} should include `http://'. I choose as default what was default 
+%% \URL\ should include `http://'. I choose as default what was default 
 %% in 'blog.sty' 
 %% (i.e., ``don't include"):                        %% add. 2011/01/27
 \@ifdefinable\httpprefix{\let\httpprefix\@empty}    %% TODO cf. above
@@ -106,30 +155,24 @@
 %% %% v0.2:
 %% ---or by `\let\httpprefix'|\theHTTPprefix|:
 \newcommand*{\theHTTPprefix}{http://}
-%% |\urlfmt{<url>}| is chosen as `\texttt' here and may be 
-%% customized, e.g., with the 'breakurl' package.
-\@ifdefinable\urlfmt{\let\urlfmt\texttt}
-%% In 'blog.sty' (as of 2010/05/26), there was a command 
-%% `\urlref' instead of `\urlhttpref'. It did not provide `\urlfmt'.
-%%
 %% With |\urlhttpsref{<url>}|, we \emph{force} displaying \qtd{`https://'}:
 \newcommand*{\urlhttpsref}[1]{\httpsref{#1}{\urlfmt{https://#1}}}
 %%
-%% === Linking \acro{URL}s in Footnotes ===     %% 2011/08/27
+%% === Linking \URL s in Footnotes ===     %% 2011/08/27
 %% \label{sec:urlfoot}
 %% |\foothttpurlref{<url>}| just is like
 %% `\footnote{\urlhttpref{<url>}}':
 \newcommand*{\foothttpurlref}[1]{\footnote{\urlhttpref{#1}}}
 %% |\urlfoot{<short>}{<id>}|
 %% redefines `\httpref' so that you can use all the shorthand 
-%% macros based on `\httpref' to get the according \acro{URL} 
+%% macros based on `\httpref' to get the according \URL\ 
 %% display (as provided by `\urlhttpref')
 %% in a footnote without the need to include the 
-%% entire \acro{URL} in your source code. `\urlfoot' is available 
+%% entire \URL\ in your source code. `\urlfoot' is available 
 %% with <short> and <id>
 %% when a shorthand |\<short>{<id>}{<text>}| has been defined
 %% where `\<short>' is the macro name and <id> is the target 
-%% identifier (usually part of the \acro{URL} generated from <id>)
+%% identifier (usually part of the \URL\ generated from <id>)
 %% according to the syntax declaration of `\<short>'. 
 \newcommand*{\urlfoot}[2]{{%
     \let\httpref\foothttpurlref 
@@ -220,7 +263,8 @@
 \newcommand*{\Wikidedisambref}{\Wikidisambref{de}}
 \newcommand*{\Wikiendisambref}{\Wikidisambref{en}}
 %% 
-%% === Blanks and Umlauts in \acro{URL}s and Anchors ===
+%%                                  \pagebreak  %% 2011/10/21
+%% === Blanks and Umlauts in \URL s and Anchors ===
 %% %% <- renamed 2011/05/17 reworked:
 %% |\underscorechar| seemed to be useful in macro 
 %% definitions. The name was inspired by \LaTeX's 
@@ -277,17 +321,10 @@
 % \@namedef{urluml:u}{\#C3\#BC}
 % \@namedef{urluml:s}{\#C3\#9F}           %% 2010/08/09
 %% 
-%% == \TeX-related ==                                   %% 2010/08/24
-%% === \acro{CTAN}               ===
-%% |\bytopicref{<anchor>}{<text>}| 
-%% makes <text> a link to <anchor> of J\"urgen Fenn's 
-%% Topical Index of the \TeX\ Catalogue. You find the <anchor> 
-%% by clicking at the respective TOC entry on top of the page 
-%% and then read the \acro{URL} from the browser's navigation display.
-\newcommand*{\bytopicref}[1]{% 
-    \httpref{mirror.ctan.org/help/Catalogue/bytopic.html\##1}}
-%% (Example:\quad `\bytopicref{html}{\acro{HTML}}' \ for \ \bytopicref{html}{\acro{HTML}}.)
-%%
+%%                                  \pagebreak  %% 2011/10/21
+%% == \TeX-related ==                           %% 2010/08/24
+%% === \CTAN                ===
+%% ==== Directories and Files in a \TeX\ Archive ====
 %% % `\newcommand*{\ctanref}[1]{\httpref{ctan.org/#1}}' 
 %% % once was replaced in 'blog.sty' by what will now be 
 %% |\tugctanref{<path>}{<text>}|
@@ -296,27 +333,64 @@
 \newcommand*{\tugctanref}[1]{% 
   \httpref{tug.ctan.org/tex-archive/#1}} 
 %% Alternatively, you can refer to an (automatically chosen) 
-%% \acro{CTAN} \emph{mirror}
+%% \CTAN\ \emph{mirror}
 %% using 
-%% \[|\mirrorctanref{<path>}{<text>}|:\]            %% 2011/10/10
+%% \[|\mirrorctanref{<path>}{<text>}|.\] %% 2011/10/10 :->.2011/10/21: 
+%% (I prefer the \emph{appearance} of the 
+%% \tugctanref{}{\acro{TUG} archive}, designed by Jim Hefferon.)
 \newcommand*{\mirrorctanref}[1]{\httpref{mirror.ctan.org/#1}} 
 %% You may actually want to ``open" a file <file-name> in <path> 
-%% on \acro{CTAN}, either by 
+%% on \CTAN, 
+%% <file-name> displayed as the link text,          %% 2011/10/21
+%% either by 
 %% \[|\tugctanfileref{<path>}{<file-name>}|\]       %% 2011/10/10
 %% or (for a mirror) by
 %% \[|\mirrorctanfileref{<path>}{<file-name>}|.\]   %% 2011/10/10
-%% The file name format |\file{<file-name>}|
-%% that is used in the definitions must be provided 
-%% elsewhere.       %% 2011/10/06; TODO provlast
 \newcommand*{\tugctanfileref}[2]{%
-    \tugctanref{#1/#2}{\file{#2}}}
+    \tugctanref{#1/#2}{\filenamefmt{#2}}}
 \newcommand*{\mirrorctanfileref}[2]{%
-    \mirrorctanref{#1/#2}{\file{#2}}}
-%% Typically, \LaTeX\ macro packages in \file{macros/latex/contrib/}
+    \mirrorctanref{#1/#2}{\filenamefmt{#2}}}
+%% Typically, \LaTeX\ macro packages in `macros/latex/contrib/'
 %% are discussed, so here is |\ltxcontrib| saving a few characters:
 \newcommand*{\ltxcontrib}{macros/latex/contrib/}
+%% |\ctanref| works like `\tugctanref' or like `\mirrorctanref', 
+%% depending on |\usetugctan| vs.\ |\usemirrorctan|.
+%% So in any case its syntax is \[|\ctanref{<path>}{<text>}|.\]
+%% Likewise, |\ctanfileref| works like 
+%% \[`\tugctanfileref'\quad \mbox{or}\quad `\mirrorctanfileref',\]
+%% depending on the same `\usetugctan' vs.\ `\usemirrorctan', 
+%% so the syntax is 
+%% \[|\ctanfileref{<path>}{<file-name>}|\] 
+\newcommand*{\ctanref}{}    \newcommand*{\ctanfileref}{}
+\newcommand*{\usemirrorctan}{%
+    \let \ctanref     \mirrorctanref
+    \let \ctanfileref \mirrorctanfileref}
+\newcommand*{\usetugctan}{%
+    \let \ctanref     \tugctanref
+    \let \ctanfileref \tugctanfileref}
+%% |\usemirrorctan| is the \strong{default}, i.e., 
+%% |\ctanref| and |\ctanfileref| use 
+%% \urlhttpref{mirror.ctan.org}:
+\usemirrorctan
+%% \meta{Remark} (TODO): \ Another implementation I consider is 
+%% using some `\ctanurl'\-`prefix' that you can redefine for 
+%% accessing your favourite mirror.
+%%
+%% ==== J\"urgen Fenn's Topical \TeX\ Catalogue  ====
+%% |\bytopicref{<anchor>}{<text>}| 
+%% \                                                %% 2011/10/21
+%% makes <text> a link to <anchor> of J\"urgen Fenn's 
+%% Topical Index of the \TeX\ Catalogue. You find the <anchor> 
+%% by clicking at the respective \acro{TOC} entry on top of the page 
+%% and then read the \URL\ from the browser's navigation display.
+\newcommand*{\bytopicref}[1]{% 
+    \httpref{mirror.ctan.org/help/Catalogue/bytopic.html\##1}}
+%% (Example:\quad `\bytopicref{html}{\acro{HTML}}' \ for \ 
+%%  \bytopicref{html}{\acro{HTML}}.)
+%%
+%% ==== Jim Hefferon's Package Descriptions      ====
 %% |\ctanpkgref{<pkg-name>}|
-%% makes <text> a link to the \acro{CTAN} package info page for 
+%% makes <text> a link to the \CTAN\ package info page for 
 %% the package <pkg-name>. 
 %% |\CtanPkgRef{<name>}{<Name>}|
 %% is a variant for the cases where authors have a special idea
@@ -327,25 +401,18 @@
 %% Also, <Name> may be a package from a \emph{bundle} <name> 
 %% where <name> has a description page while <Name> 
 %% doesn't have its \emph{own} description page 
-%% (such as \CtanPkgRef{nicetext}{fifinddo}).
+%% (such as \CtanPkgRef{nicetext}{makedoc}).
+%% %% <- was `fifinddo' 2011/10/20, no with own id.
 \newcommand*{\CtanPkgRef}[2]{%
     \httpref{ctan.org/pkg/#1}{\pkgnamefmt{#2}}}
 \newcommand*{\ctanpkgref}[1]{\CtanPkgRef{#1}{#1}}
-%% Instead of |\pkgnamefmt{<pack-name>}|, 
-%% 'blog.sty' had `\prg{<pack-name>}', without a proper 
-%% implementation. For typesetting, choosing `\pkgnamefmt' 
-%% as `\textsf' seems to conform to common practice today. 
-%% The following code may later be suppressed at some package options, 
-%% as with the choice for `\httpref':   %% TODO 2011/01/24
-\@ifdefinable\pkgnamefmt {\let\pkgnamefmt\@firstofone}
-\AtBeginDocument         {\let\pkgnamefmt\textsf}
 %%
-%% === \acro{CTAN} Announcements ===                    %% 2011/06/27
+%% === \CTAN\ Announcements ===                 %% 2011/06/27
 %% |\ctanannref{<id>}{<text>}| makes <text> a link 
-%% to the DANTE web page displaying a \acro{CTAN} 
+%% to the DANTE web page displaying a \CTAN\ 
 %% announcement. You find <id> by searching 
 %% \[\texttt{https://lists.dante.de/pipermail/ctan-ann/}\]
-%% and then reading the \acro{URL}.
+%% and then reading the \URL.
 %% <id> is composed as `<year>-<month>/<6-digits>.html'.
 \newcommand*{\ctanannref}[1]{%
     \httpsref{lists.dante.de/pipermail/ctan-ann/#1}}
@@ -355,7 +422,7 @@
 %% year, then a `-', then the (arabic) number of 
 %% the month, then another `-', and then the actual 
 %% internal identifier 
-%% (a number of six digits preceding `.html' of the \acro{URL}). 
+%% (a number of six digits preceding `.html' of the \URL). 
 \newcommand*{\ctanannpref}[1]{%
     \ctanannref{\TL@piper@parse#1/.html}}
 \def\TL@piper@parse#1-#2-#3/{%
@@ -367,7 +434,7 @@
     \fi
     /#3}
 %%
-%% === \acro{TUG}                ===
+%% === \acro{TUG}           ===
 %% |\tugref{<path>}{<text>}| makes <text> a link
 %% to <path> on domain `tug.org':
 \newcommand*{\tugref}[1]{\httpref{tug.org/#1}}
@@ -375,7 +442,7 @@
 %% |\texhaxref{<id>}{<text>}| makes <text> a link 
 %% to the \acro{TUG} web page displaying 
 %% a texhax posting. You find <id> by searching 
-%% `tug.org/pipermail/texhax/' and then reading the \acro{URL}.
+%% `tug.org/pipermail/texhax/' and then reading the \URL.
 %% <id> is composed as `<year>-<month>/<6-digits>.html'.
 \newcommand*{\texhaxref}[1]{\tugref{pipermail/texhax/#1}}
 %% |\THref{<id>}| saves you from choosing <text> 
@@ -390,9 +457,9 @@
 %% year, then a `-', then the (arabic) number of 
 %% the month, then another `-', and then the actual 
 %% internal identifier 
-%% (a number of six digits preceding `.html' of the \acro{URL}). 
+%% (a number of six digits preceding `.html' of the \URL). 
 %% I made this macro because I prefer typing to copying 
-%% from the \acro{URL}. 
+%% from the \URL. 
 \newcommand*{\texhaxpref}[1]{%              %% 2010/09/07
     \texhaxref{20\TL@piper@parse#1/.html}}  %% 2011/05/03
 %% TODO: `\texhaxPref#1' searches list of offsets 
@@ -411,22 +478,22 @@
 %% (e.g., \TUGIref{web}{\qtd{Web Projects}}):
 \newcommand*{\TUGIref}[1]{\tugref{interest.html\##1}}
 %%
-%% === \acro{UK FAQ}             ===
+%% === \acro{UK FAQ}        ===
 %% |\ukfaqref{<label>}{<text>}| makes <text> a link to 
 %% the UK~\TeX~FAQ page with ``label"~= <label>:
 \newcommand*{\ukfaqref}[1]{\httpref{%
     www.tex.ac.uk/cgi-bin/texfaq2html?label=#1}}
-%% === Wikibooks                 ===
+%% === Wikibooks            ===
 %% |\wikibooks{<language-code>}{<file>}{<text>}|:
 \newcommand*{\wikibooksref}[2]{\httpref{#1.wikibooks.org/wiki/#2}}
-%% |\wikibooks{<file>}{<subject>}{<text>}| refers to the 
+%% |\latexwikibookref{<file>}{<subject>}{<text>}| refers to the 
 %% (English) \LaTeX\ Wikibook:
 \newcommand*{\latexwikibookref}[1]{\wikibooksref{en}{LaTeX/#1}}
 %% The German 
 %% \wikibooksref{de}{LaTeX-Kompendium}{\dqtd{\LaTeX-Kompendium}}
 %% is somewhat difficult, I leave it for now~...
 %%
-%% == Leaving      ==               %% 2011/01/24
+%% == Leaving      ==                           %% 2011/01/24
 \endinput
 %%
 %% == VERSION HISTORY ==
@@ -451,3 +518,10 @@ v0.41   2011/09/03  doc.: more specific on \urluml/Wikipedia
         2011/10/06  \mirrorctanref, \tugctanfileref, 
                     \mirrorctanfileref, \ltxcontrib
         2011/10/10  doc. formatting of previous
+uploaded with MOREHYPE r0.5(1)
+v0.5    2011/10/19  doc. fix LaTeX Wikibook
+        2011/10/20  \urlfmt, \filenamefmt and \pkgnamefmt
+                    changed and moved, modified doc. on them, 
+                    doc. uses \URL
+        2011/10/21  re-order CTAN, \pagebreak's, \ctanref and 
+                    choice for it, doc. modified; rm. \ithttpref