* [NOT PULL YET -perfbook] PoC of adding index to perfbook
@ 2020-11-22 15:14 Akira Yokosawa
2020-11-23 21:06 ` Paul E. McKenney
0 siblings, 1 reply; 11+ messages in thread
From: Akira Yokosawa @ 2020-11-22 15:14 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Hi Paul,
So this *not-pull* request is to show you my WIP branch to add indices
to perfbook.
Patch 1/7 kicks of the changes by adding index annotations in Glossary.
Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
Credits, and the newly added Index belong there.
I employed "tocbibind" package to include Bibliography in TOC.
Patch 3/7 adds API Index. Annotations for the Index is mostly done in
toolsoftrade.
You can see that raw \index or \sindex macros are avoided in .tex source
files. Using custom macros for annotation can reduce diffs in adding
annotations.
glossary.tex is an exception, as every description item has
\index{} on it. If we add other annotations there, we need to use
custom macros.
Patch 4/7 adds annotations for people's names. They could be in another
independent index, but they are merged into the general index.
As a result, the ratio of people's names in the index is quite high at the
moment.
It will decrease as we add annotations for general terms/words.
Names are presented in the index in the form of "surname, forename" order.
To enable this, annotation is done by \ppl{forename}{surname}.
When you need only surname in the text, use \pplsur macro instead.
For names with abbreviated middle name, there is a \pplmdl command as
well.
Patch 5/7 highlights indexed words/terms/names in the text.
This should help us in finding out what needs to be annotated.
If the color of DarkGreen is problematic for you, please let me know
which color is easy for you.
One of the purpose of avoiding raw \index{} macros for annotation is
to realize this coloring.
Patch 6/7 adds a few more annotations of people's names in "formal".
Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
As mentioned in the change log, API Index shows a minor glitches of
extraneous line folding caused by the side effect of \co{} macro.
This issue has been fixed in the most recent LaTeX released on 2020-10-01.
I have not figured out if there is some workaround for older LaTeX.
The appearance of index pages does not matter so much at the moment,
I suppose. We need to add annotations first.
To do that, we need to agree the organization of index pages.
Current indices are flat.
LaTeX indexing framework supports up to 3 levels of hierarchy.
For example:
Flat index
Critical section, <page>
...
Read-side critical section, <page>
...
Write-side critical section, <page>
2 level index
Critical section, <page>
read-side, <page>
write-size, <page>
...
Read-side critical section, see Critical section, read-side
...
Write-side critical section, see Critical section, write-side
Which do you prefer?
Another point on people's names.
I'm *not* thinking of making index of authors of Bibliography.
Due to the amount of cited material, it will require a ton of cleanups
in .bib files if you want the author index to look consistent.
Which means, you need to mention names of authors who you want to see
in the index. Does this sound reasonable to you?
I know you are debugging/analyzing/testing RCU and lockdep interaction
right now.
I'm not in a hurry and looking forward to your feedback.
Thanks, Akira
--
The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
are available in the Git repository at:
https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
index: Trial of 3 column (2020-11-22 23:16:58 +0900)
----------------------------------------------------------------
Akira Yokosawa (7):
PoC of indexing
Reorganize backmatters
PoC of additional API Index
index: Add annotations to people's names for PoC
Color indexed text conditionally
index: Add some more people index annotations in 'formal'
index: Trial of 3 column
.gitignore | 3 +
Makefile | 10 +-
SMPdesign/SMPdesign.tex | 2 +-
SMPdesign/partexercises.tex | 5 +-
appendix/ack/ack.tex => ack.tex | 6 +-
appendix/appendix.tex | 20 --
count/count.tex | 2 +-
cpu/cpu.tex | 3 +-
cpu/hwfreelunch.tex | 6 +-
cpu/overview.tex | 4 +-
datastruct/datastruct.tex | 4 +-
debugging/debugging.tex | 5 +-
defer/rcurelated.tex | 92 +++++----
defer/rcuusage.tex | 3 +-
formal/axiomatic.tex | 4 +-
formal/ppcmem.tex | 7 +-
formal/spinhint.tex | 2 +-
future/cpu.tex | 12 +-
future/tm.tex | 2 +-
glossary.tex | 112 +++++------
howto/howto.tex | 37 ++--
intro/intro.tex | 8 +-
memorder/memorder.tex | 6 +-
perfbook-lt.tex | 75 ++++++-
toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
utilities/runlatex.sh | 2 +
26 files changed, 470 insertions(+), 382 deletions(-)
rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-22 15:14 [NOT PULL YET -perfbook] PoC of adding index to perfbook Akira Yokosawa
@ 2020-11-23 21:06 ` Paul E. McKenney
2020-11-23 21:15 ` Paul E. McKenney
2020-11-23 22:29 ` Akira Yokosawa
0 siblings, 2 replies; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-23 21:06 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> Hi Paul,
>
> So this *not-pull* request is to show you my WIP branch to add indices
> to perfbook.
>
> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
>
> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
> Credits, and the newly added Index belong there.
> I employed "tocbibind" package to include Bibliography in TOC.
>
> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
> toolsoftrade.
> You can see that raw \index or \sindex macros are avoided in .tex source
> files. Using custom macros for annotation can reduce diffs in adding
> annotations.
> glossary.tex is an exception, as every description item has
> \index{} on it. If we add other annotations there, we need to use
> custom macros.
>
> Patch 4/7 adds annotations for people's names. They could be in another
> independent index, but they are merged into the general index.
> As a result, the ratio of people's names in the index is quite high at the
> moment.
> It will decrease as we add annotations for general terms/words.
> Names are presented in the index in the form of "surname, forename" order.
> To enable this, annotation is done by \ppl{forename}{surname}.
> When you need only surname in the text, use \pplsur macro instead.
> For names with abbreviated middle name, there is a \pplmdl command as
> well.
>
> Patch 5/7 highlights indexed words/terms/names in the text.
> This should help us in finding out what needs to be annotated.
> If the color of DarkGreen is problematic for you, please let me know
> which color is easy for you.
> One of the purpose of avoiding raw \index{} macros for annotation is
> to realize this coloring.
>
> Patch 6/7 adds a few more annotations of people's names in "formal".
>
> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
> As mentioned in the change log, API Index shows a minor glitches of
> extraneous line folding caused by the side effect of \co{} macro.
> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
> I have not figured out if there is some workaround for older LaTeX.
Nice start!
This is in the "lt" flavor only, correct? The default "make" generates
the perfbook.ind file, but does not include it. But "make lt" doesn't
either. Trying again setting the "toindex" boolean to "true", which does
in fact generate a pair of three-column indexes at the end, very good!
> The appearance of index pages does not matter so much at the moment,
> I suppose. We need to add annotations first.
Agreed, the annotations will be a big job. I have a small patch
at the end for minor typos as well.
> To do that, we need to agree the organization of index pages.
> Current indices are flat.
> LaTeX indexing framework supports up to 3 levels of hierarchy.
>
> For example:
>
> Flat index
>
> Critical section, <page>
> ...
> Read-side critical section, <page>
> ...
> Write-side critical section, <page>
>
> 2 level index
>
> Critical section, <page>
> read-side, <page>
> write-size, <page>
> ...
> Read-side critical section, see Critical section, read-side
> ...
> Write-side critical section, see Critical section, write-side
>
> Which do you prefer?
I have a minor preference for the 2-level index. However, it might or
might not be worth it. For example, should "Associativity" be on its own,
or under "Cache"? Or in both places?
> Another point on people's names.
> I'm *not* thinking of making index of authors of Bibliography.
> Due to the amount of cited material, it will require a ton of cleanups
> in .bib files if you want the author index to look consistent.
>
> Which means, you need to mention names of authors who you want to see
> in the index. Does this sound reasonable to you?
That makes a lot of sense!
> I know you are debugging/analyzing/testing RCU and lockdep interaction
> right now.
But sometimes one must take a break. And I am hoping to make more
progress on updating the last few graphs this week. It turns out that
there are interesting interactions between userspace RCU's call_rcu()
worker threads and jemalloc(), for example. The surprise, especially to
the jemalloc() folks is that jemalloc() doesn't help much, even if the
call_rcu() worker threads to a throw-away allocation to help jemalloc()
realize that it must create caches for those worker threads.
It is possible that this is a consequence of the fact that the bottleneck
for large RCU-protected hash tables is in the L3 cache rather than in
any particular CPU. Which is an unexpected benefit, as this situation
clearly calls attention to the possibility of this type of bottleneck.
Not so good for second-edition schedule, though!
> I'm not in a hurry and looking forward to your feedback.
I am going to list a few additional index entries: CPU, memory, I/O,
multicore, synchronization, cache hit, Moore's Law free lunch, speed of
light, 3D integration, accelerators, CAS, socket, core, thread (hardware
and software), simultaneous multithreading, hyperthreading, interconnect,
interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
IPI?), locality of reference (spatial and temporal), cache prefetching,
cache alignment, cache ways, read-mostly replication, partitioning,
out-of-order execution, super-scalar CPU, hardware transactional memory,
software transactional memory, hazard pointers, reference counters,
lockless, the various counter algorithms, object oriented, object oriented
spaghetti code, stall (for example, pipeline stall due to a cache miss),
double-ended queue, maze (or maze solving), branch prediction, atomic
instructions, atomic read-modify-write instructions, memory barrier,
distributed-system parallelism (as opposed to shared-memory parallelism),
communications miss (of caches), herd (the LKMM tool), coherence order,
reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
and much more, but that is enough for now.
Should the index expand acronyms? Hennessy and Patterson do for some
acronyms but not others, so we can justify being inconsistent if we
would like.
You might argue that some of these need glossary entries, and you
would be quite right. ;-)
In other news, I am considering bringing back the quantum-computing
section given that things seem to have stabilized a bit. But it is
still a bit off-topic.
Again, great start on the index!
Thanx, Paul
> Thanks, Akira
>
> --
> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>
> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>
> are available in the Git repository at:
>
> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
>
> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
>
> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
>
> ----------------------------------------------------------------
> Akira Yokosawa (7):
> PoC of indexing
> Reorganize backmatters
> PoC of additional API Index
> index: Add annotations to people's names for PoC
> Color indexed text conditionally
> index: Add some more people index annotations in 'formal'
> index: Trial of 3 column
>
> .gitignore | 3 +
> Makefile | 10 +-
> SMPdesign/SMPdesign.tex | 2 +-
> SMPdesign/partexercises.tex | 5 +-
> appendix/ack/ack.tex => ack.tex | 6 +-
> appendix/appendix.tex | 20 --
> count/count.tex | 2 +-
> cpu/cpu.tex | 3 +-
> cpu/hwfreelunch.tex | 6 +-
> cpu/overview.tex | 4 +-
> datastruct/datastruct.tex | 4 +-
> debugging/debugging.tex | 5 +-
> defer/rcurelated.tex | 92 +++++----
> defer/rcuusage.tex | 3 +-
> formal/axiomatic.tex | 4 +-
> formal/ppcmem.tex | 7 +-
> formal/spinhint.tex | 2 +-
> future/cpu.tex | 12 +-
> future/tm.tex | 2 +-
> glossary.tex | 112 +++++------
> howto/howto.tex | 37 ++--
> intro/intro.tex | 8 +-
> memorder/memorder.tex | 6 +-
> perfbook-lt.tex | 75 ++++++-
> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> utilities/runlatex.sh | 2 +
> 26 files changed, 470 insertions(+), 382 deletions(-)
> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-23 21:06 ` Paul E. McKenney
@ 2020-11-23 21:15 ` Paul E. McKenney
2020-11-23 22:29 ` Akira Yokosawa
1 sibling, 0 replies; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-23 21:15 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Mon, Nov 23, 2020 at 01:06:21PM -0800, Paul E. McKenney wrote:
> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> > Hi Paul,
> >
> > So this *not-pull* request is to show you my WIP branch to add indices
> > to perfbook.
And this time with the promised patch.
Thanx, Paul
------------------------------------------------------------------------
diff --git a/glossary.tex b/glossary.tex
index 386946e..8270945 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -153,7 +153,7 @@
\item[Direct-Mapped Cache:]\index{Direct-mapped cache}
A cache with only one way, so that it may hold only one cache
line with a given hash value.
-\item[Embarrassingly Parallel:]\index{Embarrassingly parellel}
+\item[Embarrassingly Parallel:]\index{Embarrassingly parallel}
A problem or algorithm where adding threads does not significantly
increase the overall cost of the computation, resulting in
linear speedups as threads are added (assuming sufficient
@@ -248,7 +248,7 @@
used so heavily that there is often a CPU waiting on it.
Reducing lock contention is often a concern when designing
parallel algorithms and when implementing parallel programs.
-\item[Memory Consistency:]\index{Memory consisitency}
+\item[Memory Consistency:]\index{Memory consistency}
A set of properties that impose constraints on the order in
which accesses to groups of variables appear to occur.
Memory consistency models range from sequential consistency,
@@ -382,7 +382,7 @@
as well as its cache so as to ensure that the software sees
the memory operations performed by this CPU as if they
were carried out in program order.
-\item[Superscalar CPU:]\index{Superscaler CPU}
+\item[Superscalar CPU:]\index{Superscalar CPU}
A scalar (non-vector) CPU capable of executing multiple instructions
concurrently.
This is a step up from a pipelined CPU that executes multiple
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-23 21:06 ` Paul E. McKenney
2020-11-23 21:15 ` Paul E. McKenney
@ 2020-11-23 22:29 ` Akira Yokosawa
2020-11-24 15:21 ` [GIT PULL v2 " Akira Yokosawa
2020-11-24 19:22 ` [NOT PULL YET " Paul E. McKenney
1 sibling, 2 replies; 11+ messages in thread
From: Akira Yokosawa @ 2020-11-23 22:29 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
>> Hi Paul,
>>
>> So this *not-pull* request is to show you my WIP branch to add indices
>> to perfbook.
>>
>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
>>
>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
>> Credits, and the newly added Index belong there.
>> I employed "tocbibind" package to include Bibliography in TOC.
>>
>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
>> toolsoftrade.
>> You can see that raw \index or \sindex macros are avoided in .tex source
>> files. Using custom macros for annotation can reduce diffs in adding
>> annotations.
>> glossary.tex is an exception, as every description item has
>> \index{} on it. If we add other annotations there, we need to use
>> custom macros.
>>
>> Patch 4/7 adds annotations for people's names. They could be in another
>> independent index, but they are merged into the general index.
>> As a result, the ratio of people's names in the index is quite high at the
>> moment.
>> It will decrease as we add annotations for general terms/words.
>> Names are presented in the index in the form of "surname, forename" order.
>> To enable this, annotation is done by \ppl{forename}{surname}.
>> When you need only surname in the text, use \pplsur macro instead.
>> For names with abbreviated middle name, there is a \pplmdl command as
>> well.
>>
>> Patch 5/7 highlights indexed words/terms/names in the text.
>> This should help us in finding out what needs to be annotated.
>> If the color of DarkGreen is problematic for you, please let me know
>> which color is easy for you.
>> One of the purpose of avoiding raw \index{} macros for annotation is
>> to realize this coloring.
>>
>> Patch 6/7 adds a few more annotations of people's names in "formal".
>>
>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
>> As mentioned in the change log, API Index shows a minor glitches of
>> extraneous line folding caused by the side effect of \co{} macro.
>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
>> I have not figured out if there is some workaround for older LaTeX.
>
> Nice start!
>
> This is in the "lt" flavor only, correct?
Oh, why did I miss the most important to share?
I added a new target "ix" and its derivative "1cix" in patch 1/7.
These make targets enable coloring of indexed words/names/APIs added in
patch 5/7. I'm not sure the color choice works with your eyes, though.
> The default "make" generates
> the perfbook.ind file, but does not include it. But "make lt" doesn't
> either. Trying again setting the "toindex" boolean to "true", which does
> in fact generate a pair of three-column indexes at the end, very good!
>
>> The appearance of index pages does not matter so much at the moment,
>> I suppose. We need to add annotations first.
>
> Agreed, the annotations will be a big job. I have a small patch
> at the end for minor typos as well.
I thought I made quite a few typos. Thanks for catching them.
I'll merge it to patch 1/7.
>
>> To do that, we need to agree the organization of index pages.
>> Current indices are flat.
>> LaTeX indexing framework supports up to 3 levels of hierarchy.
>>
>> For example:
>>
>> Flat index
>>
>> Critical section, <page>
>> ...
>> Read-side critical section, <page>
>> ...
>> Write-side critical section, <page>
>>
>> 2 level index
>>
>> Critical section, <page>
>> read-side, <page>
>> write-size, <page>
>> ...
>> Read-side critical section, see Critical section, read-side
>> ...
>> Write-side critical section, see Critical section, write-side
>>
>> Which do you prefer?
>
> I have a minor preference for the 2-level index. However, it might or
> might not be worth it. For example, should "Associativity" be on its own,
> or under "Cache"? Or in both places?
We will need some experiments.
Let me play with terms in glossary.tex.
>
>> Another point on people's names.
>> I'm *not* thinking of making index of authors of Bibliography.
>> Due to the amount of cited material, it will require a ton of cleanups
>> in .bib files if you want the author index to look consistent.
>>
>> Which means, you need to mention names of authors who you want to see
>> in the index. Does this sound reasonable to you?
>
> That makes a lot of sense!
OK.
>
>> I know you are debugging/analyzing/testing RCU and lockdep interaction
>> right now.
>
> But sometimes one must take a break. And I am hoping to make more
> progress on updating the last few graphs this week. It turns out that
> there are interesting interactions between userspace RCU's call_rcu()
> worker threads and jemalloc(), for example. The surprise, especially to
> the jemalloc() folks is that jemalloc() doesn't help much, even if the
> call_rcu() worker threads to a throw-away allocation to help jemalloc()
> realize that it must create caches for those worker threads.
>
> It is possible that this is a consequence of the fact that the bottleneck
> for large RCU-protected hash tables is in the L3 cache rather than in
> any particular CPU. Which is an unexpected benefit, as this situation
> clearly calls attention to the possibility of this type of bottleneck.
>
> Not so good for second-edition schedule, though!
;-) ;-)
>
>> I'm not in a hurry and looking forward to your feedback.
>
> I am going to list a few additional index entries: CPU, memory, I/O,
> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
> and software), simultaneous multithreading, hyperthreading, interconnect,
> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
> IPI?), locality of reference (spatial and temporal), cache prefetching,
> cache alignment, cache ways, read-mostly replication, partitioning,
> out-of-order execution, super-scalar CPU, hardware transactional memory,
> software transactional memory, hazard pointers, reference counters,
> lockless, the various counter algorithms, object oriented, object oriented
> spaghetti code, stall (for example, pipeline stall due to a cache miss),
> double-ended queue, maze (or maze solving), branch prediction, atomic
> instructions, atomic read-modify-write instructions, memory barrier,
> distributed-system parallelism (as opposed to shared-memory parallelism),
> communications miss (of caches), herd (the LKMM tool), coherence order,
> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
> and much more, but that is enough for now.
If you want to do it on your own, why not merge the next pull request
which will address textwidth of 1c-layout index pages?
It should be safe as indexing is not enabled in existing make targets.
>
> Should the index expand acronyms? Hennessy and Patterson do for some
> acronyms but not others, so we can justify being inconsistent if we
> would like.
I guess index entries will keep somewhat inconsistent in any way.
Keeping them consistent will require huge effort.
>
> You might argue that some of these need glossary entries, and you
> would be quite right. ;-)
;-)
>
> In other news, I am considering bringing back the quantum-computing
> section given that things seem to have stabilized a bit. But it is
> still a bit off-topic.
>
> Again, great start on the index!
Glad to know you liked it!
Thanks, Akira
>
> Thanx, Paul
>
>> Thanks, Akira
>>
>> --
>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>>
>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>>
>> are available in the Git repository at:
>>
>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
>>
>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
>>
>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
>>
>> ----------------------------------------------------------------
>> Akira Yokosawa (7):
>> PoC of indexing
>> Reorganize backmatters
>> PoC of additional API Index
>> index: Add annotations to people's names for PoC
>> Color indexed text conditionally
>> index: Add some more people index annotations in 'formal'
>> index: Trial of 3 column
>>
>> .gitignore | 3 +
>> Makefile | 10 +-
>> SMPdesign/SMPdesign.tex | 2 +-
>> SMPdesign/partexercises.tex | 5 +-
>> appendix/ack/ack.tex => ack.tex | 6 +-
>> appendix/appendix.tex | 20 --
>> count/count.tex | 2 +-
>> cpu/cpu.tex | 3 +-
>> cpu/hwfreelunch.tex | 6 +-
>> cpu/overview.tex | 4 +-
>> datastruct/datastruct.tex | 4 +-
>> debugging/debugging.tex | 5 +-
>> defer/rcurelated.tex | 92 +++++----
>> defer/rcuusage.tex | 3 +-
>> formal/axiomatic.tex | 4 +-
>> formal/ppcmem.tex | 7 +-
>> formal/spinhint.tex | 2 +-
>> future/cpu.tex | 12 +-
>> future/tm.tex | 2 +-
>> glossary.tex | 112 +++++------
>> howto/howto.tex | 37 ++--
>> intro/intro.tex | 8 +-
>> memorder/memorder.tex | 6 +-
>> perfbook-lt.tex | 75 ++++++-
>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
>> utilities/runlatex.sh | 2 +
>> 26 files changed, 470 insertions(+), 382 deletions(-)
>> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* [GIT PULL v2 -perfbook] PoC of adding index to perfbook
2020-11-23 22:29 ` Akira Yokosawa
@ 2020-11-24 15:21 ` Akira Yokosawa
2020-11-24 19:29 ` Paul E. McKenney
2020-11-24 19:22 ` [NOT PULL YET " Paul E. McKenney
1 sibling, 1 reply; 11+ messages in thread
From: Akira Yokosawa @ 2020-11-24 15:21 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Tue, 24 Nov 2020 07:29:58 +0900, Akira Yokosawa wrote:
> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
>> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
>>> Hi Paul,
>>>
>>> So this *not-pull* request is to show you my WIP branch to add indices
>>> to perfbook.
>>>
>>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
>>>
>>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
>>> Credits, and the newly added Index belong there.
>>> I employed "tocbibind" package to include Bibliography in TOC.
>>>
>>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
>>> toolsoftrade.
>>> You can see that raw \index or \sindex macros are avoided in .tex source
>>> files. Using custom macros for annotation can reduce diffs in adding
>>> annotations.
>>> glossary.tex is an exception, as every description item has
>>> \index{} on it. If we add other annotations there, we need to use
>>> custom macros.
>>>
>>> Patch 4/7 adds annotations for people's names. They could be in another
>>> independent index, but they are merged into the general index.
>>> As a result, the ratio of people's names in the index is quite high at the
>>> moment.
>>> It will decrease as we add annotations for general terms/words.
>>> Names are presented in the index in the form of "surname, forename" order.
>>> To enable this, annotation is done by \ppl{forename}{surname}.
>>> When you need only surname in the text, use \pplsur macro instead.
>>> For names with abbreviated middle name, there is a \pplmdl command as
>>> well.
>>>
>>> Patch 5/7 highlights indexed words/terms/names in the text.
>>> This should help us in finding out what needs to be annotated.
>>> If the color of DarkGreen is problematic for you, please let me know
>>> which color is easy for you.
>>> One of the purpose of avoiding raw \index{} macros for annotation is
>>> to realize this coloring.
>>>
>>> Patch 6/7 adds a few more annotations of people's names in "formal".
>>>
>>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
>>> As mentioned in the change log, API Index shows a minor glitches of
>>> extraneous line folding caused by the side effect of \co{} macro.
>>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
>>> I have not figured out if there is some workaround for older LaTeX.
>>
>> Nice start!
>>
>> This is in the "lt" flavor only, correct?
>
> Oh, why did I miss the most important to share?
> I added a new target "ix" and its derivative "1cix" in patch 1/7.
> These make targets enable coloring of indexed words/names/APIs added in
> patch 5/7. I'm not sure the color choice works with your eyes, though.
>
>> The default "make" generates
>> the perfbook.ind file, but does not include it. But "make lt" doesn't
>> either. Trying again setting the "toindex" boolean to "true", which does
>> in fact generate a pair of three-column indexes at the end, very good!
>>
>>> The appearance of index pages does not matter so much at the moment,
>>> I suppose. We need to add annotations first.
>>
>> Agreed, the annotations will be a big job. I have a small patch
>> at the end for minor typos as well.
>
> I thought I made quite a few typos. Thanks for catching them.
> I'll merge it to patch 1/7.
>
>>
>>> To do that, we need to agree the organization of index pages.
>>> Current indices are flat.
>>> LaTeX indexing framework supports up to 3 levels of hierarchy.
>>>
>>> For example:
>>>
>>> Flat index
>>>
>>> Critical section, <page>
>>> ...
>>> Read-side critical section, <page>
>>> ...
>>> Write-side critical section, <page>
>>>
>>> 2 level index
>>>
>>> Critical section, <page>
>>> read-side, <page>
>>> write-size, <page>
>>> ...
>>> Read-side critical section, see Critical section, read-side
>>> ...
>>> Write-side critical section, see Critical section, write-side
>>>
>>> Which do you prefer?
>>
>> I have a minor preference for the 2-level index. However, it might or
>> might not be worth it. For example, should "Associativity" be on its own,
>> or under "Cache"? Or in both places?
>
> We will need some experiments.
> Let me play with terms in glossary.tex.
>
>>
>>> Another point on people's names.
>>> I'm *not* thinking of making index of authors of Bibliography.
>>> Due to the amount of cited material, it will require a ton of cleanups
>>> in .bib files if you want the author index to look consistent.
>>>
>>> Which means, you need to mention names of authors who you want to see
>>> in the index. Does this sound reasonable to you?
>>
>> That makes a lot of sense!
>
> OK.
>
>>
>>> I know you are debugging/analyzing/testing RCU and lockdep interaction
>>> right now.
>>
>> But sometimes one must take a break. And I am hoping to make more
>> progress on updating the last few graphs this week. It turns out that
>> there are interesting interactions between userspace RCU's call_rcu()
>> worker threads and jemalloc(), for example. The surprise, especially to
>> the jemalloc() folks is that jemalloc() doesn't help much, even if the
>> call_rcu() worker threads to a throw-away allocation to help jemalloc()
>> realize that it must create caches for those worker threads.
>>
>> It is possible that this is a consequence of the fact that the bottleneck
>> for large RCU-protected hash tables is in the L3 cache rather than in
>> any particular CPU. Which is an unexpected benefit, as this situation
>> clearly calls attention to the possibility of this type of bottleneck.
>>
>> Not so good for second-edition schedule, though!
>
> ;-) ;-)
>
>>
>>> I'm not in a hurry and looking forward to your feedback.
>>
>> I am going to list a few additional index entries: CPU, memory, I/O,
>> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
>> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
>> and software), simultaneous multithreading, hyperthreading, interconnect,
>> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
>> IPI?), locality of reference (spatial and temporal), cache prefetching,
>> cache alignment, cache ways, read-mostly replication, partitioning,
>> out-of-order execution, super-scalar CPU, hardware transactional memory,
>> software transactional memory, hazard pointers, reference counters,
>> lockless, the various counter algorithms, object oriented, object oriented
>> spaghetti code, stall (for example, pipeline stall due to a cache miss),
>> double-ended queue, maze (or maze solving), branch prediction, atomic
>> instructions, atomic read-modify-write instructions, memory barrier,
>> distributed-system parallelism (as opposed to shared-memory parallelism),
>> communications miss (of caches), herd (the LKMM tool), coherence order,
>> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
>> and much more, but that is enough for now.
>
> If you want to do it on your own, why not merge the next pull request
> which will address textwidth of 1c-layout index pages?
>
> It should be safe as indexing is not enabled in existing make targets.
So please find v2 of the pull request bellow.
It has typo fixes applied in patch 1/7 (now 1/11).
Additional 4 patches addresses the width of 1c layout index pages.
In doing so, I removed all of those margin settings by magic numbers.
Patch 8/11 fixes the 1c geometry settings for index pages.
Patch 9/11 removes remaining magical margin settings.
Patch 10/11 removes sed patterns substituting options to the \documentclass{}
command at the top of perfbook-lt.tex. The geometry package overrides
these options afterwords in the preamble.
Patch 11/11 adds new make targets in synctex-forward.sh to accept "ix" and
"1cix" targets.
Thanks, Akira
--
The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
are available in the Git repository at:
https://github.com/akiyks/perfbook.git tags/for-paul-2020.11.24a
for you to fetch changes up to d4acd14416f6a96591cd5cf6733155064acee44b:
synctex-forward: Add new targets in target list (2020-11-24 23:48:31 +0900)
----------------------------------------------------------------
Akira Yokosawa (11):
PoC of indexing
Reorganize backmatters
PoC of additional API Index
index: Add annotations to people's names for PoC
Color indexed text conditionally
index: Add some more people index annotations in 'formal'
index: Trial of 3 column
Use wider layout for Index in 1c build
Delegate geometry settings to 'geometry' package
Makefile: Remove sed patterns to substitute paper and column setting
synctex-forward: Add new targets in target list
.gitignore | 3 +
Makefile | 15 +-
SMPdesign/SMPdesign.tex | 2 +-
SMPdesign/partexercises.tex | 5 +-
appendix/ack/ack.tex => ack.tex | 6 +-
appendix/appendix.tex | 20 --
count/count.tex | 2 +-
cpu/cpu.tex | 3 +-
cpu/hwfreelunch.tex | 6 +-
cpu/overview.tex | 4 +-
datastruct/datastruct.tex | 4 +-
debugging/debugging.tex | 5 +-
defer/rcurelated.tex | 92 +++++----
defer/rcuusage.tex | 3 +-
formal/axiomatic.tex | 4 +-
formal/ppcmem.tex | 7 +-
formal/spinhint.tex | 2 +-
future/cpu.tex | 12 +-
future/tm.tex | 2 +-
glossary.tex | 112 +++++------
howto/howto.tex | 37 ++--
intro/intro.tex | 8 +-
memorder/memorder.tex | 6 +-
perfbook-lt.tex | 143 ++++++++++----
toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
utilities/runlatex.sh | 2 +
utilities/synctex-forward.sh | 6 +-
27 files changed, 510 insertions(+), 421 deletions(-)
rename appendix/ack/ack.tex => ack.tex (98%)
--
>
>>
>> Should the index expand acronyms? Hennessy and Patterson do for some
>> acronyms but not others, so we can justify being inconsistent if we
>> would like.
>
> I guess index entries will keep somewhat inconsistent in any way.
> Keeping them consistent will require huge effort.
>
>>
>> You might argue that some of these need glossary entries, and you
>> would be quite right. ;-)
>
> ;-)
>
>>
>> In other news, I am considering bringing back the quantum-computing
>> section given that things seem to have stabilized a bit. But it is
>> still a bit off-topic.
>>
>> Again, great start on the index!
>
> Glad to know you liked it!
>
> Thanks, Akira
>
>>
>> Thanx, Paul
>>
>>> Thanks, Akira
>>>
>>> --
>>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>>>
>>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>>>
>>> are available in the Git repository at:
>>>
>>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
>>>
>>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
>>>
>>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
>>>
>>> ----------------------------------------------------------------
>>> Akira Yokosawa (7):
>>> PoC of indexing
>>> Reorganize backmatters
>>> PoC of additional API Index
>>> index: Add annotations to people's names for PoC
>>> Color indexed text conditionally
>>> index: Add some more people index annotations in 'formal'
>>> index: Trial of 3 column
>>>
>>> .gitignore | 3 +
>>> Makefile | 10 +-
>>> SMPdesign/SMPdesign.tex | 2 +-
>>> SMPdesign/partexercises.tex | 5 +-
>>> appendix/ack/ack.tex => ack.tex | 6 +-
>>> appendix/appendix.tex | 20 --
>>> count/count.tex | 2 +-
>>> cpu/cpu.tex | 3 +-
>>> cpu/hwfreelunch.tex | 6 +-
>>> cpu/overview.tex | 4 +-
>>> datastruct/datastruct.tex | 4 +-
>>> debugging/debugging.tex | 5 +-
>>> defer/rcurelated.tex | 92 +++++----
>>> defer/rcuusage.tex | 3 +-
>>> formal/axiomatic.tex | 4 +-
>>> formal/ppcmem.tex | 7 +-
>>> formal/spinhint.tex | 2 +-
>>> future/cpu.tex | 12 +-
>>> future/tm.tex | 2 +-
>>> glossary.tex | 112 +++++------
>>> howto/howto.tex | 37 ++--
>>> intro/intro.tex | 8 +-
>>> memorder/memorder.tex | 6 +-
>>> perfbook-lt.tex | 75 ++++++-
>>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
>>> utilities/runlatex.sh | 2 +
>>> 26 files changed, 470 insertions(+), 382 deletions(-)
>>> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-23 22:29 ` Akira Yokosawa
2020-11-24 15:21 ` [GIT PULL v2 " Akira Yokosawa
@ 2020-11-24 19:22 ` Paul E. McKenney
2020-11-24 22:38 ` Akira Yokosawa
1 sibling, 1 reply; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-24 19:22 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Tue, Nov 24, 2020 at 07:29:58AM +0900, Akira Yokosawa wrote:
> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
> > On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> >> Hi Paul,
> >>
> >> So this *not-pull* request is to show you my WIP branch to add indices
> >> to perfbook.
> >>
> >> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
> >>
> >> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
> >> Credits, and the newly added Index belong there.
> >> I employed "tocbibind" package to include Bibliography in TOC.
> >>
> >> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
> >> toolsoftrade.
> >> You can see that raw \index or \sindex macros are avoided in .tex source
> >> files. Using custom macros for annotation can reduce diffs in adding
> >> annotations.
> >> glossary.tex is an exception, as every description item has
> >> \index{} on it. If we add other annotations there, we need to use
> >> custom macros.
> >>
> >> Patch 4/7 adds annotations for people's names. They could be in another
> >> independent index, but they are merged into the general index.
> >> As a result, the ratio of people's names in the index is quite high at the
> >> moment.
> >> It will decrease as we add annotations for general terms/words.
> >> Names are presented in the index in the form of "surname, forename" order.
> >> To enable this, annotation is done by \ppl{forename}{surname}.
> >> When you need only surname in the text, use \pplsur macro instead.
> >> For names with abbreviated middle name, there is a \pplmdl command as
> >> well.
> >>
> >> Patch 5/7 highlights indexed words/terms/names in the text.
> >> This should help us in finding out what needs to be annotated.
> >> If the color of DarkGreen is problematic for you, please let me know
> >> which color is easy for you.
> >> One of the purpose of avoiding raw \index{} macros for annotation is
> >> to realize this coloring.
> >>
> >> Patch 6/7 adds a few more annotations of people's names in "formal".
> >>
> >> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
> >> As mentioned in the change log, API Index shows a minor glitches of
> >> extraneous line folding caused by the side effect of \co{} macro.
> >> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
> >> I have not figured out if there is some workaround for older LaTeX.
> >
> > Nice start!
> >
> > This is in the "lt" flavor only, correct?
>
> Oh, why did I miss the most important to share?
> I added a new target "ix" and its derivative "1cix" in patch 1/7.
> These make targets enable coloring of indexed words/names/APIs added in
> patch 5/7. I'm not sure the color choice works with your eyes, though.
I guess I could have looked at diffs to Makefile...
I don't see any colors, though, perhaps because I am failing to
distinguish dark green from black?.
> > The default "make" generates
> > the perfbook.ind file, but does not include it. But "make lt" doesn't
> > either. Trying again setting the "toindex" boolean to "true", which does
> > in fact generate a pair of three-column indexes at the end, very good!
> >
> >> The appearance of index pages does not matter so much at the moment,
> >> I suppose. We need to add annotations first.
> >
> > Agreed, the annotations will be a big job. I have a small patch
> > at the end for minor typos as well.
>
> I thought I made quite a few typos. Thanks for catching them.
> I'll merge it to patch 1/7.
Nevertheless, I suspect that you have corrected quite a few more of
my typos than I have of yours. ;-)
> >> To do that, we need to agree the organization of index pages.
> >> Current indices are flat.
> >> LaTeX indexing framework supports up to 3 levels of hierarchy.
> >>
> >> For example:
> >>
> >> Flat index
> >>
> >> Critical section, <page>
> >> ...
> >> Read-side critical section, <page>
> >> ...
> >> Write-side critical section, <page>
> >>
> >> 2 level index
> >>
> >> Critical section, <page>
> >> read-side, <page>
> >> write-size, <page>
> >> ...
> >> Read-side critical section, see Critical section, read-side
> >> ...
> >> Write-side critical section, see Critical section, write-side
> >>
> >> Which do you prefer?
> >
> > I have a minor preference for the 2-level index. However, it might or
> > might not be worth it. For example, should "Associativity" be on its own,
> > or under "Cache"? Or in both places?
>
> We will need some experiments.
> Let me play with terms in glossary.tex.
Sounds good!
> >> I'm *not* thinking of making index of authors of Bibliography.
> >> Due to the amount of cited material, it will require a ton of cleanups
> >> in .bib files if you want the author index to look consistent.
> >>
> >> Which means, you need to mention names of authors who you want to see
> >> in the index. Does this sound reasonable to you?
> >
> > That makes a lot of sense!
>
> OK.
>
> >
> >> I know you are debugging/analyzing/testing RCU and lockdep interaction
> >> right now.
> >
> > But sometimes one must take a break. And I am hoping to make more
> > progress on updating the last few graphs this week. It turns out that
> > there are interesting interactions between userspace RCU's call_rcu()
> > worker threads and jemalloc(), for example. The surprise, especially to
> > the jemalloc() folks is that jemalloc() doesn't help much, even if the
> > call_rcu() worker threads to a throw-away allocation to help jemalloc()
> > realize that it must create caches for those worker threads.
> >
> > It is possible that this is a consequence of the fact that the bottleneck
> > for large RCU-protected hash tables is in the L3 cache rather than in
> > any particular CPU. Which is an unexpected benefit, as this situation
> > clearly calls attention to the possibility of this type of bottleneck.
> >
> > Not so good for second-edition schedule, though!
>
> ;-) ;-)
>
> >
> >> I'm not in a hurry and looking forward to your feedback.
> >
> > I am going to list a few additional index entries: CPU, memory, I/O,
> > multicore, synchronization, cache hit, Moore's Law free lunch, speed of
> > light, 3D integration, accelerators, CAS, socket, core, thread (hardware
> > and software), simultaneous multithreading, hyperthreading, interconnect,
> > interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
> > IPI?), locality of reference (spatial and temporal), cache prefetching,
> > cache alignment, cache ways, read-mostly replication, partitioning,
> > out-of-order execution, super-scalar CPU, hardware transactional memory,
> > software transactional memory, hazard pointers, reference counters,
> > lockless, the various counter algorithms, object oriented, object oriented
> > spaghetti code, stall (for example, pipeline stall due to a cache miss),
> > double-ended queue, maze (or maze solving), branch prediction, atomic
> > instructions, atomic read-modify-write instructions, memory barrier,
> > distributed-system parallelism (as opposed to shared-memory parallelism),
> > communications miss (of caches), herd (the LKMM tool), coherence order,
> > reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
> > and much more, but that is enough for now.
>
> If you want to do it on your own, why not merge the next pull request
> which will address textwidth of 1c-layout index pages?
>
> It should be safe as indexing is not enabled in existing make targets.
I am thinking in terms of merging the index first thing after the
second edition. Though at the rate I am going on it, you might well
have it ready beforehand...
> > Should the index expand acronyms? Hennessy and Patterson do for some
> > acronyms but not others, so we can justify being inconsistent if we
> > would like.
>
> I guess index entries will keep somewhat inconsistent in any way.
> Keeping them consistent will require huge effort.
As near as I can tell, the more familiar ones were left unexpanded and
the more specialized ones were expanded. So they left LAN unexpanded,
but expanded NUMA. In my old edition, anyway.
Thanx, Paul
> > You might argue that some of these need glossary entries, and you
> > would be quite right. ;-)
>
> ;-)
>
> >
> > In other news, I am considering bringing back the quantum-computing
> > section given that things seem to have stabilized a bit. But it is
> > still a bit off-topic.
> >
> > Again, great start on the index!
>
> Glad to know you liked it!
>
> Thanks, Akira
>
> >
> > Thanx, Paul
> >
> >> Thanks, Akira
> >>
> >> --
> >> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
> >>
> >> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
> >>
> >> are available in the Git repository at:
> >>
> >> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
> >>
> >> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
> >>
> >> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
> >>
> >> ----------------------------------------------------------------
> >> Akira Yokosawa (7):
> >> PoC of indexing
> >> Reorganize backmatters
> >> PoC of additional API Index
> >> index: Add annotations to people's names for PoC
> >> Color indexed text conditionally
> >> index: Add some more people index annotations in 'formal'
> >> index: Trial of 3 column
> >>
> >> .gitignore | 3 +
> >> Makefile | 10 +-
> >> SMPdesign/SMPdesign.tex | 2 +-
> >> SMPdesign/partexercises.tex | 5 +-
> >> appendix/ack/ack.tex => ack.tex | 6 +-
> >> appendix/appendix.tex | 20 --
> >> count/count.tex | 2 +-
> >> cpu/cpu.tex | 3 +-
> >> cpu/hwfreelunch.tex | 6 +-
> >> cpu/overview.tex | 4 +-
> >> datastruct/datastruct.tex | 4 +-
> >> debugging/debugging.tex | 5 +-
> >> defer/rcurelated.tex | 92 +++++----
> >> defer/rcuusage.tex | 3 +-
> >> formal/axiomatic.tex | 4 +-
> >> formal/ppcmem.tex | 7 +-
> >> formal/spinhint.tex | 2 +-
> >> future/cpu.tex | 12 +-
> >> future/tm.tex | 2 +-
> >> glossary.tex | 112 +++++------
> >> howto/howto.tex | 37 ++--
> >> intro/intro.tex | 8 +-
> >> memorder/memorder.tex | 6 +-
> >> perfbook-lt.tex | 75 ++++++-
> >> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> >> utilities/runlatex.sh | 2 +
> >> 26 files changed, 470 insertions(+), 382 deletions(-)
> >> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [GIT PULL v2 -perfbook] PoC of adding index to perfbook
2020-11-24 15:21 ` [GIT PULL v2 " Akira Yokosawa
@ 2020-11-24 19:29 ` Paul E. McKenney
2020-11-24 22:43 ` Akira Yokosawa
0 siblings, 1 reply; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-24 19:29 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Nov 25, 2020 at 12:21:44AM +0900, Akira Yokosawa wrote:
> On Tue, 24 Nov 2020 07:29:58 +0900, Akira Yokosawa wrote:
> > On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
> >> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> >>> Hi Paul,
> >>>
> >>> So this *not-pull* request is to show you my WIP branch to add indices
> >>> to perfbook.
> >>>
> >>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
> >>>
> >>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
> >>> Credits, and the newly added Index belong there.
> >>> I employed "tocbibind" package to include Bibliography in TOC.
> >>>
> >>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
> >>> toolsoftrade.
> >>> You can see that raw \index or \sindex macros are avoided in .tex source
> >>> files. Using custom macros for annotation can reduce diffs in adding
> >>> annotations.
> >>> glossary.tex is an exception, as every description item has
> >>> \index{} on it. If we add other annotations there, we need to use
> >>> custom macros.
> >>>
> >>> Patch 4/7 adds annotations for people's names. They could be in another
> >>> independent index, but they are merged into the general index.
> >>> As a result, the ratio of people's names in the index is quite high at the
> >>> moment.
> >>> It will decrease as we add annotations for general terms/words.
> >>> Names are presented in the index in the form of "surname, forename" order.
> >>> To enable this, annotation is done by \ppl{forename}{surname}.
> >>> When you need only surname in the text, use \pplsur macro instead.
> >>> For names with abbreviated middle name, there is a \pplmdl command as
> >>> well.
> >>>
> >>> Patch 5/7 highlights indexed words/terms/names in the text.
> >>> This should help us in finding out what needs to be annotated.
> >>> If the color of DarkGreen is problematic for you, please let me know
> >>> which color is easy for you.
> >>> One of the purpose of avoiding raw \index{} macros for annotation is
> >>> to realize this coloring.
> >>>
> >>> Patch 6/7 adds a few more annotations of people's names in "formal".
> >>>
> >>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
> >>> As mentioned in the change log, API Index shows a minor glitches of
> >>> extraneous line folding caused by the side effect of \co{} macro.
> >>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
> >>> I have not figured out if there is some workaround for older LaTeX.
> >>
> >> Nice start!
> >>
> >> This is in the "lt" flavor only, correct?
> >
> > Oh, why did I miss the most important to share?
> > I added a new target "ix" and its derivative "1cix" in patch 1/7.
> > These make targets enable coloring of indexed words/names/APIs added in
> > patch 5/7. I'm not sure the color choice works with your eyes, though.
> >
> >> The default "make" generates
> >> the perfbook.ind file, but does not include it. But "make lt" doesn't
> >> either. Trying again setting the "toindex" boolean to "true", which does
> >> in fact generate a pair of three-column indexes at the end, very good!
> >>
> >>> The appearance of index pages does not matter so much at the moment,
> >>> I suppose. We need to add annotations first.
> >>
> >> Agreed, the annotations will be a big job. I have a small patch
> >> at the end for minor typos as well.
> >
> > I thought I made quite a few typos. Thanks for catching them.
> > I'll merge it to patch 1/7.
> >
> >>
> >>> To do that, we need to agree the organization of index pages.
> >>> Current indices are flat.
> >>> LaTeX indexing framework supports up to 3 levels of hierarchy.
> >>>
> >>> For example:
> >>>
> >>> Flat index
> >>>
> >>> Critical section, <page>
> >>> ...
> >>> Read-side critical section, <page>
> >>> ...
> >>> Write-side critical section, <page>
> >>>
> >>> 2 level index
> >>>
> >>> Critical section, <page>
> >>> read-side, <page>
> >>> write-size, <page>
> >>> ...
> >>> Read-side critical section, see Critical section, read-side
> >>> ...
> >>> Write-side critical section, see Critical section, write-side
> >>>
> >>> Which do you prefer?
> >>
> >> I have a minor preference for the 2-level index. However, it might or
> >> might not be worth it. For example, should "Associativity" be on its own,
> >> or under "Cache"? Or in both places?
> >
> > We will need some experiments.
> > Let me play with terms in glossary.tex.
> >
> >>
> >>> Another point on people's names.
> >>> I'm *not* thinking of making index of authors of Bibliography.
> >>> Due to the amount of cited material, it will require a ton of cleanups
> >>> in .bib files if you want the author index to look consistent.
> >>>
> >>> Which means, you need to mention names of authors who you want to see
> >>> in the index. Does this sound reasonable to you?
> >>
> >> That makes a lot of sense!
> >
> > OK.
> >
> >>
> >>> I know you are debugging/analyzing/testing RCU and lockdep interaction
> >>> right now.
> >>
> >> But sometimes one must take a break. And I am hoping to make more
> >> progress on updating the last few graphs this week. It turns out that
> >> there are interesting interactions between userspace RCU's call_rcu()
> >> worker threads and jemalloc(), for example. The surprise, especially to
> >> the jemalloc() folks is that jemalloc() doesn't help much, even if the
> >> call_rcu() worker threads to a throw-away allocation to help jemalloc()
> >> realize that it must create caches for those worker threads.
> >>
> >> It is possible that this is a consequence of the fact that the bottleneck
> >> for large RCU-protected hash tables is in the L3 cache rather than in
> >> any particular CPU. Which is an unexpected benefit, as this situation
> >> clearly calls attention to the possibility of this type of bottleneck.
> >>
> >> Not so good for second-edition schedule, though!
> >
> > ;-) ;-)
> >
> >>
> >>> I'm not in a hurry and looking forward to your feedback.
> >>
> >> I am going to list a few additional index entries: CPU, memory, I/O,
> >> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
> >> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
> >> and software), simultaneous multithreading, hyperthreading, interconnect,
> >> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
> >> IPI?), locality of reference (spatial and temporal), cache prefetching,
> >> cache alignment, cache ways, read-mostly replication, partitioning,
> >> out-of-order execution, super-scalar CPU, hardware transactional memory,
> >> software transactional memory, hazard pointers, reference counters,
> >> lockless, the various counter algorithms, object oriented, object oriented
> >> spaghetti code, stall (for example, pipeline stall due to a cache miss),
> >> double-ended queue, maze (or maze solving), branch prediction, atomic
> >> instructions, atomic read-modify-write instructions, memory barrier,
> >> distributed-system parallelism (as opposed to shared-memory parallelism),
> >> communications miss (of caches), herd (the LKMM tool), coherence order,
> >> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
> >> and much more, but that is enough for now.
> >
> > If you want to do it on your own, why not merge the next pull request
> > which will address textwidth of 1c-layout index pages?
> >
> > It should be safe as indexing is not enabled in existing make targets.
>
> So please find v2 of the pull request bellow.
>
> It has typo fixes applied in patch 1/7 (now 1/11).
> Additional 4 patches addresses the width of 1c layout index pages.
> In doing so, I removed all of those margin settings by magic numbers.
>
> Patch 8/11 fixes the 1c geometry settings for index pages.
> Patch 9/11 removes remaining magical margin settings.
> Patch 10/11 removes sed patterns substituting options to the \documentclass{}
> command at the top of perfbook-lt.tex. The geometry package overrides
> these options afterwords in the preamble.
> Patch 11/11 adds new make targets in synctex-forward.sh to accept "ix" and
> "1cix" targets.
I have pulled these in and pushed them under branch akiyks.2020.11.24a,
thank you! However, given that they do not seem to affect the old
make targets, I am not seeing much reason not to merge them into the
master branch. Any reasons not to?
Thanx, Paul
> Thanks, Akira
>
> --
> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>
> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>
> are available in the Git repository at:
>
> https://github.com/akiyks/perfbook.git tags/for-paul-2020.11.24a
>
> for you to fetch changes up to d4acd14416f6a96591cd5cf6733155064acee44b:
>
> synctex-forward: Add new targets in target list (2020-11-24 23:48:31 +0900)
>
> ----------------------------------------------------------------
> Akira Yokosawa (11):
> PoC of indexing
> Reorganize backmatters
> PoC of additional API Index
> index: Add annotations to people's names for PoC
> Color indexed text conditionally
> index: Add some more people index annotations in 'formal'
> index: Trial of 3 column
> Use wider layout for Index in 1c build
> Delegate geometry settings to 'geometry' package
> Makefile: Remove sed patterns to substitute paper and column setting
> synctex-forward: Add new targets in target list
>
> .gitignore | 3 +
> Makefile | 15 +-
> SMPdesign/SMPdesign.tex | 2 +-
> SMPdesign/partexercises.tex | 5 +-
> appendix/ack/ack.tex => ack.tex | 6 +-
> appendix/appendix.tex | 20 --
> count/count.tex | 2 +-
> cpu/cpu.tex | 3 +-
> cpu/hwfreelunch.tex | 6 +-
> cpu/overview.tex | 4 +-
> datastruct/datastruct.tex | 4 +-
> debugging/debugging.tex | 5 +-
> defer/rcurelated.tex | 92 +++++----
> defer/rcuusage.tex | 3 +-
> formal/axiomatic.tex | 4 +-
> formal/ppcmem.tex | 7 +-
> formal/spinhint.tex | 2 +-
> future/cpu.tex | 12 +-
> future/tm.tex | 2 +-
> glossary.tex | 112 +++++------
> howto/howto.tex | 37 ++--
> intro/intro.tex | 8 +-
> memorder/memorder.tex | 6 +-
> perfbook-lt.tex | 143 ++++++++++----
> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> utilities/runlatex.sh | 2 +
> utilities/synctex-forward.sh | 6 +-
> 27 files changed, 510 insertions(+), 421 deletions(-)
> rename appendix/ack/ack.tex => ack.tex (98%)
> --
>
> >
> >>
> >> Should the index expand acronyms? Hennessy and Patterson do for some
> >> acronyms but not others, so we can justify being inconsistent if we
> >> would like.
> >
> > I guess index entries will keep somewhat inconsistent in any way.
> > Keeping them consistent will require huge effort.
> >
> >>
> >> You might argue that some of these need glossary entries, and you
> >> would be quite right. ;-)
> >
> > ;-)
> >
> >>
> >> In other news, I am considering bringing back the quantum-computing
> >> section given that things seem to have stabilized a bit. But it is
> >> still a bit off-topic.
> >>
> >> Again, great start on the index!
> >
> > Glad to know you liked it!
> >
> > Thanks, Akira
> >
> >>
> >> Thanx, Paul
> >>
> >>> Thanks, Akira
> >>>
> >>> --
> >>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
> >>>
> >>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
> >>>
> >>> are available in the Git repository at:
> >>>
> >>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
> >>>
> >>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
> >>>
> >>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
> >>>
> >>> ----------------------------------------------------------------
> >>> Akira Yokosawa (7):
> >>> PoC of indexing
> >>> Reorganize backmatters
> >>> PoC of additional API Index
> >>> index: Add annotations to people's names for PoC
> >>> Color indexed text conditionally
> >>> index: Add some more people index annotations in 'formal'
> >>> index: Trial of 3 column
> >>>
> >>> .gitignore | 3 +
> >>> Makefile | 10 +-
> >>> SMPdesign/SMPdesign.tex | 2 +-
> >>> SMPdesign/partexercises.tex | 5 +-
> >>> appendix/ack/ack.tex => ack.tex | 6 +-
> >>> appendix/appendix.tex | 20 --
> >>> count/count.tex | 2 +-
> >>> cpu/cpu.tex | 3 +-
> >>> cpu/hwfreelunch.tex | 6 +-
> >>> cpu/overview.tex | 4 +-
> >>> datastruct/datastruct.tex | 4 +-
> >>> debugging/debugging.tex | 5 +-
> >>> defer/rcurelated.tex | 92 +++++----
> >>> defer/rcuusage.tex | 3 +-
> >>> formal/axiomatic.tex | 4 +-
> >>> formal/ppcmem.tex | 7 +-
> >>> formal/spinhint.tex | 2 +-
> >>> future/cpu.tex | 12 +-
> >>> future/tm.tex | 2 +-
> >>> glossary.tex | 112 +++++------
> >>> howto/howto.tex | 37 ++--
> >>> intro/intro.tex | 8 +-
> >>> memorder/memorder.tex | 6 +-
> >>> perfbook-lt.tex | 75 ++++++-
> >>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> >>> utilities/runlatex.sh | 2 +
> >>> 26 files changed, 470 insertions(+), 382 deletions(-)
> >>> rename appendix/ack/ack.tex => ack.tex (98%)
>
>
>
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-24 19:22 ` [NOT PULL YET " Paul E. McKenney
@ 2020-11-24 22:38 ` Akira Yokosawa
2020-11-25 0:35 ` Paul E. McKenney
0 siblings, 1 reply; 11+ messages in thread
From: Akira Yokosawa @ 2020-11-24 22:38 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Tue, 24 Nov 2020 11:22:57 -0800, Paul E. McKenney wrote:
> On Tue, Nov 24, 2020 at 07:29:58AM +0900, Akira Yokosawa wrote:
>> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
>>> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
>>>> Hi Paul,
>>>>
>>>> So this *not-pull* request is to show you my WIP branch to add indices
>>>> to perfbook.
>>>>
>>>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
>>>>
>>>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
>>>> Credits, and the newly added Index belong there.
>>>> I employed "tocbibind" package to include Bibliography in TOC.
>>>>
>>>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
>>>> toolsoftrade.
>>>> You can see that raw \index or \sindex macros are avoided in .tex source
>>>> files. Using custom macros for annotation can reduce diffs in adding
>>>> annotations.
>>>> glossary.tex is an exception, as every description item has
>>>> \index{} on it. If we add other annotations there, we need to use
>>>> custom macros.
>>>>
>>>> Patch 4/7 adds annotations for people's names. They could be in another
>>>> independent index, but they are merged into the general index.
>>>> As a result, the ratio of people's names in the index is quite high at the
>>>> moment.
>>>> It will decrease as we add annotations for general terms/words.
>>>> Names are presented in the index in the form of "surname, forename" order.
>>>> To enable this, annotation is done by \ppl{forename}{surname}.
>>>> When you need only surname in the text, use \pplsur macro instead.
>>>> For names with abbreviated middle name, there is a \pplmdl command as
>>>> well.
>>>>
>>>> Patch 5/7 highlights indexed words/terms/names in the text.
>>>> This should help us in finding out what needs to be annotated.
>>>> If the color of DarkGreen is problematic for you, please let me know
>>>> which color is easy for you.
>>>> One of the purpose of avoiding raw \index{} macros for annotation is
>>>> to realize this coloring.
>>>>
>>>> Patch 6/7 adds a few more annotations of people's names in "formal".
>>>>
>>>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
>>>> As mentioned in the change log, API Index shows a minor glitches of
>>>> extraneous line folding caused by the side effect of \co{} macro.
>>>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
>>>> I have not figured out if there is some workaround for older LaTeX.
>>>
>>> Nice start!
>>>
>>> This is in the "lt" flavor only, correct?
>>
>> Oh, why did I miss the most important to share?
>> I added a new target "ix" and its derivative "1cix" in patch 1/7.
>> These make targets enable coloring of indexed words/names/APIs added in
>> patch 5/7. I'm not sure the color choice works with your eyes, though.
>
> I guess I could have looked at diffs to Makefile...
>
> I don't see any colors, though, perhaps because I am failing to
> distinguish dark green from black?.
How does "s/DarkGreen/FireBrick/" look?
Available color names can be found in page 38 of
http://mirrors.ctan.org/macros/latex/contrib/xcolor/xcolor.pdf
via the "svgnames option.
Can you choose a color which works with your eyes?
Thanks, Akira
>
>>> The default "make" generates
>>> the perfbook.ind file, but does not include it. But "make lt" doesn't
>>> either. Trying again setting the "toindex" boolean to "true", which does
>>> in fact generate a pair of three-column indexes at the end, very good!
>>>
>>>> The appearance of index pages does not matter so much at the moment,
>>>> I suppose. We need to add annotations first.
>>>
>>> Agreed, the annotations will be a big job. I have a small patch
>>> at the end for minor typos as well.
>>
>> I thought I made quite a few typos. Thanks for catching them.
>> I'll merge it to patch 1/7.
>
> Nevertheless, I suspect that you have corrected quite a few more of
> my typos than I have of yours. ;-)
>
>>>> To do that, we need to agree the organization of index pages.
>>>> Current indices are flat.
>>>> LaTeX indexing framework supports up to 3 levels of hierarchy.
>>>>
>>>> For example:
>>>>
>>>> Flat index
>>>>
>>>> Critical section, <page>
>>>> ...
>>>> Read-side critical section, <page>
>>>> ...
>>>> Write-side critical section, <page>
>>>>
>>>> 2 level index
>>>>
>>>> Critical section, <page>
>>>> read-side, <page>
>>>> write-size, <page>
>>>> ...
>>>> Read-side critical section, see Critical section, read-side
>>>> ...
>>>> Write-side critical section, see Critical section, write-side
>>>>
>>>> Which do you prefer?
>>>
>>> I have a minor preference for the 2-level index. However, it might or
>>> might not be worth it. For example, should "Associativity" be on its own,
>>> or under "Cache"? Or in both places?
>>
>> We will need some experiments.
>> Let me play with terms in glossary.tex.
>
> Sounds good!
>
>>>> I'm *not* thinking of making index of authors of Bibliography.
>>>> Due to the amount of cited material, it will require a ton of cleanups
>>>> in .bib files if you want the author index to look consistent.
>>>>
>>>> Which means, you need to mention names of authors who you want to see
>>>> in the index. Does this sound reasonable to you?
>>>
>>> That makes a lot of sense!
>>
>> OK.
>>
>>>
>>>> I know you are debugging/analyzing/testing RCU and lockdep interaction
>>>> right now.
>>>
>>> But sometimes one must take a break. And I am hoping to make more
>>> progress on updating the last few graphs this week. It turns out that
>>> there are interesting interactions between userspace RCU's call_rcu()
>>> worker threads and jemalloc(), for example. The surprise, especially to
>>> the jemalloc() folks is that jemalloc() doesn't help much, even if the
>>> call_rcu() worker threads to a throw-away allocation to help jemalloc()
>>> realize that it must create caches for those worker threads.
>>>
>>> It is possible that this is a consequence of the fact that the bottleneck
>>> for large RCU-protected hash tables is in the L3 cache rather than in
>>> any particular CPU. Which is an unexpected benefit, as this situation
>>> clearly calls attention to the possibility of this type of bottleneck.
>>>
>>> Not so good for second-edition schedule, though!
>>
>> ;-) ;-)
>>
>>>
>>>> I'm not in a hurry and looking forward to your feedback.
>>>
>>> I am going to list a few additional index entries: CPU, memory, I/O,
>>> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
>>> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
>>> and software), simultaneous multithreading, hyperthreading, interconnect,
>>> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
>>> IPI?), locality of reference (spatial and temporal), cache prefetching,
>>> cache alignment, cache ways, read-mostly replication, partitioning,
>>> out-of-order execution, super-scalar CPU, hardware transactional memory,
>>> software transactional memory, hazard pointers, reference counters,
>>> lockless, the various counter algorithms, object oriented, object oriented
>>> spaghetti code, stall (for example, pipeline stall due to a cache miss),
>>> double-ended queue, maze (or maze solving), branch prediction, atomic
>>> instructions, atomic read-modify-write instructions, memory barrier,
>>> distributed-system parallelism (as opposed to shared-memory parallelism),
>>> communications miss (of caches), herd (the LKMM tool), coherence order,
>>> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
>>> and much more, but that is enough for now.
>>
>> If you want to do it on your own, why not merge the next pull request
>> which will address textwidth of 1c-layout index pages?
>>
>> It should be safe as indexing is not enabled in existing make targets.
>
> I am thinking in terms of merging the index first thing after the
> second edition. Though at the rate I am going on it, you might well
> have it ready beforehand...
>
>>> Should the index expand acronyms? Hennessy and Patterson do for some
>>> acronyms but not others, so we can justify being inconsistent if we
>>> would like.
>>
>> I guess index entries will keep somewhat inconsistent in any way.
>> Keeping them consistent will require huge effort.
>
> As near as I can tell, the more familiar ones were left unexpanded and
> the more specialized ones were expanded. So they left LAN unexpanded,
> but expanded NUMA. In my old edition, anyway.
>
> Thanx, Paul
>
>>> You might argue that some of these need glossary entries, and you
>>> would be quite right. ;-)
>>
>> ;-)
>>
>>>
>>> In other news, I am considering bringing back the quantum-computing
>>> section given that things seem to have stabilized a bit. But it is
>>> still a bit off-topic.
>>>
>>> Again, great start on the index!
>>
>> Glad to know you liked it!
>>
>> Thanks, Akira
>>
>>>
>>> Thanx, Paul
>>>
>>>> Thanks, Akira
>>>>
>>>> --
>>>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>>>>
>>>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>>>>
>>>> are available in the Git repository at:
>>>>
>>>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
>>>>
>>>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
>>>>
>>>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
>>>>
>>>> ----------------------------------------------------------------
>>>> Akira Yokosawa (7):
>>>> PoC of indexing
>>>> Reorganize backmatters
>>>> PoC of additional API Index
>>>> index: Add annotations to people's names for PoC
>>>> Color indexed text conditionally
>>>> index: Add some more people index annotations in 'formal'
>>>> index: Trial of 3 column
>>>>
>>>> .gitignore | 3 +
>>>> Makefile | 10 +-
>>>> SMPdesign/SMPdesign.tex | 2 +-
>>>> SMPdesign/partexercises.tex | 5 +-
>>>> appendix/ack/ack.tex => ack.tex | 6 +-
>>>> appendix/appendix.tex | 20 --
>>>> count/count.tex | 2 +-
>>>> cpu/cpu.tex | 3 +-
>>>> cpu/hwfreelunch.tex | 6 +-
>>>> cpu/overview.tex | 4 +-
>>>> datastruct/datastruct.tex | 4 +-
>>>> debugging/debugging.tex | 5 +-
>>>> defer/rcurelated.tex | 92 +++++----
>>>> defer/rcuusage.tex | 3 +-
>>>> formal/axiomatic.tex | 4 +-
>>>> formal/ppcmem.tex | 7 +-
>>>> formal/spinhint.tex | 2 +-
>>>> future/cpu.tex | 12 +-
>>>> future/tm.tex | 2 +-
>>>> glossary.tex | 112 +++++------
>>>> howto/howto.tex | 37 ++--
>>>> intro/intro.tex | 8 +-
>>>> memorder/memorder.tex | 6 +-
>>>> perfbook-lt.tex | 75 ++++++-
>>>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
>>>> utilities/runlatex.sh | 2 +
>>>> 26 files changed, 470 insertions(+), 382 deletions(-)
>>>> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [GIT PULL v2 -perfbook] PoC of adding index to perfbook
2020-11-24 19:29 ` Paul E. McKenney
@ 2020-11-24 22:43 ` Akira Yokosawa
2020-11-25 2:48 ` Paul E. McKenney
0 siblings, 1 reply; 11+ messages in thread
From: Akira Yokosawa @ 2020-11-24 22:43 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Tue, 24 Nov 2020 11:29:47 -0800, Paul E. McKenney wrote:
> On Wed, Nov 25, 2020 at 12:21:44AM +0900, Akira Yokosawa wrote:
>> On Tue, 24 Nov 2020 07:29:58 +0900, Akira Yokosawa wrote:
>>> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
>>>> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
>>>>> Hi Paul,
>>>>>
>>>>> So this *not-pull* request is to show you my WIP branch to add indices
>>>>> to perfbook.
>>>>>
>>>>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
>>>>>
>>>>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
>>>>> Credits, and the newly added Index belong there.
>>>>> I employed "tocbibind" package to include Bibliography in TOC.
>>>>>
>>>>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
>>>>> toolsoftrade.
>>>>> You can see that raw \index or \sindex macros are avoided in .tex source
>>>>> files. Using custom macros for annotation can reduce diffs in adding
>>>>> annotations.
>>>>> glossary.tex is an exception, as every description item has
>>>>> \index{} on it. If we add other annotations there, we need to use
>>>>> custom macros.
>>>>>
>>>>> Patch 4/7 adds annotations for people's names. They could be in another
>>>>> independent index, but they are merged into the general index.
>>>>> As a result, the ratio of people's names in the index is quite high at the
>>>>> moment.
>>>>> It will decrease as we add annotations for general terms/words.
>>>>> Names are presented in the index in the form of "surname, forename" order.
>>>>> To enable this, annotation is done by \ppl{forename}{surname}.
>>>>> When you need only surname in the text, use \pplsur macro instead.
>>>>> For names with abbreviated middle name, there is a \pplmdl command as
>>>>> well.
>>>>>
>>>>> Patch 5/7 highlights indexed words/terms/names in the text.
>>>>> This should help us in finding out what needs to be annotated.
>>>>> If the color of DarkGreen is problematic for you, please let me know
>>>>> which color is easy for you.
>>>>> One of the purpose of avoiding raw \index{} macros for annotation is
>>>>> to realize this coloring.
>>>>>
>>>>> Patch 6/7 adds a few more annotations of people's names in "formal".
>>>>>
>>>>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
>>>>> As mentioned in the change log, API Index shows a minor glitches of
>>>>> extraneous line folding caused by the side effect of \co{} macro.
>>>>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
>>>>> I have not figured out if there is some workaround for older LaTeX.
>>>>
>>>> Nice start!
>>>>
>>>> This is in the "lt" flavor only, correct?
>>>
>>> Oh, why did I miss the most important to share?
>>> I added a new target "ix" and its derivative "1cix" in patch 1/7.
>>> These make targets enable coloring of indexed words/names/APIs added in
>>> patch 5/7. I'm not sure the color choice works with your eyes, though.
>>>
>>>> The default "make" generates
>>>> the perfbook.ind file, but does not include it. But "make lt" doesn't
>>>> either. Trying again setting the "toindex" boolean to "true", which does
>>>> in fact generate a pair of three-column indexes at the end, very good!
>>>>
>>>>> The appearance of index pages does not matter so much at the moment,
>>>>> I suppose. We need to add annotations first.
>>>>
>>>> Agreed, the annotations will be a big job. I have a small patch
>>>> at the end for minor typos as well.
>>>
>>> I thought I made quite a few typos. Thanks for catching them.
>>> I'll merge it to patch 1/7.
>>>
>>>>
>>>>> To do that, we need to agree the organization of index pages.
>>>>> Current indices are flat.
>>>>> LaTeX indexing framework supports up to 3 levels of hierarchy.
>>>>>
>>>>> For example:
>>>>>
>>>>> Flat index
>>>>>
>>>>> Critical section, <page>
>>>>> ...
>>>>> Read-side critical section, <page>
>>>>> ...
>>>>> Write-side critical section, <page>
>>>>>
>>>>> 2 level index
>>>>>
>>>>> Critical section, <page>
>>>>> read-side, <page>
>>>>> write-size, <page>
>>>>> ...
>>>>> Read-side critical section, see Critical section, read-side
>>>>> ...
>>>>> Write-side critical section, see Critical section, write-side
>>>>>
>>>>> Which do you prefer?
>>>>
>>>> I have a minor preference for the 2-level index. However, it might or
>>>> might not be worth it. For example, should "Associativity" be on its own,
>>>> or under "Cache"? Or in both places?
>>>
>>> We will need some experiments.
>>> Let me play with terms in glossary.tex.
>>>
>>>>
>>>>> Another point on people's names.
>>>>> I'm *not* thinking of making index of authors of Bibliography.
>>>>> Due to the amount of cited material, it will require a ton of cleanups
>>>>> in .bib files if you want the author index to look consistent.
>>>>>
>>>>> Which means, you need to mention names of authors who you want to see
>>>>> in the index. Does this sound reasonable to you?
>>>>
>>>> That makes a lot of sense!
>>>
>>> OK.
>>>
>>>>
>>>>> I know you are debugging/analyzing/testing RCU and lockdep interaction
>>>>> right now.
>>>>
>>>> But sometimes one must take a break. And I am hoping to make more
>>>> progress on updating the last few graphs this week. It turns out that
>>>> there are interesting interactions between userspace RCU's call_rcu()
>>>> worker threads and jemalloc(), for example. The surprise, especially to
>>>> the jemalloc() folks is that jemalloc() doesn't help much, even if the
>>>> call_rcu() worker threads to a throw-away allocation to help jemalloc()
>>>> realize that it must create caches for those worker threads.
>>>>
>>>> It is possible that this is a consequence of the fact that the bottleneck
>>>> for large RCU-protected hash tables is in the L3 cache rather than in
>>>> any particular CPU. Which is an unexpected benefit, as this situation
>>>> clearly calls attention to the possibility of this type of bottleneck.
>>>>
>>>> Not so good for second-edition schedule, though!
>>>
>>> ;-) ;-)
>>>
>>>>
>>>>> I'm not in a hurry and looking forward to your feedback.
>>>>
>>>> I am going to list a few additional index entries: CPU, memory, I/O,
>>>> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
>>>> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
>>>> and software), simultaneous multithreading, hyperthreading, interconnect,
>>>> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
>>>> IPI?), locality of reference (spatial and temporal), cache prefetching,
>>>> cache alignment, cache ways, read-mostly replication, partitioning,
>>>> out-of-order execution, super-scalar CPU, hardware transactional memory,
>>>> software transactional memory, hazard pointers, reference counters,
>>>> lockless, the various counter algorithms, object oriented, object oriented
>>>> spaghetti code, stall (for example, pipeline stall due to a cache miss),
>>>> double-ended queue, maze (or maze solving), branch prediction, atomic
>>>> instructions, atomic read-modify-write instructions, memory barrier,
>>>> distributed-system parallelism (as opposed to shared-memory parallelism),
>>>> communications miss (of caches), herd (the LKMM tool), coherence order,
>>>> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
>>>> and much more, but that is enough for now.
>>>
>>> If you want to do it on your own, why not merge the next pull request
>>> which will address textwidth of 1c-layout index pages?
>>>
>>> It should be safe as indexing is not enabled in existing make targets.
>>
>> So please find v2 of the pull request bellow.
>>
>> It has typo fixes applied in patch 1/7 (now 1/11).
>> Additional 4 patches addresses the width of 1c layout index pages.
>> In doing so, I removed all of those margin settings by magic numbers.
>>
>> Patch 8/11 fixes the 1c geometry settings for index pages.
>> Patch 9/11 removes remaining magical margin settings.
>> Patch 10/11 removes sed patterns substituting options to the \documentclass{}
>> command at the top of perfbook-lt.tex. The geometry package overrides
>> these options afterwords in the preamble.
>> Patch 11/11 adds new make targets in synctex-forward.sh to accept "ix" and
>> "1cix" targets.
>
> I have pulled these in and pushed them under branch akiyks.2020.11.24a,
> thank you! However, given that they do not seem to affect the old
> make targets, I am not seeing much reason not to merge them into the
> master branch. Any reasons not to?
No, I think merging into master should be safe.
There might be other typos I introduced in the branch which affects
old targets, but we can fix them later, if any.
Thanks, Akira
>
> Thanx, Paul
>
>> Thanks, Akira
>>
>> --
>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>>
>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>>
>> are available in the Git repository at:
>>
>> https://github.com/akiyks/perfbook.git tags/for-paul-2020.11.24a
>>
>> for you to fetch changes up to d4acd14416f6a96591cd5cf6733155064acee44b:
>>
>> synctex-forward: Add new targets in target list (2020-11-24 23:48:31 +0900)
>>
>> ----------------------------------------------------------------
>> Akira Yokosawa (11):
>> PoC of indexing
>> Reorganize backmatters
>> PoC of additional API Index
>> index: Add annotations to people's names for PoC
>> Color indexed text conditionally
>> index: Add some more people index annotations in 'formal'
>> index: Trial of 3 column
>> Use wider layout for Index in 1c build
>> Delegate geometry settings to 'geometry' package
>> Makefile: Remove sed patterns to substitute paper and column setting
>> synctex-forward: Add new targets in target list
>>
>> .gitignore | 3 +
>> Makefile | 15 +-
>> SMPdesign/SMPdesign.tex | 2 +-
>> SMPdesign/partexercises.tex | 5 +-
>> appendix/ack/ack.tex => ack.tex | 6 +-
>> appendix/appendix.tex | 20 --
>> count/count.tex | 2 +-
>> cpu/cpu.tex | 3 +-
>> cpu/hwfreelunch.tex | 6 +-
>> cpu/overview.tex | 4 +-
>> datastruct/datastruct.tex | 4 +-
>> debugging/debugging.tex | 5 +-
>> defer/rcurelated.tex | 92 +++++----
>> defer/rcuusage.tex | 3 +-
>> formal/axiomatic.tex | 4 +-
>> formal/ppcmem.tex | 7 +-
>> formal/spinhint.tex | 2 +-
>> future/cpu.tex | 12 +-
>> future/tm.tex | 2 +-
>> glossary.tex | 112 +++++------
>> howto/howto.tex | 37 ++--
>> intro/intro.tex | 8 +-
>> memorder/memorder.tex | 6 +-
>> perfbook-lt.tex | 143 ++++++++++----
>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
>> utilities/runlatex.sh | 2 +
>> utilities/synctex-forward.sh | 6 +-
>> 27 files changed, 510 insertions(+), 421 deletions(-)
>> rename appendix/ack/ack.tex => ack.tex (98%)
>> --
>>
>>>
>>>>
>>>> Should the index expand acronyms? Hennessy and Patterson do for some
>>>> acronyms but not others, so we can justify being inconsistent if we
>>>> would like.
>>>
>>> I guess index entries will keep somewhat inconsistent in any way.
>>> Keeping them consistent will require huge effort.
>>>
>>>>
>>>> You might argue that some of these need glossary entries, and you
>>>> would be quite right. ;-)
>>>
>>> ;-)
>>>
>>>>
>>>> In other news, I am considering bringing back the quantum-computing
>>>> section given that things seem to have stabilized a bit. But it is
>>>> still a bit off-topic.
>>>>
>>>> Again, great start on the index!
>>>
>>> Glad to know you liked it!
>>>
>>> Thanks, Akira
>>>
>>>>
>>>> Thanx, Paul
>>>>
>>>>> Thanks, Akira
>>>>>
>>>>> --
>>>>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
>>>>>
>>>>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
>>>>>
>>>>> are available in the Git repository at:
>>>>>
>>>>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
>>>>>
>>>>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
>>>>>
>>>>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
>>>>>
>>>>> ----------------------------------------------------------------
>>>>> Akira Yokosawa (7):
>>>>> PoC of indexing
>>>>> Reorganize backmatters
>>>>> PoC of additional API Index
>>>>> index: Add annotations to people's names for PoC
>>>>> Color indexed text conditionally
>>>>> index: Add some more people index annotations in 'formal'
>>>>> index: Trial of 3 column
>>>>>
>>>>> .gitignore | 3 +
>>>>> Makefile | 10 +-
>>>>> SMPdesign/SMPdesign.tex | 2 +-
>>>>> SMPdesign/partexercises.tex | 5 +-
>>>>> appendix/ack/ack.tex => ack.tex | 6 +-
>>>>> appendix/appendix.tex | 20 --
>>>>> count/count.tex | 2 +-
>>>>> cpu/cpu.tex | 3 +-
>>>>> cpu/hwfreelunch.tex | 6 +-
>>>>> cpu/overview.tex | 4 +-
>>>>> datastruct/datastruct.tex | 4 +-
>>>>> debugging/debugging.tex | 5 +-
>>>>> defer/rcurelated.tex | 92 +++++----
>>>>> defer/rcuusage.tex | 3 +-
>>>>> formal/axiomatic.tex | 4 +-
>>>>> formal/ppcmem.tex | 7 +-
>>>>> formal/spinhint.tex | 2 +-
>>>>> future/cpu.tex | 12 +-
>>>>> future/tm.tex | 2 +-
>>>>> glossary.tex | 112 +++++------
>>>>> howto/howto.tex | 37 ++--
>>>>> intro/intro.tex | 8 +-
>>>>> memorder/memorder.tex | 6 +-
>>>>> perfbook-lt.tex | 75 ++++++-
>>>>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
>>>>> utilities/runlatex.sh | 2 +
>>>>> 26 files changed, 470 insertions(+), 382 deletions(-)
>>>>> rename appendix/ack/ack.tex => ack.tex (98%)
>>
>>
>>
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [NOT PULL YET -perfbook] PoC of adding index to perfbook
2020-11-24 22:38 ` Akira Yokosawa
@ 2020-11-25 0:35 ` Paul E. McKenney
0 siblings, 0 replies; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-25 0:35 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Nov 25, 2020 at 07:38:08AM +0900, Akira Yokosawa wrote:
> On Tue, 24 Nov 2020 11:22:57 -0800, Paul E. McKenney wrote:
> > On Tue, Nov 24, 2020 at 07:29:58AM +0900, Akira Yokosawa wrote:
> >> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
> >>> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> >>>> Hi Paul,
> >>>>
> >>>> So this *not-pull* request is to show you my WIP branch to add indices
> >>>> to perfbook.
> >>>>
> >>>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
> >>>>
> >>>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
> >>>> Credits, and the newly added Index belong there.
> >>>> I employed "tocbibind" package to include Bibliography in TOC.
> >>>>
> >>>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
> >>>> toolsoftrade.
> >>>> You can see that raw \index or \sindex macros are avoided in .tex source
> >>>> files. Using custom macros for annotation can reduce diffs in adding
> >>>> annotations.
> >>>> glossary.tex is an exception, as every description item has
> >>>> \index{} on it. If we add other annotations there, we need to use
> >>>> custom macros.
> >>>>
> >>>> Patch 4/7 adds annotations for people's names. They could be in another
> >>>> independent index, but they are merged into the general index.
> >>>> As a result, the ratio of people's names in the index is quite high at the
> >>>> moment.
> >>>> It will decrease as we add annotations for general terms/words.
> >>>> Names are presented in the index in the form of "surname, forename" order.
> >>>> To enable this, annotation is done by \ppl{forename}{surname}.
> >>>> When you need only surname in the text, use \pplsur macro instead.
> >>>> For names with abbreviated middle name, there is a \pplmdl command as
> >>>> well.
> >>>>
> >>>> Patch 5/7 highlights indexed words/terms/names in the text.
> >>>> This should help us in finding out what needs to be annotated.
> >>>> If the color of DarkGreen is problematic for you, please let me know
> >>>> which color is easy for you.
> >>>> One of the purpose of avoiding raw \index{} macros for annotation is
> >>>> to realize this coloring.
> >>>>
> >>>> Patch 6/7 adds a few more annotations of people's names in "formal".
> >>>>
> >>>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
> >>>> As mentioned in the change log, API Index shows a minor glitches of
> >>>> extraneous line folding caused by the side effect of \co{} macro.
> >>>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
> >>>> I have not figured out if there is some workaround for older LaTeX.
> >>>
> >>> Nice start!
> >>>
> >>> This is in the "lt" flavor only, correct?
> >>
> >> Oh, why did I miss the most important to share?
> >> I added a new target "ix" and its derivative "1cix" in patch 1/7.
> >> These make targets enable coloring of indexed words/names/APIs added in
> >> patch 5/7. I'm not sure the color choice works with your eyes, though.
> >
> > I guess I could have looked at diffs to Makefile...
> >
> > I don't see any colors, though, perhaps because I am failing to
> > distinguish dark green from black?.
>
> How does "s/DarkGreen/FireBrick/" look?
>
> Available color names can be found in page 38 of
> http://mirrors.ctan.org/macros/latex/contrib/xcolor/xcolor.pdf
> via the "svgnames option.
>
> Can you choose a color which works with your eyes?
Never mind, DarkGreen works. I was expecting the headings in the glossary
to change color, which they do not (which should not be a problem).
But if I click back on (say) C bounded model checker, I do see the green.
Thanx, Paul
> Thanks, Akira
>
> >
> >>> The default "make" generates
> >>> the perfbook.ind file, but does not include it. But "make lt" doesn't
> >>> either. Trying again setting the "toindex" boolean to "true", which does
> >>> in fact generate a pair of three-column indexes at the end, very good!
> >>>
> >>>> The appearance of index pages does not matter so much at the moment,
> >>>> I suppose. We need to add annotations first.
> >>>
> >>> Agreed, the annotations will be a big job. I have a small patch
> >>> at the end for minor typos as well.
> >>
> >> I thought I made quite a few typos. Thanks for catching them.
> >> I'll merge it to patch 1/7.
> >
> > Nevertheless, I suspect that you have corrected quite a few more of
> > my typos than I have of yours. ;-)
> >
> >>>> To do that, we need to agree the organization of index pages.
> >>>> Current indices are flat.
> >>>> LaTeX indexing framework supports up to 3 levels of hierarchy.
> >>>>
> >>>> For example:
> >>>>
> >>>> Flat index
> >>>>
> >>>> Critical section, <page>
> >>>> ...
> >>>> Read-side critical section, <page>
> >>>> ...
> >>>> Write-side critical section, <page>
> >>>>
> >>>> 2 level index
> >>>>
> >>>> Critical section, <page>
> >>>> read-side, <page>
> >>>> write-size, <page>
> >>>> ...
> >>>> Read-side critical section, see Critical section, read-side
> >>>> ...
> >>>> Write-side critical section, see Critical section, write-side
> >>>>
> >>>> Which do you prefer?
> >>>
> >>> I have a minor preference for the 2-level index. However, it might or
> >>> might not be worth it. For example, should "Associativity" be on its own,
> >>> or under "Cache"? Or in both places?
> >>
> >> We will need some experiments.
> >> Let me play with terms in glossary.tex.
> >
> > Sounds good!
> >
> >>>> I'm *not* thinking of making index of authors of Bibliography.
> >>>> Due to the amount of cited material, it will require a ton of cleanups
> >>>> in .bib files if you want the author index to look consistent.
> >>>>
> >>>> Which means, you need to mention names of authors who you want to see
> >>>> in the index. Does this sound reasonable to you?
> >>>
> >>> That makes a lot of sense!
> >>
> >> OK.
> >>
> >>>
> >>>> I know you are debugging/analyzing/testing RCU and lockdep interaction
> >>>> right now.
> >>>
> >>> But sometimes one must take a break. And I am hoping to make more
> >>> progress on updating the last few graphs this week. It turns out that
> >>> there are interesting interactions between userspace RCU's call_rcu()
> >>> worker threads and jemalloc(), for example. The surprise, especially to
> >>> the jemalloc() folks is that jemalloc() doesn't help much, even if the
> >>> call_rcu() worker threads to a throw-away allocation to help jemalloc()
> >>> realize that it must create caches for those worker threads.
> >>>
> >>> It is possible that this is a consequence of the fact that the bottleneck
> >>> for large RCU-protected hash tables is in the L3 cache rather than in
> >>> any particular CPU. Which is an unexpected benefit, as this situation
> >>> clearly calls attention to the possibility of this type of bottleneck.
> >>>
> >>> Not so good for second-edition schedule, though!
> >>
> >> ;-) ;-)
> >>
> >>>
> >>>> I'm not in a hurry and looking forward to your feedback.
> >>>
> >>> I am going to list a few additional index entries: CPU, memory, I/O,
> >>> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
> >>> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
> >>> and software), simultaneous multithreading, hyperthreading, interconnect,
> >>> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
> >>> IPI?), locality of reference (spatial and temporal), cache prefetching,
> >>> cache alignment, cache ways, read-mostly replication, partitioning,
> >>> out-of-order execution, super-scalar CPU, hardware transactional memory,
> >>> software transactional memory, hazard pointers, reference counters,
> >>> lockless, the various counter algorithms, object oriented, object oriented
> >>> spaghetti code, stall (for example, pipeline stall due to a cache miss),
> >>> double-ended queue, maze (or maze solving), branch prediction, atomic
> >>> instructions, atomic read-modify-write instructions, memory barrier,
> >>> distributed-system parallelism (as opposed to shared-memory parallelism),
> >>> communications miss (of caches), herd (the LKMM tool), coherence order,
> >>> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
> >>> and much more, but that is enough for now.
> >>
> >> If you want to do it on your own, why not merge the next pull request
> >> which will address textwidth of 1c-layout index pages?
> >>
> >> It should be safe as indexing is not enabled in existing make targets.
> >
> > I am thinking in terms of merging the index first thing after the
> > second edition. Though at the rate I am going on it, you might well
> > have it ready beforehand...
> >
> >>> Should the index expand acronyms? Hennessy and Patterson do for some
> >>> acronyms but not others, so we can justify being inconsistent if we
> >>> would like.
> >>
> >> I guess index entries will keep somewhat inconsistent in any way.
> >> Keeping them consistent will require huge effort.
> >
> > As near as I can tell, the more familiar ones were left unexpanded and
> > the more specialized ones were expanded. So they left LAN unexpanded,
> > but expanded NUMA. In my old edition, anyway.
> >
> > Thanx, Paul
> >
> >>> You might argue that some of these need glossary entries, and you
> >>> would be quite right. ;-)
> >>
> >> ;-)
> >>
> >>>
> >>> In other news, I am considering bringing back the quantum-computing
> >>> section given that things seem to have stabilized a bit. But it is
> >>> still a bit off-topic.
> >>>
> >>> Again, great start on the index!
> >>
> >> Glad to know you liked it!
> >>
> >> Thanks, Akira
> >>
> >>>
> >>> Thanx, Paul
> >>>
> >>>> Thanks, Akira
> >>>>
> >>>> --
> >>>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
> >>>>
> >>>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
> >>>>
> >>>> are available in the Git repository at:
> >>>>
> >>>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
> >>>>
> >>>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
> >>>>
> >>>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
> >>>>
> >>>> ----------------------------------------------------------------
> >>>> Akira Yokosawa (7):
> >>>> PoC of indexing
> >>>> Reorganize backmatters
> >>>> PoC of additional API Index
> >>>> index: Add annotations to people's names for PoC
> >>>> Color indexed text conditionally
> >>>> index: Add some more people index annotations in 'formal'
> >>>> index: Trial of 3 column
> >>>>
> >>>> .gitignore | 3 +
> >>>> Makefile | 10 +-
> >>>> SMPdesign/SMPdesign.tex | 2 +-
> >>>> SMPdesign/partexercises.tex | 5 +-
> >>>> appendix/ack/ack.tex => ack.tex | 6 +-
> >>>> appendix/appendix.tex | 20 --
> >>>> count/count.tex | 2 +-
> >>>> cpu/cpu.tex | 3 +-
> >>>> cpu/hwfreelunch.tex | 6 +-
> >>>> cpu/overview.tex | 4 +-
> >>>> datastruct/datastruct.tex | 4 +-
> >>>> debugging/debugging.tex | 5 +-
> >>>> defer/rcurelated.tex | 92 +++++----
> >>>> defer/rcuusage.tex | 3 +-
> >>>> formal/axiomatic.tex | 4 +-
> >>>> formal/ppcmem.tex | 7 +-
> >>>> formal/spinhint.tex | 2 +-
> >>>> future/cpu.tex | 12 +-
> >>>> future/tm.tex | 2 +-
> >>>> glossary.tex | 112 +++++------
> >>>> howto/howto.tex | 37 ++--
> >>>> intro/intro.tex | 8 +-
> >>>> memorder/memorder.tex | 6 +-
> >>>> perfbook-lt.tex | 75 ++++++-
> >>>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> >>>> utilities/runlatex.sh | 2 +
> >>>> 26 files changed, 470 insertions(+), 382 deletions(-)
> >>>> rename appendix/ack/ack.tex => ack.tex (98%)
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [GIT PULL v2 -perfbook] PoC of adding index to perfbook
2020-11-24 22:43 ` Akira Yokosawa
@ 2020-11-25 2:48 ` Paul E. McKenney
0 siblings, 0 replies; 11+ messages in thread
From: Paul E. McKenney @ 2020-11-25 2:48 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Nov 25, 2020 at 07:43:59AM +0900, Akira Yokosawa wrote:
> On Tue, 24 Nov 2020 11:29:47 -0800, Paul E. McKenney wrote:
> > On Wed, Nov 25, 2020 at 12:21:44AM +0900, Akira Yokosawa wrote:
> >> On Tue, 24 Nov 2020 07:29:58 +0900, Akira Yokosawa wrote:
> >>> On Mon, 23 Nov 2020 13:15:42 -0800, Paul E. McKenney wrote:
> >>>> On Mon, Nov 23, 2020 at 12:14:05AM +0900, Akira Yokosawa wrote:
> >>>>> Hi Paul,
> >>>>>
> >>>>> So this *not-pull* request is to show you my WIP branch to add indices
> >>>>> to perfbook.
> >>>>>
> >>>>> Patch 1/7 kicks of the changes by adding index annotations in Glossary.
> >>>>>
> >>>>> Patch 2/7 reorganizes back matter of perfbook. Glossary, Bibliography,
> >>>>> Credits, and the newly added Index belong there.
> >>>>> I employed "tocbibind" package to include Bibliography in TOC.
> >>>>>
> >>>>> Patch 3/7 adds API Index. Annotations for the Index is mostly done in
> >>>>> toolsoftrade.
> >>>>> You can see that raw \index or \sindex macros are avoided in .tex source
> >>>>> files. Using custom macros for annotation can reduce diffs in adding
> >>>>> annotations.
> >>>>> glossary.tex is an exception, as every description item has
> >>>>> \index{} on it. If we add other annotations there, we need to use
> >>>>> custom macros.
> >>>>>
> >>>>> Patch 4/7 adds annotations for people's names. They could be in another
> >>>>> independent index, but they are merged into the general index.
> >>>>> As a result, the ratio of people's names in the index is quite high at the
> >>>>> moment.
> >>>>> It will decrease as we add annotations for general terms/words.
> >>>>> Names are presented in the index in the form of "surname, forename" order.
> >>>>> To enable this, annotation is done by \ppl{forename}{surname}.
> >>>>> When you need only surname in the text, use \pplsur macro instead.
> >>>>> For names with abbreviated middle name, there is a \pplmdl command as
> >>>>> well.
> >>>>>
> >>>>> Patch 5/7 highlights indexed words/terms/names in the text.
> >>>>> This should help us in finding out what needs to be annotated.
> >>>>> If the color of DarkGreen is problematic for you, please let me know
> >>>>> which color is easy for you.
> >>>>> One of the purpose of avoiding raw \index{} macros for annotation is
> >>>>> to realize this coloring.
> >>>>>
> >>>>> Patch 6/7 adds a few more annotations of people's names in "formal".
> >>>>>
> >>>>> Patch 7/7 changes the layout of index from default 2 columns to 3 columns.
> >>>>> As mentioned in the change log, API Index shows a minor glitches of
> >>>>> extraneous line folding caused by the side effect of \co{} macro.
> >>>>> This issue has been fixed in the most recent LaTeX released on 2020-10-01.
> >>>>> I have not figured out if there is some workaround for older LaTeX.
> >>>>
> >>>> Nice start!
> >>>>
> >>>> This is in the "lt" flavor only, correct?
> >>>
> >>> Oh, why did I miss the most important to share?
> >>> I added a new target "ix" and its derivative "1cix" in patch 1/7.
> >>> These make targets enable coloring of indexed words/names/APIs added in
> >>> patch 5/7. I'm not sure the color choice works with your eyes, though.
> >>>
> >>>> The default "make" generates
> >>>> the perfbook.ind file, but does not include it. But "make lt" doesn't
> >>>> either. Trying again setting the "toindex" boolean to "true", which does
> >>>> in fact generate a pair of three-column indexes at the end, very good!
> >>>>
> >>>>> The appearance of index pages does not matter so much at the moment,
> >>>>> I suppose. We need to add annotations first.
> >>>>
> >>>> Agreed, the annotations will be a big job. I have a small patch
> >>>> at the end for minor typos as well.
> >>>
> >>> I thought I made quite a few typos. Thanks for catching them.
> >>> I'll merge it to patch 1/7.
> >>>
> >>>>
> >>>>> To do that, we need to agree the organization of index pages.
> >>>>> Current indices are flat.
> >>>>> LaTeX indexing framework supports up to 3 levels of hierarchy.
> >>>>>
> >>>>> For example:
> >>>>>
> >>>>> Flat index
> >>>>>
> >>>>> Critical section, <page>
> >>>>> ...
> >>>>> Read-side critical section, <page>
> >>>>> ...
> >>>>> Write-side critical section, <page>
> >>>>>
> >>>>> 2 level index
> >>>>>
> >>>>> Critical section, <page>
> >>>>> read-side, <page>
> >>>>> write-size, <page>
> >>>>> ...
> >>>>> Read-side critical section, see Critical section, read-side
> >>>>> ...
> >>>>> Write-side critical section, see Critical section, write-side
> >>>>>
> >>>>> Which do you prefer?
> >>>>
> >>>> I have a minor preference for the 2-level index. However, it might or
> >>>> might not be worth it. For example, should "Associativity" be on its own,
> >>>> or under "Cache"? Or in both places?
> >>>
> >>> We will need some experiments.
> >>> Let me play with terms in glossary.tex.
> >>>
> >>>>
> >>>>> Another point on people's names.
> >>>>> I'm *not* thinking of making index of authors of Bibliography.
> >>>>> Due to the amount of cited material, it will require a ton of cleanups
> >>>>> in .bib files if you want the author index to look consistent.
> >>>>>
> >>>>> Which means, you need to mention names of authors who you want to see
> >>>>> in the index. Does this sound reasonable to you?
> >>>>
> >>>> That makes a lot of sense!
> >>>
> >>> OK.
> >>>
> >>>>
> >>>>> I know you are debugging/analyzing/testing RCU and lockdep interaction
> >>>>> right now.
> >>>>
> >>>> But sometimes one must take a break. And I am hoping to make more
> >>>> progress on updating the last few graphs this week. It turns out that
> >>>> there are interesting interactions between userspace RCU's call_rcu()
> >>>> worker threads and jemalloc(), for example. The surprise, especially to
> >>>> the jemalloc() folks is that jemalloc() doesn't help much, even if the
> >>>> call_rcu() worker threads to a throw-away allocation to help jemalloc()
> >>>> realize that it must create caches for those worker threads.
> >>>>
> >>>> It is possible that this is a consequence of the fact that the bottleneck
> >>>> for large RCU-protected hash tables is in the L3 cache rather than in
> >>>> any particular CPU. Which is an unexpected benefit, as this situation
> >>>> clearly calls attention to the possibility of this type of bottleneck.
> >>>>
> >>>> Not so good for second-edition schedule, though!
> >>>
> >>> ;-) ;-)
> >>>
> >>>>
> >>>>> I'm not in a hurry and looking forward to your feedback.
> >>>>
> >>>> I am going to list a few additional index entries: CPU, memory, I/O,
> >>>> multicore, synchronization, cache hit, Moore's Law free lunch, speed of
> >>>> light, 3D integration, accelerators, CAS, socket, core, thread (hardware
> >>>> and software), simultaneous multithreading, hyperthreading, interconnect,
> >>>> interrupt (expansion of IRQ?), inter-processor interrupt (expansion of
> >>>> IPI?), locality of reference (spatial and temporal), cache prefetching,
> >>>> cache alignment, cache ways, read-mostly replication, partitioning,
> >>>> out-of-order execution, super-scalar CPU, hardware transactional memory,
> >>>> software transactional memory, hazard pointers, reference counters,
> >>>> lockless, the various counter algorithms, object oriented, object oriented
> >>>> spaghetti code, stall (for example, pipeline stall due to a cache miss),
> >>>> double-ended queue, maze (or maze solving), branch prediction, atomic
> >>>> instructions, atomic read-modify-write instructions, memory barrier,
> >>>> distributed-system parallelism (as opposed to shared-memory parallelism),
> >>>> communications miss (of caches), herd (the LKMM tool), coherence order,
> >>>> reads-from, from-reads, Nidhugg, Promela (and spin?), Linux kernel,
> >>>> and much more, but that is enough for now.
> >>>
> >>> If you want to do it on your own, why not merge the next pull request
> >>> which will address textwidth of 1c-layout index pages?
> >>>
> >>> It should be safe as indexing is not enabled in existing make targets.
> >>
> >> So please find v2 of the pull request bellow.
> >>
> >> It has typo fixes applied in patch 1/7 (now 1/11).
> >> Additional 4 patches addresses the width of 1c layout index pages.
> >> In doing so, I removed all of those margin settings by magic numbers.
> >>
> >> Patch 8/11 fixes the 1c geometry settings for index pages.
> >> Patch 9/11 removes remaining magical margin settings.
> >> Patch 10/11 removes sed patterns substituting options to the \documentclass{}
> >> command at the top of perfbook-lt.tex. The geometry package overrides
> >> these options afterwords in the preamble.
> >> Patch 11/11 adds new make targets in synctex-forward.sh to accept "ix" and
> >> "1cix" targets.
> >
> > I have pulled these in and pushed them under branch akiyks.2020.11.24a,
> > thank you! However, given that they do not seem to affect the old
> > make targets, I am not seeing much reason not to merge them into the
> > master branch. Any reasons not to?
>
> No, I think merging into master should be safe.
>
> There might be other typos I introduced in the branch which affects
> old targets, but we can fix them later, if any.
Very good, I have merged them and pushed out the result, thank you!
Thanx, Paul
> Thanks, Akira
>
> >
> > Thanx, Paul
> >
> >> Thanks, Akira
> >>
> >> --
> >> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
> >>
> >> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
> >>
> >> are available in the Git repository at:
> >>
> >> https://github.com/akiyks/perfbook.git tags/for-paul-2020.11.24a
> >>
> >> for you to fetch changes up to d4acd14416f6a96591cd5cf6733155064acee44b:
> >>
> >> synctex-forward: Add new targets in target list (2020-11-24 23:48:31 +0900)
> >>
> >> ----------------------------------------------------------------
> >> Akira Yokosawa (11):
> >> PoC of indexing
> >> Reorganize backmatters
> >> PoC of additional API Index
> >> index: Add annotations to people's names for PoC
> >> Color indexed text conditionally
> >> index: Add some more people index annotations in 'formal'
> >> index: Trial of 3 column
> >> Use wider layout for Index in 1c build
> >> Delegate geometry settings to 'geometry' package
> >> Makefile: Remove sed patterns to substitute paper and column setting
> >> synctex-forward: Add new targets in target list
> >>
> >> .gitignore | 3 +
> >> Makefile | 15 +-
> >> SMPdesign/SMPdesign.tex | 2 +-
> >> SMPdesign/partexercises.tex | 5 +-
> >> appendix/ack/ack.tex => ack.tex | 6 +-
> >> appendix/appendix.tex | 20 --
> >> count/count.tex | 2 +-
> >> cpu/cpu.tex | 3 +-
> >> cpu/hwfreelunch.tex | 6 +-
> >> cpu/overview.tex | 4 +-
> >> datastruct/datastruct.tex | 4 +-
> >> debugging/debugging.tex | 5 +-
> >> defer/rcurelated.tex | 92 +++++----
> >> defer/rcuusage.tex | 3 +-
> >> formal/axiomatic.tex | 4 +-
> >> formal/ppcmem.tex | 7 +-
> >> formal/spinhint.tex | 2 +-
> >> future/cpu.tex | 12 +-
> >> future/tm.tex | 2 +-
> >> glossary.tex | 112 +++++------
> >> howto/howto.tex | 37 ++--
> >> intro/intro.tex | 8 +-
> >> memorder/memorder.tex | 6 +-
> >> perfbook-lt.tex | 143 ++++++++++----
> >> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> >> utilities/runlatex.sh | 2 +
> >> utilities/synctex-forward.sh | 6 +-
> >> 27 files changed, 510 insertions(+), 421 deletions(-)
> >> rename appendix/ack/ack.tex => ack.tex (98%)
> >> --
> >>
> >>>
> >>>>
> >>>> Should the index expand acronyms? Hennessy and Patterson do for some
> >>>> acronyms but not others, so we can justify being inconsistent if we
> >>>> would like.
> >>>
> >>> I guess index entries will keep somewhat inconsistent in any way.
> >>> Keeping them consistent will require huge effort.
> >>>
> >>>>
> >>>> You might argue that some of these need glossary entries, and you
> >>>> would be quite right. ;-)
> >>>
> >>> ;-)
> >>>
> >>>>
> >>>> In other news, I am considering bringing back the quantum-computing
> >>>> section given that things seem to have stabilized a bit. But it is
> >>>> still a bit off-topic.
> >>>>
> >>>> Again, great start on the index!
> >>>
> >>> Glad to know you liked it!
> >>>
> >>> Thanks, Akira
> >>>
> >>>>
> >>>> Thanx, Paul
> >>>>
> >>>>> Thanks, Akira
> >>>>>
> >>>>> --
> >>>>> The following changes since commit 810da77e1c66ad543e34a10b197aa9e629c7dc8f:
> >>>>>
> >>>>> CodeSamples/formal: Use '{}' for empty init blocks in litmus tests (2020-11-15 12:38:36 -0800)
> >>>>>
> >>>>> are available in the Git repository at:
> >>>>>
> >>>>> https://github.com/akiyks/perfbook.git tags/for-paul-not-pull-2020.11.23a
> >>>>>
> >>>>> for you to fetch changes up to 9cecce4c32c9ff97f3330591d0699c8aa7e2585b:
> >>>>>
> >>>>> index: Trial of 3 column (2020-11-22 23:16:58 +0900)
> >>>>>
> >>>>> ----------------------------------------------------------------
> >>>>> Akira Yokosawa (7):
> >>>>> PoC of indexing
> >>>>> Reorganize backmatters
> >>>>> PoC of additional API Index
> >>>>> index: Add annotations to people's names for PoC
> >>>>> Color indexed text conditionally
> >>>>> index: Add some more people index annotations in 'formal'
> >>>>> index: Trial of 3 column
> >>>>>
> >>>>> .gitignore | 3 +
> >>>>> Makefile | 10 +-
> >>>>> SMPdesign/SMPdesign.tex | 2 +-
> >>>>> SMPdesign/partexercises.tex | 5 +-
> >>>>> appendix/ack/ack.tex => ack.tex | 6 +-
> >>>>> appendix/appendix.tex | 20 --
> >>>>> count/count.tex | 2 +-
> >>>>> cpu/cpu.tex | 3 +-
> >>>>> cpu/hwfreelunch.tex | 6 +-
> >>>>> cpu/overview.tex | 4 +-
> >>>>> datastruct/datastruct.tex | 4 +-
> >>>>> debugging/debugging.tex | 5 +-
> >>>>> defer/rcurelated.tex | 92 +++++----
> >>>>> defer/rcuusage.tex | 3 +-
> >>>>> formal/axiomatic.tex | 4 +-
> >>>>> formal/ppcmem.tex | 7 +-
> >>>>> formal/spinhint.tex | 2 +-
> >>>>> future/cpu.tex | 12 +-
> >>>>> future/tm.tex | 2 +-
> >>>>> glossary.tex | 112 +++++------
> >>>>> howto/howto.tex | 37 ++--
> >>>>> intro/intro.tex | 8 +-
> >>>>> memorder/memorder.tex | 6 +-
> >>>>> perfbook-lt.tex | 75 ++++++-
> >>>>> toolsoftrade/toolsoftrade.tex | 420 ++++++++++++++++++++--------------------
> >>>>> utilities/runlatex.sh | 2 +
> >>>>> 26 files changed, 470 insertions(+), 382 deletions(-)
> >>>>> rename appendix/ack/ack.tex => ack.tex (98%)
> >>
> >>
> >>
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2020-11-25 2:48 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-22 15:14 [NOT PULL YET -perfbook] PoC of adding index to perfbook Akira Yokosawa
2020-11-23 21:06 ` Paul E. McKenney
2020-11-23 21:15 ` Paul E. McKenney
2020-11-23 22:29 ` Akira Yokosawa
2020-11-24 15:21 ` [GIT PULL v2 " Akira Yokosawa
2020-11-24 19:29 ` Paul E. McKenney
2020-11-24 22:43 ` Akira Yokosawa
2020-11-25 2:48 ` Paul E. McKenney
2020-11-24 19:22 ` [NOT PULL YET " Paul E. McKenney
2020-11-24 22:38 ` Akira Yokosawa
2020-11-25 0:35 ` 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.