summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hereapplies/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hereapplies/README.md')
-rw-r--r--macros/latex/contrib/hereapplies/README.md126
1 files changed, 107 insertions, 19 deletions
diff --git a/macros/latex/contrib/hereapplies/README.md b/macros/latex/contrib/hereapplies/README.md
index 4b688052d5..8ffda3cd99 100644
--- a/macros/latex/contrib/hereapplies/README.md
+++ b/macros/latex/contrib/hereapplies/README.md
@@ -1,13 +1,49 @@
-hereapplies.sty
-===============
+Here Applies
+============
-A LaTeX package for cross-linking applications of concepts
+A LaTeX package for cross-linking concepts to their applications
+
+
+Overview
+--------
+
+**Here Applies** is a LaTeX package that implements an _informal glossary_. Its
+core mechanism is identical to that of a conventional glossary – i.e. some
+concepts are marked as “important” and indicized every time they appear in the
+document – but it does not produce any nomenclature section, nor relies on the
+conventions that normally take part in a glossary.
+
+In fact, normally, besides an indicization mechanism, a proper glossary should
+be able to produce a dedicated section (usually at the end of the document)
+where the terms are collected in alphabetical order, their definitions are
+shown, and the lists of their occurrences are presented. By design, all these
+things but the last one are missing in **Here Applies**.
+
+Instead, the package offers only two macros: `\hereapplies` and `\whereapplies`
+(plus their “starred” versions `\hereapplies*` and `\whereapplies*`). In both
+cases a “concept name” is passed as argument – and this can be any string
+invented in the moment, as long as it contains only letters.
+
+Every time `\hereapplies` is invoked again on an identical string the document
+knows that the same concept from previous invocations is occurring at that
+point. And so every time the `\whereapplies` macro is invoked, all the
+occurrences of that concept within the entire document will be printed in the
+form of a linkable page number list (“pp. 1, 2, 3, 4, …”).
+
+As `\hereapplies` is designed to be invoked in the middle of a chapter or a
+section and make it linkable, the `\phantomsection` macro is invoked by default
+before a label is added to that place. To avoid calling `\phantomsection`,
+the “starred” macro `\hereapplies*` is available.
+
+Finally, like `\whereapplies` resembles a pluralizable version of `\pageref`,
+its “starred” version `\whereapplies*` resembles a pluralizable version of
+`\pageref*`.
Example usage
-------------
-### LaTeX source
+The following LaTeX manuscript
``` tex
\documentclass{article}
@@ -21,37 +57,89 @@ Example usage
\maketitle
-This is concept one. To see this concept applied, please
-see \whereapplies{conceptone}.
+This is concept one. To find this concept applied, please
+see \whereapplies{conceptOne}.
-This is concept four. To see this concept applied, please
-see \whereapplies{conceptfour}.
+This is concept two. To find this concept applied, please
+see \whereapplies{conceptTwo}.
\newpage
-\hereapplies{conceptone}This is page \thepage. As you can see, ``concept
+\hereapplies{conceptOne}This is page \thepage. As you can see, ``concept
one'' applies here.\newpage
-\hereapplies{conceptfour}This is page \thepage. As you can see,
-``concept four'' applies here.\newpage
+\hereapplies{conceptTwo}This is page \thepage. As you can see,
+``concept two'' applies here.\newpage
-\hereapplies{conceptone}This is page \thepage. As you can see, ``concept
+\hereapplies{conceptOne}This is page \thepage. As you can see, ``concept
one'' applies here.\newpage
-\hereapplies{conceptfour}This is page \thepage. As you can see,
-``concept four'' applies here.\newpage
+\hereapplies{conceptTwo}This is page \thepage. As you can see,
+``concept two'' applies here.\newpage
-\hereapplies[myref]{conceptone}This is page \thepage. As you can
+\hereapplies[myref]{conceptOne}This is page \thepage. As you can
see, ``concept one'' applies here. This point in the document is
-labeled \texttt{appl:conceptone:myref}.
+labeled \texttt{myref}.
\end{document}
```
-### Result
+will generate [this document][1].
+
+
+A minimal tutorial
+------------------
+
+### Macro `\hereapplies[label]{concept_name}`
+
+The `\hereapplies` macro notifies the document that a particular concept
+applies to a particular point and creates a label for it.
+
+If the optional argument is passed the label created will be named accordingly,
+otherwise an opaque name will be assigned to it. This argument may contain only
+what is legal in both `\label` and `\pageref`.
+
+The `concept_name` argument may contain only letters and the “at” sign (`@`).
+
+The “starred” version of this macro (`\hereapplies*`) does not invoke the
+`\phantomsection` directive.
+
+
+### Macro `\whereapplies{concept_name}`
+
+The `\whereapplies` macro prints all the occurrences of a concept, in the form
+“p. …” or “pp. …”
+
+The `concept_name` argument may contain only letters and the “at” sign (`@`).
+
+The “starred” version of this macro (`\whereapplies*`) will use `\pageref*`
+instead of `\pageref` for generating the page list.
+
+
+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].
+
+
+Free software
+-------------
-![Example of hereapplies LaTeX package][1]
+**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.
- [1]: example.png
+ [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
+ [6]: COPYING