diff options
Diffstat (limited to 'macros/latex/contrib/hereapplies')
-rw-r--r-- | macros/latex/contrib/hereapplies/ChangeLog.md | 11 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/README.md | 37 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies-doc.lyx | 1116 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies-doc.pdf | bin | 0 -> 364778 bytes | |||
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies-doc.tex | 230 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies-example.pdf | bin | 49764 -> 49420 bytes | |||
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies.sty | 49 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/lyx-module/hereapplies.module | 31 | ||||
-rw-r--r-- | macros/latex/contrib/hereapplies/package.json | 11 |
9 files changed, 1427 insertions, 58 deletions
diff --git a/macros/latex/contrib/hereapplies/ChangeLog.md b/macros/latex/contrib/hereapplies/ChangeLog.md index 0dbba84996..97ee241848 100644 --- a/macros/latex/contrib/hereapplies/ChangeLog.md +++ b/macros/latex/contrib/hereapplies/ChangeLog.md @@ -2,6 +2,17 @@ Change Log ========== +## 0.8.0 (2022-09-03) + +Changes: + +* The package now checks that the optional argument of the `\hereapplies` macro + does not contain commas +* The LyX module has been updated +* The documentation is now available in `.lyx`, `.tex` and `.pdf` format +* Code review + + ## 0.7.0 (2022-08-29) Changes: diff --git a/macros/latex/contrib/hereapplies/README.md b/macros/latex/contrib/hereapplies/README.md index 380a1fbdf1..6767f52376 100644 --- a/macros/latex/contrib/hereapplies/README.md +++ b/macros/latex/contrib/hereapplies/README.md @@ -81,7 +81,7 @@ labeled \texttt{myref}. \end{document} ``` -will generate [this document][1]. +will generate the [`hereapplies-example.pdf`][1] document attached. A minimal tutorial @@ -93,8 +93,8 @@ The `\hereapplies` command notifies the document that one or more identifiers apply to a particular point and adds a label to it. If the optional argument is passed the label created will be named accordingly, -otherwise an opaque name will be chosen. This argument may contain only what is -legal for `\pageref`. +otherwise an opaque name will be chosen for it. This argument may contain only +what is legal for `\pageref`. The `identifiers` argument must be a comma-separated list of identifiers (leading and trailing spaces around each member will be ignored). Each of these @@ -104,8 +104,7 @@ not create conflicts with possible macros or labels of the same names. After storing some internal values, `\hereapplies` will expand exactly to ``` tex -\phantomsection -\label{...} +\phantomsection\label{...} ``` Its “starred” version (`\hereapplies*`) will not invoke the `\phantomsection` @@ -133,19 +132,18 @@ Internationalization Currently the localization of **Here Applies** is not automatic. It is possible however to control the strings generated by overwriting the four macros -`\hapage`, `\hapages`, `\hadelimiter` and `\halastdelimiter`. - -For example, writing at the beginning of a document +`\hapage`, `\hapages`, `\hadelimiter` and `\halastdelimiter`. For example, +writing at the beginning of a document ``` tex % German translation of **Here Applies** -% English: `p.\ ` +% English: "p.\ " \gdef\hapage{S.\ } -% English: `pp.\ ` +% English: "pp.\ " \gdef\hapages{S.\ } -% English: `\ and\ ` +% English: "\ and\ " \gdef\halastdelimiter{\ und\ } -% English: `,\ ` (exactly like in German -- leave it) +% English: ",\ " (exactly like in German -- leave it) %\gdef\hadelimiter{,\ } ``` @@ -156,12 +154,9 @@ Get involved ------------ If you wish to get involved, please do not hesitate to send [merge requests][2] -or participate in the discussion. - -The package is also [available on CTAN][3] under -[`macros/latex/contrib/hereapplies`][4]. - -For any issue, please [drop a message][5]. +or participate in the discussion. The package is also [available on +**CTAN**][3] under [`macros/latex/contrib/hereapplies/`][4]. For any issue, +please [drop a message][5]. Free software @@ -169,13 +164,13 @@ Free software **Here Applies** is free software. You can redistribute it and/or modify it under the terms of the **AGPL** license version 3 or any later version. See -[COPYING][6] for details. +[`COPYING`][6] for details. [1]: hereapplies-example.pdf [2]: https://github.com/madmurphy/hereapplies.sty/pulls [3]: https://www.ctan.org/pkg/hereapplies - [4]: https://www.ctan.org/tex-archive/macros/latex/contrib/hereapplies - [5]: https://github.com/madmurphy/libgnunetworker/issues + [4]: https://www.ctan.org/tex-archive/macros/latex/contrib/hereapplies/ + [5]: https://github.com/madmurphy/hereapplies.sty/issues [6]: COPYING diff --git a/macros/latex/contrib/hereapplies/hereapplies-doc.lyx b/macros/latex/contrib/hereapplies/hereapplies-doc.lyx new file mode 100644 index 0000000000..8bd29fc9c5 --- /dev/null +++ b/macros/latex/contrib/hereapplies/hereapplies-doc.lyx @@ -0,0 +1,1116 @@ +#LyX 2.3 created this file. For more info see http://www.lyx.org/ +\lyxformat 544 +\begin_document +\begin_header +\save_transient_properties true +\origin unavailable +\textclass article +\begin_preamble +\usepackage{doc} + +\AtBeginDocument{% + % LyX should add automatically `\usepackage{listings}` to the preamble... + \lstset{% + language=TeX, + basicstyle=\footnotesize, + numbers=left, + stepnumber=1, + showstringspaces=false, + tabsize=1, + breaklines=true, + breakatwhitespace=false, + }% +} +\end_preamble +\use_default_options false +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding ascii +\fontencoding global +\font_roman "default" "default" +\font_sans "default" "default" +\font_typewriter "default" "default" +\font_math "auto" "auto" +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 100 +\font_tt_scale 100 100 +\use_microtype true +\use_dash_ligatures true +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing onehalf +\use_hyperref true +\pdf_title "The \\textquotedblleft{}Here Applies\\textquotedblright{} LaTeX Package" +\pdf_author "madmurphy" +\pdf_subject "Package documentation" +\pdf_keywords "Glossary, Index, LaTeX, LaTeX hyperref, LaTeX labels, LaTeX package, LyX, LyX module, TOC" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder false +\pdf_colorlinks false +\pdf_backref false +\pdf_pdfusetitle false +\papersize a4paper +\use_geometry true +\use_package amsmath 1 +\use_package amssymb 0 +\use_package cancel 0 +\use_package esint 1 +\use_package mathdots 0 +\use_package mathtools 0 +\use_package mhchem 0 +\use_package stackrel 0 +\use_package stmaryrd 0 +\use_package undertilde 0 +\cite_engine basic +\cite_engine_type default +\biblio_style plain +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\justification true +\use_refstyle 0 +\use_minted 0 +\index Index +\shortcut idx +\color #008000 +\end_index +\leftmargin 3.25cm +\topmargin 3.25cm +\rightmargin 3.25cm +\bottommargin 3.25cm +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\paragraph_indentation default +\is_math_indent 0 +\math_numbering_side default +\quotes_style english +\dynamic_quotes 0 +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Title +The +\series bold +Here Applies +\series default + \SpecialChar LaTeX + Package +\end_layout + +\begin_layout Standard +\begin_inset VSpace bigskip +\end_inset + + +\end_layout + +\begin_layout Abstract +A \SpecialChar LaTeX + package for referencing groups of pages that share something in common. + +\end_layout + +\begin_layout Standard +\begin_inset VSpace 2cm +\end_inset + + +\end_layout + +\begin_layout Section +Overview +\end_layout + +\begin_layout Standard + +\series bold +Here Applies +\series default + is a \SpecialChar LaTeX + package that allows to collect groups of labels and reference them + altogether. + It can be used for creating informal glossaries that cross-link concepts + to their applications, or simply mentioning multiple pages that share something + in common. +\end_layout + +\begin_layout Standard +The package offers two commands: +\family typewriter + +\backslash +hereapplies +\family default + and +\family typewriter + +\backslash +whereapplies +\family default + (plus their +\begin_inset Quotes eld +\end_inset + +starred +\begin_inset Quotes erd +\end_inset + + versions +\family typewriter + +\backslash +hereapplies* +\family default + and +\family typewriter + +\backslash +whereapplies* +\family default +). + In both cases an identifier is passed as argument – and this can be any + string invented in the moment ( +\family typewriter + +\backslash +hereapplies +\family default + additionally supports more than one identifier in the form of a comma-separated + list). +\end_layout + +\begin_layout Standard +Every time +\family typewriter + +\backslash +hereapplies +\family default + is invoked with known identifiers, the document is made aware that the + place shares some kind of connection with other places in which the same + identifiers were used. + And so, every time the +\family typewriter + +\backslash +whereapplies +\family default + command is invoked with a known identifier, all the occurrences of the + latter within the entire document will be printed in the form of a linkable + page list (e.g. + +\begin_inset Quotes eld +\end_inset + +pp. +\begin_inset space \space{} +\end_inset + +1, 5, 8–9, 14–20… +\begin_inset Quotes erd +\end_inset + +). +\end_layout + +\begin_layout Standard +As +\family typewriter + +\backslash +hereapplies +\family default + is designed to be invoked in the middle of a chapter or a section and that + location must be made linkable, the +\family typewriter + +\backslash +phantomsection +\family default + directive is invoked by default before a label is added. + To avoid calling +\family typewriter + +\backslash +phantomsection +\family default +, the +\begin_inset Quotes eld +\end_inset + +starred +\begin_inset Quotes erd +\end_inset + + command +\family typewriter + +\backslash +hereapplies* +\family default + is available. +\end_layout + +\begin_layout Standard +Finally, like +\family typewriter + +\backslash +whereapplies +\family default + resembles a pluralizable version of +\family typewriter + +\backslash +pageref +\family default +, its +\begin_inset Quotes eld +\end_inset + +starred +\begin_inset Quotes erd +\end_inset + + version +\family typewriter + +\backslash +whereapplies* +\family default + will resemble a pluralizable version of +\family typewriter + +\backslash +pageref* +\family default +. +\end_layout + +\begin_layout Standard +If you use LyX, the package ships a LyX module as well (please check the + +\family typewriter +lyx-module +\family default + subdirectory). +\end_layout + +\begin_layout Standard +\begin_inset Newpage pagebreak +\end_inset + + +\end_layout + +\begin_layout Section +Example usage +\end_layout + +\begin_layout Standard +The following \SpecialChar LaTeX + manuscript +\end_layout + +\begin_layout Standard +\begin_inset VSpace 3ex +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset CommandInset include +LatexCommand lstinputlisting +filename "hereapplies-example.tex" +lstparams "language=TeX" + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset VSpace 3ex +\end_inset + + +\end_layout + +\begin_layout Standard +\noindent +will generate the +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +hereapplies-example.pdf +\end_layout + +\end_inset + + document attached. +\end_layout + +\begin_layout Section +A minimal tutorial +\end_layout + +\begin_layout Standard +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +begin{macro}{ +\backslash +hereapplies} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Syntax: +\end_layout + +\begin_layout Standard +\begin_inset VSpace bigskip +\end_inset + + +\end_layout + +\begin_layout Standard + +\family typewriter + +\backslash +hereapplies +\begin_inset space \enskip{} +\end_inset + +[ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +label +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +] +\begin_inset space \enskip{} +\end_inset + +{ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +identifiers +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +} +\end_layout + +\begin_layout Standard + +\family typewriter + +\backslash +hereapplies* +\begin_inset space \enskip{} +\end_inset + +[ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +label +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +] +\begin_inset space \enskip{} +\end_inset + +{ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +identifiers +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +} +\end_layout + +\begin_layout Standard +\noindent +\begin_inset VSpace smallskip +\end_inset + + +\end_layout + +\begin_layout Standard +\noindent +The +\family typewriter + +\backslash +hereapplies +\family default + command notifies the document that one or more identifiers apply to a particula +r point and adds a label to it. +\end_layout + +\begin_layout Standard +If the optional argument is passed the label created will be named accordingly, + otherwise an opaque name will be chosen for it. + This argument may contain only what is legal for +\family typewriter + +\backslash +pageref +\family default +. +\end_layout + +\begin_layout Standard +The +\family typewriter +\shape italic +identifiers +\family default +\shape default + argument must be a comma-separated list of identifiers (leading and trailing + spaces around each member will be ignored). + Each of these strings will remain confined within the internal scope of + the package and will not create conflicts with possible macros or labels + of the same names. +\end_layout + +\begin_layout Standard +After storing some internal values, +\family typewriter + +\backslash +hereapplies +\family default + will expand exactly to +\end_layout + +\begin_layout Standard +\begin_inset listings +lstparams "language=TeX,numbers=none" +inline false +status open + +\begin_layout Plain Layout + + +\backslash +phantomsection +\backslash +label{...} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Its +\begin_inset Quotes eld +\end_inset + +starred +\begin_inset Quotes erd +\end_inset + + version ( +\family typewriter + +\backslash +hereapplies* +\family default +) will not invoke the +\family typewriter + +\backslash +phantomsection +\family default + directive. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +end{macro} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset VSpace smallskip +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +begin{macro}{ +\backslash +whereapplies} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Syntax: +\end_layout + +\begin_layout Standard +\begin_inset VSpace bigskip +\end_inset + + +\end_layout + +\begin_layout Standard + +\family typewriter + +\backslash +whereapplies +\begin_inset space \enskip{} +\end_inset + +{ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +identifier +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +} +\end_layout + +\begin_layout Standard + +\family typewriter + +\backslash +whereapplies* +\begin_inset space \enskip{} +\end_inset + +{ +\begin_inset Formula $\langle$ +\end_inset + + +\shape italic +identifier +\shape default + +\begin_inset Formula $\rangle$ +\end_inset + +} +\end_layout + +\begin_layout Standard +\noindent +\begin_inset VSpace smallskip +\end_inset + + +\end_layout + +\begin_layout Standard +\noindent +The +\family typewriter + +\backslash +whereapplies +\family default + command prints all the occurrences of an identifier, in the form +\begin_inset Quotes eld +\end_inset + +p. +\begin_inset space \space{} +\end_inset + +… +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +pp. +\begin_inset space \space{} +\end_inset + +… +\begin_inset Quotes erd +\end_inset + + (with page range support). +\end_layout + +\begin_layout Standard +The +\family typewriter +\shape italic +identifier +\family default +\shape default + argument will remain confined within the internal scope of the package + and will not create conflicts with possible commands or labels of the same + name. + Leading and trailing spaces around this string will be ignored. +\end_layout + +\begin_layout Standard +If the same +\family typewriter +\shape italic +identifier +\family default +\shape default + is not passed to +\family typewriter + +\backslash +hereapplies +\family default + at least once throughout the document, +\family typewriter + +\backslash +whereapplies +\family default + will print +\begin_inset Quotes eld +\end_inset + + +\series bold +?? +\series default + +\begin_inset Quotes erd +\end_inset + +. +\end_layout + +\begin_layout Standard +The +\begin_inset Quotes eld +\end_inset + +starred +\begin_inset Quotes erd +\end_inset + + version of this command ( +\family typewriter + +\backslash +whereapplies* +\family default +) will use +\family typewriter + +\backslash +pageref* +\family default + instead of +\family typewriter + +\backslash +pageref +\family default + for generating the page list. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +end{macro} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Internationalization +\end_layout + +\begin_layout Standard +Currently the localization of +\series bold +Here Applies +\series default + is not automatic. + It is possible however to control the strings generated by overwriting + the four macros +\family typewriter + +\backslash +hapage +\family default +, +\family typewriter + +\backslash +hapages +\family default +, +\family typewriter + +\backslash +hadelimiter +\family default + and +\family typewriter + +\backslash +halastdelimiter +\family default +. + For example, writing at the beginning of a document +\end_layout + +\begin_layout Standard +\begin_inset VSpace 3ex +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset listings +lstparams "language=TeX" +inline false +status open + +\begin_layout Plain Layout + +% German translation of **Here Applies** +\end_layout + +\begin_layout Plain Layout + +% English: "p. +\backslash + " +\end_layout + +\begin_layout Plain Layout + + +\backslash +gdef +\backslash +hapage{S. +\backslash + } +\end_layout + +\begin_layout Plain Layout + +% English: "pp. +\backslash + " +\end_layout + +\begin_layout Plain Layout + + +\backslash +gdef +\backslash +hapages{S. +\backslash + } +\end_layout + +\begin_layout Plain Layout + +% English: " +\backslash + and +\backslash + " +\end_layout + +\begin_layout Plain Layout + + +\backslash +gdef +\backslash +halastdelimiter{ +\backslash + und +\backslash + } +\end_layout + +\begin_layout Plain Layout + +% English: ", +\backslash + " (exactly like in German -- leave it) +\end_layout + +\begin_layout Plain Layout + +% +\backslash +gdef +\backslash +hadelimiter{, +\backslash + } +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset VSpace 3ex +\end_inset + + +\end_layout + +\begin_layout Standard +\noindent +will translate +\begin_inset Quotes eld +\end_inset + +pp. +\begin_inset space \space{} +\end_inset + +2, 4 and 6 +\begin_inset Quotes erd +\end_inset + + into +\begin_inset Quotes eld +\end_inset + +S. +\begin_inset space \space{} +\end_inset + +2, 4 und 6 +\begin_inset Quotes erd +\end_inset + +. +\end_layout + +\begin_layout Section +Get involved +\end_layout + +\begin_layout Standard +If you wish to get involved, please do not hesitate to send +\begin_inset CommandInset href +LatexCommand href +name "merge requests" +target "https://github.com/madmurphy/hereapplies.sty/pulls" +literal "false" + +\end_inset + + or participate in the discussion. + The package is also +\begin_inset CommandInset href +LatexCommand href +name "available on \\textbf{CTAN}" +target "https://www.ctan.org/pkg/hereapplies" +literal "true" + +\end_inset + + under +\begin_inset CommandInset href +LatexCommand href +name "\\texttt{macros/latex/contrib/hereapplies/}" +target "https://www.ctan.org/tex-archive/macros/latex/contrib/hereapplies/" +literal "true" + +\end_inset + +. + For any issue, please +\begin_inset CommandInset href +LatexCommand href +name "drop a message" +target "https://github.com/madmurphy/hereapplies.sty/issues" +literal "false" + +\end_inset + +. +\end_layout + +\begin_layout Section +Free software +\end_layout + +\begin_layout Standard + +\series bold +Here Applies +\series default + is free software. + You can redistribute it and/or modify it under the terms of the +\series bold +AGPL +\series default + license version 3 or any later version. + See +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +COPYING +\end_layout + +\end_inset + + for details. +\end_layout + +\begin_layout Standard +\begin_inset Newpage newpage +\end_inset + + +\end_layout + +\begin_layout Section* +Code appendix +\end_layout + +\begin_layout Standard +\begin_inset ERT +status collapsed + +\begin_layout Plain Layout + + +\backslash +addcontentsline{toc}{section}{Code appendix} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset CommandInset include +LatexCommand lstinputlisting +filename "hereapplies.sty" +lstparams "language=TeX" + +\end_inset + + +\end_layout + +\end_body +\end_document diff --git a/macros/latex/contrib/hereapplies/hereapplies-doc.pdf b/macros/latex/contrib/hereapplies/hereapplies-doc.pdf Binary files differnew file mode 100644 index 0000000000..812792219e --- /dev/null +++ b/macros/latex/contrib/hereapplies/hereapplies-doc.pdf diff --git a/macros/latex/contrib/hereapplies/hereapplies-doc.tex b/macros/latex/contrib/hereapplies/hereapplies-doc.tex new file mode 100644 index 0000000000..9f4f5027b3 --- /dev/null +++ b/macros/latex/contrib/hereapplies/hereapplies-doc.tex @@ -0,0 +1,230 @@ +%% LyX 2.3.6.1 created this file. For more info, see http://www.lyx.org/. +%% Do not edit unless you really know what you are doing. +\documentclass[english]{article} +\usepackage[T1]{fontenc} +\usepackage[a4paper]{geometry} +\geometry{verbose,tmargin=3.25cm,bmargin=3.25cm,lmargin=3.25cm,rmargin=3.25cm} +\usepackage{babel} +\usepackage{url} +\usepackage{setspace} +\usepackage{microtype} +\onehalfspacing +\usepackage[unicode=true, + bookmarks=true,bookmarksnumbered=false,bookmarksopen=false, + breaklinks=false,pdfborder={0 0 1},backref=false,colorlinks=false] + {hyperref} +\hypersetup{pdftitle={The \textquotedblleft{}Here Applies\textquotedblright{} LaTeX Package}, + pdfauthor={madmurphy}, + pdfsubject={Package documentation}, + pdfkeywords={Glossary, Index, LaTeX, LaTeX hyperref, LaTeX labels, LaTeX package, LyX, LyX module, TOC}} + +\makeatletter +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands. +\usepackage{doc} + +\AtBeginDocument{% + % LyX should add automatically `\usepackage{listings}` to the preamble... + \lstset{% + language=TeX, + basicstyle=\footnotesize, + numbers=left, + stepnumber=1, + showstringspaces=false, + tabsize=1, + breaklines=true, + breakatwhitespace=false, + }% +} + +\makeatother + +\usepackage{listings} +\renewcommand{\lstlistingname}{Listing} + +\begin{document} +\title{The \textbf{Here Applies} \LaTeX{} Package} + +\maketitle +\bigskip{} + +\begin{abstract} +A \LaTeX{} package for referencing groups of pages that share something +in common. +\end{abstract} +\vspace{2cm} + + +\section{Overview} + +\textbf{Here Applies} is a \LaTeX{} package that allows to collect +groups of labels and reference them altogether. It can be used for +creating informal glossaries that cross-link concepts to their applications, +or simply mentioning multiple pages that share something in common. + +The package offers two commands: \texttt{\textbackslash hereapplies} +and \texttt{\textbackslash whereapplies} (plus their ``starred'' +versions \texttt{\textbackslash hereapplies{*}} and \texttt{\textbackslash whereapplies{*}}). +In both cases an identifier is passed as argument -- and this can +be any string invented in the moment (\texttt{\textbackslash hereapplies} +additionally supports more than one identifier in the form of a comma-separated +list). + +Every time \texttt{\textbackslash hereapplies} is invoked with known +identifiers, the document is made aware that the place shares some +kind of connection with other places in which the same identifiers +were used. And so, every time the \texttt{\textbackslash whereapplies} +command is invoked with a known identifier, all the occurrences of +the latter within the entire document will be printed in the form +of a linkable page list (e.g. ``pp.\ 1, 5, 8--9, 14--20\dots ''). + +As \texttt{\textbackslash hereapplies} is designed to be invoked +in the middle of a chapter or a section and that location must be +made linkable, the \texttt{\textbackslash phantomsection} directive +is invoked by default before a label is added. To avoid calling \texttt{\textbackslash phantomsection}, +the ``starred'' command \texttt{\textbackslash hereapplies{*}} +is available. + +Finally, like \texttt{\textbackslash whereapplies} resembles a pluralizable +version of \texttt{\textbackslash pageref}, its ``starred'' version +\texttt{\textbackslash whereapplies{*}} will resemble a pluralizable +version of \texttt{\textbackslash pageref{*}}. + +If you use LyX, the package ships a LyX module as well (please check +the \texttt{lyx-module} subdirectory). + +\pagebreak{} + +\section{Example usage} + +The following \LaTeX{} manuscript + +\vspace{3ex} + +\lstinputlisting[language=TeX]{hereapplies-example.tex} + +\vspace{3ex} + +\noindent will generate the \url{hereapplies-example.pdf} document +attached. + +\section{A minimal tutorial} + +\begin{macro}{\hereapplies} + +Syntax: + +\bigskip{} + +\texttt{\textbackslash hereapplies\enskip{}{[}$\langle$}\texttt{\textit{label}}\texttt{$\rangle${]}\enskip{}\{$\langle$}\texttt{\textit{identifiers}}\texttt{$\rangle$\}} + +\texttt{\textbackslash hereapplies{*}\enskip{}{[}$\langle$}\texttt{\textit{label}}\texttt{$\rangle${]}\enskip{}\{$\langle$}\texttt{\textit{identifiers}}\texttt{$\rangle$\}} + +\noindent \smallskip{} + +\noindent The \texttt{\textbackslash hereapplies} command notifies +the document that one or more identifiers apply to a particular point +and adds a label to it. + +If the optional argument is passed the label created will be named +accordingly, otherwise an opaque name will be chosen for it. This +argument may contain only what is legal for \texttt{\textbackslash pageref}. + +The \texttt{\textit{identifiers}} argument must be a comma-separated +list of identifiers (leading and trailing spaces around each member +will be ignored). Each of these strings will remain confined within +the internal scope of the package and will not create conflicts with +possible macros or labels of the same names. + +After storing some internal values, \texttt{\textbackslash hereapplies} +will expand exactly to + +\begin{lstlisting}[language=TeX,numbers=none] +\phantomsection\label{...} +\end{lstlisting} + +Its ``starred'' version (\texttt{\textbackslash hereapplies{*}}) +will not invoke the \texttt{\textbackslash phantomsection} directive. + +\end{macro} + +\smallskip{} + +\begin{macro}{\whereapplies} + +Syntax: + +\bigskip{} + +\texttt{\textbackslash whereapplies\enskip{}\{$\langle$}\texttt{\textit{identifier}}\texttt{$\rangle$\}} + +\texttt{\textbackslash whereapplies{*}\enskip{}\{$\langle$}\texttt{\textit{identifier}}\texttt{$\rangle$\}} + +\noindent \smallskip{} + +\noindent The \texttt{\textbackslash whereapplies} command prints +all the occurrences of an identifier, in the form ``p.\ \dots '' +or ``pp.\ \dots '' (with page range support). + +The \texttt{\textit{identifier}} argument will remain confined within +the internal scope of the package and will not create conflicts with +possible commands or labels of the same name. Leading and trailing +spaces around this string will be ignored. + +If the same \texttt{\textit{identifier}} is not passed to \texttt{\textbackslash hereapplies} +at least once throughout the document, \texttt{\textbackslash whereapplies} +will print ``\textbf{??}''. + +The ``starred'' version of this command (\texttt{\textbackslash whereapplies{*}}) +will use \texttt{\textbackslash pageref{*}} instead of \texttt{\textbackslash pageref} +for generating the page list. + +\end{macro} + +\section{Internationalization} + +Currently the localization of \textbf{Here Applies} is not automatic. +It is possible however to control the strings generated by overwriting +the four macros \texttt{\textbackslash hapage}, \texttt{\textbackslash hapages}, +\texttt{\textbackslash hadelimiter} and \texttt{\textbackslash halastdelimiter}. +For example, writing at the beginning of a document + +\vspace{3ex} + +\begin{lstlisting}[language=TeX] +% German translation of **Here Applies** +% English: "p.\ " +\gdef\hapage{S.\ } +% English: "pp.\ " +\gdef\hapages{S.\ } +% English: "\ and\ " +\gdef\halastdelimiter{\ und\ } +% English: ",\ " (exactly like in German -- leave it) +%\gdef\hadelimiter{,\ } +\end{lstlisting} + +\vspace{3ex} + +\noindent will translate ``pp.\ 2, 4 and 6'' into ``S.\ 2, 4 +und 6''. + +\section{Get involved} + +If you wish to get involved, please do not hesitate to send \href{https://github.com/madmurphy/hereapplies.sty/pulls}{merge requests} +or participate in the discussion. The package is also \href{https://www.ctan.org/pkg/hereapplies}{available on \textbf{CTAN}} +under \href{https://www.ctan.org/tex-archive/macros/latex/contrib/hereapplies/}{\texttt{macros/latex/contrib/hereapplies/}}. +For any issue, please \href{https://github.com/madmurphy/hereapplies.sty/issues}{drop a message}. + +\section{Free software} + +\textbf{Here Applies} is free software. You can redistribute it and/or +modify it under the terms of the \textbf{AGPL} license version 3 or +any later version. See \url{COPYING} for details. + +\newpage{} + +\section*{Code appendix} + +\addcontentsline{toc}{section}{Code appendix} + +\lstinputlisting[language=TeX]{hereapplies.sty} +\end{document} diff --git a/macros/latex/contrib/hereapplies/hereapplies-example.pdf b/macros/latex/contrib/hereapplies/hereapplies-example.pdf Binary files differindex a175e64cd5..512d7c2410 100644 --- a/macros/latex/contrib/hereapplies/hereapplies-example.pdf +++ b/macros/latex/contrib/hereapplies/hereapplies-example.pdf diff --git a/macros/latex/contrib/hereapplies/hereapplies.sty b/macros/latex/contrib/hereapplies/hereapplies.sty index ba13cdb9a7..7802e30a11 100644 --- a/macros/latex/contrib/hereapplies/hereapplies.sty +++ b/macros/latex/contrib/hereapplies/hereapplies.sty @@ -1,4 +1,4 @@ -% -*- Mode: latex; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*- +% -*- Mode: latex; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*- % % % hereapplies.sty @@ -8,7 +8,7 @@ % % https://github.com/madmurphy/hereapplies.sty % -% Version 0.7.0 +% Version 0.8.0 % % Copyright (C) 2022 madmurphy <madmurphy333@gmail.com> % @@ -66,7 +66,7 @@ % \end{document} % % -\ProvidesPackage{hereapplies}[2022/08/29 Here Applies] +\ProvidesPackage{hereapplies}[2022/09/03 Here Applies] \RequirePackage{hyperref} \RequirePackage{refcount} % @@ -101,7 +101,7 @@ % This macro is mainly for internal purposes (but nothing forbids invoking it % directly). When invoked it checks whether a comma is present in `text to % check`, then expands to `if yes` or `if no` accordingly. - +% % Please do not put curly brackets around the text to check. The comma at the % end of the text is mandatory. % @@ -350,16 +350,18 @@ % other packages, if needed. % % -% Macro: `\starred@labeled@hereapplies{label}{identifiers}` +% Macro: `\starred@nochecks@hereapplies{label}{identifiers}` % ***************************************************************************** % -% Identical to `\hereapplies*`, but the two arguments are both mandatory +% Similar to `\hereapplies*`, but without checks and with two mandatory +% arguments % % This macro is mainly for internal purposes (but nothing forbids invoking it -% directly). See the documentation of `\hereapplies` for more information. +% directly). Here the two arguments are both mandatory and there will be no +% checks that first argument does not contain a comma. See the documentation of +% `\hereapplies` for more information. % -\newcommand*{\starred@labeled@hereapplies}[2]{% - \begingroup% +\newcommand*{\starred@nochecks@hereapplies}[2]{% % Assign a label to this occurrence \label{#1}% % Iterate through the comma-separated list `identifiers` @@ -384,7 +386,8 @@ @ha@iter@@labels@\@ha@tmp@@id\endcsname{#1}% \fi% }% - \endgroup% + % Clean the environment + \let\@ha@tmp@@id\undefined% } % % @@ -402,15 +405,23 @@ % The macro has been called with only one argument % Assign a unique number to the unnamed occurrence \stepcounter{@ha@unlabeled@counter}% - % Call `\starred@hereapplies` with an opaque label - {\edef\@ha@tmp@@mcall{\noexpand\starred@labeled@hereapplies{% - hereapplies:unnamed\the@ha@unlabeled@counter}{#2}% - }\@ha@tmp@@mcall}% + % Create an opaque label + \edef\@ha@tmp@@lbl{hereapplies:unnamed\the@ha@unlabeled@counter}% \else% % The macro has been called with two arguments - % Call `\starred@labeled@hereapplies` with the same arguments - \starred@labeled@hereapplies{#1}{#2}% + % Expand the first argument for checking properly + \edef\@ha@tmp@@lbl{#1}% + % Make sure that there are no commas in the `label` argument + \expandafter\@ha@ifcomma\@ha@tmp@@lbl,\@then{% + \PackageError{hereapplies}{Comma detected in "\@ha@tmp@@lbl"}{% + It is possible to assign only one single label.% + }% + }{}% \fi% + % Call `\starred@nochecks@hereapplies` + \expandafter\starred@nochecks@hereapplies\expandafter{\@ha@tmp@@lbl}{#2}% + % Clean the environment + \let\@ha@tmp@@lbl\undefined% } % % @@ -431,12 +442,11 @@ % same name. Leading and trailing spaces around this string will be ignored. % \newcommand*{\get@hainfo}[2][labels]{% - \begingroup% % Trim leading and trailing spaces from the identifier \edef\@ha@tmp@@id{\ha@trim{#2}}% % Make sure that there are no commas \expandafter\@ha@ifcomma\@ha@tmp@@id,\@then{% - \PackageError{hereapplies}{Comma detected in "#2"}{% + \PackageError{hereapplies}{Comma detected in "\@ha@tmp@@id"}{% It is possible to query only one single identifier at a time.% }% }{}% @@ -444,7 +454,8 @@ \expandafter\@ha@newidentifier\expandafter{\@ha@tmp@@id}% % Print the identifier's property \csname @ha@prop@@#1@\@ha@tmp@@id\endcsname% - \endgroup% + % Clean the environment + \let\@ha@tmp@@id\undefined% } % % diff --git a/macros/latex/contrib/hereapplies/lyx-module/hereapplies.module b/macros/latex/contrib/hereapplies/lyx-module/hereapplies.module index 573b49c797..eae3e13919 100644 --- a/macros/latex/contrib/hereapplies/lyx-module/hereapplies.module +++ b/macros/latex/contrib/hereapplies/lyx-module/hereapplies.module @@ -1,9 +1,10 @@ #\DeclareLyXModule[hereapplies.sty]{Here Applies} +#\DeclareCategory{Label and References} #DescriptionBegin #A module for for referencing groups of pages that share something in common. #See the hereapplies.sty LaTeX package for more information. #DescriptionEnd -#Authors: madmurphy +#Author: madmurphy Format 66 @@ -11,9 +12,9 @@ AddToPreamble \usepackage{hereapplies} EndPreamble -InsetLayout Flex:Here_applies - LyXType custom - Decoration Classic +InsetLayout "Flex:Here applies" + LyXType custom + Decoration Classic Font Family Typewriter Color black @@ -32,7 +33,7 @@ InsetLayout Flex:Here_applies MultiPar false CustomPars false ForcePlain true - PassThru true + PassThru false ParbreakIsNewline true FreeSpacing false ForceLTR true @@ -49,9 +50,9 @@ InsetLayout Flex:Here_applies EndArgument End -InsetLayout Flex:Here_applies* - LyXType custom - Decoration Classic +InsetLayout "Flex:Here applies*" + LyXType custom + Decoration Classic Font Family Typewriter Color black @@ -70,7 +71,7 @@ InsetLayout Flex:Here_applies* MultiPar false CustomPars false ForcePlain true - PassThru true + PassThru false ParbreakIsNewline true FreeSpacing false ForceLTR true @@ -87,7 +88,7 @@ InsetLayout Flex:Here_applies* EndArgument End -InsetLayout Flex:Where_applies +InsetLayout "Flex:Where applies" LyXType custom Decoration Classic Font @@ -100,7 +101,7 @@ InsetLayout Flex:Where_applies Color purple Size Small EndFont - LabelString "Applications of" + LabelString "Where applies" LatexType command LatexName whereapplies Requires hereapplies @@ -108,14 +109,14 @@ InsetLayout Flex:Where_applies MultiPar false CustomPars false ForcePlain true - PassThru true + PassThru false ParbreakIsNewline true FreeSpacing false ForceLTR true BgColor lightgray End -InsetLayout Flex:Where_applies* +InsetLayout "Flex:Where applies*" LyXType custom Decoration Classic Font @@ -128,7 +129,7 @@ InsetLayout Flex:Where_applies* Color purple Size Small EndFont - LabelString "Applications of*" + LabelString "Where applies*" LatexType command LatexName whereapplies* Requires hereapplies @@ -136,7 +137,7 @@ InsetLayout Flex:Where_applies* MultiPar false CustomPars false ForcePlain true - PassThru true + PassThru false ParbreakIsNewline true FreeSpacing false ForceLTR true diff --git a/macros/latex/contrib/hereapplies/package.json b/macros/latex/contrib/hereapplies/package.json index fa375b37a7..ae02719882 100644 --- a/macros/latex/contrib/hereapplies/package.json +++ b/macros/latex/contrib/hereapplies/package.json @@ -1,15 +1,19 @@ { "name": "hereapplies.sty", - "version": "0.7.0", + "version": "0.8.0", "description": "A LaTeX package for referencing groups of pages that share something in common", - "homepage": "https://madmurphy.github.io/hereapplies.sty", + "homepage": "https://www.ctan.org/pkg/hereapplies", "author": "madmurphy", "license": "AGPL-3.0-or-later", + "main": "hereapplies.sty", "repository": { "url": "https://github.com/madmurphy/hereapplies.sty.git" }, "src": [ - "hereapplies.sty" + "hereapplies.sty", + "hereapplies-doc.lyx", + "hereapplies-doc.tex", + "hereapplies-example.tex" ], "bugs": { "url": "https://github.com/madmurphy/hereapplies.sty/issues", @@ -20,6 +24,7 @@ "index", "latex", "latex-hyperref", + "latex-labels", "latex-package", "lyx", "lyx-module", |