* [NOT YET PULL -perfbook] Index and acronym annotation scheme
@ 2021-04-01 15:50 Akira Yokosawa
2021-04-01 18:36 ` Paul E. McKenney
0 siblings, 1 reply; 4+ messages in thread
From: Akira Yokosawa @ 2021-04-01 15:50 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: Balbir Singh, SeongJae Park, perfbook, Akira Yokosawa
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [NOT YET PULL -perfbook] Index and acronym annotation scheme
2021-04-01 15:50 [NOT YET PULL -perfbook] Index and acronym annotation scheme Akira Yokosawa
@ 2021-04-01 18:36 ` Paul E. McKenney
2021-04-02 4:27 ` Akira Yokosawa
0 siblings, 1 reply; 4+ messages in thread
From: Paul E. McKenney @ 2021-04-01 18:36 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: Balbir Singh, SeongJae Park, perfbook
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!
> 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").
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? 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. ;-)
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!!! :-/
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.
> 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 "hierarchical index list" you mention below, got it.
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}}
> 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. ;-)
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [NOT YET PULL -perfbook] Index and acronym annotation scheme
2021-04-01 18:36 ` Paul E. McKenney
@ 2021-04-02 4:27 ` Akira Yokosawa
2021-04-02 15:11 ` Paul E. McKenney
0 siblings, 1 reply; 4+ messages in thread
From: Akira Yokosawa @ 2021-04-02 4:27 UTC (permalink / raw)
To: paulmck; +Cc: Balbir Singh, SeongJae Park, perfbook
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.
>
>> 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".
> 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!
> 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.
>
> 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.
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.
>
> 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.
>
>> 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.
>
> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [NOT YET PULL -perfbook] Index and acronym annotation scheme
2021-04-02 4:27 ` Akira Yokosawa
@ 2021-04-02 15:11 ` Paul E. McKenney
0 siblings, 0 replies; 4+ messages in thread
From: Paul E. McKenney @ 2021-04-02 15:11 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: Balbir Singh, SeongJae Park, perfbook
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-04-02 15:11 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-04-01 15:50 [NOT YET PULL -perfbook] Index and acronym annotation scheme Akira Yokosawa
2021-04-01 18:36 ` Paul E. McKenney
2021-04-02 4:27 ` Akira Yokosawa
2021-04-02 15:11 ` Paul E. McKenney
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.