diff options
Diffstat (limited to 'Master')
| -rw-r--r-- | Master/texmf-dist/doc/latex/morehype/RELEASEs.txt | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/morehype/SrcFILEs.txt | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/morehype/texlinks.pdf | bin | 733232 -> 667494 bytes | |||
| -rw-r--r-- | Master/texmf-dist/source/latex/morehype/texlinks.tex | 61 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/morehype/morehype.RLS | 1 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/morehype/texlinks.sty | 1162 |
6 files changed, 743 insertions, 509 deletions
diff --git a/Master/texmf-dist/doc/latex/morehype/RELEASEs.txt b/Master/texmf-dist/doc/latex/morehype/RELEASEs.txt index e18a04b3c7d..7ae25c74757 100644 --- a/Master/texmf-dist/doc/latex/morehype/RELEASEs.txt +++ b/Master/texmf-dist/doc/latex/morehype/RELEASEs.txt @@ -2,6 +2,20 @@ BUNDLE `morehype' RELEASES: ============================================================ +r0.83 2015/11/09 texlinks v0.83 CTANology +------------------------------------------------------------ + +TEXLINKS (generating links to TeX-related websites) v0.83 + + * offers choices among certain kinds of CTAN sites + (w.r.t. design) + + * updates Google Search links + +(not a bundle snapshot, just what I need for documenting + other packages.) + +============================================================ r0.82 2013/01/22 texlinks v0.82 improves access to CTAN ------------------------------------------------------------ diff --git a/Master/texmf-dist/doc/latex/morehype/SrcFILEs.txt b/Master/texmf-dist/doc/latex/morehype/SrcFILEs.txt index 25b4fa8dbd8..e0411d41290 100644 --- a/Master/texmf-dist/doc/latex/morehype/SrcFILEs.txt +++ b/Master/texmf-dist/doc/latex/morehype/SrcFILEs.txt @@ -1,7 +1,7 @@ *File List* -RELEASE.--- -- -- -- -- ---- -morehype.RLS 2013/01/22 r0.82 texlinks v0.82 Jim? new! dir/open +morehype.RLS 2015/11/09 r0.83 texlinks v0.83 CTANology -----USE.--- -- -- -- -- ---- blog.sty 2013/01/21 v0.81a simple fast HTML (UL) blogdot.sty 2013/01/22 v0.41b HTML presentations (UL) @@ -11,16 +11,16 @@ blogligs.sty 2012/11/29 v0.2 pervasive blog ligatures (UL) hypertoc.sty 2011/01/23 v0.1 pretty TOC links (UL) lnavicol.sty 2011/10/13 -- left navigation column with blog.sty markblog.sty 2012/11/29 v0.2 wiki markup with blog.sty (UL) -texlinks.sty 2013/01/22 v0.82 TeX-related links (UL) +texlinks.sty 2015/07/20 v0.83 TeX-related links (UL) atari_ht.fdf 2012/10/05 -- Atari umlauts for blog.sty texblog.fdf 2013/01/19 -- extra blog settings -----DOC.SRC -- -- -- -- ---- - blog.tex 2013/01/04 -- documenting blog.sty -blogexec.tex 2012/12/20 -- documenting blogexec.sty + blog.tex 2015/05/11 -- documenting blog.sty +blogexec.tex 2014/04/09 -- documenting blogexec.sty hellowor.tex 2012/11/30 -- hello world source hypertoc.tex 2011/01/27 -- documenting hypertoc.sty markblog.tex 2012/11/29 -- extended blog markup -texlinks.tex 2013/01/21 -- documenting texlinks.sty +texlinks.tex 2015/05/24 -- documenting texlinks.sty wiki_mwe.tex 2012/12/20 -- texlinks wiki MWE -----DOC.FMT -- -- -- -- ---- README.tex 2012/03/18 -- make README.pdf @@ -31,10 +31,10 @@ NICETEXT.--- -- -- -- -- ---- fifinddo.sty 2012/11/17 v0.61 filtering TeX(t) files by TeX (UL) makedoc.sty 2012/08/28 v0.52 TeX input from *.sty (UL) niceverb.sty 2012/11/27 v0.51 minimize doc markup (UL) - makedoc.cfg 2012/11/30 -- documentation settings + makedoc.cfg 2014/08/01 -- documentation settings mdoccorr.cfg 2012/11/13 -- `makedoc' local typographical corrections *********** - List made at 2013/01/22, 22:46 + List made at 2015/11/09, 10:50 from script file srcfiles.tex diff --git a/Master/texmf-dist/doc/latex/morehype/texlinks.pdf b/Master/texmf-dist/doc/latex/morehype/texlinks.pdf Binary files differindex 46bb6895093..b835af12d2b 100644 --- a/Master/texmf-dist/doc/latex/morehype/texlinks.pdf +++ b/Master/texmf-dist/doc/latex/morehype/texlinks.pdf diff --git a/Master/texmf-dist/source/latex/morehype/texlinks.tex b/Master/texmf-dist/source/latex/morehype/texlinks.tex index 01d3e5dbf54..4c81991f9c9 100644 --- a/Master/texmf-dist/source/latex/morehype/texlinks.tex +++ b/Master/texmf-dist/source/latex/morehype/texlinks.tex @@ -1,4 +1,4 @@ -\ProvidesFile{texlinks.tex}[2013/01/21 documenting texlinks.sty] +\ProvidesFile{texlinks.tex}[2015/05/24 documenting texlinks.sty] \title{{\Huge\textsf{texlinks.sty}}\\---\\\TeX-Related Links for \textsf{hyperref}, \textsf{blog.sty}\\ (and maybe more)\thanks{This @@ -8,11 +8,14 @@ % \listfiles { \RequirePackage{makedoc} \ProcessLineMessage{} % %% 2011/01/24: + \MakeJobDoc{17}% %% 2011/01/24 + {\SectionLevelThreeParseInput} % \renewcommand*{\mdSectionLevelOne}{\string\subsection} % \renewcommand*{\mdSectionLevelTwo}{\string\subsubsection} -% \renewcommand*{\mdSectionLevelThree}{\string\paragraph} - \MakeJobDoc{17}% %% 2011/01/24 - {\SectionLevelThreeParseInput} } +% % \renewcommand*{\mdSectionLevelThree}{\string\paragraph} +% \HeaderLines{2} +% \MakeSingleDoc{wikimed.sty} +} \documentclass[fleqn]{article} %% TODO paper dimensions!? \input{makedoc.cfg} %% shared formatting settings \newcommand*{\xmltagcode}[1]{\texttt{<#1>}} @@ -40,25 +43,50 @@ \fbox{\def~{\string~}%% TODO etc. \strut\CmdSyntaxVerb#1}} \newcommand*{\simplecodeoutfbox}[1]{% - \fbox{\MakeActiveLet\&\empty \strut #1}} -%% <- TODO 2012/12/30 \href mod.s & + \fbox{\MakeActiveLetHere\&\empty \strut %% 2015/05/21: +% \pdfstringdefDisableCommands{\MakeActiveLetHere\&\PDFempty}% + \let\nvCSV\empty + #1}} +% \newcommand*{\PDFempty}{\134} +\newlet\nvCSV\CmdSyntaxVerb \newenvironment*{simpleexamples}{% \fboxrule=0pt - \def\simpleexample##1{\hskip-\fboxsep - \simplecodefbox{##1}\endcell - \simplecodeoutfbox{##1}\cr\hline}% + \let\simpleexample\innersimpleexample %% 2015/05/21 %% <- TODO by Plain TeX -> \center\strong{Examples}\\[\topsep]% \def\arraystretch{1.5} \tabular{|l|l|}% \hline - \fbox{\strong{Code}}\endcell - \fbox{\strong{Outcome}}\cr\hline\hline}{% +% \exampletitlefbox{\strong{Code}}\endcell +% \exampletitlefbox{\strong {Outcome}}\cr\hline\hline}{% +%% 2015/05/21: + \exampletitlefbox{\strong{Code:}}\endcell + \exampletitlefbox{\strong{clickable:}}\cr\hline\hline}{% \endtabular \endcenter} +\newcommand*{\exampletitlefbox}[1]{% + \fbox{\exampletablenarrow#1\exampletablenarrow}} +\newcommand*{\exampletablenarrow}{\kern-.3333em} %% 2015/05/21 +\newcommand*{\innersimpleexample}[1]{% +% \hskip-\fboxsep %% ?? 2015/05/21 + \exampletablenarrow + \simplecodefbox{#1}\exampletablenarrow\endcell + \exampletablenarrow + \simplecodeoutfbox{#1}\exampletablenarrow\cr + \hline} \newcommand*{\simpleyields}[1]{% %% 2012/12/30 \simplecodefbox{#1} yields \simplecodeoutfbox{#1}} -\RequirePackage{filesdo} \MDfinaldatechecks %% 2012/12/20 +\newcommand*{\longsimpleexample}[1]{% %% 2015/05/22f. + \example\leavevmode\[\simplecodefbox{#1}\]% + \makebox[\mathindent][l]{for}\simplecodeoutfbox{#1}% + \endexample} +% %% 2015/05/23: +% \newcommand*{\titlefootnote}[1]{% +% \IfTypesetting{\footnote{#1}{}}} +% \makeatletter +\pdfstringdefDisableCommands{\let\titlefootnote\@gobble} +\makeatother +\RequirePackage{filesdo} \MDfinaldatechecks %% 2012/12/20 \sloppy \begin{document} \maketitle @@ -129,6 +157,10 @@ below in the implementation section. \subsection{Package File Header (Legalese)} %% ize -> ese 2012/11/09 \input{texlinks.doc} +% \section{\file{wikimed.sty}} +% \ResetCodeLineNumbers +% \input{wikimed.doc} + %% rm. 2012/12/30 for \MDfinaldatechecks: % \ModDates % \CheckDateOfPDFmod{texlinks.sty} @@ -159,3 +191,8 @@ VERSION HISTORY 2012/12/31 corr. M\"unch; see sec:fonts 2013/01/20 {singthm} 2013/01/21 \section{Preliminaries} +2015/03/28 wikimed.sty +2015/05/21 \awfulsimpleexample -- replaced by \nvCSV, + \longsimpleexample, \exampletablenarrow +2015/05/22 \longcodesimpleexample corrected +2015/05/23 -> longsimpleexample diff --git a/Master/texmf-dist/tex/latex/morehype/morehype.RLS b/Master/texmf-dist/tex/latex/morehype/morehype.RLS index c6f0d3bd48d..cfdf2e49d00 100644 --- a/Master/texmf-dist/tex/latex/morehype/morehype.RLS +++ b/Master/texmf-dist/tex/latex/morehype/morehype.RLS @@ -1,4 +1,5 @@ \ProvidesFile{morehype.RLS} %% RELEASE INFO + [2015/11/09 r0.83 texlinks v0.83 CTANology] [2013/01/22 r0.82 texlinks v0.82 Jim? new! dir/open] [2013/01/04 r0.81 texlinks v0.81 www.ctan..., blog v0.81 enum..., diff --git a/Master/texmf-dist/tex/latex/morehype/texlinks.sty b/Master/texmf-dist/tex/latex/morehype/texlinks.sty index c5f02ec1558..49469b247a6 100644 --- a/Master/texmf-dist/tex/latex/morehype/texlinks.sty +++ b/Master/texmf-dist/tex/latex/morehype/texlinks.sty @@ -1,6 +1,6 @@ \NeedsTeXFormat{LaTeX2e}[1994/12/01] %% \newcommand* etc. -\ProvidesPackage{texlinks}[2013/01/22 v0.82 TeX-related links (UL)] -%% copyright (C) 2011 2012 2013 Uwe Lueck, +\ProvidesPackage{texlinks}[2015/07/20 v0.83 TeX-related links (UL)] +%% copyright (C) 2011 2012 2013 2015 Uwe Lueck, %% http://www.contact-ednotes.sty.de.vu %% -- author-maintained in the sense of LPPL below. %% @@ -20,7 +20,7 @@ \providecommand*{\newlet}[2]{\@ifdefinable#1{\let#1#2}} %% %% == Links in General == %% 2012/12/15 -%% === Outline === +%% === Outline === %% % Almost %% 2011/07/23 %% % all the %% including https 2011/08/27 %% The link macros of 'texlinks' are based on macros @@ -54,7 +54,7 @@ %% % package option forcing `\httpref' to use this style. %% % Well, better \emph{not today} ... [2011/01/24, TODO] %% -%% === Package Options === +%% === Package Options === %% \label{sec:opt} %% 2013/01/21 %% Somebody may want to suppress a definition of `\httpref' %% at `\begin{document}' ... [2011/01/24, TODO] @@ -67,7 +67,22 @@ %% useful for different purposes than running 'blog.sty'. \ProcessOptions %% -%% === Fonts for \URL s and File/Package Names === +%% === Obvious Shorthands === +%% |\htm|, |\html|, and |\pdf| for typical filename extensions +%% save a few tokens in macro definitions (v0.83): +\newcommand*{\htm}{.htm} +\newcommand*{\html}{\htm l} %% 2012/12/08 below previously +\newcommand*{\pdf}{.pdf} +%% |\DoubleArg{<cmd-maybe-args>}{<arg>}| (v0.83) works like +%% \[`<cmd-maybe-args>{<arg>}{<arg>}'\] +%% It replaces `\@double@first@arg' from v0.8; +%% it may also be useful as a user command. +%% It differs from \LaTeX's `\@dblarg' that adds +%% a missing optional argument: +\newcommand*{\DoubleArg}[2]{#1{#2}{#2}} +%% +%% === Formatting \URL s and File/Package Names === +%% %% <- was "Fonts for" 2013/02/20 %% \label{sec:fonts} %% 2012/12/19 %% %% ** Fonts for \URL s, File Names, and Package Names ** %% %% new 2011/10/19, TODO: `meansltx'? vgl. `makedoc.cfg' @@ -99,7 +114,7 @@ %% wants/adjusts it, \emph{here} it is the \emph{same:} \providecommand*{\filenamefmt}{\texttt} %% ... -%% I favour `\code' over `\texttt' as ``logical markup," +%% I favor `\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 ... %% @@ -126,7 +141,7 @@ %% that web pages use sans-serif as the \emph{normal} font ... %% %% %% moving \httpsref 2011/08/27: -%% === Providing &\httpref\ and &\httpsref === +%% === Providing &\httpref\ and &\httpsref === %% %% rm. \kern-\baselineskip 2011/10/10 %% \[|\httpref{<host-path[#frag]>}{<text>}|\] %% should display <text> @@ -142,7 +157,7 @@ }{\newcommand*{\httpref} [1]{\href {http://#1}}% \newcommand*{\httpsref}[1]{\href{https://#1}}}} %% -%% === Variants of &\httpref\ and &\httpsref === +%% === Variants of &\httpref\ and &\httpsref === %% |\NormalHTTPref| may be used as an alias for `\httpref' %% in situations where the latter has been redefined %% v0.2 %% (as in \secref{urlfoot}): @@ -158,7 +173,7 @@ %% \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 +\newlet\httpprefix\@empty %% \newlet 2015/05/25 %% `\let\httpprefix\relax' would be bad for 'blog.sty' %% (would display `\relax'), %% while it would be somewhat more efficient.%%%---%%% @@ -188,13 +203,37 @@ %% and when comparing what different web portals have %% to say about the same matter, such as the web versions %% of newspapers or magazines. So you may compare how -%% \domainref{www.ctan.org}{pkg/morehype} and -%% \domainref {\tugctanorg}{pkg/morehype} inform about %% \tugc... 2012/12/29 -%% the 'morehype' bundle (v0.8). -%% The command is also used in \secref{wiki-stack} -%% for `tex.stackexchange.com'. +%% %% v0.83 new example, \tugctanorg gone: +%% % \domainref{www.ctan.org}{pkg/morehype} and +%% % \domainref {\tugctanorg}{pkg/morehype} inform about %% \tugc... 2012/12/29 +%% % the 'morehype' bundle (v0.8). +%% \domainref{www.ctan.org}{tex-archive/macros} and +%% \domainref{tug.ctan.org}{tex-archive/macros} +%% display the top-level `macros' directory of the \TeX\ archive. +%% % The command is also used in \secref{wiki-stack} +%% % for `tex.stackexchange.com'. %% why? rm. 2015/05/24 -- see below %% %% texblog 2012/06/08; v0.8 here \newcommand*{\domainref}[2]{\httpref{#1/#2}{\urlfmt{#1}}} +%% Note that on some domains +%% only domain, an article \acro{ID} and maybe the `.html' +%% suffix and/or a ``category" between domain and \acro{ID} +%% is required for a working \URL, as opposed to an \URL +%% that is displayed in the browser's address line +%% and contains a kind of transcription of the article's title---e.g., +%% \urlhttpref{tex.stackexchange.com/questions/84878}. +%% +%% v0.83 adds \ |\prefixref{<prefix>}{<suffix>}{<text>}| \ +%% just as an alias for `\domainref' because the same function +%% may be useful in some cases when `<domain>/<path>', +%% for some code strings <prefix> and <suffix>, +%% is the same as `<prefix><suffix>' and `<prefix>' +%% for some <category>, +%% is the same as `<domain>/<category>': +\newlet\prefixref\domainref +%% Then you may compair how +%% \[\prefixref{www.ctan.org/tex-archive}{macros}\] +%% and \[\prefixref{tug.ctan.org/tex-archive}{macros}\] +%% display the `generic' subdirectory of the `macros' directory. %% %% ==== Linking \URL s in Footnotes ==== %% 2011/08/27 %% \label{sec:urlfoot} @@ -279,16 +318,29 @@ %% with v0.82 we add a shorthand for definitions like the avove one %% for `\myref'. \[|\MakeBasedHref{<cmd>}{<base>}|\] may be applied %% as \[`\MakeBasedHref{\myref}{<my-base>}'\] above. In the general -%% situation, \ `<cmd>{<path>}{<text>}' \ will work like -%% \ `\httpref{<base>/<path>}{<text>}'. -\newcommand*{\MakeBasedHref}[2]{% - \ifx#1\@undefined \else \ifx#1\relax \else - \PackageWarning{texlinks}{Redefining \string#1.}% - \fi \fi - \def#1{\httpbaseref{#2}}} -%% However, it does not act like `\newcommand' when <cmd> has been -%% defined earlier, it rather resembles `\DeclareRobustCommand', -%% in that it just \emph{warns} in such a case. +%% situation, `<cmd>{<path>}{<text>}' will work like +%% \[`\httpref{<base>/<path>}{<text>}'\] %% own line 2015/03/27 +%% v0.83 extends this to `https' +%% (has been tested in `texblog.fdf' for more than a year): +\newcommand*{\httpsbaseref}[2]{\httpsref{#1/#2}} %% 2014/03/21 +%% provides |\httpsbaseref{<base>}{<rest>}{<text>}|. +\newcommand*{\MakeBasedHref}[3][http]{% %% 2014/03/21 + \ifx#2\@undefined \else \ifx#2\relax %% was \ifx#1 2014/12/23 + \PackageWarning{texlinks}{Redefining \string#2.}% + \fi \fi + \expandafter\def\expandafter#2\expandafter{% +%% ... or `\DefExpandStart' from \ctanpkgstyref{dowith} TODO ... + \csname#1baseref\endcsname{#3}}% +} +%% This also provides an optional argument for choosing `https' +%% instead of `http': +%% \[|\MakeBasedHref[https]{<cmd>}{<base>}|\] +%% Now `\newcommand*{\mysecureref}{\httpsbaseref{<my-secure-base>}}' +%% may be replaced by +%% \[`\MakeBasedHref{\mysecureref}{<my-base>}'\] -- +%% However, `\MakeBasedHref' does not act like `\newcommand' +%% when <cmd> has been defined earlier, it rather resembles +%% `\DeclareRobustCommand', in that it just \emph{warns} in such a case. %% I don't actually make <cmd> robust because I guess it is anyway: %% The reason for allowing redefinitions has been application %% to cases where the user should be able to customize commands @@ -314,7 +366,9 @@ %% which results in (I'm curious ...) %% \googleref{tex+friends}{\TeX~\& friends:} \newcommand*{\googlecom}{google.com/} -\newcommand*{\googleref}[1]{\httpref{\googlecom\#q=#1}} +% \newcommand*{\googleref}[1]{\httpref{\googlecom\#q=#1}} +%% ... correct link has been very different since 2012: %% 2014/05/25 +\newcommand*{\googleref}[1]{\httpref{\googlecom/search?q=#1}} %% |\googlemapsref{<keywords>}{<text>}| \ generates a %% \wikiref{Google Maps}{Google map} from the <keywords>. %% <keywords> may compose an address for a \TeX\ users' meeting, @@ -325,7 +379,6 @@ \newcommand*{\googlemapsref}[1]{\httpref{maps.\googlecom maps?q=#1}} %% %% == Wikipedia == -%% %% TODO separate wikilink.sty? https:!? %% === Overview === %% \label{sec:wiki-stack} %% The present section on links to Wikipedia articles @@ -354,6 +407,13 @@ %% \emph{disambiguation} (\secref{wiki-back}), %% ``piped links" (\secref{wiki-pipe}), and %% special characters in \URL s (\secref{wiki-urls}). +%% +%% %% 2015/05/19: +%% Starting in spring 2015, the 'morehype' bundle offers +%% an additional package 'wikimed.sty' that includes +%% Wikipedias ``sister projects" like Wiktionary and +%% provides a variant of \wikienref{URL encoding}{\URL\ encoding}, +%% converting punctuation and things like umlauts for valid \URL s. %% %% === Backbones === %% \label{sec:wiki-back} @@ -431,23 +491,24 @@ \fi}% \fi} \def\wiki@noparen#1 (#2\@nil{#1} -%% I have thought about improving 'bitelist.sty', resulting -%% in the following code. In the present application, -%% I do not consider it superior. It uses -%% the same number of tokens but new one has additional -%% expansion step. The situation is different to the general case -%% because doing everything before `\fi' is okay here. -% \newcommand*{\Wikilangref}[2]{% -% \@wikilPref{#1}#2\BiteSep\@secondoftwo -% |\BiteSep\@firstoftwo\@nil{#2}} -% \def\@wikilPref#1#2|#3\BiteSep#4#5\@nil#6{% -% #4{\wikilangref{#1}{#6}{#6}}% -% {\wikilangref{#1}{#2}{% -% \ifx\@three#3\@three -% \wiki@noparen#2\@nil% -% \else -% #3% -% \fi}}} +%% (Removing 'bitelist' considerations 2015/05/22 ... +%% % I have thought about improving 'bitelist.sty', resulting +%% % in the following code. In the present application, +%% % I do not consider it superior. It uses +%% % the same number of tokens but new one has additional +%% % expansion step. The situation is different to the general case +%% % because doing everything before `\fi' is okay here. +%% % \newcommand*{\Wikilangref}[2]{% +%% % \@wikilPref{#1}#2\BiteSep\@secondoftwo +%% % |\BiteSep\@firstoftwo\@nil{#2}} +%% % \def\@wikilPref#1#2|#3\BiteSep#4#5\@nil#6{% +%% % #4{\wikilangref{#1}{#6}{#6}}% +%% % {\wikilangref{#1}{#2}{% +%% % \ifx\@three#3\@three +%% % \wiki@noparen#2\@nil% +%% % \else +%% % #3% +%% % \fi}}} %% %% === English and German === %% The next macros just save you from typing braces around @@ -554,221 +615,338 @@ % \@namedef{urluml:u}{\#C3\#BC} % \@namedef{urluml:s}{\#C3\#9F} %% 2010/08/09 %% -%% \pagebreak %% 2013/01/19 %% == \TeX-related == %% 2010/08/24 -%% === \code{\html} === %% 2012/12/18 -%% The shorthand macro |\html| saves a few tokens for -%% the standard extension \qtdcode{\html} of \HTML\ -%% files on \TeX-related sites: -\newcommand*{\html}{.html} -%% %% === \CTAN === -%% ==== Overview: Archive vs.\ Descriptions Roots ==== %% 2013/01/19 -%% \label{sec:ctan-over} -%% There have been \emph{\TeX\ archive roots} and -%% \emph{\TeX\ package description roots} on -%% \wikiref{CTAN}{\CTAN} web sites. -%% I cannot define those terms exactly. +%% \label{sec:ctan} +%% %% new from scratch 2015/05/16f.: +%% ==== Personal motivation ==== +%% When I created `texlinks.sty' originally, referring to +%% \CTAN\ material seemed simple to me. Well, what is \CTAN? +%% Please don't ask me, see the \wikiref{CTAN}{Wikipedia article} +%% and/or its major ``home page" \urlhttpref{www.ctan.org}---or +%% \CTAN\ introducing itself on \urlhttpref{ctan.org/ctan}---or +%% the \ukfaqref{ctan}{\acro{UK FAQ}!}---Well, +%% in order to generate \wikiref{URL}{\URL}s from human-readable +%% or memorizable input and to document my macros that try to +%% serve this purpose, I must guess what a domain or \CTAN\ has in +%% mind when they provide \URL s, while they don't seem to tell us +%% what they have in mind and what rules they follow. So I am just +%% reporting what I observed and what I guess, and I am trying to +%% introduce two technical terms ... \ The ``discovery" section +%% (\secref{ctan-discovery}) may be confusing, then I hope that +%% the ``summarizing section" (\secref{ctan-tables}) +%% will help by its tables.---The present \CTAN\ section (\secref{ctan}) +%% became especially difficult in December 2012 +%% (cf. \ctanannpref{12-12-006718}{\CTAN\ announcement}) +%% and January 2013 when some \URL s stopped to work +%% or changed their behavior---several times very much +%% within a few days---and I struggled to follow. +%% +%% ==== \CTAN ology: kinds of \CTAN\ \URL s (archives, bases) ==== +%% % \subsubsection{\CTAN ology:\titlefootnote{A moment ago, +%% % \wikienref{L. Ron Hubbard}{L.~Ron Hubbard} +%% % kindly suggested the section's title to me.} +%% % \ \ kinds of \CTAN\ \URL s (archives, bases)} +%% \label{sec:ctan-discovery} +%% \strong{One thing} are \strong{files} that have been \strong{contributed} +%% to the \strong{\CTAN\ archive} so that \strong{users} can download +%% them in order to run \TeX\ on their computers, especially for new +%% features that have been made available only in recent months. +%% Such files are submitted to the/a \CTAN\ archive, available through +%% certain \URL s over the internet. %% -%% \begin{singthm}{Examples} %% 2013/01/20 -%% of \TeX\ \strong{archive} roots currently -%% (2012-01-20) are \urlhttpref{tug.ctan.org}, the random -%% resolutions of \urlhttpref{mirror.ctan.org}, and -%% \urlhttpref{www.ctan.org/tex-archive/}. -%% They provide almost all material that may be useful -%% in running \TeX\ and share an essentially fixed directory -%% structure which however may vary over time due to new -%% contributions. Among the top-level subdirectories of -%% an archive root are `fonts', `graphics', and -%% `macros/latex/contrib'. -%% \end{singthm} +%% It seems that after some years it became difficult to understand +%% what features have been provided by so many contributors and +%% how to find them. For a while, the `help' subtree of a \CTAN\ archive +%% tried to help here (especially the \emph{\TeX\ catalogue}) ... +%% but eventually only experts could understand the abundance. +%% So a starting page just for providing tools for +%% \strong{exploring} the \TeX\ archive became useful and was +%% provided---over certain \URL s. Here I have called pages +%% available by such \URL s as ``\CTAN\ \strong{description}" +%% pages or so---\strong{second thing}. %% -%% Macro names for \TeX\ archive roots will look like -%% |<prefix>ctanref|. -%% In order to access an archive with root <ctan>, such a macro -%% will be defined as -%% \[`\httpbaseref{<ctan>}'\] -%% in \secref{texarc} (apart from using shorthand macros for -%% <ctan>)---see \secref{ctan-over} for `\httpbaseref'. +%% In order to save internet capacity (per time, +%% and to save users' patience), \strong{\Wikiref{web mirror}}s +%% of both archive and description pages have been established +%% and maintained---copies of the central directory structure. +%% +%% I have seen two kinds of \strong{\URL s} interesting here: +%% \begin{itemize} +%% \item \strong{domains} ending on `ctan.org' +%% \item \URL s ending on `/tex-archive' +%% \end{itemize} +%% +%% \TeX\ \strong{archive} \URL s show (only) a list of top-level +%% directories `biblio'..., `dviware', `fonts', `graphics', +%% `help', `indexing', `info', `install', `language'..., +%% `macros', `obsolete', `support', `systems', `tds', +%% `usergrps', and `web'. This is what characterizes \TeX\ +%% \emph{archives} or their \emph{roots}, as opposed to +%% \emph{description} pages, by their \strong{content} +%% (as opposed to characterization by the form of \strong{\URL s}). +%% Including deeper subdirectories, the directory structures +%% of all \TeX\ archives are the same (``mirrors"). They +%% change by new contributions, but within 24 hours, +%% other \TeX\ archives copy the changes of the first +%% one.---There are several \strong{designs} of archive root pages, +%% varying between archive \emph{mirrors.} %% -%% \begin{singthm}{Examples} -%% of \TeX\ package \strong{description} roots -%% currently are \urlhttpref{www.ctan.org} (which works like `ctan.org') -%% and \urlhttpref{alan.smcvt.edu} (Jim Hef{}feron's site at -%% \wikiref{Saint Michael\string's College}{Saint~Michael's College} -%% in \Wikiref{Vermont}, \acro{USA}. -%% They have shared subdirectories `pkg' and `author'. -%% When some package is described with an \emph{identifier} <id>, -%% its description appears under -%% \[`http://ctan.org/pkg/<id>'.\] -%% \end{singthm} +%% \CTAN\ \strong{description} pages have \emph{roots} as well, +%% and 'texlinks' previously has chosen macro names containing +%% `ctanorgbase' for accessing them, so there is an idea to call those roots +%% \strong{\CTAN\ bases}. In spring 2015, all bases I know +%% have the same \strong{design}, and they actually \emph{combine} +%% archive and description: an upper section shows the +%% archive top-level directories, the remaining page offers +%% the description/exploring tools. To compare bases with archives +%% in terms of top-level subdirectories, I know of \CTAN\ base +%% subdirectories `pkg', `author', `topic', and `tex-archive'. %% -%% Macro names for such domains will look like |<prefix>ctanorgbaseref|. -%% In order to access package descriptions from <ctan-org>, -%% such a macro will be defined as -%% \[`\httpbaseref{<ctan-org>}'\] -%% in \secref{x.ctan.org}. -%% % However, |alan.smcvt.edu| below has been a different domain~... -%% \pagebreak[3] -%% \begin{singthm}{Observations:}\leavevmode -%% \begin{enumerate} -%% \item All the \emph{description} roots have been \emph{domains}. -%% \item A \emph{domain} -%% \InlineCmdBox{<prefix>\code{\ctanorg}}---|\ctanorg| -%% saves a few tokens here: %% 2012/12/18, mv. down 2012/12/29 ... -\newcommand*{\ctanorg}{.ctan.org} -%% ---has been \emph{either} a package \emph{description} root -%% \emph{or} a \TeX\ \emph{archive} root. -%% \item When <ctan-org> has been a \emph{description} root, -%% `<ctan-org>/tex-archive' has been a \TeX\ \emph{archive} root -%% (with a similar design). %% 2013/01/21 -%% \end{enumerate} -%% \end{singthm} %% -%% ==== History of `tug.ctan.org' ==== %% 2012/12/29 -%% \label{sec:tug.ctan.org} -%% %% Moved down 2013/01/20: -%% When the present 'texlinks' package started in January 2011, -%% I preferred the design and information of Jim's -%% package descriptions under `ctan.org' to the very similar -%% descriptions by \catalogueref{}{\meta{The \TeX\ Catalogue}} -%% (\secref{texcat}), and I preferred Jim's design of -%% \TeX\ archive directory displays in the above-mentioned -%% archive with root `ctan.org/tex-archive'. -%% The 'texlinks' \emph{documentation} explicitly said that -%% certain \URL s referred to Jim Hef{}feron's pages. +%% ==== Summary tables with macro names ==== +%% \label{sec:ctan-tables} +%% In the following tables, a macro in the right-hand column +%% is just \emph{one} to access paths under the corresponding +%% \URL\ in the left-hand column, so the list of macros +%% probably is not complete here, it just is to give an \emph{idea} +%% for the following sections. The `\nullctan'\codedots\ +%% macros keep some `\ctan'\codedots\ control sequences free +%% so the latter are available as shorthands for accessing the users' +%% favorite domains. %% -%% With the advent of ``the new `www.ctan.org'" announced on -%% \ctanannpref{12-12-006718}{2012-12-12,} Jim's design was -%% no longer available as described before. The links intended to -%% get Jim's design received a collection of different designs -%% to choose from, while I preferred Jim's to all of them. -%% So the 'texlinks' documentation suddenly was wrong. -%% A serious contentual shortcoming in my view was that, -%% unlike Jim's and the Catalogue's package descriptions, -%% the new ones did not display direct links to package -%% documentations---this difference vanished after Christmas. -%% Moreover, the links to lists of packages by the same author -%% suddenly just failed, were ``dead." -%% -%% %% Much modified 2013/01/19: -%% % In the ``new `www.ctan.org'" situation described above, %% rm. 2013/01/20 -%% I discovered that I only had to replace -%% `ctan.org' by |tug.ctan.org| in order to get the original -%% functionality of 'texlinks'---linking to Jim's pages---back. -%% This was implemented by 'texlinks' v0.8, introducing -%% |\tugctanorg| (useful in the present -%% documentation---\secref{search-pkg}, \secref{x.ctan.org}) -%% and derived macros. In the terms introduced -%% above, `tug.ctan.org' then was a \emph{package description root}. +%% \vskip\medskipamount %%% \noindent +%% The first table is a list of \URL s resolving to +%% \CTAN\ description bases according to the previous subsection +%% (\secref{ctan-discovery}) I know of. +%% (It shrinked and changed much after some very recent discoveries of mine.) +%% Sections starting at \secref{sing-pkgs} tell about many more +%% macros for accessing description pages. %% 2015/05/20 +%% \MakeOther\|\MakeNormal\& +%% % \noNiceVerb +%% \begin{center} +%% \begin{tabular}{|r|r|} +%% \hline +%% \multicolumn{2}{|c|}{\strong{\CTAN\ bases for package descriptions}} \\ +%% \hline \hline +%% \multicolumn{1}{|c|}{\strong{\URL}} & \multicolumn{1}{c|}{\strong{macro}} \\ +%% \hline \hline +%% \urlhttpref{www.ctan.org} & `\wwwctanorgbaseref{<path>}{<text>}' \\ +%% \hline +%% \urlhttpref{ctan.org} & `\nullctanorgbaseref{<path>}{<text>}' \\ +%% \hline +%% \urlhttpref{dante.ctan.org} & \multicolumn{1}{c|}{---}\\ +%% \hline +%% \end{tabular} +%% \end{center} +%% \MakeActiveLet\|\nvCmdBox\MakeActiveLet\&\CmdSyntaxVerb +%% % \useNiceVerb +%% \strong{Remarks:}\enspace (a)~|www.ctan.org| and |ctan.org| +%% have the same functionality. %% -%% Apparently on December 21th, within 24 hours after uploading -%% v0.8, `tug.ctan.org' ceased to refer to Jim's pages -%% and actually no longer provided a \TeX\ archive or -%% package descriptions. My -%% \[\urlhttpref{www.webdesign-bu.de/uwe\string_lueck/heyctan.htm}\] -%% became a superb collection of dead links, and -%% `\tugctanref' and `\usetugctan' from v0.41 as well as -%% `\TugCtanPkgRef' and `\useTUGpkgpages' (among others) -%% became useless. +%% (b)~|\nullctanorgbaseref| appears here rather than |\ctanorgbaseref| +%% because the latter is used as an alias for either +%% |\wwwctanorgbaseref| or `\nullctanorgbaseref', by default for +%% `\ctanorgbaseref', cf. \secref{sing-pkgs}. %% -%% Then I discovered that |ctan.tug.org| still was a -%% \emph{package description root} with Jim's design. -%% Although Robin Fairbairns and Jim warned me that -%% Jim's pages may be switched off altogether soon, -%% I replaced `tug.ctan.org' by `ctan.tug.org' -%% (including the definition of |\tugctanorg|) for 'texlinks' v0.81 -%% and released it on 2013-01-04. Quite immediately, -%% `ctan.tug.org' showed the same behaviour has `tug.ctan.org', -%% killing the links of my `heyctan.htm' again. +%% (c)~|dante.ctan.org| just redirects to |www.ctan.org|. +%% \vskip\medskipamount %%% \pagebreak %%% \noindent +%% The second table is a list of \URL s resolving to +%% \CTAN\ \TeX\ archives according to the previous subsection +%% (\secref{ctan-discovery}) I know of. +%% Macros are described from \secref{texarc} onwards. +%% \MakeOther\|\MakeNormal\& +%% % \noNiceVerb +%% \begin{center} +%% \begin{tabular}{|r|r|} +%% \hline +%% \multicolumn{2}{|c|}{\strong{\CTAN\ archives}} \\ +%% \hline \hline +%% \multicolumn{1}{|c|}{\strong{\URL}} & \multicolumn{1}{c|}{\strong{macro}} \\ +%% \hline \hline +%% \urlhttpref{www.ctan.org/tex-archive} & `\wwwctanref{<path>}{<text>}' \\ +%% \hline +%% \urlhttpref{ctan.org/tex-archive} & `\nullctanref{<path>}{<text>}' \\ +%% \hline \hline +%% \urlhttpref{tug.ctan.org/tex-archive} & \multicolumn{1}{c|}{---} \\ +%% \hline +%% \urlhttpref{tug.ctan.org} & `\tugctanref{<path>}{<text>}' \\ +%% \hline +%% \urlhttpref{dante.ctan.org/tex-archive} & `\dantectanref{<path>}{<text>}'\\ +%% \hline +%% \urlhttpref{ctan.sciserv.eu} & `\sciservref{<path>}{<text>}' \\ +%% \hline \hline +%% \urlhttpref{mirror.ctan.org} & `\mirrorctanref{<path>}{<text>}'\\ +%% \hline +%% `<domain>/<path>tex-archive' & \multicolumn{1}{c|}{TODO} \\ +%% \hline +%% `<domain>/<path>ctan/' & \multicolumn{1}{c|}{TODO} \\ +%% \hline +%% `<domain>' & \multicolumn{1}{c|}{TODO} \\ +%% \hline +%% \end{tabular} +%% \end{center} +%% \MakeActiveLet\|\nvCmdBox\MakeActiveLet\&\CmdSyntaxVerb +%% % \useNiceVerb +%% \strong{Remarks:}\enspace \ \ (a)~|\nullctanref| +%% rather than |\ctanref| appears here because the latter +%% is used as an alias for one of the other `ctanref' commands, +%% by default for `\mirrorctanref', cf. \secref{texarc}. %% -%% |alan.smcvt.edu| seems to be the last resort to get -%% Jim's package descriptions and archive directories. -%% |\tugctanorg| now becomes heavily counter-intuitive, -%% but this way I need not change so much. -\newcommand*{\tugctanorg}{alan.smcvt.edu} %%% {ctan.tug.org} -%% Karl Berry informed me 2013-01-09 that |tug.ctan.org| -%% has started to be a relatively long-term -%% \emph{\TeX\ archive root}---while I first used it as a -%% \emph{package description} root and -%% `tug.ctan.org/tex-archive' as an archive root). %% 2013/01/21 -%% One may remember in the sequel that |tugctan| refers to -%% \emph{former} `tug.ctan.org' rather than to the \emph{present} one. -%% % (TODO: cf. \secref{tug}) -%% Anyway, usage of these macros is \strong{not recommended}, -%% they are rather a kind of ``compatibility" code for -%% old source files. Personally, -%% I also restrict their usage to source files that I edit -%% regularly, so I am quickly aware of changes of links. +%% (b)~|tug.ctan.org/tex-archive|,\quad |tug.ctan.org|, +%% \[|dante.ctan.org/tex-archive|\mbox{,\quad and\quad} |ctan.sciserv.eu|\] +%% have the same functionality; +%% which includes (i)~that they show the same page of its own +%% design and (z)~that this page includes a few lines of links +%% to the basic functions of `www.ctan.org'. The design is much +%% less heavy than the design of `www.ctan.org' with respect +%% to ($\alpha$)~graphics and to ($\beta$)~the number of columns. +%% At its bottom, the page describes itself as ``experimental" +%% and as dating from February~2015 (observed in May 2015). %% -%% ==== Directories and Files in a \TeX~Archive ==== -%% \label{sec:texarc} %% 2013/01/19 -%% % `\newcommand*{\ctanref}[1]{\httpref{ctan.org/#1}}' -%% % once was replaced in 'blog.sty' by what will now be -%% \[|\tugctanref{<path>}{<text>}|\] %% \[...\] 2012/12/19 -%% hopefully %% 2012/12/29 -%% makes <text> a link -%% to a \TeX~Archive directory or file <path> -%% with Jim Hef{}feron's interface. %% 2012/12/29 -\MakeBasedHref{\tugctanref}{\tugctanorg/tex-archive} -%% \simpleexample{\tugctanref{}{Archive root}} -%% Alternatively, you can refer to an (automatically chosen) -%% \CTAN\ \emph{mirror} -%% using -%% \[|\mirrorctanref{<path>}{<text>}|.\] %% 2011/10/10 :->.2011/10/21: -%% % (I prefer the \emph{appearance} of the %% rm. 2012/12/29 -%% % \tugctanref{}{\TUG\ archive}, designed by Jim Hefferon.) -\MakeBasedHref{\mirrorctanref}{mirror\ctanorg} -%% \simpleexample{\mirrorctanref{}{Archive root}} -%% You may actually want to ``open" a file <file-name> in <path> -%% 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 -%% by %% 2013/01/21 -%% \[|\mirrorctanfileref{<path>}{<file-name>}|.\] %% 2011/10/10 -% \newcommand*{\tugctanfileref}[2]{% -% \tugctanref{#1/#2}{\filenamefmt{#2}}} -\newcommand*{\mirrorctanfileref}[2]{% - \mirrorctanref{#1/#2}{\filenamefmt{#2}}} +%% (c)~\strong{Examples} for |<domain>/<path>/tex-archive|, %%%\quad +%% |<domain>/<path>ctan| and |<domain>| +%% (as listed below `mirror.ctan.org') +%% are \strong{\wikienref{web mirror}{mirrors}} of +%% \[|ctan.org/tex-archive|\mbox{\quad or \quad} +%% |www.ctan.org/tex-archive|\] +%% and appear as (somewhat random) resolutions of |mirror.ctan.org|. +%% <path> may be empty. +%% |tug.ctan.org| and |ctan.sciserv.eu| listed earlier +%% actually are examples of the last entry, +%% and |dante.ctan.org/tex-archive| exemplifies the other +%% lower entry. The file \ctanfileref{CTAN.sites} +%% in the root directory of any \TeX\ archive should +%% contain all the example \URL s to which `mirror.ctan.org' +%% resolves. However, my intention (which failed) for +%% the final table entries was that they exemplify mirrors +%% with rather \emph{simple} directory designs, +%% as opposed to the \URL s listed in the upper part +%% of the table. +%% +%% +%% ==== Some \CTAN\ Domains ==== +%% \label{sec:domains} %% 2015/05/22 +%% |\ctanorg| saves a few tokens, using |\nullctanorg| for |ctan.org| +%% (latter new with v0.83, keeping ultimate expansion of `\ctanorg' from prior +%% versions). +\newcommand*{\nullctanorg}{ctan.org} +\newcommand*{\ctanorg}{.\nullctanorg} +%% `\nullctanorg' and |\wwwctanorg| are useful both for +%% description pages and \TeX\ archives: +\newcommand*{\wwwctanorg}{www\ctanorg} +%% % Instances are |tug.ctan.org| (|\tugctanorg|), +%% % |www.ctan.org| (|\wwwctanorg|): +%% % |dante.ctan.org| (|\dantectanorg|): +%% % \newcommand*{\tugctanorg} {tug\ctanorg} +%% % \newcommand*{\wwwctanorg} {www\ctanorg} +%% % \newcommand*{\dantectanorg} {dante\ctanorg} +%% % \newcommand*{\mirrorctanorg}{mirror\ctanorg} +%% Referring to \strong{``description"} pages +%% according to \secref{ctan-discovery} +%% (`\httpbaseref' from \secref{bases}):\MDdocnewline +%% |\wwwctanorgbaseref{<path>}{<text>}| \ links to |www.ctan.org|: +\newcommand*{\wwwctanorgbaseref}{\httpbaseref\wwwctanorg} +%% |\nullctanorgbaseref{<path>}{<text>}| is like +%% the previous command without `www.': +\newcommand*{\nullctanorgbaseref}{\httpbaseref\nullctanorg} +%% |\metactan@ref{<sub>}{<ref-cmd>}| for some ``null" vs. +%% `www'-commands that are defined in \secref{sing-pkgs}: +\newcommand*{\metactan@ref}[3]{#2{#1/#3}} +%% +%% ==== Fixed Macros for Paths in Various \TeX\ Archives ==== %% 2015/05/22 +%% \label{sec:texarc} %% 2013/01/19 +%% \paragraph{Shorthands for paths.} +%% |\texarchive| saves a few tokens: %% 2015/05/21 +\newcommand*{\texarchive}{/tex-archive} %% Typically, \LaTeX\ macro packages in `macros/latex/contrib/' -%% are discussed, so here is |\ltxcontrib| saving a few characters: -\newcommand*{\ltxcontrib}{macros/latex/contrib/} -%% \begin{example}\leavevmode %% 2013/01/22 -%% \[\simplecodefbox{% -%% \mirrorctanref{&\ltxcontrib morehype}{&\pkg{morehype}}}\] -%% yields \ \simplecodeoutfbox{% -%% \mirrorctanref{\ltxcontrib morehype}{&\pkg{morehype}}}. -%% %% <- & doesn't work in first arg. of \href 2012/12/30 -%% %% -> `replace.sty'? -%% \end{example} -%% -%% %% 2013/01/21: -%% v0.82 removes `\tugctanfileref' which seems not to be useful. -%% My reason to choose Jim Hef{}feron's pages was -%% how \CTAN\ \emph{directories} are displayed. -%% For \emph{opening a file} from, any mirror should do. -%% However ... TODO +%% are discussed, so here is |\ltxcontrib| saving both characters +%% and tokens +%% (no starting slash so it can be used with `\httpbaseref'; +%% likewise no final one---hopefully only used in present demos +%% before v0.83): +\newcommand*{\ltxcontrib}{macros/latex/contrib} +%% We now proceed along the second table of \secref{ctan-tables}: +%% \paragraph{Advanced design of directories.} +%% \TeX\ archive directories on |www.ctan.org| +%% and |ctan.org| show an advanced design, +%% as compared with mirror \TeX\ archives. +%% They can be accessed by +%% \begin{itemize} +%% \item |\wwwctanref{<path>}{<text>}| and +%% \item |\nullctanref{<path>}{<text>}| respectively +%% \end{itemize} +%% (<path> without starting slash): +\MakeBasedHref{\wwwctanref} {\wwwctanorg/\texarchive} +\MakeBasedHref{\nullctanref}{\nullctanorg/\texarchive} +%% \begin{simpleexamples} +%% \simpleexample{\wwwctanref{}{Archive root}} +%% \simpleexample{\wwwctanref{macros/generic}{generic macros}} +%% \simpleexample{\nullctanref{macros/generic}{generic macros}} +%% % \longsimpleexample{\nullctanref{macros/generic}{generic macros}} +%% \simpleexample{\nullctanref{\nvCSV\ltxcontrib/morehype}{hypertext}} +%% \end{simpleexamples} +%% In the final example, you see that the ``directory" design +%% even includes something like the corrsponding +%% \strong{\ctanpkggenref{morehype}{package description}}---especially +%% the ``\acro{README}" is displayed in a ``frame." %% -%% Only for v0.82 I realize that the ``new `www.ctan.org'" -%% might provide directory designs (you can choose from predefined -%% ones and install your own) that users prefer to -%% the directory display of common \CTAN\ mirrors. -%% \[|\wwwctanref{<path>}{<text>}|\] -%% is made for this purpose. It may replace `\tugctanref' -%% especially when the latter vanishes: -\MakeBasedHref{\wwwctanref}{www\ctanorg/tex-archive} -%% \simpleexample{\wwwctanref{}{Archive root}} +%% \paragraph{Advanced root page design.} +%% Next, there are archive roots showing a special \emph{starting page}, +%% while subdirectories show a rather simple design. +%% \begin{itemize} +%% \item |\tugctanref{<path>}{<text>}|, +%% \item |\dantectanref{<path>}{<text>}|, and +%% \item |\sciservref{<path>}{<text>}| +%% \end{itemize} +%% make <text> a link to a \TeX~Archive directory or file <path> +%% on the corresponding domain: +\MakeBasedHref{\tugctanref}{tug\ctanorg} +%% (`tug.ctan.org' once behaved like `alan.smcvt.edu', +%% Jim Hefferon's former \CTAN\ interface.) +\MakeBasedHref{\dantectanref}{dante\ctanorg/\texarchive} +\MakeBasedHref{\sciservref}{dante\ctanorg} +%% Using the \emph{empty} <path> may be most interesting +%% for that starting page; otherwise they may simply serve as +%% (known) \emph{nearby mirrors}---speed preferred over design. +%% \begin{simpleexamples} +%% \simpleexample{\tugctanref{}{Archive root}} +%% \simpleexample{\tugctanref{info}{Info}} +%% \end{simpleexamples} +%% \paragraph{Random mirrors.} +%% For speed, saving energy (i.e., the \emph{world}), +%% and certain servers from overload, +%% using |mirror.ctan.org| is recommended, +%% which automatically chooses a \CTAN\ \wikienref{web mirror}{\emph{mirror}}. +%% \[|\mirrorctanref{<path>}{<text>}|.\] %% 2011/10/10 :->.2011/10/21: +%% is provided for this purpose: +\MakeBasedHref{\mirrorctanref}{mirror\ctanorg} +%% Resulting design may be poor ... +%% \begin{simpleexamples} +%% \simpleexample{% +%% \mirrorctanref{}{Archive root}} +%% \simpleexample{% +%% \mirrorctanref{help}{Help}} +%% \end{simpleexamples} %% -%% ==== Shorthand \cs{ctanref} for \CTAN\ Mirrors ==== %% 2013/01/21 +%% ==== \cs{ctanref} for Favourite Mirror, Customizing ==== %% fav. 2015/05/21 %% \label{sec:custom-ref} -%% |\ctanref| works like one out of -%% \[`\tugctanref', `\mirrorctanref', `\wwwctanref', `\myctanref'\] +%% |\ctanref| should work like one out of +%% \begin{itemize} +%% \item `\wwwctanref', `\nullctanref', +%% \item `\tugctanref', `\dantectanref', `\sciservctanref', and +%% \item `\mirrorctanref', +%% \end{itemize} +%% %%%(as introduced in \secref{texarc}) +%% (as listed in the second table of \secref{ctan-tables}) %% depending on which out of -%% \[|\usetugctan|, |\usemirrorctan|, |\usewwwctan|, |\usemyctan|\] +%% \begin{itemize} +%% \item |\usewwwctan|, |\usenullctan|, +%% \item |\usetugctan|, |\usedantectan|, |\usesciservctan|, and +%% \item |\usemirrorctan|, +%% \end{itemize} %% appeared most recently. -%% By default, it works like `\mirrorctanref'. +%% By \strong{default}, `\ctanref' works like `\mirrorctanref'. %% So in any case its syntax is \[|\ctanref{<path>}{<text>}|.\] %% The idea is that it is a shorthand to access the user's %% favourite \CTAN\ mirror, or just to save the `www' @@ -776,78 +954,92 @@ %% using %% \[|\MakeBasedHref{\ctanref}{<ctan-mirror>}|\] %% where <ctan-mirror> is a \URL\ of a root of -%% a \CTAN\ mirror, or by -%% \[|\renewcommand{\ctanref}{\dirctanref}|\] -%% for instance ... \ another macro for a \CTAN\ mirror -%% that you may meet soon. (See \secref{bases} for `\MakeBasedHref'.) -\newcommand*{\usemirrorctan}{% - \let \ctanref \mirrorctanref -% \let \ctanfileref \mirrorctanfileref +%% a \CTAN\ mirror (imitate code from \secref{texarc}---TODO: +%% more \URL s in \secref{domains}?), +%% or by +%% \[|\renewcommand{\ctanref}{\<prefix>ctanref}|\] +\newcommand*{\let@ctanref}{\let\ctanref} %% v0.83 2015/05/22 +\newcommand*{\usemirrorctan}{\let@ctanref\mirrorctanref + %% v0.83 rm. reminiscence of \let\ctanfileref } -%% |\usemirrorctan| is the \strong{default}, i.e., -%% |\ctanref| % and |\ctanfileref| use -%% uses -%% \urlhttpref{mirror.ctan.org}: +%% |\usemirrorctan| \emph{sets} the \strong{default} +%% meaning for |\ctanref| as announced +%% (so it uses \urlhttpref{mirror.ctan.org}): \usemirrorctan -\newcommand*{\usetugctan}{% - \let \ctanref \tugctanref -% \let \ctanfileref \tugctanfileref -} -\newcommand*{\usewwwctan}{\let\ctanref\wwwctanref} -%% |\myctanref| again is \emph{initialized} to work like -%% `\mirrorctanref': -\newlet\myctanref\mirrorctanref -%% However, it is \emph{intended} to store the -%% user's favourite mirror <my-ctan>, hoping that the user issues -%% \[|\MakeBasedHref{\myctanref}{<my-ctan>}|\] -%% and \emph{only afterwards} issues |\usemyctanref|: -\newcommand*{\usemyctanref}{\let\ctanref\myctanref} -%% ... not entirely sure ... the user could directly issue -%% \[`\MakeBasedHref{\ctanref}{<my-ctan>}'\] -%% The advantage of `\usemyctanref' is that you can -%% switch to another `\ctanref' later and then return to -%% `\myctanref' ... not so stable TODO -%% \begin{singthm}{Remark} (TODO) \ Another implementation -%% of adjusting `\ctanref' I consider is -%% using some `\ctanurl'\-`prefix' that you can redefine for -%% accessing your favourite mirror. -%% \end{singthm} +\RequirePackage{domore} +\setdo[2]{\newcommand*#1{\let@ctanref#2}} +%% TODO `\DoDoWithMore'? +\DoWithMore\do{\usewwwctan \wwwctanref } + {\usenullctan \nullctanref } + {\usetugctan \tugctanref } + {\usedantectani \dantectanref} + {\usesciservctan \sciservref }\StopDoing +%% v0.83 drops |\myctanref|, while it might be useful for the user's +%% preferred mirror. However, \secref{texarc} should show how to +%% set up `\myctanref' then, and +%% \[|\renewcommand*{\ctanref}{\myctanref}|\] +%% could replace the |\usemyctan| I haven't put here. +%% % \begin{singthm}{Remark} (TODO) \ Another implementation +%% % of adjusting `\ctanref' I consider is +%% % using some `\ctanurl'\-`prefix' that you can redefine for +%% % accessing your favourite mirror. +%% % \end{singthm} %% -%% ==== Flexibiblity with Files and Directories ==== %% 2013/01/22 -%% With some influence of the ideas of v0.41, `\ctanref' -%% now is a shorthand for viewing \CTAN\ directories, -%% e.g., working like `\mirrorctanref'. There was a -%% flexible variant of `\mirrorctanfileref' too, -%% but the implementation was bad from my present view. -%% I no longer want to offer downloads from Jim's pages. -%% \[|\ctanfileref{<path>}{<file>}|\] displays <file> as link text -%% and opens it. The mirror is chosen according to a shorthand -%% \ |\filectanref{<path>/<file>}{<text>}| \ that can be -%% adjusted with `\MakeBasedHref' like `\ctanref': -\newcommand*{\ctanfileref}[2]{% - \filectanref{#1/#2}{\filenamefmt{#2}}} -%% |\filectanref| is initialized to work like `\mirrorctanref': -\newlet\filectanref\mirrorctanref -%% The purpose is that the user adjusts it by -%% \[|\MakeBasedHref{\filectanref}{<ctan-down>}|\] -%% when she wants to download (open) files from \CTAN\ mirror <ctan-down>, -%% which may be the mirror at the university where she sits. -%% \begin{example}\leavevmode -%% \[ \simplecodefbox{\ctanfileref{&\ltxcontrib morehype/doc}{texlinks.pdf}}\] -%% yields \ -%% \simplecodeoutfbox{\ctanfileref{\ltxcontrib morehype/doc}{texlinks.pdf}} -%% \end{example} +%% ==== Opening/Downloading Files from an Archive ==== %% 2015/05/25 +%% %% moved down 2015/05/18 +%% You may actually want to \emph{open} a file <file-name> in <path> +%% of a \TeX\ archive +%% % <file-name> displayed as the link text, %% 2011/10/21 +%% % by %% 2013/01/21 +%% by clicking on <file-name> (which is formatted by +%% |\filenamefmt| from \secref{fonts})---or +%% to \emph{offer} this opportunity to readers of your document. +%% In this case, the formatting of \CTAN\ pages +%% (directories) doesn't matter at all, +%% so a randomly chosen archive mirror should do: +%% |\mirrorctanfileref{<path>}{<file-name>}| +\newcommand*{\CTANfileref}[3]{#1{#2/#3}{\filenamefmt{#3}}} +\newcommand*{\mirrorctanfileref}{\CTANfileref\mirrorctanref} +%% |\ctanfileref{<path>}{<file-name>}| is provided as an alias +%% or shorthand for `\mirrorctanfileref': +\newlet\ctanfileref\mirrorctanfileref +%% \begingroup\hfuzz=14pt %% TODO +%% \begin{simpleexamples} +%% \simpleexample{\ctanfileref{\nvCSV\ltxcontrib/filedate/doc}{filedate.pdf}} +%% \simpleexample{\ctanfileref{\nvCSV\ltxcontrib/filedate}{README}} +%% \simpleexample{\ctanfileref{\nvCSV\ltxcontrib}{filedate.zip}} +%% \end{simpleexamples} +%% \endgroup +%% %% 2013/01/21: rm. \tugctanfileref %%%% 2015/05/21 +%% |\mirrorctanfileref| should not be changed, +%% while the user might +%% \[|\renewcommand*{\ctanfileref}{\CTANfileref<archive-ref>}|\] +%% with <archive-ref> from the previous section or the +%% second table in \secref{ctan-tables} +%% (immitate the earlier definition of `\mirrorctanfiler'), +%% or s(h)e might +%% \[|\newcommand*{\myctanfileref}{\CTANfileref<archive-ref>}|\] +%% and (temporarily) +%% \[|\renewcommand*{\ctanfileref}{\myctanfileref}|\] +%% (|\filectanref| that I earlier offered for customizing +%% is dropped with v0.83.) %% %% It may be psychologically useful to have an \emph{opposite} -%% to `\filectanref' that can easily be recognized as such, +%% to `\ctanfileref' %% 2015/05/23: filectan -> ctanfile +%% that can easily be recognized as such, %% while `\ctanref' may be unclear. I offer -%% \ |\dirfilectanref{<path>}{<text>}|. \ It may be an alias -%% for `\ctanref', even respecting the `\use'\codedots\ commands -%% from above. Another proposal above is dangerous with the present idea: +%% |\dirctanref{<path>}{<text>}| ... +%% %. It may be an alias %% was \dirfile... 2015/05/21 +%% %for `\ctanref', even respecting the `\use'\codedots\ commands +%% %from above. Another proposal above is dangerous with the present idea: +%% as a kind of alias for `\ctanref'---you might change that +%% by `\renewcommand': \newcommand*{\dirctanref}{\ctanref} +%% \strong{Note:}\enspace Links for opening \CTAN\ files +%% with a different link text than the filename +%% can be generated by `ctanref' commands discribed earlier. %% %% ==== The \TeX\ Catalogue OnLine ==== -%% %% **** J\"urgen Fenn's Topical \TeX\ Catalogue **** %% \label{sec:texcat} %% 2012/12/18 %% % We are not providing access to everything in the %% % \catalogueref{}{\TeX~catalogue}. @@ -862,6 +1054,16 @@ %% in a \CTAN\ mirror %% shorthand 2012/12/17 %% of \meta{The \TeX~Catalogue OnLine}: \newcommand*{\catalogueref}[1]{\mirrorctanref{help/Catalogue/#1}} +%% The user may modify this by +%% \begin{center} +%% `\renewcommand*{\catalogueref}[1]{\myctanref{help/Catalogue/#1}}' +%% \end{center} +%% or by +%% \begin{center} +%% `\MakeBasedHref{\catalogueref}{texcatalogue\ctanorg}' +%% \end{center} +%% ---cf. \urlhttpref{texcatalogue\ctanorg}. +%% %% Some mirrors seem to display the Catalogue's root directory %% only this way, while others display the ``Welcome" page. %% |\cataloguestartref{<text>}| accesses the @@ -875,13 +1077,9 @@ %% 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]{\catalogueref{bytopic\html\##1}} -%% %% <- \mirrorctanref 2012/03/09 -%% % \begin{example} -%% % |\bytopicref{html}{\TeX~to \acro{HTML}}| \ for \ -%% % \simpleexample{\bytopicref{html}{&\TeX~to &\acro{HTML}}} %% \simpleexample{\bytopicref{html}{&\TeX~to HTML}} -%% % \end{example} -%% \[|\catpkgref{<pkg-name>}|\] makes <pkg-name> +%% \par %% recplaces \[\] 2015/05/20 +%% |\catpkgref{<pkg-name>}| makes <pkg-name> %% a link to the description of the \strong{package} <pkg-name> %% in \meta{The \TeX~Catalogue Online}. %% \[|\CatPkgRef{<name>}{<Name>}|\] @@ -895,13 +1093,16 @@ %% where <name> has a description page while <Name> %% doesn't have its \emph{own} description page~... %% \simpleexample{\CatPkgRef{morehype}{texlinks}} -%% \noindent The auxiliary |\@double@first@arg<cmd>{<arg>}| -%% doubles `{<arg>}' for <cmd>: -\newcommand*{\catpkgref}{\@double@first@arg\CatPkgRef} -\newcommand*{\@double@first@arg}[2]{#1{#2}{#2}} -\newcommand*{\CatPkgRef}[1]{% - \cat@ctan@pkg@ref\catalogueref{entries/#1\html}} -%% |\cat@ctan@pkg@ref<cmd>{<path[#frag]>}{<text>}| %% 2012/12/19 +\newcommand*{\catpkgref}{\DoubleArg\CatPkgRef} +%\newcommand*{\CatPkgRef}[1]{% +% \cat@ctan@pkg@ref\catalogueref{entries/#1\html}} +%% <- v0.83 2015/05/20 -> + \newcommand*{\CatPkgRef}{\cat@ctan@pkg@ref\catpkggenref} +%% v0.83 introduces |\catpkggenref{<pkg-name>}{<text>}| +%% where formatting <text> is up to the user +%% (or not special formatting required): +\newcommand*{\catpkggenref}[1]{\catalogueref{entries/#1\html}} +%% |\cat@ctan@pkg@ref<cmd>{<path>}{<text>}| %% 2012/12/19, rm. frag 2015/05/26 %% \ ensures that <Name> is typeset as the argument of %% `\pkgnamefmt' (\secref{fonts}). %% It is used in \secref{sing-pkgs} again: @@ -917,195 +1118,130 @@ %% % \fbox{\catpkgref{morehype}} %% % \end{example} %% -%% ==== Domains for Other Package Descriptions ==== -%% %% **** Other Interfaces to Package Descriptions **** -%% \label{sec:x.ctan.org} -%% v0.6 in the spirit of \secref{bases} introduced an auxiliary -%% \[|\ctanorgbaseref{<path>}{<text>}|\] for accessing Jim -%% Hef{}feron's package descriptions, as the 'texlinks' -%% documentation told then. By the advent of ``the new -%% `www.ctan.org'" announced on \ctanannpref{12-12-006718}{2012-12-12,} -%% this was falsified. `\ctanorgbaseref' formerly linked to -%% `ctan.org', i.e., to `www.ctan.org'. The package description -%% pages under that domain have been changed in December -%% and no longer call themselves ``Jim Hef{}feron's." -%% The latter's pages seem to stay available under -%% \urlfmt{\tugctanorg}. Major contentual differences at present -%% (2013-01-21) seem to be that %%% (2012-12-18) seem to be: -%% % \begin{enumerate} -%% % \item -%% `www.ctan.org' classifies packages by a new concept -%% of ``\strong{topics}," %% \strong 2013/01/21 -%% while \urlfmt{\tugctanorg} classifies them -%% by ``\strong{keywords}" as well as -%% by ``\strong{char\-ac\-teri\-za\-tions}" out of which one is -%% ``primary" and others are ``secondary." -%% % \item \urlfmt{\tugctanorg} like the Catalogue as in \secref{texcat} -%% % provides links to single documentation files, -%% % unlike `www.ctan.org'. -%% % \end{enumerate} -%% -%% In order to keep as much as possible, I introduce new -%% `\tugctan'\codedots\ and `\wwwctan'\codedots\ commands. -%% The first ones link to \urlfmt{\tugctanorg} -%% (see \secref{tug.ctan.org} for why), the others to -%% `www.ctan.org'. The user may choose whether the -%% `\ctan'\codedots\ commands link to \urlfmt{\tugctanorg} -%% or to `www.ctan.org'. -%% -%% |\tugctanorgbaseref{<path>}{<text>}| \ links to \urlfmt{\tugctanorg} -%% independently of the choice for `\ctanorgbaseref': -\newcommand*{\tugctanorgbaseref}{\httpbaseref\tugctanorg} -%% |\wwwctanorgbaseref{<path>}{<text>}| \ links to `www.ctan.org' -%% independently of the choice for `\ctanorgbaseref': -\MakeBasedHref{\wwwctanorgbaseref}{www\ctanorg} -%% |\useTUGctanbases| \ lets `\ctanorgbaseref' be `\tugctanorgbaseref': -\newcommand*{\useTUGctanbases}{\let\ctanorgbaseref\tugctanorgbaseref} -%% `\ctanorgbaseref{<path>}{<text>}' before v0.81 aimed to get Jim Hef{}feron's -%% pages via `\tugctanorgbaseref' by default: -% \useTUGctanbases -%% ... but that is bad when the future of \urlfmt{\tugctanorg} is unclear. -%% Therefore, \ -%% |\useWWWctanbases| \ will choose `www.ctan.org' to look for package -%% descriptions as the default instead (as of v0.81): -\newcommand*{\useWWWctanbases}{\let\ctanorgbaseref\wwwctanorgbaseref} -\useWWWctanbases -%% %% ==== Single Packages without The \TeX~Catalogue ==== %% \label{sec:sing-pkgs} %% 2012/12/19 -%% |\ctanpkgref{<pkg-name>}| -%% makes -%% <pkg-name> %%% <text> %% 2012/12/14 -%% a link to a package info page for the package <pkg-name>. -%% |\CtanPkgRef{<name>}{<Name>}| -%% is a variant of `\ctanpkgref' relating to the latter -%% as `\CatPkgRef' relates to `\catpkgref' (\secref{texcat}). -\newcommand*{\ctanpkgref}{\@double@first@arg\CtanPkgRef} -\newcommand*{\CtanPkgRef}{\Ct@nPkgRef\ctanorgbaseref} -%% Using `\cat@ctan@pkg@ref' from \secref{texcat}: -\newcommand*{\Ct@nPkgRef}[2]{\cat@ctan@pkg@ref#1{pkg/#2}} -%% |\ctanpkgstyref{<name>}| %% 2012/11/27 +%% v0.83 introduces a way to refer to a package description without +%% telling a package's name. |\wwwctanpkggenref{<id>}{<text>}| +%% does not coerce <text> into a special format: +\newcommand*{\metactan@pkgref}{\metactan@ref{pkg}} +\newcommand*{\wwwctanpkggenref}{\metactan@pkgref\wwwctanorgbaseref} +%% \longsimpleexample +%% {\wwwctanpkggenref{morehype}{an awesome bundle}} +%% |\nullctanpkggenref{<id>}{<text>}| similarly without `www.': +\newcommand*{\nullctanpkggenref}{\metactan@pkgref\nullctanorgbaseref} +%% |\wwwctanpkgref{<pkg-name>}| makes <pkg-name> %% 2015/05/26 +%% a link to a package info page for the package <pkg-name> +%% on `www.ctan.org'. <pkg-name> is displayed and formatted +%% by `\pkgnamefmt{<pkg-name>}'. |\WwwCtanPkgRef{<name>}{<Name>}| +%% is a variant of `\wwwctanpkgref' relating to the latter +%% as `\CatPkgRef' relates to `\catpkgref' (\secref{texcat}): +\newcommand*{\wwwctanpkgref}{\DoubleArg\wwwCtanPkgRef} +\newcommand*{\WwwCtanPkgRef}{\cat@ctan@pkg@ref\wwwctanpkggenref} +% %% Using `\cat@ctan@pkg@ref' from \secref{texcat}: +% \newcommand*{\Ct@nPkgRef}[2]{\cat@ctan@pkg@ref#1{pkg/#2}} +%% |\wwwctanpkgstyref{<name>}| %% 2012/11/27 %% adds \qtdcode{.sty} to the package name: +\newcommand*{\wwwctanpkgstyref}[1]{\wwwCtanPkgRef{#1}{#1.sty}} +%% Likewise |\nullctanpkgstyref{<name>}| etc.: +\newcommand*{\nullctanpkgstyref}[1]{\nullCtanPkgRef{#1}{#1.sty}} +\newcommand*{\nullctanpkgref}{\DoubleArg\nullCtanPkgRef} +\newcommand*{\NullCtanPkgRef}{\cat@ctan@pkg@ref\nullctanpkggenref} +%% Command names \ |\ctanpkgstyref|, \ |\ctanpkgref|, \ |\CtanPkgRef|, \ +%% and \ |\ctanpkggenref| \ interrelate analogously. +%% I expect these ones are mainly used. +%% Their exact behavior can be chosen from the `\nullctan'\codedots, +%% `\wwwctan'\codedots\ things, they even can use the \TeX\ catalogue: \newcommand*{\ctanpkgstyref}[1]{\CtanPkgRef{#1}{#1.sty}} -%% The previous commands for package info pages choose between -%% \urlfmt{\tugctanorg} and `www.ctan.org' according to -%% `\useTUGctanbases' or `\useWWWctanbases' -%% (i.e., `\ctanorgbaseref', \secref{x.ctan.org}). -%% The next commands allow that choice independently of -%% `\ctanorgbaseref', by contrast. -%% |\useTUGpkgpages| may be issued to stick to the \TUG\ -%% package descriptions (from `\CtanPkgRef'). %% \ 2013/01/21 -%% % even after `\useWWWctanorgbases' (useful? TODO): %% rm. 2012/12/29 -\newcommand*{\TugCtanPkgRef}{\Ct@nPkgRef\tugctanorgbaseref} -\newcommand*{\tugctanpkgref}{\@double@first@arg\TugCtanPkgRef} -\newcommand*{\useTUGpkgpages}{\let\CtanPkgRef\TugCtanPkgRef} -%% After |\useWWWpkgpages|, `\CtanPkgRef' and `\ctanpkgref' -%% use the package descriptions -%% from `www.ctan.org' even after `\useTUGctanorgbases': -\newcommand*{\WwwCtanPkgRef}{\Ct@nPkgRef\wwwctanorgbaseref} -\newcommand*{\wwwctanpkgref}{\@double@first@arg\WwwCtanPkgRef} -\newcommand*{\useWWWpkgpages}{\let\CtanPkgRef\WwwCtanPkgRef} +\newcommand*{\ctanpkgref}{\DoubleArg\CtanPkgRef} +\newcommand*{\CtanPkgRef}{\cat@ctan@pkg@ref\ctanpkggenref} +\newcommand*{\ctanpkggenref}{\metactan@pkgref\ctanorgbaseref} +%% v0.83 abolishes `tugctanorgbaseref' as +%% \urlhttpref{tug.ctan.org} no longer has a +%% `pkg' top-level subdirectory: +% \newcommand*{\useTUGpkgpages}{\let\CtanPkgRef\TugCtanPkgRef} +%% After |\useWWWpkgpages|, +%% the package descriptions from `www.ctan.org' are used: +\newcommand*{\let@ctanobref}{\let\ctanorgbaseref} +\newcommand*{\useWWWpkgpages}{\let@ctanobref\wwwctanorgbaseref} +%% After |\useOpkgpages|, `\CtanPkgRef' and `\ctanpkgref' +%% use the package descriptions from `ctan.org'. This command +%% and the previous |\useOpkgpages| also decide whether +%% author (\secref{pkg-au}), topic, and search pages +%% (\secref{pkg-search}) have `www.' in their \URL\ or not: +\newcommand*{\useOpkgpages}{\let@ctanobref\nullctanorgbaseref} +%% And the latter is the \strong{default:} +\useOpkgpages %% After |\useCATpkgpages|, `\CtanPkgRef' and `\ctanpkgref' -%% use the \TeX~Catalogue to display package informations: +%% use the \TeX~Catalogue to display package informations. +%% The content should be much the same as with +%% [`www.']`ctan.org', the same database is used, +%% it is the design that differs: \newcommand*{\useCATpkgpages}{\let\CtanPkgRef\CatPkgRef} %% Finally, we provide experimental %% \[|\AllPkgRefs{<name>}{<Name>}| \mbox{\quad and\quad} %% |\allpkgrefs{<name>}|\] -%% offering choice between the three interfaces for each package. -%% \qtdcode{c} will stand for The \TeX~Catalogue, -%% \qtdcode{t} for \urlfmt{\tugctanorg}, and +%% offering choice between the two interfaces for each package. +%% \qtdcode{c} will stand for The \TeX~Catalogue and %% \qtdcode{w} for `www.ctan.org'. After |\useALLpkgpages|, %% this is what `\CtanPkgRef' and `\ctanpkgref' offer: \newcommand*{\AllPkgRefs}[2]{% \pkgnamefmt{#2}\,[\CatPkgRef{#1}{c}\textbar - \TugCtanPkgRef{#1}{t}\textbar + % \TugCtanPkgRef{#1}{t}\textbar %% rm. v0.83 \WwwCtanPkgRef{#1}{w}]} -\newcommand*{\allpkgrefs}{\@double@first@arg\AllPkgRefs} +\newcommand*{\allpkgrefs}{\DoubleArg\AllPkgRefs} \newcommand*{\useALLpkgpages}{\let\CtanPkgRef\AllPkgRefs} %% \simpleexample{\allpkgrefs{morehype}} %% (With 'blog.sty', this requires some `\def\textbar{|}' TODO.) %% %% ==== Package Author Pages ==== -%% Before v0.8, we told that -%% \[|\ctanpkgauref{<id>}{<text>}|\] -%% referred to a package author page---a -%% list of all the author's packages---of -%% Jim Hef{}feron's interface, -%% provided <id> had been chosen properly. -%% With the advent of ``the new `www.ctan.org'" announced on -%% \ctanannpref{12-12-006718}{2012-12-12,} links generated -%% by this command stopped working altogether. -%% For v0.8, we repaired the definition so that the claim -%% became true again---for a few days. -%% v0.81 changes the default, see \secref{x.ctan.org}. -%% But ``the new `www.ctan.org'" also -%% provides its own author pages, and we offer a choice -%% between both interfaces for the author pages. -%% A little problem has been that the paths to these pages -%% differ between \urlfmt{\tugctanorg} and `www.ctan.org' now. -\newcommand*{\ctanpkgauref}[1]{\ctanorgbaseref{author/% -%% Only \urlfmt{\tugctanorg} uses \qtdcode{id/}: - \ifx\ctanorgbaseref\tugctanorgbaseref id/\fi - #1}} -%% % \simpleexample{\ctanpkgauref{lueck}{&\emph{My} packages}} -%% \simpleexample{\ctanpkgauref{lueck}{mine}} -%% %---On 2012-12-30, however, I see that with `ctan.org/author/id', -%% %\qtdcode{/id} is automatically removed. (TODO) -%% -%% |\tugctanpkgauref{<id>}{<text>}| chooses Jim Hef{}feron's -%% author pages even if `www.ctan.org' has been chosen to be -%% the main interface for package descriptions (\secref{x.ctan.org}): -\newcommand*{\tugctanpkgauref}[1]{\tugctanorgbaseref{author/id/#1}} -%% \simpleexample{\tugctanpkgauref{lueck}{mine}} -%% |\wwwctanpkgauref{<id>}{<text>}| chooses the new `www.ctan.org''s -%% author pages even if \urlfmt{\tugctanorg} has been chosen to be -%% the main interface for package descriptions (\secref{x.ctan.org}): -\newcommand*{\wwwctanpkgauref}[1]{\wwwctanorgbaseref{author/#1}} +%% \label{sec:pkg-au} +%% |\wwwctanpkgauref{<id>}{<description>}| creates a link +%% to the list of packages somebody described by <description> +%% maintains: +\newcommand*{\metactan@auref}{\metactan@ref{author}} +\newcommand*{\wwwctanpkgauref}{\metactan@auref\wwwctanorgbaseref} %% \simpleexample{\wwwctanpkgauref{lueck}{mine}} -%% By the default settings as of v0.81, `\wwwctanpkgauref' %% 2012/12/30 -%% is equivalent to `\ctanpkgauref'. To change this, issue -%% \[`\renewcommand{\ctanpkgauref}{\tugctanpkgauref}'\] +%% |\nullctanpkgauref{<id>}{<description>}| removes `www.': +\newcommand*{\nullctanpkgauref}{\metactan@auref\nullctanorgbaseref} +%% |\ctanpkgauref{<id>}{<description>}| chooses from the former +%% possibilities according to the `\use'\codedots\ commands +%% in the previous \secref{sing-pkgs}: +\newcommand*{\ctanpkgauref}{\metactan@auref\ctanorgbaseref} %% %% ==== Other Ways to Search for Packages ==== -%% \label{sec:search-pkg} %% 2012/12/29 -%% |\ctanpkgtopicref{<topic-id>}{<text>}| accesses a list of +%% \label{sec:pkg-search} %% 2012/12/29 +%% |\wwwctanpkgtopicref{<topic-id>}{<text>}| accesses a list of %% packages belonging to the ``topic" with identifier <topic-id>. -\newcommand*{\ctanpkgtopicref}[1]{\wwwctanorgbaseref{topic/#1}} -%% \simpleexample{\ctanpkgtopicref{cvt-html}{make HTML}} +\newcommand*{\metactan@topicref}{\metactan@ref{topic}} +\newcommand*{\wwwctanpkgtopicref}{% + \metactan@topicref\wwwctanorgbaseref} +%% \longsimpleexample{\wwwctanpkgtopicref{cvt-html}{make HTML}} +%% |\nullctanpkgtopicref{<topic-id>}{<text>}| without `www.': +\newcommand*{\nullctanpkgtopicref}{% + \metactan@topicref\nullctanorgbaseref} +%% |\nullctanpkgsearch{<text>}| \ and \ |\wwwctanpkgsearch{<text>}| \ +%% create links to a page for searching packages +%% with several options for search criteria: +\newcommand*{\metactan@searchref}[1]{#1{search}} +\newcommand*{\nullctanpkgsearchref}{% + \metactan@searchref\nullctanorgbaseref} +%% \simpleexample{\ctanpkgsearchref{CTAN~search}} +\newcommand*{\wwwctanpkgsearchref}{% + \metactan@searchref\wwwctanorgbaseref} +%% |\ctanpkgtopicref| and |\ctanpkgsearchref| choose +%% according to the `\use'\codedots\ commands in \secref{sing-pkgs}: +\newcommand*{\ctanpkgtopicref}{\metactan@topicref\ctanorgbaseref} +\newcommand*{\ctanpkgsearchref}{\metactan@searchref\ctanorgbaseref} +%% The \TeX\ Catalogue OnLine has offered searching as well, +%% yet today this search page is just the same as the one you +%% get by \wwwctanpkgsearchref. %% -%% \urlfmt{\tugctanorg} and `www.ctan.org' offer more pages for which -%% I don't create own macros, while I use some of them on a -%% \httpref{www.webdesign-bu.de/uwe_lueck/taeglich.htm} -%% {page collecting my favourite links.} -%% They are accessed either by -%% `\tugctanorgbaseref{<path>}'---resulting in `tug.ctan.org/<path>'---or by -%% `\wwwctanorgbaseref{<path>}'---resulting in `www.ctan.org/<path>'. -%% I am listing a few. -%% \begin{itemize} -%% \item On \urlhttpref{www.ctan.org/author}, you can browse -%% package authors. I could not find an equivalent -%% page under \urlfmt{\tugctanorg}. -%% \item \urlhttpref{\tugctanorg/search} and -%% \urlhttpref{www.ctan.org/search} offer different -%% criteria for searches. -%% \item On \urlhttpref{www.ctan.org/topic}, you can browse topics. -%% This page in fact is accessed by `\ctanpkgtopicref{}' -%% (<topic-id> empty). Jim Hef{}feron's keywords -%% %%% and characterizations -%% can be browsed on \[\urlhttpref{\tugctanorg/keywords}.\] -%% His characterizations can be browsed from -%% \[\urlhttpref{\tugctanorg/characterization/choose\string_dimen}.\] -%% \item \urlhttpref{\tugctanorg/pkg} is a single page listing -%% all package identifiers <pkg-id> -%% (for `\ctanpkgref{<pkg-id>}', as links). -%% %%% The corresponding -%% \urlhttpref{www.ctan.org/pkg} -%% just offers a link alphabet for pages of packages -%% that share their first letter (in the identifier). -%% \end{itemize} %% %% === Mailing Lists === %% \label{sec:mail} +%% This section mainly provides tools for referring %% 2015/05/28 +%% to pages of or postings to the \CTAN\ announcments +%% (\secref{ctan-ann}) and texhax (\secref{texhax}) mailing lists. %% v0.7 relies on package \ctanpkgref{langcode} for %% |\enmonthname{<month-number>}| and |\demonthname{<month-number>}|, %% for tricks with language codes extending those in @@ -1145,6 +1281,7 @@ \newcommand*{\texlistmonthref}{\texlanglistmonthref\monthname} %% %% === \CTAN\ Announcements === %% 2011/06/27 +%% \label{sec:ctan-ann} %% 2015/05/28 %% |\ctanannref{<id>}{<text>}| makes <text> a link %% to the DANTE web page displaying a \CTAN\ %% announcement. You find <id> by searching @@ -1198,6 +1335,7 @@ %% to <path> on domain `tug.org': \MakeBasedHref{\tugref}{tug.org} %% ==== texhax ==== +%% \label{sec:texhax} %% 2015/05/28 %% |\texhaxref{<id>}{<text>}| makes <text> a link %% to the \TUG\ web page displaying %% a texhax posting. You find <id> by searching @@ -1219,8 +1357,11 @@ %% (a number of six digits preceding `.html' of the \URL). %% I made this macro because I prefer typing to copying %% from the \URL. -\newcommand*{\texhaxpref}[1]{% %% 2010/09/07 - \texhaxref{20\TL@piper@parse#1/\html}} %% 2011/05/03 +\newcommand*{\texhaxpref}[1]{% %% 2010/09/07 + \texhaxref{20\TL@piper@parse#1/\html}} %% 2011/05/03 +%% |\THpref{<id-code>}| is a variant of `\THref' using +%% <id-code> as with `\texhaxpref': +\newcommand*{\THpref}[1]{\texhaxpref{#1}{texhax}} %% 2011/03/24 %% TODO: `\texhaxPref#1' searches list of offsets %% to determine year/month from id ... %% @@ -1237,9 +1378,14 @@ %% |\tugbartref{tb<vol>-<issue>/<filename-base>}{<text>}| %% makes <text> a link to the \TUG boat article %% `<filename-base>.pdf' in vol.~<vol> and issue~<issue>: -% \newcommand*{\tugbartref}[1]{\tugref{TUGboat/Articles/#1.pdf}} +% \newcommand*{\tugbartref}[1]{\tugref{TUGboat/Articles/#1\pdf}} \newcommand*{\tugbartref}[1]{\tugref{TUGboat/#1.pdf}} %% %% <- 2011/04/30 +%% That `tb' can be dropped with +%% \[|\tugbArtref{<vol>-<issue>/<filename-base>}{<text>}|\] +%% %% <- 2015/03/27 -> +%% after this definition: +\newcommand*{\tugbArtref}[1]{\tugbartref{tb#1}} %% |\tugiref{<anchor>}{<text>}| makes <text> %% <text> 2012/07/23 tugi 2012/08/05 %% a link to an <anchor> %% on the \TUG\ web page entitled \qtd{TeX Resources on the Web} @@ -1254,7 +1400,9 @@ %% |\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}} +% www.tex.ac.uk/cgi-bin/texfaq2html?label=#1}} + www.tex.ac.uk/FAQ-#1.html}} %% 2015/07/20 +%% %% === Wikibooks === %% \label{sec:wikibooks} %% 2013/01/21 %% |\wikilangbooksref{<language-code>}{<book>/<subject>}{<text>}| @@ -1341,6 +1489,7 @@ v0.7b 2012/12/06 there again: blogexec -> markblog, above entry ... -> r0.7b v0.71 2012/12/08 \ctanannpref like \texhaxpref -> r0.71 + v0.8 2012/12/15 \domainref from `texblog.fdf' doc.: \secref, gathering first subsections in new section "Links in General" @@ -1362,11 +1511,44 @@ v0.81 2012/12/28 doc.: "fonts" \provide, corr. \pkgnamefmt, more doc. wiki "overview", \simplecodefbox etc., 2012/12/31 doc. "the" Welcome ... -> r0.81 -v0.82 2013/01/18 \tugctanorg -> alan.smcvt.edu - 2013/01/19 reworking doc. on CTAN; \pagebreak - 2013/01/20 updated (C), reworking doc. on CTAN - 2013/01/21 \MakeBasedHref, \wwwctanref, \usewwwctan, - \newlet; doc.: typo fix, updated sec:x.ctan.org - 2013/01/21 applying \newlet, \myctanref, \usemyctan, - \ctanfileref reimplemented, \filectanref, - \dirctanref; doc.: \ltxcontrib with {example} +v0.82 2013/01/18 \tugctanorg -> alan.smcvt.edu + 2013/01/19 reworking doc. on CTAN; \pagebreak + 2013/01/20 updated (C), reworking doc. on CTAN + 2013/01/21 \MakeBasedHref, \wwwctanref, \usewwwctan, + \newlet; doc.: typo fix, updated sec:x.ctan.org + 2013/01/21 applying \newlet, \myctanref, \usemyctan, + \ctanfileref reimplemented, \filectanref, + \dirctanref; doc.: \ltxcontrib with {example} + -> r0.82 +v0.83 2013/02/04 comment out code for alan.smcvt.edu and + reduce doc. on it -- started + 2013/02/20 \tugbArtref; sec. "Obvious Shorthands": + \hmtl moves, \htm, \pdf, \DoubleArg; + some adjustments for AZ's vanishing; + doc. "Fonts for" -> "Formatting" + 2014/05/25 updated Google search link + 2015/03/27 doc. lines on "dropped" and "URL bases"; + 2015/05/16 short UK FAQ URL + 2015/05/17f. new doc. CTAN: overview/summary + 2015/05/18 rm. old doc. on Jim, reducing CTAN base cmd.s + 2015/05/19 CTAN domains, description pages reworked + 2015/05/20 more discovering, tidyingm and reworking + w.r.t. CTAN + 2015/05/21 doc. fix \dirctanref, ren. titles; \sciservref, + fewer CTAN domains, \texarchive and reworked ... + \awfulexample ... replaced + 2015/05/22 rm. bitelist considerations/\pagebreaks, + different titles + 2015/05/23 typo fix; \nullctanorgbases, reduce table text; + \paragraph -> again reworking early parts of + CTAN section + 2015/05/24 opening CTAN files ready; \prefixref; + doc.: removing page breaks + 2015/05/25 another \newlet; again reworking the CTAN + tables section. + 2015/05/26 doc. \cat@ctan...; \nullctanorgbaseref etc. + -- finished CTAN section + 2015/05/28 some more doc. on mailing lists; \THpref; + rm. "short UK FAQ" -- did *not* work! + 2015/06/14 rm. spurious section title + 2015/07/20 another short URL for the UK FAQ |