Hartree--Fock--Bogoliubov theory with applications to nuclei