summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hereapplies/hereapplies-doc.lyx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hereapplies/hereapplies-doc.lyx')
-rw-r--r--macros/latex/contrib/hereapplies/hereapplies-doc.lyx1116
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