Beej's Guide builds with Pandoc, XeLaTeX and a sibling repo

What the repository is for

The README's first instruction is aimed at readers rather than builders: if you merely wish to read the guide, visit the Beej's Guide to Network Programming website. The repository exists for two other reasons.

The stated reasons are that Beej has everything in a repo and that translators can easily clone it. The second is that translators can easily clone it, which is the reason anyone outside the author would want the source rather than the rendered book.

That framing matters for evaluating it. This is not a library, not a tool and not an example project. It is a book written in a markup format, with a build that produces a PDF and a website. The repository root reflects that: `src/` and `source/` for the content, `translations/` for localised versions, `website/` for the site, a `Makefile` and a `Dockerfile`.

The guide's subject, sockets and network programming in C, is not described in this README at all, because this README is about how to build the thing rather than what is inside it.

So the useful question is whether the build system is reproducible and whether the text is easy to fork. Both answers are in the build instructions.

The build needs a second repository

The dependency list is short and specific: GNU make, Python 3 or newer, Pandoc 2.7.3 or newer, XeLaTeX from TeX Live, and the Liberation fonts in sans, serif and mono.

The non-obvious dependency is the build system itself. The README says this depends on an external repo to build, Beej's Guide Build System for Pandoc, at `github.com/beejjorgensen/bgbspd`. You are expected to clone that repository as a sibling of this one:

mystuff-->bggit
      \-->bgbspd

The Makefiles here look for it there, which is visible in the root Makefile:

BGBSPD_BUILD_DIR?=../bgbspd

include $(BGBSPD_BUILD_DIR)/main.make

You can override the location before running make:

export BGBSPD_BUILD_DIR=/some/path/to/bgbspd

That single `include` line explains the whole structure. This repository contains the book and no build logic of its own; all of it arrives through an external Makefile. That is good separation, and it is also why a lone clone does not build.

The build sequence is three steps, and the README is unusually blunt about the last one. Type `make all` from the top-level directory, then `make stage` to copy all the build products and the website into the `stage` directory, and then there is no step three. You can also `cd` into `src` and run make there. `make clean` cleans, and `make pristine` cleans back to the original state.

There is also an `upload` target in the root Makefile that demonstrates the steps for a complete release. Using it means changing the `UPLOADIR` macro to point at your own host, and you can upload individual versions if you prefer.

Docker avoids the local toolchain entirely

For anyone who does not want to assemble Pandoc and a TeX distribution locally, there is a container path, and it is the shortest route to a built book.

The Dockerfile is three lines of real content:

FROM python:3.8.2
RUN apt-get update && apt-get install -y pandoc texlive-xetex fonts-liberation && apt-get clean

WORKDIR /guide
CMD make -e SHELL=/bin/bash pristine all stage

Note what that image installs: Pandoc, the XeTeX bundle and the Liberation fonts, on top of a Python 3.8.2 base. That is the entire toolchain, and the default command runs the full sequence, pristine, all, stage.

Building and running it is:

docker build -t beej-bgnet-builder .
docker run --rm -v "$PWD":/guide -ti beej-bgnet-builder

The volume mount is what makes it useful rather than a curiosity. The image expects the project at `/guide`, so mounting the checkout there and running the container leaves your `./stage` directory ready to be published.

One caveat: the container does not contain the bgbspd build system. The documented command mounts only the current project at `/guide`, so the external build system must also be made available to the container.

The Python base being 3.8.2 is worth noting as a small inconsistency with the documented requirement of Python 3 or newer. It satisfies the floor, but the image pins an old patch release.

Translations, contribution policy and the gaps

The `translations/` directory at the repository root is the practical reason the source is public, and it is also why the contribution policy is unusually restrictive.

The README asks that pull requests be kept to the scale of typo and bug fixes, and gives the reason directly: that way the author does not have to consider any copyright issues when merging changes. For a book, that is a sensible boundary. It is a licence question rather than a technical one, and it means substantial new content will not be accepted.

The TODO section is short and reads as an honest statement of scope rather than a roadmap. Under content it lists a possible file transfer example in the data encapsulation section, whether to cover multicast, and event IO. Three open questions, which is a useful signal about where the guide's coverage stops.

The build instructions also cover font embedding, with the note that examples are in the `src/Makefile`, and that make implementations other than GNU make might work, with Cygwin suggested for Windows users.

On status, the last push was on 2026-04-18 and the repository is not archived. There are no GitHub releases, which is expected for a book whose artefacts are a website rather than a software distribution.

One thing to flag before republishing anything: there is no LICENSE file among the repository's entries and the project's licence field is unknown. The guide is readable and forkable as source, but the absence of a stated licence means the default position on redistribution is the one you would get from not having one.

Editorial conclusion

Clone this repository if you want to read the guide offline, translate it, or build the PDF and website yourself. Do not expect a self-contained build, since the build system is an external dependency that must sit beside the checkout or be pointed at with BGBSPD_BUILD_DIR. Verify first that your Pandoc is 2.7.3 or newer and that XeLaTeX and the Liberation fonts are installed, and note that the repository declares no license, which matters if you intend to republish the text.

Frequently asked questions

Official sources

1. beejjorgensen/bgnet on GitHub
2. Issues
3. README