summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tugboat/ltubguid.ltx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-03-13 03:02:35 +0000
committerNorbert Preining <norbert@preining.info>2020-03-13 03:02:35 +0000
commit7f2b2a9d664831db3f6dcb985d3a10212ce3b752 (patch)
tree5b5ca88ef53ca03a6e4d8232ae8964bf2001b053 /macros/latex/contrib/tugboat/ltubguid.ltx
parentc4777604044f5d7ed37fd9e47edd58b44630a66d (diff)
CTAN sync 202003130302
Diffstat (limited to 'macros/latex/contrib/tugboat/ltubguid.ltx')
-rw-r--r--macros/latex/contrib/tugboat/ltubguid.ltx142
1 files changed, 97 insertions, 45 deletions
diff --git a/macros/latex/contrib/tugboat/ltubguid.ltx b/macros/latex/contrib/tugboat/ltubguid.ltx
index 906789bf28..db9f183dac 100644
--- a/macros/latex/contrib/tugboat/ltubguid.ltx
+++ b/macros/latex/contrib/tugboat/ltubguid.ltx
@@ -1,7 +1,7 @@
-% $Id: ltubguid.ltx 261 2019-11-09 22:00:31Z karl $
+% $Id: ltubguid.ltx 274 2020-03-12 16:47:21Z karl $
% ltubguid.ltx - documentation for ltugboat classes.
%
-% Copyright 1994-2019 TeX Users Group.
+% Copyright 1994-2020 TeX Users Group.
%
% This file is part of the tugboat package.
%
@@ -207,7 +207,7 @@ authors. The macros represent a development of the earlier
use with \LaTeX~2.09; major contributors have been Robin Fairbairns,
Sebastian Rahtz, Michel Goossens, Nico Poppelier and Johannes Braams.
Many others have been involved, including Barbara Beeton, Karl Berry,
-Mimi Burbank, and the \LaTeX3 team.
+Mimi Burbank, and the \LaTeX\ team.
\section{Availability}
@@ -226,8 +226,8 @@ produced. (\path|ltugproc.cls| is also produced for compatibility, but
is no longer used for proceedings or anything else.)
The\,\verb|.dtx| file may itself be processed by \LaTeX{} to
-produce a formatted (somewhat `literate') source listing for those who
-would like more detailed descriptions of the \TUB\ macros.
+produce a formatted (somewhat `literate') source listing for those
+interested in the implementation of the \TUB\ macros.
\section{The general structure of a paper}
@@ -631,7 +631,7 @@ generate calls to \cs{acro}; two examples, \cs{CTAN} and \cs{tug} of the
list in figure~\ref{fig:acro-logo} have already been used in the present
paper.
-\subsection{Other special typesetting}
+\subsection{Assorted other markup}
A small list of special typesetting commands follows: a large set of
such commands is defined in the classes, but the list covers most of
@@ -654,6 +654,8 @@ the `everyday' ones.
% for example \verb|\sfrac{3}{4}| is set as \sfrac{3}{4}\,.
\end{cmdlist}
+For commands to typeset urls, see section~\ref{sec:urls}.
+
\section{Use of packages}
Being a \TeX\ journal, authors may use both standard and non-standard
@@ -667,7 +669,7 @@ zip or other archive.
In general, packages currently on \CTAN, and known to work with
\emph{current} \LaTeX{} are likely to be fine. In particular,
the team is happy to accept papers using packages that are supported by
-members of the \LaTeX3 team,\footnote{%
+members of the \LaTeX\ team,\footnote{%
Those in the \LaTeX{} base distribution, or one of those in the
\CTANref{packages} sub-tree on \CTAN.} subject to the warning already
mentioned (section~\ref{sec:verbatim}): that use of the standard
@@ -689,15 +691,64 @@ important feature.)
An additional canonically-recommended package is \path|url.sty|
\cite{Arseneau:url:1996}, for typesetting filenames, email addresses,
urls, etc.; it is being used throughout the present paper (not least in
-the bibliography). Speaking of urls, nowadays we generally omit a
-leading \texttt{http://} or \texttt{https://}.
+the bibliography), either on its own or via \texttt{hyperref}.
Although not necessarily recommended in all cases, many additional
packages are commonly used. To mention a few: \texttt{microtype} can
-help reduce overfull boxes; sometimes it may be preferable to use the
-Latin Modern fonts via \texttt{lmodern}; \texttt{iftex} provides tests
-for the \TeX\ engine being run; and \texttt{hyperref} supports live and
-internal hyperlinks, outlines, and many other features.
+help reduce overfull boxes (and improve appearance); sometimes it may be
+preferable to use the Latin Modern fonts via \texttt{lmodern};
+\texttt{iftex} provides tests for the \TeX\ engine being run;
+\texttt{texosquery} provides operating system information; and
+\texttt{hyperref} supports live and internal hyperlinks, outlines, and
+many other features.
+
+\section{Typesetting urls}
+\label{sec:urls}
+
+As mentioned above, please load either \texttt{url} or (preferably)
+\texttt{hyperref} so that reasonable line breaking of urls can happen.
+
+Furthermore, for the printed (visible) \TUB\ page, nowadays we typically
+omit a leading \texttt{http://} or \texttt{https://}. But for the link
+to actually work in the output \PDF\ or \HTML, the protocol is required
+(or it appears to be a local filesystem path). Therefore the
+\texttt{ltugboat} class provides (as of version 2.23, released
+March~2020) commands \cs{tbsurl} for \texttt{https} and \cs{tbhurl} for
+\texttt{http}.\footnote{They are simple two-line wrapper around
+\cs{hyper@linkurl}, and are due to Ulrike Fischer.
+\url{https://github.com/latex3/hyperref/issues/125}\raggedright}
+
+For example, \verb|\tbsurl{tug.org}| typesets the text
+`\texttt{tug.org}' (with the usual url line breaks) as a link to
+\url{https://tug.org}.
+
+Similarly, \verb|\tbhurl{mirror.ctan.org}| typesets the text
+`\texttt{mirror.ctan.org}' as a link to \url{http://mirror.ctan.org}.
+
+\cs{tbsurl} and \cs{tbhurl} only add the protocol and make live links if
+\texttt{hyperref} is loaded. Without \texttt{hyperref}, they are merely
+synonyms for \cs{url}. This is ok, and we still request that the
+protocol not be included; if live links are not being produced in the
+output, the printed url without the protocol suffices. (When a user
+copies/pastes url text into a browser, it will normally work.)
+
+For \texttt{ftp}, \texttt{rsync}, and other protocols, it is best to
+include them explicitly and use \cs{url}:\\ \verb|\url{ftp://tug.org}|,\\
+\verb|\url{rsync://tug.org}|, etc.
+
+\subsection{Url shortcuts}
+\label{sec:urlshortcuts}
+
+Another aspect of urls: the \tug\ web server supports a shortcut url
+mechanism, \url{tug.org/l/}\meta{ident}, where \meta{ident} can be any
+tag, similar to \url{tinyurl.com} and similar sites. The idea is that
+\url{tug.org} shortcuts can be used in \TUB\ articles needing to link to
+excessively long and/or unstable web resources; then we update the
+shortcut if needed, and not worry that a commercial shortcut provider
+will disappear.
+
+The only way to create a \url{tug.org/l/} shortcut is by request, which
+we are happy to receive.
\section{Bibliography}
\label{sec:biblio}
@@ -705,8 +756,8 @@ internal hyperlinks, outlines, and many other features.
In short: our basic recommendation for handling bibliographies is to use
\BibTeX\ and the \pkgname{tugboat} bibliography style. No document
options are needed or recommended. All that is required in the article
-source (as shown in the template available from
-\url{tug.org/TUGboat}) is the following:
+source (as in the template available from \url{tug.org/TUGboat}) is the
+following:
\begin{verbatim}[\small]
\bibliographystyle{tugboat}
@@ -720,31 +771,35 @@ though, you may enjoy the following small but useful features:
\begin{itemize}
\item It is based on \pkgname{abbrvurl.bst} (see \url{ctan.org/pkg/urlbst}),
-\item thus supports \textsf{url} and \textsf{doi} fields, among others.
+\item and thus supports \textsf{url} and \textsf{doi} fields, among others.
+Please use \textsf{url} instead of putting urls in the
+\textsf{note} field, where possible. Also, please don't bother to
+include ``url access date'' information for \TUB; we find that extraneous.
-\item The \textsf{url} field is ignored if either the \textsf{doi} or
-\textsf{howpublished} field is present, since in practice we observe
-that people put the same information in all those fields, and we don't
-typeset redundant information.
+\item The \textsf{url} field is ignored if either the \textsf{howpublished} or
+\textsf{doi} field is present. In practice we observe that people put
+the same information in all those fields, and we don't want to typeset
+redundant information.
-\item Has even more abbreviations than \textsf{abbrv}, including
-printing only two author names (plus ``et~al\@.'') if there are more
-than four authors (thanks to Mico Loretan).
+\item Has even more abbreviations than \textsf{abbrv}, such as
+printing only two author names (plus ``et~al.'')\ if there are more than
+four authors (thanks to Mico Loretan).
\item Defines an \textsf{@online} entry type as an alias for \textsf{@misc}.
-\item For completeness only: \verb|tugboat.bst| provides ``secret''
+\item For completeness only: \verb|tugboat.bst| provides editor-intended
fields \textsf{newpage} to force a page break after the current item,
-and \textsf{urlnewline} to force a line break before the \textsf{url}
-value. As editors, we've found that these presentation tweaks are often
-necessary for the final typeset output. Authors need not worry about
-them.
+\textsf{urlnewline} to force a line break before the \textsf{url} value,
+and \textsf{journaltie} to output a tie instead of space after the
+\textsf{journal} value. As editors, we've found that these presentation
+tweaks can be desirable for the final typeset output. Authors need not
+worry about them.
\end{itemize}
If you use \BibTeX, feel free to take advantage of the accumulated
bibliography of \TUB{} itself (\url{info/tugboat.bib} on \CTAN), and the
-various compilations by Nelson Beebe in that same directory.
+other compilations by Nelson Beebe in that same directory.
Bibliographies provide further problems because they're notoriously
difficult to typeset at the best of times. \LaTeX{} sets \cs{sloppy}
@@ -756,7 +811,7 @@ set \cs{sloppy}, by default (just like \LaTeX{}), but the author may
\begin{verbatim}
\SetBibJustification{\raggedright}
\end{verbatim}
-as the present article does, to achieve somewhat better results.
+as the present article does, to often achieve somewhat better results.
A last note for references: for \TUB\ issues, please use the format
\textsl{volno\,:\,issno}, e.g., ``\TUB\ 32:1'' for volume~32, number~1.
@@ -764,23 +819,23 @@ A last note for references: for \TUB\ issues, please use the format
\section{Non-recommended bibliography facilities}
The preceding gives the bibliography recommendations for current \TUB\
-article. If, for whatever reason, you cannot follow the recommendation,
-this section is about some of the myriad historical and other
-possibilities.
+articles. If, for whatever reason, you do not wish to follow those
+recommendations, this section is about some of the myriad historical and
+other possibilities.
-Notwithstanding the general recommendation for the \pkgname{tugboat}
-(falling back to \pkgname{plain}) \BibTeX\ style, \TUB's Harvard
+Notwithstanding that general recommendation for the \pkgname{tugboat}
+(falling back to \pkgname{plain}) \BibTeX\ style, \TUB's Harvard-style
citation support may be selected by specifying \optname{harvardcite} as
an option of the \cs{documentclass} command.\footnote{%
The macros used derive rather directly from the `harvard' styles
- written by Glenn Paulley and now maintained by Peter Williams; the
+ written by Glenn Paulley and later maintained by Peter Williams; the
\BibTeX{} style derives from one developed by Patrick Daly.}
If your article demands Harvard-style citations, you may prefer to load
\pkgname{natbib} or similar instead of using \TUB's facilities; that's
-ok.
+fine.
-The basic citation format is `author(s), year', but the macros are
-capable of many variations: this in turn places somewhat of a load on
+This basic citation format is `author(s), year', but the macros are
+capable of many variations. This in turn places somewhat of a load on
the author to use the correct citation macro. The macros available are
shown in figure~\ref{fig:citation-macros}; the figure assumes an entry
in the bibliography with authors Tom, Dick, and~Harry, and with a 1990
@@ -818,7 +873,7 @@ controlled by the \optname{extralabel} and \optname{noextralabel} class
options. The default state (option \optname{extralabel}) attaches the
extra characters.
-As for \BibLaTeX, we don't recommend it for \TUB. If you feel you must
+As for \BibLaTeX: we don't recommend it for \TUB. If you feel you must
use it, that is ok, but we may still change it to using the default
\LaTeX\ and \BibTeX\ facilities in processing for publication if the
output from \BibLaTeX\ is problematic, as we have often seen it to be.
@@ -865,11 +920,8 @@ section~\ref{sec:verbatim}).
Of course, the syntax of commands given to the \LaTeX{} classes is
different (as discussed in section~\ref{sec:syntax}); arguments are
-(almost always) enclosed in braces, and neither of the forms of
-argument provision promulgated by the `plain' macros
-(\cs{macro}\meta{argument}\linebreak[0]\cs{endmacro} and
-\cs{macro * }\meta{argument}\verb| *|) are provided by the \LaTeX{}
-classes.
+(almost always) enclosed in braces instead of the various
+forms provided by the `plain' macros.
\SetBibJustification{\raggedright}
\bibliographystyle{tugboat}