Skip to content

Commit

Permalink
Metadata edits (mostly normalization)
Browse files Browse the repository at this point in the history
Unsure what "installation of required packets" meant. My
first run takes no longer than my second, so I removed the
confusing reasoning. Did you mean packages?

Fix markdown syntax for wildcards; * was invoking italics.

Normalized a lot of capitalization and punctuation.
  • Loading branch information
dankamongmen committed Sep 4, 2024
1 parent d09f798 commit 65092f4
Showing 2 changed files with 17 additions and 22 deletions.
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -14,14 +14,14 @@ My goal is to accumulate as much knowledge as possible from all the best experts
# Contributing

There are many ways how you can help.
- You can author a section(s) on a topic you are an expert in. But let me know before you start.
- Small improvements are welcome without prior approval, just open a new PR.
- You can author a section(s) on a topic on which you are expert; let me know before you start.
- Small improvements are welcome without prior approval; just open a new PR.
- Feel free to propose ideas for new content.
- Reviewers with all backgrounds are needed.

Check out the [discussions](https://github.com/dendibakh/perf-book/discussions) page to start.

For examples on how to add images, table, code listings, etc, see [how-to.md](how-to.md).
For examples on how to add images, table, code listings, etc., see [how-to.md](how-to.md).

# Building a book (pdf)

@@ -30,10 +30,10 @@ At the moment, building a PDF only works on Windows and Linux. MacOS requires bu
Requirements:

* Python3. Install natsort module: `pip install natsort`.
* [pandoc](https://pandoc.org/installing.html) - install [version 2.9](https://github.com/jgm/pandoc/releases/tag/2.9.2.1).
* install pandoc filters: `pip install pandoc-fignos pandoc-tablenos`
* install `pandoc-crossref`. This one requires manual installation. I just downloaded the binary from [here](https://github.com/lierdakil/pandoc-crossref/releases/tag/v0.3.6.4) and copied it to the same place where `pandoc-fignos` is.
* [MiKTeX](https://miktex.org/download) - check `Yes` for automatic package installation
* [Pandoc](https://pandoc.org/installing.html). Install [version 2.9](https://github.com/jgm/pandoc/releases/tag/2.9.2.1)
* `pandoc-fignos` and `pandoc-tablenos`. Run `pip install pandoc-fignos pandoc-tablenos`.
* `pandoc-crossref`. This one requires manual installation. I just downloaded the binary from [here](https://github.com/lierdakil/pandoc-crossref/releases/tag/v0.3.6.4) and copied it to the same place where `pandoc-fignos` is.
* [MiKTeX](https://miktex.org/download). Check `Yes` for automatic package installation.

Run:
```bash
@@ -48,7 +48,7 @@ function Run-Block-With-Error($block) {
Run-Block-With-Error {python.exe export_book.py; pdflatex book.tex; bibtex book; pdflatex book.tex; pdflatex book.tex}
```

As a result, `book.pdf` will be generated. The first compilation may be slow due to the installation of required packets.
As a result, `book.pdf` will be generated. The first compilation may be slow.

## License

23 changes: 9 additions & 14 deletions how-to.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ Hint: to save time for exporting the entire book, you can limit it to only a sin
python.exe export_book.py -ch 1 && pdflatex book.tex && bibtex book && pdflatex book.tex && pdflatex book.tex
```

You can also insert LaTex tags directly into the *.md files as shown below. They will not be translated by pandoc. Please try to avoid doing so. :)
You can also insert LaTeX tags directly into the `*.md` files as shown below. They will not be translated by pandoc. Please try to avoid doing so. :)

```
\sectionbreak
@@ -21,7 +21,7 @@ You can also insert LaTex tags directly into the *.md files as shown below. They
```
![40 Years of Microprocessor Trend Data.](../img/1/40-years-processor-trend.png){#fig:40YearsProcessorTrend width=90%}
```
reference it in the text with `@fig:40YearsProcessorTrend`
Reference it in the text with `@fig:40YearsProcessorTrend`.

### Two images side-by-side

@@ -33,8 +33,8 @@ reference it in the text with `@fig:40YearsProcessorTrend`
Two different layouts for the code snippet.
</div>
```
reference it in the text with `@fig:BB_default`, `@fig:BB_better`, or `@fig:BBLayout`
Reference it in the text with `@fig:BB_default`, `@fig:BB_better`, or `@fig:BBLayout`

## Table

```
@@ -51,12 +51,11 @@ C4H 00H BR_INST_RETIRED. Branch instructions retired.
Table: Example of encoding Skylake performance events. {#tbl:perf_count}
```

reference it in the text with `{@tbl:perf_count}`
Reference it in the text with `{@tbl:perf_count}`.

## Paper/Book reference

To reference a book, first download it's citation in a Bibtex format, e.g.:
To reference a book, first download its citation in BibTeX format, e.g.:

```
@Article{Mytkowicz09,
@@ -78,8 +77,7 @@ To reference a book, first download it's citation in a Bibtex format, e.g.:
url = {https://doi.org/10.1145/1508284.1508275},
}
```

Reference the paper in the text with `[@Mytkowicz]`
Reference the paper in the text with `[@Mytkowicz]`.

Not all fields in the citations are required, but get at least `title`, `organization`, `year`, `url`.

@@ -100,7 +98,6 @@ void foo(float* __restrict__ a,
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```

Reference the code listing in the text with `[@lst:optReport]`

You can also use a simpler version for tiny snippets or command line scripts:
@@ -114,17 +111,15 @@ You can also use a simpler version for tiny snippets or command line scripts:
```
[^1]: Profiling(wikipedia) - [https://en.wikipedia.org/wiki/Profiling_(computer_programming)](https://en.wikipedia.org/wiki/Profiling_(computer_programming)).
```

Reference the footnote in the same `*.md` file with `[^1]`

## Section reference

To reference a section af the book from another chapter, first add a tag to the header of the section that you want to refer to, e.g.:
To reference a section of the book from another chapter, first add a tag to the header of the section that you want to refer to, e.g.:

```
# Performance Analysis {#sec:sec1}
```

Reference the section in the text with `[@sec:sec1]`

## Math formulas
@@ -149,4 +144,4 @@ $$

```
> "During the post-Moore era, it will become ever more important to make code run fast and, in particular, to tailor it to the hardware on which it runs." [@Leisersoneaam9744]
```
```

0 comments on commit 65092f4

Please sign in to comment.