From e26083c00a1a2ee3fcca3cc1dbfa1b8b6c2aeb3e Mon Sep 17 00:00:00 2001
From: Martyn Welch <martyn.welch@collabora.com>
Date: Mon, 27 Jul 2020 16:57:27 +0100
Subject: [PATCH] Minor tidy up of designs
A number of broken links remained after scripted conversion and a
number of spurious code blocks were found in the docs. Clean these up
so that the documents render correctly.
Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
---
content/designs/applications.md | 2 --
content/designs/coding_conventions.md | 8 +-------
content/designs/contribution-process.md | 2 --
content/designs/hwpack-requirements.md | 4 ++--
content/designs/image-build-infrastructure.md | 1 -
content/designs/inter-domain-communication.md | 2 +-
content/designs/license-applying.md | 2 --
content/designs/list.md | 8 ++++----
content/designs/preferences-and-persistence.md | 1 -
content/designs/release-flow.md | 8 ++++----
content/designs/robustness.md | 1 -
content/designs/security.md | 3 ---
content/designs/sensors-and-actuators.md | 1 -
content/designs/supported-api.md | 2 --
content/designs/ui-customisation.md | 5 -----
15 files changed, 12 insertions(+), 38 deletions(-)
diff --git a/content/designs/applications.md b/content/designs/applications.md
index 2dd9cf148..df0a48fef 100644
--- a/content/designs/applications.md
+++ b/content/designs/applications.md
@@ -927,7 +927,6 @@ be made.
For more invasive system extensions, the application manager can decide
based on the extension type in the application bundle metadata whether the
-```
functionality requires that the system be restarted. The user should be
informed during installation that new features will only be present next
time they start their vehicle.
@@ -1194,7 +1193,6 @@ appropriate for Apertis to provide API to assist in performing the task
accurately.
A minimal C language API for state saving could be developed consisting
-```
- A way to register a callback for a D-Bus signal that requests a save
of state information.
diff --git a/content/designs/coding_conventions.md b/content/designs/coding_conventions.md
index 63ea1a635..b3e426480 100644
--- a/content/designs/coding_conventions.md
+++ b/content/designs/coding_conventions.md
@@ -243,7 +243,7 @@ such as `(nullable)`.
Pre- and post-condition assertions are implemented using
[`g_return_if_fail()`](https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-if-fail)
-```
+
[`g_return_val_if_fail()`](https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-return-val-if-fail).
The pre-conditions should check each parameter at the start of the function,
@@ -323,12 +323,10 @@ implemented using the linking pointers, rather than a incrementing index:
GList *some_list, *l;
for (l = some_list; l != NULL; l = l->next)
-```
gpointer element_data = l->data;
/* Do something with @element_data. */
```
-```
Using an incrementing index instead results in an exponential decrease in
performance (O(2×N^2) rather than O(N)):
@@ -339,12 +337,10 @@ guint i;
/* This code is inefficient and should not be used in production. */
for (i = 0; i < g_list_length (some_list); i++)
-```
gpointer element_data = g_list_nth_data (some_list, i);
/* Do something with @element_data. */
```
-```
The performance penalty comes from `g_list_length()` and `g_list_nth_data()`
which both traverse the list (O(N)) to perform their operations.
@@ -358,12 +354,10 @@ GPtrArray *some_array;
guint i;
for (i = 0; i < some_array->len; i++)
-```
gpointer element_data = some_array->pdata[i];
/* Do something with @element_data. */
```
-```
## Magic values
diff --git a/content/designs/contribution-process.md b/content/designs/contribution-process.md
index 5cfa237e8..6b191ba18 100644
--- a/content/designs/contribution-process.md
+++ b/content/designs/contribution-process.md
@@ -67,8 +67,6 @@ might be started by sending an email to the projects devel
[mailing list](https://lists.apertis.org/) saying:
```
-```
-
I'm attempting to use <project> to <task> for my project.
I'm thinking about doing <brief technical overview> to enable this usecase.
diff --git a/content/designs/hwpack-requirements.md b/content/designs/hwpack-requirements.md
index bc2e07751..2f5dfe022 100644
--- a/content/designs/hwpack-requirements.md
+++ b/content/designs/hwpack-requirements.md
@@ -26,13 +26,13 @@ The selection and packaging of these packages are predominantly driven by the ne
The OSpack stage generates one or more generic (architecture specific but largely hardware independent) archived rootfs built from Apertis packages. These rootfs archives are known as OSpacks. The process is managed by a tool called [Debos](https://github.com/go-debos/debos), which uses yaml configuration files to guide what steps it takes. Apertis provides yaml files to assemble a number of differently targeted OSpacks, ranging from a minimal GUI-less OSpack, a target focused GUI OSpack and a development environment with a desktop style GUI and has pre-packaged the components required to generate these OSpacks.
-
+
#### HWpack
Unlike the OSpack step, the hardware package (HWpack) step does not result in an item known as a HWpack. The HWpack is comprised of a Debos script which controls the processing of a run time determined OSpack to convert it from a hardware independent OSpack into an image which can be successfully booted on a specific hardware platform. In addition to developing the HWpack script, the HWpack step requires the modification and packaging of the required components to perform this transformation.
-
+
### Apertis packages
diff --git a/content/designs/image-build-infrastructure.md b/content/designs/image-build-infrastructure.md
index e85476281..7680b3368 100644
--- a/content/designs/image-build-infrastructure.md
+++ b/content/designs/image-build-infrastructure.md
@@ -35,7 +35,6 @@ environment.
For each Apertis release there are two relevant Jenkins jobs to build images;
The first job builds a Docker image which defines the build environment and
uploads the resulting image to the Apertis Docker registry. This is defined in
-```
[apertis-docker-images git repository](https://gitlab.apertis.org/infrastructure/apertis-docker-images).
The second job defines the build steps for the various ospacks, hardware packs and
images which are run in the Docker image build by the previous job; it also
diff --git a/content/designs/inter-domain-communication.md b/content/designs/inter-domain-communication.md
index 3d21285ca..25028a3fd 100644
--- a/content/designs/inter-domain-communication.md
+++ b/content/designs/inter-domain-communication.md
@@ -2654,7 +2654,7 @@ domains must trigger the
[`NameOwnerChanged signal`](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-name-owner-changed)
in response to the
[`org.freedesktop.DBus.ReleaseName()`](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-release-name)
-```
+
[`org.freedesktop.DBus.RequestName()`](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name)
calls. No specific ordering is required and thus the service may be
temporarily unavailable or the two domains may export the same service
diff --git a/content/designs/license-applying.md b/content/designs/license-applying.md
index e03eb46cd..516ddfa83 100644
--- a/content/designs/license-applying.md
+++ b/content/designs/license-applying.md
@@ -130,7 +130,6 @@ This is what a typical MPL license header looks like:
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
```
-```
For additional guidance on how license headers work, please read the
[GNU license guidance](https://www.gnu.org/licenses/gpl-howto.html). The
@@ -210,7 +209,6 @@ resulting copyright header would look like:
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
```
-```
## License for images
diff --git a/content/designs/list.md b/content/designs/list.md
index 1cf76122f..206765235 100644
--- a/content/designs/list.md
+++ b/content/designs/list.md
@@ -271,8 +271,8 @@ An application author wants the list widget to render as a grid with
multiple items on the same line. The following video shows such a grid layout.
<video width="640" height="480" controls>
- <source src="media/album_cover_roller.mp4" type="video/mp4">
- <source src="media/album_cover_roller.ogv" type="video/ogg">
+ <source src="/images/album_cover_roller.mp4" type="video/mp4">
+ <source src="/images/album_cover_roller.ogv" type="video/ogg">
</video>
### Concurrent presentation of the same model in different list widgets
@@ -530,7 +530,7 @@ for rendering.
The following diagram illustrates how this adapter helps decoupling the list
widget from the underlying model.
-
+
> In the above example, we assume a program that simply displays a list widget
> exposing items stored in a database, and an adapter that stores strong
@@ -792,7 +792,7 @@ appropriately when notified of changes.
An example of this is shown in [the next section](#filtering1), the following
diagram illustrates the filtering process.
-
+
> The ‘cursors’ in the above diagram are a representation of whatever database
> access API is in use, as most databases use cursor-based APIs for reading.
diff --git a/content/designs/preferences-and-persistence.md b/content/designs/preferences-and-persistence.md
index 4cc371577..d04e96338 100644
--- a/content/designs/preferences-and-persistence.md
+++ b/content/designs/preferences-and-persistence.md
@@ -1634,7 +1634,6 @@ they are written. This is what dconf uses for storage.
All updates to a GVDB file are atomic, as it uses the same
atomic-overwrite technique as [GKeyFile]( {{< ref "#gkeyfile" >}} ). Transactions are
supported similarly — by writing out the updated database or discarding
-```
The amount of I/O for reads from a GVDB file is small, as it memory-maps
the database, so only pages in the data it actually reads (plus some
diff --git a/content/designs/release-flow.md b/content/designs/release-flow.md
index 50acb4afc..9bdaeca65 100644
--- a/content/designs/release-flow.md
+++ b/content/designs/release-flow.md
@@ -64,7 +64,7 @@ LTS team which provides other two years of security support before a release
enters end of life (EOL). The following diagram shows the expected timeline for
the current Debian release and the upcoming releases:
-
+
## Process towards a release
@@ -213,7 +213,7 @@ support release which is supported for 2 years.
The following diagram shows the expected timelines for the current and next
expected Linux long term stable releases.
-
+
## Process towards a release
@@ -565,7 +565,7 @@ product-line release of the Apertis it's based on. If a product is based
on a direct downstream of Apertis, then the chart would be nearly identical,
replacing the Apertis labels with the name of the direct downstream.
-
+
## Post-production support guidelines
@@ -600,7 +600,7 @@ into the field. If a product is based
on a direct downstream of Apertis, then the chart would be nearly identical,
replacing the Apertis labels with the name of the direct downstream.
-
+
## Product guideline conclusions
diff --git a/content/designs/robustness.md b/content/designs/robustness.md
index a3aaa5bec..cc07f12ab 100644
--- a/content/designs/robustness.md
+++ b/content/designs/robustness.md
@@ -241,7 +241,6 @@ hardware features available with the storage media.
The System Updates and Rollback Design describes the partition layout
for Apertis. Not all the partitions have the same requirements, so both
the FAT32 and BTRFS filesystems are used. The partitions are configured
-```
- **Factory Recovery** – This partition is never mounted read-write
and must be readable by the boot loader. Currently the boot loader
diff --git a/content/designs/security.md b/content/designs/security.md
index 92f95124f..fb1f89c18 100644
--- a/content/designs/security.md
+++ b/content/designs/security.md
@@ -402,7 +402,6 @@ IPC mechanism. Android uses two very simple strategies to forcibly stop
an application: 1) it kills applications when the device is out of
memory; 2) it notifies the user of [unresponsive applications][Android-responsiveness] and allows
them to force the application to close, similar to how GNOME does
-```
An application is deemed to not be responding after about 5 seconds of
not being able to handle user input. This feature is implemented by the
@@ -903,7 +902,6 @@ policy file:
```shell
$ cat /etc/apparmor.d/bin.ping
-```
/bin/ping {
#include <abstractions/base>
#include <abstractions/consoles>
@@ -919,7 +917,6 @@ $ cat /etc/apparmor.d/bin.ping
}
$
```
-
> AppArmor policy shipped for ping in Ubuntu
This is the policy for the ping command. The binary is specified, then a
diff --git a/content/designs/sensors-and-actuators.md b/content/designs/sensors-and-actuators.md
index 7fb629af7..6a2b39ce0 100644
--- a/content/designs/sensors-and-actuators.md
+++ b/content/designs/sensors-and-actuators.md
@@ -1568,7 +1568,6 @@ if (action.id == 'org.apertis.vehicle_device_daemon.WriteProperty' &&
/* Deny all other accesses. */
return polkit.Result.NO;
```
-```
In the rules, the subject is always the program in the bundle which is
requesting access to the device.
diff --git a/content/designs/supported-api.md b/content/designs/supported-api.md
index fea22f98c..4fc692e1e 100644
--- a/content/designs/supported-api.md
+++ b/content/designs/supported-api.md
@@ -187,7 +187,6 @@ the best way to guarantee stability, but that will only delay the impact
of the changes. Building a set of APIs that abstract some of the
platform can also be sensible: applications using high level widgets can
be shielded from changes done at the lower levels – Clutter, Mx, and so
-```
To conclude: taking advantage of open source code takes away some of the
control over the platform's future. While Google and Apple are able to
@@ -453,7 +452,6 @@ but work may be done on a case-by-case basis to provide a smooth
migration path, with old versions coexisting with newer ones when
possible. Most existing open source APIs related to core functionality
fall in this support level: Mx, clutter, clutter-gst, GStreamer, and so
-```
As discussed in section 3.5.1, [The GTK upgrade and a Clutter API break]( {{< ref "#the-gtk-upgrade-and-a-clutter-api-break" >}} ),
there are ways to deal with ABI/API breakage in these libraries. Keeping
diff --git a/content/designs/ui-customisation.md b/content/designs/ui-customisation.md
index 0f26c1b20..ce5369475 100644
--- a/content/designs/ui-customisation.md
+++ b/content/designs/ui-customisation.md
@@ -665,7 +665,6 @@ user interface:
{ "name": "activated", "handler": "app_activated_cb" }
]
}
-```
}]
```
@@ -712,7 +711,6 @@ chooser user interface:
{ "name": "activated", "handler": "app_activated_cb" }
]
}
-```
}]
```
@@ -833,7 +831,6 @@ reference. For example:
```
{
"id": "example-with-children",
-```
"children": [
"first-child",
{
@@ -844,7 +841,6 @@ reference. For example:
"external-uri": "file:///path/to/another.json",
"id": "third-child"
}
-```
}
```
@@ -928,7 +924,6 @@ gint item_id)
/* change animation */
} else {
/* reset animation */
-```
/* chain up */
return roller_class->activate (roller, item_id);
--
GitLab