summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-08-14 20:27:30 +0000
committerKarl Berry <karl@freefriends.org>2022-08-14 20:27:30 +0000
commite8eab1499a1580923a76e92453fe80dc2459538d (patch)
treec70a8db9aeabcd4cb73fcfb05ecbec997650ee0d /Master/texmf-dist/doc
parentda3819b94650c1e252d285d0c3a8e821e2ec56b8 (diff)
hereapplies (14aug22)
git-svn-id: svn://tug.org/texlive/trunk@64117 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/ChangeLog.md16
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/README.md126
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/example.pngbin17734 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/example.tex36
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.pdfbin0 -> 49807 bytes
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.tex36
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies-example.lyx (renamed from Master/texmf-dist/doc/latex/hereapplies/lyx-module/lyx-module-example.lyx)40
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies.module89
-rw-r--r--Master/texmf-dist/doc/latex/hereapplies/package.json4
9 files changed, 233 insertions, 114 deletions
diff --git a/Master/texmf-dist/doc/latex/hereapplies/ChangeLog.md b/Master/texmf-dist/doc/latex/hereapplies/ChangeLog.md
index 0c8b9e934f5..0835e321b9d 100644
--- a/Master/texmf-dist/doc/latex/hereapplies/ChangeLog.md
+++ b/Master/texmf-dist/doc/latex/hereapplies/ChangeLog.md
@@ -2,11 +2,25 @@ Change Log
==========
+## 0.3.0 (2022-08-13)
+
+Changes:
+
+* A starred version of the `\whereapplies` macro has been created
+* The label generated when `\hereapplies` is invoked with two arguments has now
+ become verbatim equal to the first argument -- previously it was equal to
+ `appl:[concept]:[label]`
+* Code review
+* The LyX module has been updated
+* Documentation
+* Examples
+
+
## 0.2.0 (2022-08-12)
Changes:
-* A starred version of `\hereapplies` has been created
+* A starred version of the `\hereapplies` macro has been created
* A module for LyX has been added to the repository
* The package now prints `??` (instead of generating an error) when
`\whereapplies` is invoked but `\hereapplies` is never invoked
diff --git a/Master/texmf-dist/doc/latex/hereapplies/README.md b/Master/texmf-dist/doc/latex/hereapplies/README.md
index 4b688052d56..8ffda3cd99b 100644
--- a/Master/texmf-dist/doc/latex/hereapplies/README.md
+++ b/Master/texmf-dist/doc/latex/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
diff --git a/Master/texmf-dist/doc/latex/hereapplies/example.png b/Master/texmf-dist/doc/latex/hereapplies/example.png
deleted file mode 100644
index 89e0172cd8f..00000000000
--- a/Master/texmf-dist/doc/latex/hereapplies/example.png
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/hereapplies/example.tex b/Master/texmf-dist/doc/latex/hereapplies/example.tex
deleted file mode 100644
index 1635e73f304..00000000000
--- a/Master/texmf-dist/doc/latex/hereapplies/example.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-\documentclass{article}
-
-\usepackage{hereapplies}
-
-\begin{document}
-
-\title{Some title}
-\author{Some author}
-
-\maketitle
-
-This is concept one. To see this concept applied, please
-see \whereapplies{conceptone}.
-
-This is concept four. To see this concept applied, please
-see \whereapplies{conceptfour}.
-
-\newpage
-
-\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{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[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}.
-
-\end{document}
diff --git a/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.pdf b/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.pdf
new file mode 100644
index 00000000000..7e58c9011e3
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.tex b/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.tex
new file mode 100644
index 00000000000..18b2154e10d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/hereapplies/hereapplies-example.tex
@@ -0,0 +1,36 @@
+\documentclass{article}
+
+\usepackage{hereapplies}
+
+\begin{document}
+
+\title{Some title}
+\author{Some author}
+
+\maketitle
+
+This is concept one. To find this concept applied, please
+see \whereapplies{conceptOne}.
+
+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
+one'' 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
+one'' 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
+see, ``concept one'' applies here. This point in the document is
+labeled \texttt{myref}.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/hereapplies/lyx-module/lyx-module-example.lyx b/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies-example.lyx
index 2b12bf2e48d..0b9e259dca8 100644
--- a/Master/texmf-dist/doc/latex/hereapplies/lyx-module/lyx-module-example.lyx
+++ b/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies-example.lyx
@@ -101,12 +101,12 @@ Some author
\begin_layout Standard
This is concept one.
- To see this concept applied, please see
-\begin_inset Flex Where Applies
+ To find this concept applied, please see
+\begin_inset Flex Where applies
status open
\begin_layout Plain Layout
-conceptone
+conceptOne
\end_layout
\end_inset
@@ -115,13 +115,13 @@ conceptone
\end_layout
\begin_layout Standard
-This is concept four.
- To see this concept applied, please see
-\begin_inset Flex Where Applies
+This is concept two.
+ To find this concept applied, please see
+\begin_inset Flex Where applies
status open
\begin_layout Plain Layout
-conceptfour
+conceptTwo
\end_layout
\end_inset
@@ -137,11 +137,11 @@ conceptfour
\end_layout
\begin_layout Standard
-\begin_inset Flex Here Applies
+\begin_inset Flex Here applies
status open
\begin_layout Plain Layout
-conceptone
+conceptOne
\end_layout
\end_inset
@@ -176,11 +176,11 @@ concept one
\end_layout
\begin_layout Standard
-\begin_inset Flex Here Applies
+\begin_inset Flex Here applies
status open
\begin_layout Plain Layout
-conceptfour
+conceptTwo
\end_layout
\end_inset
@@ -203,7 +203,7 @@ thepage
\begin_inset Quotes eld
\end_inset
-concept four
+concept two
\begin_inset Quotes erd
\end_inset
@@ -215,11 +215,11 @@ concept four
\end_layout
\begin_layout Standard
-\begin_inset Flex Here Applies
+\begin_inset Flex Here applies
status open
\begin_layout Plain Layout
-conceptone
+conceptOne
\end_layout
\end_inset
@@ -254,11 +254,11 @@ concept one
\end_layout
\begin_layout Standard
-\begin_inset Flex Here Applies
+\begin_inset Flex Here applies
status open
\begin_layout Plain Layout
-conceptfour
+conceptTwo
\end_layout
\end_inset
@@ -281,7 +281,7 @@ thepage
\begin_inset Quotes eld
\end_inset
-concept four
+concept two
\begin_inset Quotes erd
\end_inset
@@ -293,7 +293,7 @@ concept four
\end_layout
\begin_layout Standard
-\begin_inset Flex Here Applies
+\begin_inset Flex Here applies
status open
\begin_layout Plain Layout
@@ -306,7 +306,7 @@ myref
\end_inset
-conceptone
+conceptOne
\end_layout
\end_inset
@@ -336,7 +336,7 @@ concept one
applies here.
This point in the document is labeled
\family typewriter
-appl:conceptone:myref
+myref
\family default
.
\end_layout
diff --git a/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies.module b/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies.module
index b19419024cd..6d927540ca7 100644
--- a/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies.module
+++ b/Master/texmf-dist/doc/latex/hereapplies/lyx-module/hereapplies.module
@@ -1,6 +1,6 @@
#\DeclareLyXModule[hereapplies.sty]{Here Applies}
#DescriptionBegin
-#A module for cross-linking applications of concepts.
+#A module for cross-linking concepts to their applications.
#See the hereapplies.sty LaTeX package for more information.
#DescriptionEnd
#Authors: madmurphy
@@ -11,75 +11,79 @@ AddToPreamble
\usepackage{hereapplies}
EndPreamble
-InsetLayout Flex:Here_Applies
+InsetLayout Flex:Here_applies
LyXType custom
Decoration Classic
- LabelString "Applies"
- LatexType command
- LatexName hereapplies
- Requires hereapplies
- ForcePlain 1
- MultiPar 0
- NoInsetLayout 1
- BgColor lightgray
Font
+ Family Typewriter
Color black
Size Small
EndFont
LabelFont
+ Family Serif
Color teal
Size Small
EndFont
+ LabelString "Here applies"
+ LatexType command
+ LatexName hereapplies
+ Requires hereapplies
+ ForcePlain 1
+ MultiPar 0
+ NoInsetLayout 1
+ BgColor lightgray
Argument 1
+ Decoration Classic
LabelString "Label"
- MenuString "Occurrence label"
- Tooltip "A string that will used to build a reference label in the form “appl:concept:label”"
+ MenuString "Instance label"
+ Tooltip "A string that will become the label of the instance (which can be referenced with \ref, \pageref, etc.)"
Mandatory 0
- LabelFont
- Color blue
- EndFont
- Font
- Color red
- EndFont
EndArgument
End
-InsetLayout Flex:Here_Applies*
+InsetLayout Flex:Here_applies*
LyXType custom
Decoration Classic
- LabelString "Applies*"
- LatexType command
- LatexName hereapplies*
- Requires hereapplies
- ForcePlain 1
- MultiPar 0
- NoInsetLayout 1
- BgColor lightgray
Font
+ Family Typewriter
Color black
Size Small
EndFont
LabelFont
+ Family Serif
Color teal
Size Small
EndFont
+ LabelString "Here applies*"
+ LatexType command
+ LatexName hereapplies*
+ Requires hereapplies
+ ForcePlain 1
+ MultiPar 0
+ NoInsetLayout 1
+ BgColor lightgray
Argument 1
+ Decoration Classic
LabelString "Label"
- MenuString "Occurrence label"
- Tooltip "A string that will used to build a reference label in the form “appl:concept:label”"
+ MenuString "Instance label"
+ Tooltip "A string that will become the label of the instance (which can be referenced with \ref, \pageref, etc.)"
Mandatory 0
- LabelFont
- Color blue
- EndFont
- Font
- Color red
- EndFont
EndArgument
End
-InsetLayout Flex:Where_Applies
+InsetLayout Flex:Where_applies
LyXType custom
Decoration Classic
+ Font
+ Family Typewriter
+ Color black
+ Size Small
+ EndFont
+ LabelFont
+ Family Serif
+ Color green
+ Size Small
+ EndFont
LabelString "Applications of"
LatexType command
LatexName whereapplies
@@ -88,6 +92,11 @@ InsetLayout Flex:Where_Applies
MultiPar 0
NoInsetLayout 1
BgColor lightgray
+End
+
+InsetLayout Flex:Where_applies*
+ LyXType custom
+ Decoration Classic
Font
Family Typewriter
Color black
@@ -98,5 +107,13 @@ InsetLayout Flex:Where_Applies
Color green
Size Small
EndFont
+ LabelString "Applications of*"
+ LatexType command
+ LatexName whereapplies*
+ Requires hereapplies
+ ForcePlain 1
+ MultiPar 0
+ NoInsetLayout 1
+ BgColor lightgray
End
diff --git a/Master/texmf-dist/doc/latex/hereapplies/package.json b/Master/texmf-dist/doc/latex/hereapplies/package.json
index 0c3d6dd1eb8..b74ebec02cd 100644
--- a/Master/texmf-dist/doc/latex/hereapplies/package.json
+++ b/Master/texmf-dist/doc/latex/hereapplies/package.json
@@ -1,7 +1,7 @@
{
"name": "hereapplies.sty",
- "version": "0.2.0",
- "description": "A LaTeX package for cross-linking applications of concepts",
+ "version": "0.3.0",
+ "description": "A LaTeX package for cross-linking concepts to their applications",
"homepage": "https://madmurphy.github.io/hereapplies.sty",
"author": "madmurphy",
"license": "AGPL-3.0-or-later",