syntax cosmetics

docs/architecture.md

@@ -132,10 +132,11 @@ caller does not receive `ENOMEM`.
 Primitive types
 ---------------
 
-`User` and `Group` entries are sorted by the order they were received in the input
-file. All entries are aligned to 8 bytes. All `User` and `Group` entries are
-referred by their byte offset in the `Users` and `Groups` section relative to
-the beginning of the section.
+`User` and `Group` entries are sorted by the order they were received in the
+input file. All entries are aligned to 8 bytes. All `User` and `Group` entries
+are referred by their byte offset (shifted by 3 bits due to the 8-byte
+alignment) in the `Users` and `Groups` section relative to the beginning of the
+section.
 
 ```
 const PackedGroup = packed struct {
@@ -146,7 +147,8 @@ const PackedGroup = packed struct {
 ```
 
 PackedGroup is followed by the group name (of length `groupname_len`), followed
-by a varint-compressed offset to the groupmembers section, followed by 8b padding.
+by a varint-compressed offset to the groupmembers section, followed by padding
+upto 8 bytes.
 
 PackedUser is a bit more involved:
 
@@ -177,9 +179,9 @@ them.
 
 PackedUser employs two data-oriented compression techniques:
 - shells are often shared across different users, see the "Shells" section.
-- `name` is frequently a suffix of `home`. For example, `/home/vidmantas` and
-  `vidmantas`. In this case storing both name and home is wasteful. Therefore
-  name has two options:
+- `name` is frequently a suffix of `home`. For example, `home=/home/vidmantas`
+  and `name=vidmantas`. In this case storing both name and home is wasteful.
+  Therefore name has two options:
   1. `name_is_a_suffix=true`: name is a suffix of the home dir. Then `name`
   starts at the `home_len - name_len`'th byte of `home`, and ends at the same
   place as `home`.