On Fri, Apr 02, 2021 at 01:27:50PM +0900, Akira Yokosawa wrote:
> On Thu, 1 Apr 2021 11:36:40 -0700, Paul E. McKenney wrote:
> > On Fri, Apr 02, 2021 at 12:50:01AM +0900, Akira Yokosawa wrote:
> >> Hi all,
> >>
> >> This is a RFC of my attempt on indexing scheme in the form of a pull
> >> request.
> >
> > I fired it up on my incoming laptop, which runs Ubuntu 20.04.
> > It built without errors. (Yes, I need to get moved over to
> > that laptop, much easier.)
> >
> >> 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.
> >
> > And I do see them. Looks good!
> >
> >> 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.
> >
> > It sounds like getting this working was quite a process!
>
> Mostly done while -rc stage of Second Edition.
It did take some time then. Thank you for doing it!
> >> 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).
> >
> > Let me see if I understand it. ;-)
> >
> > There is a new glsdict.tex that defines some dazzling macros and then
> > defines the acronyms using \newacronym. This takes three arguments,
> > the tag used to select the acronym (e.g., "cas"), the printed form of the
> > acronym (e.g., "CAS"), and the full version (e.g., "compare-and-swap").
>
> They call the third argument "long form".
> Combination of "long form" + (short form) is called "full form".
Got it!
> > With this definition, \acr{cas} prints "CAS", \IXacr{cas} prints
> > "compare-and-swap (CAS)" with italics, and \IXacrf{cas} does the same,
> > but without italics. Presumably the first \acr{cas} would include the
> > expansion of the acronym?
>
> You are right here!
Don't worry, it won't happen again.
> > It appears that \glsunset{cas} prevents the
> > first occurrence from including the expansion.
> >
> > In my younger days, I might have objected to the tag and the printed
> > form being different, but as my fingers get older, they do appreciate
> > fewer trips to the SHIFT key. ;-)
>
> I chose the lower-case key to ease the search of not-yet-annotated
> acronyms.
Even better!
I am not brave enough to want "CPU" in the acronym list. For one thing,
there are a -lot- of instances. For another, there are probably way
more people who know what a CPU is than know what a central processing
unit is...
> > The "compare-and-swap" is interesting. If the first use was (say)
> > "\acr{cas} operation", this would be correct. However, if the first
> > use was instead "Use a \acr{cas} to update \co{foo}", the hyphens
> > would no longer be correct.
> >
> > I have no reasonable ideas on how to handle this. One possibly
> > unreasonable idea would be to have a fourth argument to the
> > \newacronym{} macro, and use something like \acrmod{} to select
> > the modifier form, that is, the one having the hyphens. Automatically
> > removing the hyphens gets complicated. For example:
> >
> > Use a compare-and-swap (CAS) operation!
> > The only reasonable choice is compare and swap (CAS).
> > We use read-copy update (RCU).
> > We use the read-copy-update (RCU) synchronization mechanism.
> >
> > English!!! :-/
>
> Hmm...
>
> Maybe by using two categories of acronym dictionary, one is for
> normal (noun) usage, and another for modifier usage.
> Modifier usages will not be included in the "Acronyms" pages.
>
> Most acronyms' first appearances are (hopefully) normal nouns,
> I suppose.
>
> Indexing of acronyms are collectively done as normal nouns.
>
> I'll see if this can really be done.
Another approach might be to have a given acronym used consistently
either as a noun or an adjective, but not both. So maybe replace all
"CAS operations" with "CASes". In some cases, this would probably be
quite awkward, though. Might be awkward for CAS as well, for that matter.
> Anyway, I need to amend and reorder commits for the rewritten
> scheme would look like as if it were implemented in that way
> from the beginning.
>
> Will send another pull request when it gets ready.
Sounds good!
> > It might be necessary to tweak the definition depending on the
> > type of first use. Sounds painful, though.
> >
> > Thoughts?
> >
> >> 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{} ...
> >
> > I am guessing that \acrpl{} is for plural, and that capitalizing the first
> > letter as in \Acr{} is for when the acronym is the first word in a sentence.
>
> You are right. I'm afraid a lot of variants can cause typos in their
> uses, though.
> "These \acrpl{nmi} are handled by xxx." might look incorrect until you
> are well accustomed to those macros.
I am afraid that I can promise the occasional "\acr{nmi}s". Which would
almost always work... :-/
> >> To add index annotations for acronyms, use \IXacr{}, \IXacrpl{}, etc.
> >
> > I am lost on \IXh{}, but many of them are documented at their definition.
> > Oh, does \IXh{} make this sort of index entry?
> >
> > Capacity miss, see Cache miss, capacity
> >
> > Oh, this is the list" you mention below, got it.
>
> I'm not that sure the "hierarchical indexing" is really worthwhile
> to maintain. You might have not noticed, IXh{}{} macro can generate
> info for either the single-layer or the two-layer indexing depending
> to the boolean "indexhier". We can easily fall back to the single-layer
> scheme.
It is good to have that flexibility.
Thanx, Paul
> > And you can index within epigraphs, it appears. For example, in
> > future/fp.tex:
> >
> > \epigraph{The curious failure of \IX{functional programming} for parallel
> > applications.}
> > {\emph{Malte Skarupke}}
>
> Nice!
>
> >
> >> 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.
> >
> > Ah, that could be helpful.
> >
> >> 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!
> >
> > Let's not have an index entry that refers to itself. ;-)
>
> Indeed ;-) ;-).
>
> Thanks, Akira
>
> >
> > Thanx, Paul
> >
> >> 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
