README.md

@@ -2,9 +2,9 @@
 
 This is the source for the main Apertis website. It is generated using
 [Hugo](https://gohugo.io/) with a modified
-[beautifulHugo theme](https://github.com/halogenica/beautifulhugo), changing
+[Beautiful Hugo theme](https://github.com/halogenica/beautifulhugo), changing
 the look, implementing search and allowing for the generation of PDFs. The page
-is served from gitlab pages.
+is served from GitLab pages.
 
 ---
 
@@ -17,7 +17,8 @@ layout guidelines:
   - Documenting procedures and rules
   - Minimal requirements for project involvement
 - Concepts:
-  - Topics that have been researched and/or planned but which haven't yet been implemented
+  - Topics that have been researched and/or planned but which haven't yet been
+    implemented
 - Architecture:
   - Description of project infrastructure
   - Details of technologies and software used by Apertis
@@ -26,12 +27,30 @@ layout guidelines:
   - Worked examples of expected project workflows
 - QA:
   - Test reports
-  - Test procedures (realistically, a description of the testing performed and a pointer to qa.apertis.org)
+  - Test procedures (realistically, a description of the testing performed and
+    a pointer to qa.apertis.org)
 - Releases:
   - Release notes
   - Release schedules
 
-## Use of Hugo `ref` shortcode
+## Spelling
+
+In order to provide some consistency and quality to the website, we would like
+to ensure that all documents have been spellchecked. In the mid-term we would
+like checks to be performed as part of the websites CI/CD, using Aspell to
+check the spellings. As it is likely that many of the documents use words not
+in Aspell's dictionaries, we are starting with a manual approach to start
+building up a personal dictionary of additional words that the Apertis project
+is happy with.
+
+When making changes or adding documents, please run:
+
+    aspell --personal="./dictionary.aspell" --lang="en_us" --mode=markdown check <document>
+
+Any issues caught should be rectified or added to the `dictionary.aspell` file
+(maintaining the alphabetical order being used).
+
+## Use of Hugo `ref` Shortcode
 
 Hugo provides the `ref` shortcode to aid with
 [creating links between documents](https://gohugo.io/content-management/cross-references/).
@@ -44,17 +63,17 @@ provided on the website.
 
 In order to generate PDFs, we are getting Hugo to create a simplified HTML
 pages. So as not to have every page generating a PDF, to get a page to be
-generated as a PDF (and html at the same time) add the following to the
-frontmatter of the page:
+generated as a PDF (and HTML at the same time) add the following to the front
+matter of the page:
 
 ```
 outputs = ["html", "pdf-in"]
 ```
 
-This will result in the simplifed HTML being produced in a file called
-`index.pdf-in` in the relevant directory. The CI is configured to look
-for these files once Hugo has generated the site and create PDFs of them. For
-the page `www.apertis.org/concepts/foo/`, a PDF will be available as
+This will result in the simplified HTML being produced in a file called
+`index.pdf-in` in the relevant directory. The CI is configured to look for
+these files once Hugo has generated the site and create PDFs of them. For the
+page `www.apertis.org/concepts/foo/`, a PDF will be available as
 `www.apertis.org/concepts/foo/foo.pdf`.
 
 ## GitLab CI
@@ -76,6 +95,6 @@ Read more at Hugo's [documentation][https://gohugo.io/overview/introduction/].
 
 ### Preview your site
 
-If you clone or download this project to your local computer and run `hugo server`,
-your site can be accessed under `localhost:1313/hugo/`.
+If you clone or download this project to your local computer and run `hugo
+server`, your site can be accessed under `localhost:1313/hugo/`.
 

content/architecture/application-design.md

@@ -102,7 +102,7 @@ a main entry point named `net.example.ShoppingList` and an [agent] named
 
 <!-- Local link definitions -->
 
-[Agent]: appdev-agents.md
+[Agent]: {{< ref "creating-a-canterbury-agent.md" >}}
 
 <!-- External link definitions -->
 

content/architecture/bundle-spec.md

@@ -1195,7 +1195,7 @@ backwards compatibility, and is considered deprecated.
 [Content hand-over]:  {{< ref "content_hand-over.md" >}} 
 [Content type handler]:  {{< ref "content_hand-over.md" >}} 
 [Interface discovery]:  {{< ref "interface_discovery.md" >}} 
-[Internationalization concept design]:  {{< ref "designs/internationalization.md" >}} 
+[Internationalization concept design]:  {{< ref "internationalization.md" >}}
 [Platform layer]:  {{< ref "applications.md#software-categories" >}} 
 [Preferences]:  {{< ref "preferences-and-persistence.md#preferences-approach" >}} 
 [Security between application bundles]:  {{< ref "security.md#security-between-applications" >}} 

content/designs/application-bundle-metadata.md → content/concepts/application-bundle-metadata.md

@@ -12,8 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-08-05"
 +++
 
-# Application bundle metadata
-
 This document extends the Apertis [Applications concept design]
 to cover metadata about [application bundles][Application bundle] (app-bundles).
 
@@ -557,9 +555,9 @@ requester's AppArmor label (part of the AppArmor context).
 <!-- External references -->
 [Android App Manifest]: https://developer.android.com/guide/topics/manifest/manifest-intro.html
 [Android icon sizes]: https://developer.android.com/guide/practices/ui_guidelines/icon_design_launcher.html
-[Apertis Application Bundle Specification]: https://appdev.apertis.org/documentation/bundle-spec.html
+[Apertis Application Bundle Specification]: {{< ref "bundle-spec.md" >}}
 [Apertis Glossary]:  {{< ref "glossary.md" >}} 
-[Applications concept design]: applications.md
+[Applications concept design]: {{< ref "applications.md" >}}
 [Application bundle]:  {{< ref "glossary.md#application-bundle" >}} 
 [AppStream]: https://www.freedesktop.org/software/appstream/docs/
 [AppStream collection XML]: https://www.freedesktop.org/software/appstream/docs/chap-CollectionData.html
@@ -580,11 +578,11 @@ requester's AppArmor label (part of the AppArmor context).
 [libappstream]: https://www.freedesktop.org/software/appstream/docs/api/index.html
 [OEM]:  {{< ref "glossary.md#oem" >}} 
 [Namespaces in XML]: https://www.w3.org/TR/REC-xml-names/
-[Permissions]: permissions.md
-[Permissions concept design]: permissions.md
+[Permissions]: {{< ref "permissions.md" >}}
+[Permissions concept design]: {{< ref "permissions.md" >}}
 [Platform]:  {{< ref "glossary.md#platform" >}} 
-[Security concept design]: security.md
+[Security concept design]: {{< ref "security.md" >}}
 [Snappy]: http://snapcraft.io/
 [Snappy metadata]: https://developer.ubuntu.com/en/snappy/guides/meta/
-[System extension]: applications.md#system-extensions
+[System extension]: {{< ref "applications.md#system-extensions" >}}
 [X-Vendor]: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extending

content/designs/application-entry-points.md → content/concepts/application-entry-points.md

@@ -12,8 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-08-24"
 +++
 
-# Application entry points
-
 ## Requirements
 
 [Application bundles] may contain *application entry points*, which are

content/concepts/application-framework.md

@@ -700,7 +700,7 @@ The store and the deployment management service are kept separate:
 1. Ensure that the whole app-store workflow is documented and functional to
    handle user-driven installations and updates via hawkBit.
 1. Extend the hawkBit agent and other tools to handle the
-   [conditional access]( {{< ref "/wip/conditional_access/_index.md" >}} ) use cases.
+   [conditional access] use cases.
 1. Provide a guide for product teams about deploying their own app-store.
 
 [System services]:  {{< ref "glossary.md#system-service" >}} 
@@ -712,5 +712,5 @@ The store and the deployment management service are kept separate:
 [Flatdeb]: https://gitlab.collabora.com/smcv/flatdeb
 [PipeWire]: https://pipewire.org
 [WirePlumber]: https://gitlab.freedesktop.org/gkiagia/wireplumber
-[conditional access]:  {{< ref "/wip/conditional_access/_index.md" >}} 
+[conditional access]:  {{< ref "/designs/conditional_access/_index.md" >}}
 [Apertis audio management]:  {{< ref "audio-management.md" >}} 

content/designs/application-layout.md → content/concepts/application-layout.md

@@ -12,8 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-08-23"
 +++
 
-# Application layout
-
 Application bundles in the Apertis system may require several categories
 of storage, and to be able to write correct AppArmor profiles, we need
 to be able to restrict each of those categories of storage to a known
@@ -82,8 +80,8 @@ functionality that is not necessarily long-term stable.
 ### Variable files
 
 * The programs in application bundles may save variable data
-  (configuration, state and/or cached files) for each [user]. ([Applications
-  design] §3, "Data Storage")
+  (configuration, state and/or cached files) for each [user]
+  ([Applications design - Data Storage]).
     * *Configuration* is any setting or preference for which there is a
       reasonable default value. If configuration is deleted, the expected
       result is that the user is annoyed by the preference being reset,
@@ -105,7 +103,7 @@ functionality that is not necessarily long-term stable.
       it from a backup.
 * The programs in application bundles may save variable data
   (configuration, state and/or cached files) that are shared between all
-  [users][user]. ([Applications design] §3, "Data Storage")
+  [users][user] ([Applications design - Data storage]).
 * [Newport needs to be able to write downloaded files][bug 283] to a
   designated directory owned by the application bundle.
     * Because Newport is a platform service, its AppArmor profile will
@@ -120,7 +118,7 @@ functionality that is not necessarily long-term stable.
   vulnerabilities considerably more difficult to exploit.
 * Large media files such as music and videos should normally be
   shared between all [users][user] and all multimedia application
-  bundles. ([Multi-user design] §3, "Requirements")
+  bundles. ([Multi-user design - Requirements])
 
 ### Upgrade, rollback, reset and uninstall
 
@@ -1313,20 +1311,22 @@ writing, no implementations of this idea are known.
 <!-- Other documents -->
 
 [Apertis Application Bundle Specification]: https://appdev.apertis.org/documentation/bundle-spec.html
-[Applications design]: applications.md
-[Applications design document]: applications.md
+[Applications design]: {{< ref "applications.md" >}}
+[Applications design document]: {{< ref "applications.md" >}}
+[Applications design - Data storage]: {{< ref "applications.md#data-storage" >}}
 [Application Entry Points]: {{< ref "application-entry-points.md" >}}
 [App store approval]:  {{< ref "app_store_approval.md" >}} 
 [Interface discovery]:  {{< ref "interface_discovery.md" >}} 
-[Multimedia design]: multimedia.md
-[Multimedia design document]: multimedia.md
-[Multi-user design]: multiuser.md
-[Multi-user design document]: multiuser.md
-[Preferences and Persistence design document]: preferences-and-persistence.md
-[System Update and Rollback design]: system-updates-and-rollback.md
-[System Update and Rollback design document]: system-updates-and-rollback.md
-[Security design]: security.md
-[Security design document]: security.md
+[Multimedia design]: {{< ref multimedia.md >}}
+[Multimedia design document]: {{< ref multimedia.md >}}
+[Multi-user design]: {{< ref multiuser.md >}}
+[Multi-user design document]: {{< ref multiuser.md >}}
+[Multi-user design - Requirements]: {{< ref "multiuser.md#requirements" >}}
+[Preferences and Persistence design document]: {{< ref preferences-and-persistence.md >}}
+[System Update and Rollback design]: {{< ref system-updates-and-rollback.md >}}
+[System Update and Rollback design document]: {{< ref system-updates-and-rollback.md >}}
+[Security design]: {{< ref security.md >}}
+[Security design document]: {{< ref security.md >}}
 
 <!-- Glossary -->
 

content/designs/applications.md → content/concepts/applications.md

@@ -12,8 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Applications
-
 This document is intended to give a high-level overview of application
 handling by Apertis. Topics handled include the storage of applications
 and related data on the device, the format of the distributable

content/designs/audio-management.md → content/concepts/audio-management.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-11-23"
 +++
 
-# Audio management
-
-## Introduction
-
 Apertis audio management was previously built around PulseAudio but with the
 move to the Flatpak-based application framework [PipeWire](https://pipewire.org/)
 offers a better match for the use-cases below. Compared to PulseAudio, PipeWire

content/designs/connectivity.md → content/concepts/connectivity.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Connectivity
-
-##  Introduction
-
 Network management is the task of managing the access to networks. In
 other words, deciding when and through which means to connect to the
 internet. In an IVI context this task is affected by several conflicting

content/designs/contacts.md → content/concepts/contacts.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Contacts
-
-##  Introduction
-
 This document outlines our design for address book contacts within the
 Apertis system. It describes the many sources the system can draw upon
 for the user's contacts, how it will manage those contacts, which

content/concepts/coreutils-replacement.md

++++
+title = "GPL-3-free replacements of coreutils"
+short-description = "GPL-3-free replacements of coreutils"
+weight = 100
+
+outputs = [ "html", "pdf-in",]
+date = "2020-12-22"
++++
+
+Due to the nature of Apertis and its target markets there are [licensing terms that are problematic]( {{< ref "license-expectations.md" >}} ) and that forces the project to look for alternatives packages.
+The `coreutils` package is good example of this situation as its license changed to GPLv3 and as result Apertis cannot provide it in the `target` repositories and images.
+The current solution of shipping an old version which precedes the license change is not tenable in the long term, as there are no upgrades with bugfixes or new features for such important package.
+
+This situation leads to the search for a drop-in replacement of `coreutils`, which need to provide compatibility with the standard GNU `coreutils` packages. The reason behind is that many other packages rely on the tools it provides, and failing to do that would lead to hard to debug failures and many custom patches spread all over the archive.
+In this regard the strict requirement is to support the features needed to boot a target image with ideally no changes in other components. The features currently available in our `coreutils-gplv2` fork are a good approximation.
+
+Besides these specific requirements, the are general ones common to any Open Source Project, such as maturity and reliability. Particularly important aspects are also the available community support, the development process and user adoption.
+
+As a summary, bellow is the list of attributes
+
+- License suitable for inclusion in Apertis
+- Compatible with GNU `coreutils`
+- Support for the features needed to boot a target image
+- User adoption
+- Community support
+- Long term solution
+
+# Coreutils GPLv2
+Currently Apertis provides `coreutils-gplv2`, with the following features
+
+`
+[ base64 basename cat chgrp chmod chown chroot cksum comm cp csplit cut date
+dd df dir dircolors dirname du echo env expand expr factor false fmt fold
+groups head hostid id install join link ln logname ls md5sum md5sum.textutils
+mkdir mkfifo mknod mktemp mv nice nl nohup od paste pathchk pinky pr printenv
+printf ptx pwd readlink rm rmdir seq sha1sum sha224sum sha256sum sha384sum
+sha512sum shred shuf sleep sort split stat stty sum sync tac tail tee test
+touch tr true tsort tty uname unexpand uniq unlink users vdir wc who whoami
+yes
+`
+# Alternatives
+
+In order to perform a comparison among different projects this section list different projects and metrics of each them. These metrics are quantitative ones, which can obtain from the Git log, and qualitative that can be derive from the first ones. The value of showing all these metrics is to allow non-technical users to clearly understand the comparison.
+
+## uutils-coreutils
+Link: https://github.com/uutils/coreutils  
+Language: Rust  
+License: MIT  
+GNU compatibility: High (it is the project goal)  
+User adoption: Low  
+Completeness: Missing 14 commands  
+Started: 2013  
+Developers in last year: 40  
+Commits in last year: 885  
+Project status: Very active  
+Community support: High  
+Maturity: Medium  
+
+**Pros**
+- High GNU compatibility
+- High community support
+- High community impact
+- Portability in mind
+- Ongoing development
+- Implemented in a modern memory safe language
+
+**Cons**
+- Missing commands and features
+- Not used in production environments
+- Depends on many Rust crates, which may not all be already available in Debian
+**Notes**
+- Semi-done: `cp expr install ls more od printf sort split tail test date join df`
+- To do: `chcon csplit dd numfmt pr stty`
+- Missing compared to coreutils-gplv2: `csplit dd dir pr stty vdir`
+- Builds successfully on Apertis using the available Rust compiler
+- Initial tests for basic features were successful
+
+## BSDutils
+Link: https://github.com/dcantrell/bsdutils  
+Language: C  
+License: BSD  
+GNU compatibility: Low (project is only a port of OpenBSD compatible with Linux)  
+User adoption: Very low  
+Completeness: Missing 25 commands, long options unsupported, other differences
+Started: 2019  
+Developers in last year: 1  
+Commits in last year: 86  
+Project status: Active  
+Community support: Low (base project high)  
+Maturity: Medium (base project high)  
+
+**Pros**
+- Linux support
+- Based on OpenBSD, which is a mature project
+
+**Cons**
+- Missing commands and features
+- Not fully compatible with GNU as it is a port from OpenBSD
+- Low community support for the port itself
+- Not used in production environments
+- Original project only supports OpenBSD, Linux support added in a low activity fork
+- Requires libbsd-dev
+
+**Notes**
+- This project is a port of tools from OpenBSD to have an BSD-licensed and lightweight replacement of GNU coreutils
+- Provides a set of scripts to import new OpenBSD versions and a set of patches to be applied and provide Linux compatibility
+- In order to upstream contributions might need to be done to this specific project or to OpenBSD
+- Missing from coreutils-gplv2: `base64 cksum dir dircolors hostid link md5sum md5sum.textutils od pathchk pinky ptx seq sha1sum sha224sum sha256sum sha384sum sha512sum shred shuf sum tac tail unlink vdir`
+
+## Busybox
+Link: https://busybox.net/  
+Language: C  
+License: GPLv2  
+GNU compatibility: High (compatibility in mind but a subset of features)  
+User adoption: Very high  
+Completeness: Commands with limited features  
+Started: 1999  
+Developers in last year: 27  
+Commits in last year: 299  
+Project status: Very active  
+Community support: High  
+Maturity: High  
+
+**Pros**
+- High GNU compatibility
+- High community support
+- Very low footprint
+- Already part of Apertis
+
+**Cons**
+- Supports a subset of features
+
+## Nbase
+Link: https://github.com/cheusov/nbase  
+Language: C  
+License: BSD  
+GNU compatibility: Low (project is only a port of NetBSD compatible with Linux)  
+User adoption: Very low__
+Completeness: Missing 33 commands  
+Started: 2015
+Developers in last year: 1  
+Commits in last year: 119  
+Project status: Active  
+Community support: Low  
+Maturity: Medium  
+
+**Pros**
+- Linux support
+- Based on NetBSD, which is a mature project
+
+**Cons**
+- Missing commands and features
+- Not fully compatible with GNU as it is a port from NetBSD
+- Low community support
+- Not used in production environments
+- Requires bmake mk-configure libbsd-dev
+- Original project only supports NetBSD, Linux support added in a low activity fork
+
+**Notes**
+- This project is a port of tools from NetBSD compatible with other Unix like systems
+- Missing from coreutils-gplv2: `[ base64 chgrp chown chroot dir dircolors factor groups hostid install link md5sum md5sum.textutils od pathchk pinky ptx readlink sha1sum sha224sum sha256sum sha384sum sha512sum shred shuf sum tac unlink users vdir who whoami`
+
+## FreeBSD
+Link: https://github.com/freebsd/freebsd/tree/master/bin  
+Link: https://github.com/freebsd/freebsd/tree/master/usr.bin  
+Language: C  
+License: FreeBSD  
+GNU compatibility: Very low
+User adoption: High  
+Developers in last year: 72 (on usr.bin)  
+Commits in last year: 423 (on usr.bin)  
+Project status: Active  
+Community support: High  
+Maturity: High  
+
+**Pros**
+- High community support
+
+**Cons**
+- Missing commands and features
+- No Linux support
+- No GNU compatibility
+
+## Sbase and Ubase
+Link: https://gitlab.com/garbeam/src/-/tree/master/bin/sbase  
+Link: https://gitlab.com/garbeam/src/-/tree/master/bin/ubase  
+Language: C  
+Project status: Inactive, no activity since 2016  
+Community support: None  
+
+**Pros**
+- Linux support
+
+**Cons**
+- Project inactive
+
+## Heirloom
+Link: https://en.wikipedia.org/wiki/Heirloom_Project  
+Link: https://wiki.archlinux.org/index.php/Heirloom  
+Language: C  
+Project status: No activity since 2007  
+Community support: None  
+
+**Pros**
+- Linux support
+
+**Cons**
+- Project inactive
+
+# Replacement: uutils-coreutils
+Based on the above comparison the best option is `uutils-coreutils`, since it is the only one with the explicit goal of providing a fully compatible alternative to GNU `coreutils`, and it has a good community support which most probably will continue and improve in the future. The main risk is the current low user adoption and  the lack of usage in production scenarios. It is worth to mention that the main license used in the project is MIT but further analysis needs to be done to confirm the licensing of all the used dependencies.
+
+These risks enumerated will be handled by the testing and migration in order to provide a reliable approach.
+
+# Testing
+In order to confirm the missing features/commands in the `uutils-coreutils` which are required by Apertis a testing needs to be performed. The steps proposed are:
+
+- Run initial tests on target images
+  - Test booting standard target images
+  - Test installing/removing packages
+- Run current `coreutils-gplv2` test plan with `uutils-coreutils`
+- Run `uutils-coreutils` as default on development environments
+- Make `uuutils-coreutils` and all the Rust crates it depends on available in Debian
+- Provide long-term maintenance of the new packages in Debian as well  
+Note that some effort is being driven by `uutils-coreutils` community to use the `coreutils` test case to generate a report for the still missing features. This will be a nice to have feature but it is more than it is actually required for this stage.
+
+# Initial test and results
+
+As part of an initial test using `uutils-coreutils` the following steps have been taken
+
+- Replace utilities from `coreutils-gplv2` with the ones provided by `uutils-coreutils`
+- Boot target image without issues
+- Reinstall pacakgage `libc6` without issues
+
+These initial results are promising, however more detailed tests should be planned and executed to spot potential issues.
+
+# Migration
+Since `coreutils-gplv2` is a base package special care should be taken. Also the fact that it is outdated adds additions possible security issues, which should be addressed in the short term.
+
+The following guidelines will be followed to assure a smooth transition minimizing risks.
+
+- Determine the list of tools supported and successfully tested provided by `uutils-coreutils`.
+- Create a new package based on `uutils-coreutils` named `coreutils-uutils` with all the tools that are supported and successfully tested.
+- For missing tools a replacement will be provided on case by case basis.
+
+Due to the [Apertis release flow]( {{< ref "release-flow.md" >}} ) this process will start on development releases allowing any potential issue to be addressed before a stable point release, with the possibility of switching back to `coreutils-gplv2` if a proper fix cannot be implemented on time.

content/designs/debug-and-logging.md → content/concepts/debug-and-logging.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Debug and logging
-
-## Introduction
-
 This documents several approaches to debugging components of an Apertis
 system, either during development, or in the field. This includes
 debugging tools for reproducing and analysing problems; and logging

content/designs/geolocation-and-navigation.md → content/concepts/geolocation-and-navigation.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Geolocation and navigation
-
-## Introduction
-
 This documents existing solutions for geo-related features (sometimes
 known as location-based services, LBS) which could be integrated into
 Apertis for providing geolocation, geofencing, geocoding and navigation

content/designs/global-search.md → content/concepts/global-search.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Global search
-
-## Introduction
-
 Apertis will store several types of information – media files,
 documents, contacts, e-mails, applications and their preferences, chat
 logs, and more. Much of this content will be stored with the application

content/designs/inter-domain-communication.md → content/concepts/inter-domain-communication.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Inter-domain communication
-
-## Introduction
-
 This documents a suggested design for an inter-domain communication system,
 which exports services between different domains. Some domains can be trusted
 such as the automotive domain. Some domains are untrusted such as the
@@ -26,7 +22,7 @@ The major considerations with an inter-domain communication system are:
 
   - Security. The purpose of having separate domains is for
     security, so that untrusted code (application bundles) can be run in
-    one domain while minimising the attack surface of the
+    one domain while minimizing the attack surface of the
     safety-critical systems which drive the car.
 
   - Flexibility for different hardware configurations. The domains
@@ -189,12 +185,12 @@ to escape from the isolated environment or get access to resources on the
 host system or other containers for which they haven't been explicitly
 granted access.
 
-[Multiple CE domains][Multiple CE domains setup] are allowed with the
-above setup.
-In this setup, a [Connectivity Domain][Connectivity Domain] can also coexist
-with AD and CE. It is responsible for any interaction with external networks
-and provides isolation in the case a network stack is compromised when that
-stack is not implemented in the shared kernel.
+[Multiple CE domains]({{< ref "#multiple-ce-domains-setup" >}}) are allowed
+with the above setup.  In this setup, a
+[Connectivity Domain]({{< ref "#connectivity-domain" >}}) can also coexist with
+AD and CE. It is responsible for any interaction with external networks and
+provides isolation in the case a network stack is compromised when that stack
+is not implemented in the shared kernel.
 
 ### Separate CPUs setup
 
@@ -304,52 +300,47 @@ The following diagrams depict the data and control flow when the Bluetooth
 device is attached to the AD.
 
 Sending audio stream from BT to AD
-```
-  BT device                  AD                      CE
-      |  ---   attach   ---> |                        |
-      |  ---------      encoded audio      ---------> |
-      |                      | <--- decoded audio --- |
-                (mixing decoded audio in AD) 
-```
+
+    BT device                  AD                      CE
+        |  ---   attach   ---> |                        |
+        |  ---------      encoded audio      ---------> |
+        |                      | <--- decoded audio --- |
+                  (mixing decoded audio in AD) 
 
 Sending audio stream from AD to BT
-```
-  BT device                  AD                      CE
-      |  ---   attach   ---> |                        |
-      |                      | ---- LPCM audio ---->  |
-      |  <--------      encoded audio      ---------  |
-```
+
+    BT device                  AD                      CE
+        |  ---   attach   ---> |                        |
+        |                      | ---- LPCM audio ---->  |
+        |  <--------      encoded audio      ---------  |
 
 The following diagram depicts the data and control flow when the Bluetooth
 device is directly attached to the CE instead.
 
-```
-BT device                           CE                       AD
-    | --------- attach -----------> |                         |
-    | <-------- control ----------  |                         |
-    |                               |                         |
-    | --------- encoded audio ----> |                         |
-    |                               | ------- LPCM audio ---> |
-    |                               | <------ LPCM audio ---- |
-    | <-------- encoded audio ----- |
-```
+    BT device                           CE                       AD
+        | --------- attach -----------> |                         |
+        | <-------- control ----------  |                         |
+        |                               |                         |
+        | --------- encoded audio ----> |                         |
+        |                               | ------- LPCM audio ---> |
+        |                               | <------ LPCM audio ---- |
+        | <-------- encoded audio ----- |
 
 The following diagram depicts the data and control flow when the Bluetooth
 device is directly attached to the CD.
 
-```
-BT device                      CD                CE          AD
-    | ---- attach -----------> |                  |           |
-    | <--- control ----------  |                  |           |
-    |                          | <---- scan ----- |           |
-    |                          | ---- result ---> |           |
-    |                          | <---- play ----- |           |
-    |                          |                              |
-    | ---- encoded audio ----> |                              |
-    |                          | --------- LPCM audio ------> |
-    |                          | <-------- LPCM audio ------- |
-    | <--- encoded audio ----- |
-```
+    BT device                      CD                CE          AD
+        | ---- attach -----------> |                  |           |
+        | <--- control ----------  |                  |           |
+        |                          | <---- scan ----- |           |
+        |                          | ---- result ---> |           |
+        |                          | <---- play ----- |           |
+        |                          |                              |
+        | ---- encoded audio ----> |                              |
+        |                          | --------- LPCM audio ------> |
+        |                          | <-------- LPCM audio ------- |
+        | <--- encoded audio ----- |
+
 Multiple variations are possible on this model.
 
 ### Audio transfer
@@ -401,8 +392,9 @@ decoding of trusted or untrusted video content. This is high bandwidth,
 but means that the output from the video decoder could potentially be
 directed straight onto a surface on the screen.
 
-(See  [Appendix: Audio and video decoding]( {{< ref "#appendix-audio-and-video-decoding" >}} ) for a discussion of options for video and audio
-decoding.)
+(See the appendix on
+[Audio and video decoding]({{< ref "#appendix-audio-and-video-decoding" >}})
+for a discussion of options for video and audio decoding.)
 
 #### Video or audio decoder bugs
 
@@ -415,15 +407,17 @@ apply it to their vehicles. To reduce the window of opportunity for
 exploitation, this update has to be applied by the vehicle owner, rather
 than taking the vehicle into a garage (which could take weeks).
 
+{{% notice info %}}
+For example, like the series of exploitable bugs which
+[affected the ‘secure’ media decoding library on Android](https://en.wikipedia.org/wiki/Stagefright_\(bug\))
+in 2015.
+{{% /notice %}}
 
-> For example, like the series of exploitable bugs which affected the
-> ‘secure’ media decoding library on Android in 2015,
-> [*https://en.wikipedia.org/wiki/Stagefright\_%28bug%29*](https://en.wikipedia.org/wiki/Stagefright_\(bug\))
-
-(*Note: This means we cannot securely support decoding untrusted video
-or audio content in the AD, due to its slow software update cycle,
-unless we use a* hardware *video decoder which is specifically designed
-to cope with malicious inputs.*)
+{{% notice note %}}
+This means we cannot securely support decoding untrusted video or audio content
+in the AD, due to its slow software update cycle, unless we use a *hardware*
+video decoder which is specifically designed to cope with malicious inputs.
+{{% /notice %}}
 
 ### Streaming media
 
@@ -495,7 +489,9 @@ ignore invalid messages, and must not cause unsafe vehicle behaviour.
 The tampering must be detectable by the vendor when the vehicle is
 serviced or investigated after an accident.
 
-(*Note that secure bootloading itself is a separate topic.*)
+{{% notice note %}}
+[Secure bootloading]({{< ref "secure-boot.md" >}}) itself is a separate topic.
+{{% /notice %}}
 
 ### Support multiple AD operating systems
 
@@ -554,7 +550,7 @@ not result in loss of control of the vehicle.
 
 Recent protocol failures have been discovered that allowed an attacker to
 take control of a device remotely. To mitigate this, the network management stack has been moved to a Connectivity Domain.
-The impact of those attacks must be minimized. While the CD functionnality
+The impact of those attacks must be minimised. While the CD functionality
 can be degraded, it must not result in loss of control of the vehicle.
 
 ### After-market upgrade of a domain
@@ -2197,7 +2193,7 @@ described above.
 
 #### Decoded video streams
 
-A fully decoded video stream consumes large quantities of bandwith and sharing
+A fully decoded video stream consumes large quantities of bandwidth and sharing
 it between domains using the same approach used by audio (RTP) can only work
 for very small resolutions (see  [Memory bandwith usage on the i.MX6 Sabrelite]( {{< ref "#memory-bandwith-usage-on-the-imx6-sabrelite" >}} )
 for the bandwidth limitations on one of the platforms targeted by Apertis).
@@ -2212,7 +2208,7 @@ the actual decoding and playback, plus the need for the same memory bandwidth
 toward the GPU where the decoded frames need to be composed.
 
 To be able to handle 1080p video streams it is very important that zero-copy
-mechanisms are used for the trasfer of frames, see
+mechanisms are used for the transfer of frames, see
  [Appendix: Audio and video decoding]( {{< ref "#appendix-audio-and-video-decoding" >}} ) for further considerations about how a
 protocol can be defined to match such expectations.
 
@@ -2391,23 +2387,21 @@ A possible use-case of the API is a Media Player frontend hosted on the AD with
 The frontend requests the backend to decode a specific stream using an application specific API
 and passing a token with the request.
 
-```
-                 AD                          |                       CE
-media player              gateway            |         adapter                media player
- frontend                                    |                                  backend
-    o ------ Play() ------------o------------|------------o----------------------> o
-                                             |            o <-- CreateChannel() -- o
-                                o <-- RequestChannel() -- o
-    o <-- ChannelRequested() -- o            |
-    o -- ChannelRequested() --> o            |
-               reply                         |
-                                o -- RequestChannel() --> o
-                                          reply
-                                o <- connect and nonce -- o
-    o <-- ChannelCreated() ---- o            |            o -- CreateChannel() --> o
-                                             |                     reply
-    o <------------------------------- data channel ------------------------------ o
-```
+                     AD                          |                       CE
+    media player              gateway            |         adapter                media player
+     frontend                                    |                                  backend
+        o ------ Play() ------------o------------|------------o----------------------> o
+                                                 |            o <-- CreateChannel() -- o
+                                    o <-- RequestChannel() -- o
+        o <-- ChannelRequested() -- o            |
+        o -- ChannelRequested() --> o            |
+                   reply                         |
+                                    o -- RequestChannel() --> o
+                                              reply
+                                    o <- connect and nonce -- o
+        o <-- ChannelCreated() ---- o            |            o -- CreateChannel() --> o
+                                                 |                     reply
+        o <------------------------------- data channel ------------------------------ o
 
 The Media Player frontend initially calls
 the application-specific `Play()` method on its backend,
@@ -2452,27 +2446,24 @@ shares them with the update manager in the AD which has access to the devices
 to be updated.
 
 
-```
-                 AD                          |                       CD
-update manager               gateway         |         adapter                 OTA agent
-    o ----> GetUpdate()  -------o------------|------------o----------------------> o
-                                             |            o <-- CreateChannel() -- o
-                                o <-- RequestChannel() -- o
-    o <-- ChannelRequested() -- o            |
-    o -- ChannelRequested() --> o            |
-               reply                         |
-                                o -- RequestChannel() --> o
-                                          reply
-                                o <- connect and nonce -- o
-                                             |            o -- CreateChannel() --> o
-                                             |                     reply
-                                o <-----data channel ----------------------------- o
-                                             |            o <- CommitChannel() --- o
-                                o <-- CommitChannel() --- o
-    o <-- ChannelCreated() ---- o            |            o -- CommitChannel() --> o
-                                             |                     reply
-
-```
+                     AD                          |                       CD
+    update manager               gateway         |         adapter                 OTA agent
+        o ----> GetUpdate()  -------o------------|------------o----------------------> o
+                                                 |            o <-- CreateChannel() -- o
+                                    o <-- RequestChannel() -- o
+        o <-- ChannelRequested() -- o            |
+        o -- ChannelRequested() --> o            |
+                   reply                         |
+                                    o -- RequestChannel() --> o
+                                              reply
+                                    o <- connect and nonce -- o
+                                                 |            o -- CreateChannel() --> o
+                                                 |                     reply
+                                    o <-----data channel ----------------------------- o
+                                                 |            o <- CommitChannel() --- o
+                                    o <-- CommitChannel() --- o
+        o <-- ChannelCreated() ---- o            |            o -- CommitChannel() --> o
+                                                 |                     reply
 
 The update manager calls the `GetUpdate()` method of the agent, with a token
 identifying the request. The OTA agent retrieves the metadata of the file to
@@ -2606,7 +2597,7 @@ There's no requirement that domains run `dbus-daemon` or that they use
 a specific D-Bus implementation to talk to other domains.
 
 Several implementations of the D-Bus serialization format exists and
-their use is trongly encouraged rather than reimplementing the protocol
+their use is strongly encouraged rather than reimplementing the protocol
 from scratch:
 
   - [GDBus] is a GTK+/GNOME oriented implementation of the D-Bus protocol in GLib
@@ -2621,8 +2612,8 @@ from scratch:
 
   - [pydbus] is a python implementation of the D-Bus protocol
 
-On networked setups the D-Bus-based protocol is trasported over TCP, relying on
-IPSec for authentication, confidentialitity and reliability.
+On networked setups the D-Bus-based protocol is transported over TCP, relying on
+IPSec for authentication, confidentiality and reliability.
 
 If IPSec nor TLS are available, those properties cannot be guaranteed, and thus
 such setup is strongly discouraged. In that case every input should be treated
@@ -3651,7 +3642,7 @@ a kind of partial verification of the stream even without decoding it.
 Decoding in the CE poses some challenges in terms of bandwidth, as the amount
 of data generated by fully decoded video streams is very high. It's not going
 to be a viable solution on ethernet-based setups, and advanced zero-copy mechanisms
-to trasfer frames are recommended on single board setups (virtualised or container-based).
+to transfer frames are recommended on single board setups (virtualised or container-based).
 
 [conc-dis-sys]: https://www.cl.cam.ac.uk/teaching/1516/ConcDisSys/materials.html
 
@@ -3659,11 +3650,11 @@ to trasfer frames are recommended on single board setups (virtualised or contain
 
 [bandwidth management]: https://en.wikipedia.org/wiki/Bandwidth_management
 
-[Security concept design]:  {{< ref "/concepts/_index.md" >}} 
+[Security concept design]:  {{< ref "security.md" >}} 
 
 [ucam-cl-tr-630]: http://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-630.html
 
-[Conditional Access design]:  {{< ref "/wip/conditional_access/_index.md" >}} 
+[Conditional Access design]:  {{< ref "/designs/conditional_access/_index.md" >}} 
 
 [GAsyncResult]: https://developer.gnome.org/gio/stable/GAsyncResult.html
 

content/designs/internationalization.md → content/concepts/internationalization.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Internationalization
-
-##  Introduction
-
 This design explains how the Apertis platform will be made localizable
 and how it will be localized to specific locales.
 

content/designs/media-management.md → content/concepts/media-management.md

@@ -12,10 +12,6 @@ outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
 +++
 
-# Media management
-
-##  Introduction 
-
 This document covers the management of media content in the Apertis
 platform. There are several types of media content to handle in the
 platform: images, audio, video and documents. We can identify the