diff options
Diffstat (limited to 'macros/latex/contrib/hereapplies/hereapplies-doc.lyx')
-rw-r--r-- | macros/latex/contrib/hereapplies/hereapplies-doc.lyx | 1116 |
1 files changed, 1116 insertions, 0 deletions
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 |