n-doc: Creating CC Documentation with LaTeX
n-doc is a platform for creating Common Criteria documentation. This repository is the official distribution of n-doc. It contains sample documents, LaTeX macros, Lua programs and everything else you need to write your own developer documentation. The documents here are the developer documentation for "Mauve VPN Client", a fictional TOE serving as a template for the n-doc process. Follow the links to see the resulting PDFs!
Those documents provide an outline that can be used when adapting the sample documents for your own purposes. Especially ASE, ADV_FSP and ADV_TDS contain enough text to show the interaction between documents and database. Clone the repository, build the documents and start changing them for your own TOE!
Compiling the documents
./runmake.sh to build the documents. Result documents are copied
to the directory
runmake.sh starts a
container. This container contains all the tools necessary for building the
documents. There is no need to install any software on your computer. The
current directory that contains the repository is mounted into the container:
docker run --rm --volume $(pwd):/data ndesign/n-doc make -j4 delivery
Use a specific document type instead of
delivery to build only a single
adv_tds etc, see below) . The result document will be in the
subdirectory with the same name.
The optional parameter
-j controls the number of threads (jobs) that GNU Make
starts in parallel. Use the number of cores of your CPU. The more, the faster.
Without a number after
Working on the docments / Structure of the repository
Each document has its own subdirectory. The subdirectories have the
same name as the document type:
adv_tds etc. All files that are
specific to that document type reside in that directory. Elements shared between
documents are in the
common directory. Lua programs are in
engine subdirectory contains the resources needed to create the Docker image
containing TeX Live and all other tools. See the separate documentation in
engine/README.adoc for details.
The documents are usually modularized. There is a main document that includes
the other parts during compile time. This main document must have the same name
as the directory it resides in, e.g.
To add a document use the script
scripts/add_document.sh and provide the type
of the new document as an argument on the command line,
This generates an empty (but compileable) document from a template.
To remove a document use the script
scripts/remove_document.sh and provide
the type of the document as an argument on the command line, e.g.:
latexmk is used at the level of individual documents. To build several
documents at once,
latexmk is combined with
The following goals are availavble at the root level
Creates all PDF-documents and the DB file in their respective directories
Creates all PDF-documents and copies them to the directory
Creates the Security Target
Creates the Funktional Specification (
Creates the Design Specification (
Creates the Security Architecture (
Creates the Test Coverage (
Creates the List of References (
Removes all documents and auxiliary files
Creates the "minimal working examples" (
Removes all documents and auxiliary files for the minimal working examples
The following shell scripts support the build management:
Adds a new document to the repository. The new
document is created from the template in the
Removes a document from the repository. The directory is deleted and the document removed from the Makefile.
Creates a document release. Raises the version number and tags the repository.
Not to be called by the user. Adds the version number to the file name. Is called from the
Not to be called by the user. Creates an archive with the documents in
Collaborating with Others
All the work is done in feature branches. No direct pushes to the
are accepted. Feature branches are spun off the
main branch. Their names
should reflect the purpose, e.g. a ticket number or a short description such as
fix-st-todos. Sometimes it is helpful to prefix branch names with the editor’s
When a feature description is complete and the branch is pushed to the upstream
repository, the editor creates a pull request (Depending on the git server used
in the project, this is called either a merge request or a pull
request. These terms mean the same thing.) The pull request is assigned to the
coordinating editor. They can review the changes and merge the changeset into
main branch. To facilitate a clean repository structure, it is recommended
to rebase the feature branch before accepting the pull request. This can be
done either by using
git rebase or
git pull --rebase. Both are acceptable
and it is a matter of personal taste which one is used.
Not all editors have access to the central git servers that host this document repository. For external editors, who cannot directly push their changes to the upstream repo, there is a patch workflow that is implemented by shell scripts.
Instead of pushing a branch and submitting a pull request, the external editor creates a patch file that incorporates all commits of their feature branch. This patch file is sent to the coordinating editor who will recreate the feature branch by applying the patch file. They then create the pull request themselves.
To create a patch file, call
scripts/create-patch.sh with the feature branch
checked out. The script accepts a single optional argument
followed by a file name. If no file name is given, the script will use the
branch name to derive a file name. In the patch file, every commit of the
feature branch since the spin off from
main has its own patch.
To process a patch file, call
scripts/process-patch.sh. This script requires
the name of a patch file. With no other arguments, the script checks whether the
patch file can be applied to the
main branch. It will also print the names of
the files that are modified by each commit in the patch file.
If called with
--apply) the patch file is not only verified, but also
applied to the repository. A feature branch is created, the script derives the
branch name from the name of the patch file. The script can optionally be called
-b switch followed by a branch name.
It makes no sense to check commit the patch files. Files with the extension
*.patch are ignored in the
Creating releases is described in a separate document.
Minimal Working Examples
documents that serve as Minimal Working Examples (MWE, as is common at
TeX Stackexchange). They provide the same
macros as their "bigger" counterparts and serve as test environments for
reproducing bugs or developing smaller chapters that are quicker to compile than
the ADV documents themselves. The main documents
mwe_fsp/mwe_fsp.tex should not be
modified. Instead, create a file
mwe_<documenttype>_body.tex that can be
freely edited. This
_body file is ignored by git so that there are no merge
conflicts that result from experiments. The make goal
make mwe creates
_body files for all MWE-types.
Command Line Completion
n-doc provides command line completion if you use GNU bash as your shell. Add