diff options
author | Micah Abbott <miabbott@redhat.com> | 2016-03-16 15:02:18 -0400 |
---|---|---|
committer | Micah Abbott <miabbott@redhat.com> | 2016-03-16 15:02:18 -0400 |
commit | 0b068c668a182ceca4d581ad46fdc6b1ac087afd (patch) | |
tree | 8aa8da48dd0d45836cd2f8f76fa32324d38dfeac /docs | |
parent | 89624ee57d5ab69fbed91753aff7510c204707e8 (diff) | |
download | ostree-0b068c668a182ceca4d581ad46fdc6b1ac087afd.tar.gz |
docs: Cleanup Markdown
I was going through the new version of the docs and noticed a few
problems. Mostly URLs that aren't linked, extra whitespace, and a few
mis-spellings.
I ran the files through `aspell check` and made some manual changes
myself.
These changes were tested locally with `mkdocs serve`
Diffstat (limited to 'docs')
-rw-r--r-- | docs/CONTRIBUTING.md | 36 | ||||
-rw-r--r-- | docs/manual/adapting-existing.md | 2 | ||||
-rw-r--r-- | docs/manual/atomic-upgrades.md | 9 | ||||
-rw-r--r-- | docs/manual/deployment.md | 2 | ||||
-rw-r--r-- | docs/manual/formats.md | 12 | ||||
-rw-r--r-- | docs/manual/introduction.md | 6 | ||||
-rw-r--r-- | docs/manual/repo.md | 4 |
7 files changed, 35 insertions, 36 deletions
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4458256e..397ffeb0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -3,17 +3,18 @@ Submitting patches You can: - 1. Send mail to ostree-list@gnome.org, with the patch attached - 1. Submit a pull request against https://github.com/GNOME/ostree - 1. Attach them to https://bugzilla.gnome.org/ + 1. Send mail to <ostree-list@gnome.org>, with the patch attached + 1. Submit a pull request against <https://github.com/GNOME/ostree> + 1. Attach them to <https://bugzilla.gnome.org/> -Please look at "git log" and match the commit log style. +Please look at `git log` and match the commit log style. Running the test suite ---------------------- -Currently, ostree uses https://wiki.gnome.org/GnomeGoals/InstalledTests -To run just ostree's tests: +Currently, OSTree uses <https://wiki.gnome.org/GnomeGoals/InstalledTests> + +To run just OSTree's tests: ./configure ... --enable-installed-tests gnome-desktop-testing-runner -p 0 ostree/ @@ -47,16 +48,16 @@ This is an example of an "early exit": myfunc (...) { gboolean ret = FALSE; - + /* some code */ - + /* some more code */ - + if (condition) return FALSE; - + /* some more code */ - + ret = TRUE; out: return ret; @@ -85,14 +86,14 @@ functions, particularly inside loops. For example, rather than: { /* deeply nested code */ } - + /* more nested code */ } } } Instead do this: - + static gboolean helperfunc (..., GError **error) { @@ -100,22 +101,21 @@ Instead do this: { /* deeply nested code */ } - + /* more nested code */ - + return ret; } - + while (condition) { /* some code */ if (!condition) continue; - + for (i = 0; i < somevalue; i++) { if (!helperfunc (..., i, error)) goto out; } } - diff --git a/docs/manual/adapting-existing.md b/docs/manual/adapting-existing.md index 858c82d3..8509d48e 100644 --- a/docs/manual/adapting-existing.md +++ b/docs/manual/adapting-existing.md @@ -140,7 +140,7 @@ Now, because we are merely installing new packages and not removing anything, we can make the major optimization of reusing our existing filesystem tree, and merely *layering* the composed filesystem tree of -these new packages on top. A command like this: +these new packages on top. A command like this: ``` ostree commit -b osname/releasename/description diff --git a/docs/manual/atomic-upgrades.md b/docs/manual/atomic-upgrades.md index 9ce2c8ae..42855593 100644 --- a/docs/manual/atomic-upgrades.md +++ b/docs/manual/atomic-upgrades.md @@ -15,7 +15,7 @@ exactly one ref, which is stored in the `.origin` file for the deployment. The command `ostree admin upgrade` implements this. -o begin a simple upgrade, OSTree fetches the contents of the ref from +To begin a simple upgrade, OSTree fetches the contents of the ref from the remote server. Suppose we're tracking a ref named `exampleos/buildmaster/x86_64-runtime`. OSTree fetches the URL `http://$example.com/repo/refs/exampleos/buildmaster/x86_64-runtime`, @@ -56,11 +56,10 @@ checking it back out of the repo into a deployment. Given a commit to deploy, OSTree first allocates a directory for it. This is of the form `/boot/loader/entries/ostree-$osname-$checksum.$serial.conf`. -he $serial is normally 0, but if a +The `$serial` is normally 0, but if a given commit is deployed more than once, it will be incremented. his is supported because the previous deployment may have -configuration in `/etc` -hat we do not want to use or overwrite. +configuration in `/etc` that we do not want to use or overwrite. Now that we have a deployment directory, a 3-way merge is performed between the (by default) currently booted deployment's @@ -74,7 +73,7 @@ hardlink farm; the running system is untouched, and the bootloader configuration is untouched. We want to add this deployment o the "deployment list". -To support a more general case, OSTree supports atomic ransitioning +To support a more general case, OSTree supports atomic transitioning between arbitrary sets of deployments, with the restriction that the currently booted deployment must always be in the new set. In the normal case, we have exactly one deployment, which is the booted one, diff --git a/docs/manual/deployment.md b/docs/manual/deployment.md index 53b0b662..f1172959 100644 --- a/docs/manual/deployment.md +++ b/docs/manual/deployment.md @@ -13,7 +13,7 @@ OSTree is designed to boot directly into exactly one deployment at a time; each deployment is intended to be a target for `chroot()` or equivalent. -### "osname": Group of deployments that share /var</title> +### "osname": Group of deployments that share /var Each deployment is grouped in exactly one "osname". From above, you can see that an osname is physically represented in the diff --git a/docs/manual/formats.md b/docs/manual/formats.md index bf7fd0ae..e689f8a8 100644 --- a/docs/manual/formats.md +++ b/docs/manual/formats.md @@ -67,7 +67,7 @@ or an unprivileged container. ## Static deltas -OSTree itself was originally focused on a continous delivery model, where +OSTree itself was originally focused on a continuous delivery model, where client systems are expected to update regularly. However, many OS vendors would like to supply content that's updated e.g. once a month or less often. @@ -82,7 +82,7 @@ object. Static deltas also support `from NULL`, where the client can more efficiently download a commit object from scratch. Effectively, we're spending server-side storage (and one-time compute -cost), and gaining efficiency in client network bandwith. +cost), and gaining efficiency in client network bandwidth. ## Static delta repository layout @@ -99,7 +99,7 @@ management easier for filesystem tools A delta is named `$(mbase64 $from)-$(mbase64 $to)`, for example `GpTyZaVut2jXFPWnO4LJiKEdRTvOw_mFUCtIKW1NIX0-L8f+VVDkEBKNc1Ncd+mDUrSVR4EyybQGCkuKtkDnTwk`, -which in sha256 format is +which in SHA256 format is `1a94f265a56eb768d714f5a73b82c988a11d453bcec3f985502b48296d4d217d-2fc7fe5550e410128d73535c77e98352b495478132c9b4060a4b8ab640e74f09`. Finally, the actual content can be found in @@ -136,7 +136,7 @@ The superblock contains: - delta generation timestamp - the new commit object - An array of recursive deltas to apply - - An array of per-part metadata, including total object sizes (compressed and uncompressed), + - An array of per-part metadata, including total object sizes (compressed and uncompressed), - An array of fallback objects Let's define a delta part, then return to discuss details: @@ -160,14 +160,14 @@ a per-file delta algorithm called [bsdiff](https://github.com/mendsley/bsdiff) that most notably works well on executable code. -The current delta compiler scans for files with maching basenamesin +The current delta compiler scans for files with matching basenames in each commit that have a similar size, and attempts a bsdiff between them. (It would make sense later to have a build system provide a hint for this - for example, files within a same package). A generated bsdiff is included in the payload blob, and applying it is an instruction. - + ## Fallback objects It's possible for there to be large-ish files which might be resistant diff --git a/docs/manual/introduction.md b/docs/manual/introduction.md index b9c69c21..c88d6c14 100644 --- a/docs/manual/introduction.md +++ b/docs/manual/introduction.md @@ -1,6 +1,6 @@ # OSTree Overview -## Introduction +## Introduction OSTree an upgrade system for Linux-based operating systems that performs atomic upgrades of complete filesystem trees. It is @@ -15,7 +15,7 @@ content-addressed object store, and layered on top of that is bootloader configuration, management of `/etc`, and other functions to perform an upgrade beyond just replicating files. - + You can use OSTree standalone in the pure replication model, but another approach is to add a package manager on top, thus creating a hybrid tree/package system. @@ -46,7 +46,7 @@ HTTP, and where the OS includes (if desired) an entirely separate mechanism to install applications, stored in `/var` if they're system global, or `/home` for per-user application installation. An example application mechanism is -http://docker.io/ +<http://docker.io/> However, it is entirely possible to use OSTree underneath a package system, where the contents of `/usr` are computed on the client. diff --git a/docs/manual/repo.md b/docs/manual/repo.md index 3a9e8c9a..e8d94b4b 100644 --- a/docs/manual/repo.md +++ b/docs/manual/repo.md @@ -54,12 +54,12 @@ modes: `bare`, `bare-user`, and `archive-z2`. A bare repository is one where content files are just stored as regular files; it's designed to be the source of a "hardlink farm", where each operating system checkout is merely links into it. If you want to store files -owned by e.g. root in this mode, you must run OSTree as root. +owned by e.g. root in this mode, you must run OSTree as root. The `bare-user` is a later addition that is like `bare` in that files are unpacked, but it can (and should generally) be created as non-root. In this mode, extended metadata such as owner uid, gid, and -extended attributes are stored but not actually applied. +extended attributes are stored but not actually applied. The `bare-user` mode is useful for build systems that run as non-root but want to generate root-owned content, as well as non-root container systems. |