Hi all,
This is a RFC of my attempt on indexing scheme in the form of a pull
request.
Change history is not yet straightened out.
Also, commit titles have quite a few typos. I'll fix them by the
final pull request.
Now, "Acronyms", "Index", and "API Index" pages are generated by
default, except for the target -df.
The scheme for acronyms introduced in the first commit is repeatedly
updated in later commits, and almost rewritten in commits
"acronym: Use glossaries-extra way of defining custom acronym style",
"acronym: Make pf-long-short style similar to 'long-em-short'", and
"acronym: Refactor macros to annotate acronyms".
Also, it turns out that the rewritten scheme is incompatible with
glossaries-extra of TeX Live 2017/Debian on Ubuntu Bionic.
So I added the required version of glossaries-extra in commit
"FAQ-BUILD: Ubuntu Bionic needs up-to-date glossaries-extra".
In this commit, install_latex_package.sh is also updated so that
glossaries-extra can be installed by it. Hence +CC: SeongJae.
Restructuring of make targets are done in some of the later commits
"EXP Makefile: (help text only) Refactor build targets" and
"Makefile: Update rules to reflect help text".
New make targets can be listed by "make help" and "make help-full".
While I have tested most of the targets, I'd like Balbir to double
check if ebook-size build works as expected. Hence +CC: Balbir.
Paul, I'd like you to see if the annotations added in LaTeX sources
look reasonable (not too complex).
I know I need to prepare documentation on how to annotate, which
I have not done yet.
Almost all the annotations are done by macros defined in
the preamble. There are a variety of slightly different macros
such as \IX{}, \IXh{}{}, \IXalt{}{}, and so on.
For acronyms, there are \acr{}, \acrpl{}, \Acr{}, \Acrpl{} ...
To add index annotations for acronyms, use \IXacr{}, \IXacrpl{}, etc.
My idea is to tweak definitions of these macros if there need
some changes in their appearance, if ever.
Acronyms are defined in glsdict.tex.
First use of an acronym is expanded to "\emph{long name} (SHORTNAME)".
Later uses are expanded to "SHORTNAME" only.
Long name can be extracted by \acrl{} and their variants.
If first use form is preferable in a later position,
you can use \acrfst{} and its friends.
As for hierarchical index list, I have some terms indexed as
such. For example, "Code locking" is indexed as "Locking, code"
in the Index page. The entry of "Code locking" has "see Locking code".
Furthermore, acronyms in index list can have second level
entries. Current scheme for doing it is not elegant, but
at least doable. See commit
"EXP index: Apply two-level index scheme around acronym to RCU variants".
Any feedback and question is more than welcome!
Thanks, Akira
------------
The following changes since commit 3f2f8d91e68e21cce46d2608dc6df611d126ff98:
summary: Unpin Figure 18.1 in 1c builds (2021-03-31 18:13:49 -0700)
are available in the Git repository at:
https://github.com/akiyks/perfbook.git tags/index-2021.04.01a
for you to fetch changes up to d6a2a4961c3dce3b9cdb53b1d847f464cfea1d03:
FAQ-BUILD: Ubuntu Bionic needs up-to-date glossaries-extra (2021-04-01 19:40:47 +0900)
----------------------------------------------------------------
Akira Yokosawa (40):
index: Add acronym index by 'glossaries-extra' package
future/htm: Annotate TM, HTM, STM, and RCU via acronym dictionary
index: Add macro to automatic capitalizatin into index
future/htm: Use \acrl{} and \IXacrl{} macro for 'transactional lock elision'
rcurelated: Add acronym annotation for CBMC
index: PoC of two-level hierarchical index
index, glossary: Replace \index{} macro with \IX{} and its variants
index, acronym: Annotatieo IPI using \IXacr{}, \acr{}, etc.
index: Annotate 'data race', 'plain access', and 'marked access'
index: Annotate 'atomic read-modify-write operation'
index: Annotate 'cache associativity'
index: Annotate 'direct-mapped cache'
index: Annotate 'cache miss' related terms
index: Annotate acronym of 'CAS'
acronym: Put plural 's' to short form acronym in 1st appearance
index: whymb: Add/Fix cache related annotations
index, whymb, glossary: Annotate 'cache-coherence protocol'
index, cpu: Annotate 'cache-coherency protocol' as 'cache-coherence protocol'
index, memorder: Annotate 'Cache coherence'
index: Annotate 'single-copy atomic' and 'multicopy atomic'
index: Annotate 'atomic', take one
index: Annotete 'locking' and 'lock' related terms
Use 2c-layout for acronyms in both 1c- and 2c- layout builds
acronym: Annotate QSBR and EBR
index, perfbook-lt: Put index marker at the head of indexed terms
acronym: Annotate 'MPI', 'SQL', 'UPC', and 'TM' related acronyms
acronym: Annotate 'NBS'
acronym: Annotete 'non-blocking synchronization' using acronym key 'nbs'
acronym, perfbook-lt: Define macros for plural of full form
acromyn: Annotate 'DSP', 'FPGA', and 'GPGPU'
acronym: Annotate 'IRQ' and 'NMI'
perfbook-lt: Remove macro definition '\IRQ'
acronym: Use glossaries-extra way of defining custom acronym style
acronym: Make pf-long-short style similar to 'long-em-short'
acronym: Refactor macros to annotate acronyms
EXP index: Apply two-level index scheme around acronym to RCU variants
EXP Makefile: (help text only) Refactor build targets
Makefile: Update rules to reflect help text
FAQ-BUILD: Drop Ubuntu Xenial from build environment
FAQ-BUILD: Ubuntu Bionic needs up-to-date glossaries-extra
Paul E. McKenney (1):
Glossary: Add an entry for "Plain Access"
.gitignore | 8 +
FAQ-BUILD.txt | 51 ++----
Makefile | 133 ++++++++------
SMPdesign/SMPdesign.tex | 39 ++---
SMPdesign/beyond.tex | 8 +-
SMPdesign/criteria.tex | 12 +-
SMPdesign/partexercises.tex | 8 +-
advsync/advsync.tex | 68 ++++----
advsync/rcu.tex | 2 +-
advsync/rt.tex | 14 +-
appendix/questions/concurrentparallel.tex | 2 +-
appendix/whymb/whymemorybarriers.tex | 56 +++---
count/count.tex | 20 +--
cpu/cpu.tex | 4 +-
cpu/hwfreelunch.tex | 4 +-
cpu/overheads.tex | 59 +++----
cpu/overview.tex | 12 +-
cpu/swdesign.tex | 8 +-
datastruct/datastruct.tex | 2 +-
debugging/debugging.tex | 3 +-
defer/hazptr.tex | 2 +-
defer/rcu.tex | 6 +-
defer/rcuapi.tex | 5 +-
defer/rcufundamental.tex | 4 +-
defer/rcuintro.tex | 13 +-
defer/rcurelated.tex | 19 +-
defer/rcuusage.tex | 41 ++---
defer/whichtochoose.tex | 11 +-
formal/dyntickrcu.tex | 110 ++++++------
formal/ppcmem.tex | 5 +-
future/cpu.tex | 12 +-
future/htm.tex | 279 +++++++++++++++---------------
future/tm.tex | 241 +++++++++++++-------------
glossary.tex | 170 +++++++++---------
glsdict.tex | 94 ++++++++++
indexsee.tex | 17 ++
intro/intro.tex | 29 ++--
locking/locking.tex | 23 +--
memorder/memorder.tex | 70 ++++----
owned/owned.tex | 12 +-
perfbook-lt.tex | 118 +++++++++++--
summary.tex | 4 +-
together/refcnt.tex | 6 +-
toolsoftrade/toolsoftrade.tex | 74 ++++----
utilities/install_latex_package.sh | 4 +-
utilities/runlatex.sh | 1 +
46 files changed, 1070 insertions(+), 813 deletions(-)
create mode 100644 glsdict.tex
create mode 100644 indexsee.tex
