Introduction

This site contains various documentation-like notes that peter.schuller@infidyne.com decided to write down publicly for whatever reason.

Hardware

ThinkPad T580 impressions (with Linux)

NOTE: This is not a review. These are various impressions after using it and is not intended to be a complete review. In particular, don't assume something works for me if I didn't specifically spell it out.

The following impressions are based on running Ubuntu on a dual-battery T580 with Xorg and i3. The T580 only has the Intel graphics (on purpose for Linux compatibility).

Changelog (significant updates only)

  • 2019-11-09
    • Added note around resume not working w/ external mouse.
  • 2018-10-07
    • Noted upgrading to Ubuntu 18.04.
    • Updated trackpoint section with decision to use external kb/mouse.
  • 2018-07-15
    • Added more comments on my experience with the trackpoint.
  • 2018-04-08
    • More information about the webcam.
  • 2018-04-07
    • Initial version, about 3 weeks or so after receiving the laptop.

Ubuntu compatibility

This was originally written based on experience using Unbutu 17.10. As of 2018-10-07 I have upgraded to upgraded to Ubuntu 18.04 and preliminarily everything seems to work comparably. I tried booting the 18.04 live USB, but I have not performed an installation of 18.04 from scratch.

The touchpad

The touchpad is physically clickable but it appears to use a "hinged" design, with the hinge being on top. In other words, clicking the very bottom of the touchpad works fine and only requires a small amonunt of force (and it differentiates between the left/right side to simulate left/right mouse buttons).

The further up the touchpad you go, the harder you need to press to generate a click. The implication is that as you move your hand around while moving the cursor, it's a crapshoot as to what it feels like to click the touchpad - and if you're far up enough you end up with a lot of "ugh the click didn't take" situations.

My only explanation for this design is that the touchpad is not intended to be a clickable touchpad in the sense you'd expect of a MacBook, but rather that it is intended to behave as if you had dedicated buttons on the bottom of the touchpad (the actual dedicated physical buttons are on top).

That is not really how I want to use a touchpad. I pretty quickly stopped trying to get used to it, and am instead trying to get used to the trackpoint.

TrackPoint

As mentioned above, the touchpad is not really to my taste. Therefore, I used the trackpoint exclusively for the first few months of use.

I did get "used" to it in the sense that usage was natural to me. However, I never became anywhere near as fast as I am with a Macbook Touchpad, and I never shook the feeling of being "restricted" and uncomfortable when needing to do something pointer heavy.

As a result I decided to get an external mouse and keyboard + the docking station which I now use whenever I'm at my desk. I still use the TrackPoint regularly and it remains servicable if not pleasant.

This topic is of course highly subjective and I know many people love trackpoints. But the above is my experience, and figured I would share it.

(As an aside, the CODE 87-Key Cherry MX Brown has been a great keyboard for me. Note there are variants with other Cherry MX switches. Also for some reason it is currently listed with an insanely high price - not sure why; it was $145 when I got it).

The fact that the keyboard/touchpad isn't centered

This definitely irks me a lot, but I'm mostly okay with it. It is legit annoying, especially when using the laptop in my actual lap, because of the balance is off but also because there isn't as good support for my palm/arm on the left hand side as there is on the right hand side.

I should note that this is my private laptop, and the nature of my use is very different than my work laptop. In particular, I don't tend to use it constantly for 12 hours or similar things, and I do worry what would happen if I used it more intensively.

Noise

Spinning a single CPU core for several seconds appears approximately enough to cause the fan to run at a noticable volume. I don't really mind for most cases since I have noise canceling headphones with music in them most of the time. However, it would be enough that I think it will bother me to use the T580 as the chrome casting source if watching TV w/o headphones in the living room with the laptop next to me, for example. (This assumes the browser is streaming video; i.e. use of chrome cast with a non-supported site.)

I would not call it terribly loud, but noticeably so. I am generally not super sensitive to noise compared to some folks, for whatever that is worth in terms of calibration.

Keyboard

As usual with Thinkpads, the keyboard is quite good even if not as good as the classic Thinkpads of old. The primary "annoyance" for me compared with what I've become used to with MacBooks is that the arrow keys are small and stuffed in with other keys making them harder/more risky to use.

This isn't a big deal for me since all my heavy duty keyboard use (text editing) does not involve use of arrow keys, but it does affect certain random things where I don't have other bindings.

Battery

The large cylindrical battery (which is opt-in when you purchase the laptop) sticks out from the laptop and acts as a "foot" for the laptop - slightly elevating the back of it. I have no problem with this myself, but I wanted to mention it in case some folks may prefer it flush.

In terms of battery time, all these experiences based on using Linux and i3; other operating systems, or potentially graphically heavy desktop environments, may see different results.

With both batteries fully charged, it appears that sitting around idling with the screen on and reasonably (but not maximally) bright, I can get around 12 hours.

Playing a typical 1080p YouTube video (without video decoding acceleration) it's around 5-6 hours.

These numbers are currently based on the battery estimate given to me by acpi. I have not spent time measuring how correct they are, or down full draining to confirm rate of reported discharge doesn't change. That said, it feels roughly consistent with what I've experienced when spending multiple hours off battery and keeping a casual eye on battery levels.

Battery problems, possibly gone with BIOS update

The behavior I observed at first was that the large cylindrical battery would be drained first, followed by the smaller battery. This makes sense, since one may want to use the built-in battery as the bridge to allow a battery swap. Upon charging it would fill up the built-in battery first, followed by the cylindrical.

I started observing some anomalies with respect to the wrong battery draining, and the charging happening in the wrong order. Finally, I ended up in a state where the built-in battery would just not charge, even when drained all the way down to 37%.

After much ado, I got a USB CD drive and CDR discs, and did a BIOS update using Lenovo's bootable CD (I had some trouble converting it into a bootable USB stick). Sorry, I lost the exact bios version but this was done early April or late Mars and using whatever was the latest BIOS version at the time.

After the BIOS update, it successfully charged the smaller built-in battery. However, after charging it fully (it was at like 99%), it kept simmering on the built-in battery for I think even hours and I was worried that it would never swap over and charge the larger battery.

I left it overnight and in the morning the larger battery was charged.

I have not exercised the battery a lot, and so lack further anecdotes.

Linux compatibility and tweaks

I only briefly booted Windows for a few minutes, so I effectively only have experience running Linux on this laptop.

xorg driver + avoiding screen tearing

The modesetting driver appears to be picked by default by Xorg on this laptop, and there is signficant screen tearing noticable when doing simple things like scrolling a web page.

A solution is to force the intel driver to be used, and to enable the TearFree option (I don't know what the trade-off is; presumably there is some trade-off if it's not enabled by default).

In my case, I dropped the following into a file in /usr/share/X11/xorg.conf.d:

Section "Device"
      Identifier  "card0"
      Driver      "intel"
      Option      "TearFree" "true"
EndSection

Wayland

My only use of wayland has been through the default Ubuntu desktop that uses Wayland+XWayland. Seems to superficially work, but I spent as little time as possible in this mode until I got my i3 environment bootstrapped.

There was no particular problem with Wayland, and I may still try it out. However, my priority was getting my environment set up rather than playing with Wayland. I am hopeful Wayland will work well and that sway is a good i3 replacement - I just don't know yet.

Suspend/resume

I have one problem with suspend/resume: If I suspend the laptop while an external mouse (USB) is connected, it won't resume again and I have to reset it. I have not done any debugging of the issue.

Outside of that, suspend/resume has been fully reliable. Resume seems to take maybe 2-3 seconds or so.

Bluetooth audio

My use of Bluetooth audio is almost entirely for watching videos (including YouTube) and listening to Audio (in Chrome).

My primary headset is the Bose QC35 (though I have briefly tried the Avantree Audition as well).

I am using pulseaudio.

I have not tried the microphone; if you care about bluetooth audio input, I can't help much.

The good news is that overall, Bluetooth works. I did not require any tweaks w.r.t. bluetooth drivers or bluez etc (the standard pair X, connect X works), but there are a few quirks/things to keep in mind.

  • In order to put the headset into the appropriate mode to get high quality audio, pacmd set-card-profile N a2dp_sink (whatever your card N is). It appears to be defaulting into a headset profile (where the mic theoretically works, but audio quality is horrible.)

  • Once (but only once so far), a huge amount of latency built up; it was on the order of half a second to a second of delay. I "fixed" it by restarting my headset.

  • During normal operation, latency is low enough that I don't consciously notice anything annoying. That said, I should mention that I haven't used this setup to watch a lot of human faces speaking (though I have some).

  • Contrary to the behavior on macOS, the PulseAudio volume control does not appear to affect the hardware volume of the headset. I did not find a way to do this through software, but in the case of the Bose QC35 there are physical buttons on the headset to control the hardware volume. The significance of this is that software volume above 100% will cause distortion, and so it is important that 100% is sufficient volume. If you have a bluetooth headset without physical volume buttons, maybe this could be a problem. I'm not sure.

  • Most of the time, turning on the Bose headset after having resumed the laptop will either (a) cause it to connect after a couple of seconds, or (b) require me to turn the headset back off and back on again and then connect after an additional couple of seconds.

    I have had a few cases that required more attempts. Once I spent almost 5 minutes restarting the headset, flipping scan on/scan off and doing suspend/resumes until it finally started working.

    So TLDR: As usual, Bluetooth pairing/connection is freaking horrible. However, it has been a bit more horrible than I'm used to with macOS, though not incredibly so. With macOS you have random issues sometimes as well, but the biggest difference is that having to turn the headset on and off an extra time seems to be the common case right now. But at least it's mostly consistent.

    I am not entirely sure what these issues are correlated with, and whether e.g. suspend/resume cycles make it more likely.

Battery

It's worth nothing that two separate batteries could potentially complicate matters from a UI perspective.

In my case, I mostly monitor the battery using i3status which will by default aggregate all batteries in the system (configurable, though I did not try it).

But, I mention this just in case the reader may anticipate any problems resulting from the fact that there are multiple batteries exposed logically through ACPI.

Accelerated video decoding

Accelerated decoding in Chrome is disabled. I was not able to find a fix.

The webcam

Very limited testing indicates the webcam works.

One caveat is that Chrome appears to use the infrafed camera by default (it shows up as /dev/video0 with the visible light camera being /dev/video1). If video capture results in a bunch of green garbage this is likely what's going on. Chrome's setting for selecting video device is under "advanced" settings, and under "content" settings. You pick the device in the same place you managed permissions to use the camera.

Misc tweaks

I've done various tweaking to my environment since getting the laptop. If interested you can check out scode/dotfiles - in particular i3status.conf, my i3 config, my keyboard layout and my backlight script (note: requires permissions to write to /sys/class/backlight/intel_backlight/brightness which needs automation to surfive across reboots).

NETGEAR LB1120 (LTE modem) with Google Fi

As of 2020-10-20, I was able to use the NETGEAR LB1120 with Google Fi, with a data-only SIM. The SIM was previously used (as data-only) in a phone, so there may have been some historical activation step that would be required with a fresh SIM - not sure.

For reliable operation I had to use the APN settings documented by Google:

  • Name: Google Fi
  • APN: h2g2

This is configured by heading to the admin interface of the device at http://192.168.5.1 (default password is on the label on the device).

Roomba S9+

NOTE: This is not a review. It is additional information that I was not able to find prior to purchase.

Learning behavior and room labeling

As advertised, the Roomba needs to learn your space before it will allow you to map out different rooms and have it go to specific rooms to clean. This can be more frustrating than first apparent, the more so the larger your living space is. The following experience is for a living space slightly over 2000 square feet.

First, be aware there is a dedicated mapping mode. The dedicated mapping mode causes the roomba not to run the vacuum; instead it will just navigate around the space. This is supposed to be a little faster than vacuuming per documentation. However, unless your living space is small enough for charging not to matter, the biggest difference lies in avoiding charging. In our case, a mapping run of the entire apartment took 6-8 hours, including one charging session. Had we attempted to let it finish a normal "clean all" run it would have taken more than twice as long just from charging, which would have meant more than reasonable day and would have been untenable.

The Roomba is documented to require 2-3 complete runs before an initial map is made, which allows you to begin labeling rooms and clean individual rooms.

In our case, we suspect we encountered a bug on our first attempt - possibly due to the first mapping run being cut short due to the Roomba getting stuck while we were away and us not making it back in time to avoid the Roomba cancelling the job entirely. After that partial run + 3 additional we still didn't get a map, and decided to have the roomba forget the map entirely and restart from scratch. After we did, it completed mapping in 2 mapping runs.

Be aware that the Roomba, when it encounters a problem such as beeing stuck, requires human intervention within a certain amount of time (I think it's like an hour and a half) before it automatically cancels the job. This can prove difficult when your goal is to finish a complete run end to end without cancellations, unless you're home for the entire stretch of the run (6-8 hours in our case).

All in all it took us about a week of having the roomba run every day for 6-8 hours w/o cleaning, before we finally had a map covering the entire living space and we could start running actual vacuum runs.

Can you break up a cleaning run or does it have to finish all in one go?

Documentation is silent on this matter, but my best estimate is that the answer is no. At least not reliably. From what I can tell, if you cancel a mapping run or a clean all run, it'll just start fresh as if the prevous run didn't happen. There is evidence that it still stores and remembers whatever it saw while it was out, but I have not seen any evidence that it will "resume where it left off" in terms of navigating the apartment.

Can you complete initial mapping in a smaller area and add rooms later?

This would be great, as it would avoid needing to finish the entire area in a single uninterrupted run multiple time. From what I can tell though, this does not appear to be supported but I can't be sure. Let me elaborate.

The documentation and other information online is a slittle conflicting, with some accounts claiming it will keep learning after initial mapping and others saying the opposite.

From observations, there is definitely some amount of learning that goes on after initial mapping. For example, if upon mapping you had a giant box in the middle of the room the Roomba might conclude there's a wall/pillar there. After subsequent runs without the box, it will update the map realizing that there is open space (but it may take multiple runs). You can tell this is happening because the visualization of the map in the app updates clearly showing changes like this.

However, I tried opening the door adjacent to a room already within the mapped area. I would tell the roomba to clean the adjacent room, and I was hoping it would find its way into said room and expand the map. While it did enter the room a little (maybe 1-2 meters in and back), it did not keep exploring the room in its entirety. The map also did not expand to include that room. I speculate that there may be a limit to how far the roomba is willing to go beyond its previously mapped area. It's also possible it needs to encounter the new room multiple times before concluding it exists and updating the map.

Because experimenting takes a lot of time, and as described we suffered an entire week before finally getting our area mapped, I don't have a lot of data to share here. It's possible that had I been patient and repeated the process a few times, it would have eventually mapped out the new space entirely - I can't know for sure.

Software

Setting up Chrome Remote Desktop on Ubuntu

Updates

I have been informed of two other solutions. Most recently, this comment appears to describe a better process more directly supported by Google. In the past I was also pointed to this askubuntu question which appears to have a better (shorter, headless) solution than what I describe here. I have not personally tested either of these, but I recommend starting there.

This was written in September of 2015. Not sure whether it still applies.

Sources

The upstream documentation is a little bit scattered, not always entirely complete, and the Ubuntu package provided needs some poking to work. Hence this summary.

The two main sources of information I found are:

Overview of how remote-desktop works

The Linux version of chrome remote desktop (henceforth, CRD) doesn't allow clients to connect and control an existing X session; rather, there is a dedicated X session specific to CRD. This is similar to the classic vncserver mechanic. When you connect, a session is started if one is not already running. If it is running, you are connected to the in-progress session.

Initial setup still requires a non-headless environment: A running Chrome (until someone or Google makes a tool that generates the necessary on-disk state in your home directory for authorizing remote access).

Once set up however, CRD is completely headless and is controlled using an init script. For example:

sudo /etc/init.d/chrome-remote-desktop restart

It determines which users should have CRD running based on which users are part of the chrome-remote-desktop Unix group.

Why Chrome Remote Desktop instead of $OTHER_OPTION?

Mostly:

  • It works natively on ChromeOS, and works well. It handles hi-dpi displays correctly, and passes through keyboard combinations correctly (e.g., it stops CTRL-N from opening a new local window).
  • It seems faster than any other remote desktop option I have tried. I don't know technical details, but likely their use of some kind of modified VP9 codec has to do with this. When originally writing this I thought it was lossy and pixel perfect nonetheless, but I've been informed it's not. At least it was good enough to fool me :)

Setup instructions

Install the package

Download the package linked from https://support.google.com/chrome/answer/1649523?hl=en and install it:

sudo dpkg -i chrome-remote-desktop_current_amd64.deb
sudo apt-get -f install

Prepare the chrome-remote-desktop group

At the time of this writing, the package installer seems to fail to create the chrome-remote-desktop group, so add it:

sudo groupadd chrome-remote-desktop

You may need to add yourself to the group (unclear if this happens correctly automatically):

sudo usermod -a -G chrome-remote-desktop $USER

Set up the desktop session

If ~/.chrome-remote-desktop-session is missing or contains bad information, the attempt to connect to the remote desktop will fail without a clear cause. Example:

#!/bin/bash

xterm &
exec i3

Unconfirmed whether chmod +x is needed.

Set up your desired resolution in your shell profile

Wherever your shell profile is, add an appropriate resolution selection:

export CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES=1024x768

Bootstrap through SSH+VNC

On the server:

sudo apt-get install vnc4server
vncpasswd
vncserver

# log in remotely and bootstrap chrome (see later)

vncserver -kill :1

On the client, log into the server using a VNC client over SSH forwarding. I.e:

ssh -L 5901:localhost:5901 username@remotehost

And run your preferred VNC client to connect to localhost:5901.

Enable remote connections in Chrome

Start Chrome, install the "Chrome Remote Desktop" app, run it. Under "My Computers", hit "Enable remote connections".

Hopefully it should succeed. After this, the session will automatically start on boot thanks to the init script, and chrome will have directly launched a session for you just now - so you should now be able to connect through a CRD client.

Chrome tweaks

More aggressive relaunch prompting for updates

TLDR:

defaults write com.google.Chrome RelaunchNotification -int 1

This appears to work - triggering an actual pop-up and requiring restart within a few days, thus making it harder to accidentally just forget to restart your browser. However, I don't know how to make it more aggressive. At first I wasn't convinced it worked, probabably because I did not wait long enough for the pop-up to appear after the update badge changed color. I eventually forgot about it and finally did get the pop-up a few weeks later after another update.

More info:

rstquil: reStructuredText (rst) + sphinx frustration relief

So you're considering, or even being asked to, adopt reStructuredText and Sphinx for your documentation needs. You've done a ton of markdown or possibly asciidoc in the past, but every time you try to use reStructuredText for real, something non-trivial, it instantly becomes painful to get it to do what you want and you spend unreasonable amounts of time googling around. This is for you.

Or... so I hope. This is what I would have wanted, based on what I consider to be the "obviously immediately important" things I care about when writing documentation. Other people's definition of what is "obviously immediately important" may differ, or their points of frustration may differ, but this is my best attempt at easing adoption for people with similar biases to myself.

My relevant background is writing technical documentation aimed at other software developers in a large organization, and so my needs are heavily based on this. Further, while I write a lot of documentation for a typical developer, it's not the only thing that I do. Part of the frustration of adoption originally was that I would figure something out, and then just about forget it again before the next time I sat down and did similar things.

Some of the terminology here is not formally correct with respect to the reStructuredText spec, but rather intended to convey meaning for someone with reasonable markup/asciidoc experience (sometimes it may also be because I felt it was unclear what correct terminology is).

Finally, this is not meant to be a complete replacement for other documentation. Rather, it's selectively picking a few topics that I believe to be extra important and/or extra likely to cause frustration.

Suggestions/feedback? Feel free to file a github issue, open a pull request on github, or just email me at peter.schuller@infidyne.com1.

Inline literals

Use double backticks:

Let me tell you about the ``cool_function`` function!

A single backtick, like you're used to, may superficially appear to do what you want based on rendered output, but actually is for interpreted text which is different.

Code blocks / multi-line literals

The simplest way is to end your previous paragraph with a double-colon (and don't forget empty lines for paragraph separation):

Here's an example of foo::

    # example of foo here
    # continued example of foo

And this is the next paragraph of text.

The is actually taking advantage of a convenience feature in reStructuredText. The above code-block is equivalent to both of these:

Here's an example of foo: ::

    # example of foo here
    # continued example of foo

And this is the next paragraph of text.

Here's an example of foo:

::

    # example of foo here
    # continued example of foo

And this is the next paragraph of text.

See the literal blocks section of the spec for more.

The biggest disadvantage of the form is that it does not allow you to specify the language contained in the block of text - which you may want to do, for example to enable syntax highlighting. You may therefor use this form instead (which appears to be Sphinx specific):

Here is an example snippet of Python:

.. code-block:: python

    print('Hello world!')

In the above example, we ...

See showing code examples in the Sphinx docs for more.

Linking to URLs

NOTE: This is for linking to arbitrary URLs. For linking internally in your documentation (such as between sections), please see the cross reference section later on.

The short story is to always use the following form unless you specifically know what you're doing (note the use of two underscores at the end, not just one):

`link text <link-url>`__

For example:

Please make sure you foo the bar (such as
in `this example <https://github.com/scode/docs/blob/master/README.md>`__).

Use of a single underscore (instead of two) will create a named hyperlink target. This may appear to work, but you'll find that you start generating warnings over time when you have multiple links with the same link text (even if they have different target URLs).

The seemingly primary use of the single underscore form seems to be to allow you to specify the link target separately from the inline text. For example:

If you want you can look at the `project README`_.

bla bla...

.. _project README: https://github.com/scode/docs/blob/master/README.md

See the hyperlink targets section of the spec for more information.

Bulleted lists

First, a rule of thumb: Always keep an empty line between items in a bulleted or numbered list. I cannot tell you what the rules are here, but I can tell you it will avoid a ton of frustration trying to understand why something isn't interpreted the way you want. It's unfortunate because it is a strain on the eyes when reading the rst source, but I would advice sticking to this rule until you feel like you want to really figure out and understand restructured text and are prepared to deal with the problems when they arise.

Second, continuation of an item happens by starting the next line at the same column position as the previous line, not counting the list markup. The example below illustrates.

#. Foo, which requires a very long
   explanation. Notice the indentation of these
   lines ensuring that these sentences are all part of the
   same item in the list.

   #. Subfoo 1. Notice the alignment of the hash with the parent item's body.

   #. Subfoo 2.

#. Bar

Bulleted lists are exactly the same in terms of indentation and such, but use * (and others) instead of hashes:

* Foo, which requires a very long
  explanation. Notice the indentation of these
  lines ensuring that these sentences are all part of the
  same item in the list.

  * Subfoo 1. Notice the alignment of the hash with the parent item's body.

  * Subfoo 2.

* Bar

For more, see enumerated lists and bullet lists in the spec.

Cross reference best practices

One of the very enticing benefits of using Sphinx is that of stable cross references that do not break when things move around or sections are re-named - provided that best practices are followed (there is also support for cross references across projects through intersphinx but I have not used it so am not covering it here).

Let's assume we have a document with a section on eating apples, and it has a label defined (eating-apples) for the section:

.. _eating-apples:

Eating apples
-------------

We can now link to it from anywhere in our documentation project like this:

See :ref:`eating-apples` for more information.

See :ref:`the later section on apples <eating-apples>` for more information.

Note how the label is specified with a leading underscore but is referred to without it.

In the former case, the name of the section itself will be used in the rendered text. This is not always appropriate because the context of the link is different than the context of the section heading itself, so you may want to refer to the section by a different name - hence the second form.

The key to get the benefit here is to explicitly define all labels that you ever link to. By default, sections will receive an implicit label based on their name, but the problem with using those include:

  • Links break when section names are tweaked, which defeats a big part of the purpose of using cross references.
  • A section without an explicit label fails to signal to the person editing the file containing that section, that someone may be linking to the label.

For this reason, I strongly recommend always explicitly labeling sections when you decide to link to them. When editing existing documentation, you should also assume that explicit labels may be linked to and take care to preserve them. It's an indicator that someone cared about it enough to put a label there, and there's probably a link to it somewhere.

(The previous guidance will obviously not work if you don't have the ability to modify the documentation you're linking to. I don't know if there's a solution to that problem.)

Though I mentioned sections above, labels can be used anywhere and not just in front of sections. For example:

Roses are red and violates are blue, here's a code snippet:

.. _hello-world-snippet:

.. code-block:: python

    print('Hello!')

Footnotes

The following example demonstrates the use of a named footnote.

I love eating fruits [#not-all-fruits]_.

.. [#not-all-fruits] Well, most of them.

In particular, note the white space preceding the [ when referencing the footnote. This is required.

For more information, see footnotes in the rst spec, and the basics in the sphinx docs.

Semi-automated conversion from markdown to rst

I've found pandoc to be quite useful. It will not be perfect, but it will take care of most of the simple stuff and after the automated conversion you go through and perform manual fix-ups. Once you've got it installed:

pandoc -f markdown -t rst < file.md > file.rst

Then edit as appropriate.

1

This would be a link, except I have not been able to figure out how to make a mailto: link in which the @ sign is not URL encoded in the output. Know how to fix that? I'll add it to this guide :)

Reading lists

JVM garbage collection

  • Uniprocessor Garbage Collection Techniques is a good introduction to some core theoretical concepts. This is the paper I read many many years ago and originally helped me become interested in garbage collection.
  • A Generational Mostly-concurrent Garbage Collector is what I think of as "the CMS" paper. It describes the CMS (concurrent mark/sweep) collector in HotSpot. For many ears this was the best option for trying to achieve low latency. It's a non-copying non-compacting old generation collector.
  • Garbage-First Garbage Collection is "the G1" paper. G1 is a newer garbage collector than CMS. This time, it is responsible for both the young generation and the old generation and it's a copying and compacting collector.
  • Azul collectors (these apply to Azul's JVM which AFAIK has never been freely available).
  • Current (2018) "state of the art" with respect to GC in freely available HotSpot are zgc and shenandoah.

Relatedly, you may be interested in scode/lrugctest which is designed to stress a garbage collector using a very simple simulation of a worst-case (for the GC) LRU cache. As of mid 2018, zgc and shenandoah are the only freely available HotSpot GCs that are capable of low (< 10 ms) pause times under that workload.