diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ede0d123..1e2bd856 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,12 @@ # Contributing to `qubes-doc` Thank you for your interest in contributing to `qubes-doc`, the Qubes OS -Project's dedicated documentation repository! Please take a moment to read our -[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before -you begin writing. These guidelines are important to maintaining high quality -documentation, and following them will increase the likelihood that your -contribution will be accepted. +Project's dedicated documentation repository! Please see [how to edit the +documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/) for +detailed contribution instructions. + +In addition, please take a moment to read our [documentation style +guide](https://www.qubes-os.org/doc/documentation-style-guide/) before +contributing. These guidelines are important to maintaining high standards of +quality, and following them will increase the likelihood that your contribution +will be accepted. diff --git a/README.md b/README.md index c31a58ee..0ab67025 100644 --- a/README.md +++ b/README.md @@ -7,5 +7,5 @@ stored as plain text files in this dedicated repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the Web. -For more information about the documentation, including how to contribute, -please see the [Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/). +To contribute, please see [how to edit the +documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/). diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index ecfc2030..0146fe3a 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -7,7 +7,7 @@ redirect_from: - /doc/DevelopmentWorkflow/ - /wiki/DevelopmentWorkflow/ ref: 66 -title: Development Workflow +title: Development workflow --- A workflow for developing Qubes OS+ diff --git a/developer/building/qubes-builder-details.md b/developer/building/qubes-builder-details.md index 8b5c8c8a..f3582284 100644 --- a/developer/building/qubes-builder-details.md +++ b/developer/building/qubes-builder-details.md @@ -7,7 +7,7 @@ redirect_from: - /doc/QubesBuilderDetails/ - /wiki/QubesBuilderDetails/ ref: 65 -title: Qubes Builder Details +title: Qubes builder details --- Components Makefile.builder file @@ -50,4 +50,4 @@ Most settings are documented in *builder.conf.default* file, which can be used a Notes ----- -* For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](/doc/supported-versions/). +* For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](/doc/supported-releases/). diff --git a/developer/building/qubes-builder.md b/developer/building/qubes-builder.md index 8090d6da..b50ce540 100644 --- a/developer/building/qubes-builder.md +++ b/developer/building/qubes-builder.md @@ -7,7 +7,7 @@ redirect_from: - /doc/QubesBuilder/ - /wiki/QubesBuilder/ ref: 64 -title: Qubes Builder +title: Qubes builder --- **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.** diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index f30b7b26..1dda3064 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -9,7 +9,7 @@ redirect_from: - /doc/QubesR3Building/ - /wiki/QubesR3Building/ ref: 63 -title: Qubes ISO Building +title: Qubes ISO building --- Build Environment diff --git a/developer/building/qubes-template-configs.md b/developer/building/qubes-template-configs.md index 446fa39f..71139116 100644 --- a/developer/building/qubes-template-configs.md +++ b/developer/building/qubes-template-configs.md @@ -4,5 +4,5 @@ layout: doc permalink: /doc/qubes-template-configs/ redirect_to: https://github.com/QubesOS/qubes-template-configs ref: 248 -title: Qubes Template Configs +title: Qubes template configs --- diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index 236c6aac..faee5c7d 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/code-signing/ ref: 51 -title: Code Signing +title: Code signing --- All contributions to the Qubes OS [source code](/doc/source-code/) must be cryptographically signed by the author's PGP key. diff --git a/developer/code/coding-style.md b/developer/code/coding-style.md index 4f2013c5..5bc1dec5 100644 --- a/developer/code/coding-style.md +++ b/developer/code/coding-style.md @@ -8,7 +8,7 @@ redirect_from: - /wiki/CodingStyle/ - /trac/wiki/CodingStyle/ ref: 53 -title: Coding Style +title: Coding style --- Rationale diff --git a/developer/code/license.md b/developer/code/license.md index 95d71c23..f7fe3682 100644 --- a/developer/code/license.md +++ b/developer/code/license.md @@ -7,7 +7,7 @@ redirect_from: - /doc/QubesLicensing/ - /wiki/QubesLicensing/ ref: 52 -title: Software License +title: Software license --- Qubes OS is a compilation of software packages, each under its own license. The diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 7098ace7..85e5cf13 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -7,7 +7,7 @@ redirect_from: - /doc/SourceCode/ - /wiki/SourceCode/ ref: 54 -title: Source Code +title: Source code --- All the Qubes code is kept in Git repositories. We have divided the project into diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index e4a7e674..c57df136 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -6,7 +6,7 @@ redirect_from: - /en/doc/automated-tests/ - /doc/AutomatedTests/ ref: 45 -title: Automated Tests +title: Automated tests --- ## Unit and Integration Tests diff --git a/developer/debugging/mount-lvm-image.md b/developer/debugging/mount-lvm-image.md index d484b5a7..d5b76080 100644 --- a/developer/debugging/mount-lvm-image.md +++ b/developer/debugging/mount-lvm-image.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/mount-lvm-image/ ref: 46 -title: How to Mount LVM Images +title: How to mount LVM images --- You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0). diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md index 230351de..2932b4cb 100644 --- a/developer/debugging/profiling.md +++ b/developer/debugging/profiling.md @@ -7,7 +7,7 @@ redirect_from: - /doc/Profiling/ - /wiki/Profiling/ ref: 48 -title: Python Profiling +title: Python profiling --- This is a python profiling primer. diff --git a/developer/debugging/safe-remote-ttys.md b/developer/debugging/safe-remote-ttys.md index bd71d96c..b6183116 100644 --- a/developer/debugging/safe-remote-ttys.md +++ b/developer/debugging/safe-remote-ttys.md @@ -5,7 +5,7 @@ permalink: /doc/safe-remote-ttys/ redirect_from: - /en/doc/safe-remote-ttys/ ref: 49 -title: Safe Remote Dom0 Terminals +title: Safe remote dom0 terminals --- If you do not have working graphics in Dom0, then using a terminal can be quite annoying! diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md index 9fea836a..5051a28d 100644 --- a/developer/debugging/test-bench.md +++ b/developer/debugging/test-bench.md @@ -7,7 +7,7 @@ redirect_from: - /doc/TestBench/ - /wiki/TestBench/ ref: 44 -title: How to Set Up a Test Bench +title: How to set up a test bench --- This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal. diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index 741e52c7..d6fc2dff 100644 --- a/developer/debugging/vm-interface.md +++ b/developer/debugging/vm-interface.md @@ -8,7 +8,7 @@ redirect_from: - /doc/SystemDoc/VMInterface/ - /wiki/SystemDoc/VMInterface/ ref: 47 -title: VM Configuration Interface +title: Qube configuration interface --- Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: diff --git a/developer/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md index cc81c2c4..852d1c67 100644 --- a/developer/debugging/windows-debugging.md +++ b/developer/debugging/windows-debugging.md @@ -7,7 +7,7 @@ redirect_from: - /doc/WindowsDebugging/ - /wiki/WindowsDebugging/ ref: 50 -title: Windows Debugging +title: Windows debugging --- Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs. diff --git a/developer/general/continuous-integration.md b/developer/general/continuous-integration.md new file mode 100644 index 00000000..61749361 --- /dev/null +++ b/developer/general/continuous-integration.md @@ -0,0 +1,34 @@ +--- +lang: en +layout: doc +permalink: /doc/continuous-integration/ +title: Continuous integration (CI) +--- + +This page explains the [continuous integration +(CI)](https://en.wikipedia.org/wiki/Continuous_integration) infrastructure that +the Qubes OS Project uses. + +## Website and documentation + +The following commands may be useful as a way to interact with our CI +infrastructure on website +([qubesos.github.io](https://github.com/QubesOS/qubesos.github.io)) and +documentation ([qubes-doc](https://github.com/QubesOS/qubes-doc)) pull requests +(PRs). Note that special permissions may be required to use some of these +commands. These commands are generally issued by adding a comment to a PR +containing only the command. + +- `PipelineRetry`: Attempts to run the entire build pipeline over again. This + can be useful if CI incorrectly uses a stale branch instead of testing the PR + as if it were merged into `master`. + +- `TestDeploy`: Deploys a test website, which is a live version of the Qubes + website as if this PR had been merged. This can be useful for previewing a PR + on a live public website. **Note:** You must wait for the site to finish + building before issuing this command, or else it will deploy an empty + website. To find the URL of the test website, look for text similar to "This + branch was successfully deployed" and a button named something like "View + deployment." Note that there are two different testing sites: `wwwtest` is + manually updated, whereas `wwwpreview` is managed by the `TestDeploy` + command. diff --git a/developer/general/devel-books.md b/developer/general/devel-books.md index 2fc9e566..d7ae9ae0 100644 --- a/developer/general/devel-books.md +++ b/developer/general/devel-books.md @@ -7,7 +7,7 @@ redirect_from: - /doc/DevelBooks/ - /wiki/DevelBooks/ ref: 32 -title: Developer Books +title: Developer books --- Below is a list of various books that might be useful in learning some basics needed for Qubes development. diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md deleted file mode 100644 index 6d55644e..00000000 --- a/developer/general/doc-guidelines.md +++ /dev/null @@ -1,662 +0,0 @@ ---- -lang: en -layout: doc -permalink: /doc/doc-guidelines/ -redirect_from: -- /en/doc/doc-guidelines/ -- /wiki/DocStyle/ -- /doc/DocStyle/ -ref: 30 -title: Documentation Guidelines ---- - -All Qubes OS documentation pages are stored as plain text files in the -dedicated [qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By -cloning and regularly pulling from this repo, users can maintain their own -up-to-date offline copy of all Qubes documentation rather than relying solely -on the web. - -The documentation is a community effort. Volunteers work hard trying to keep -everything accurate and comprehensive. If you notice a problem or some way it -can be improved, please [edit the documentation](#how-to-contribute)! - -## Security - -*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)* - -All pull requests (PRs) against -[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be -merged, except in the case of [external -documentation](/doc/#external-documentation) (see -[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is -designed to ensure that contributed text is accurate and non-malicious. This -process is a best effort that should provide a reasonable degree of assurance, -but it is not foolproof. For example, all text characters are checked for ANSI -escape sequences. However, binaries, such as images, are simply checked to -ensure they appear or function the way they should when the website is -rendered. They are not further analyzed in an attempt to determine whether they -are malicious. - -Once a pull request passes review, the reviewer should add a signed comment -stating, "Passed review as of ``" (or similar). The -documentation maintainer then verifies that the pull request is mechanically -sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the -documentation maintainer then merges the pull request, adds a PGP-signed tag to -the latest commit (usually the merge commit), then pushes to the remote. In -cases in which another reviewer is not required, the documentation maintainer -may review the pull request (in which case no signed comment is necessary, -since it would be redundant with the signed tag). - -## Questions, problems, and improvements - -If you have a question about something you read in the documentation, please -send it to the appropriate [mailing list](/support/). If you see that something -in the documentation should be fixed or improved, please -[contribute](#how-to-contribute) the change yourself. To report an issue with -the documentation, please follow our standard [issue reporting -guidelines](/doc/issue-tracking/). (If you report an issue with the -documentation, you will likely be asked to address it, unless there is a clear -indication in your report that you are not willing or able to do so.) - -## How to contribute - -Editing the documentation is easy, so if you see that a change should be made, -please contribute it! - -A few notes before we get started: - -- Since Qubes is a security-oriented project, every documentation change will - be [reviewed](#security) before it's accepted. This allows us to maintain - quality control and protect our users. - -- We don't want you to spend time and effort on a contribution that we can't - accept. If your contribution would take a lot of time, please [file an - issue](/doc/issue-tracking/) for it first so that we can make sure we're on - the same page before significant works begins. - -- Alternatively, you may already have written content that doesn't conform to - these guidelines, but you'd be willing to modify it so that it does. In this - case, you can still submit it by following the instructions below. Just make - a note in your pull request (PR) that you're aware of the changes that need - to be made and that you're just asking for the content to be reviewed before - you spend time making those changes. - -- Finally, if you've written something that doesn't belong in qubes-doc but that - would be beneficial to the Qubes community, please consider adding it to the - [external documentation](/doc/doc-guidelines/#core-vs-external-documentation). - -As mentioned above, we keep all the documentation in a dedicated [Git -repository](https://github.com/QubesOS/qubes-doc) hosted on -[GitHub](https://github.com/). Thanks to GitHub's interface, you can edit the -documentation even if you don't know Git at all! The only thing you need is a -GitHub account, which is free. - -(**Note:** If you're already familiar with GitHub or wish to work from the -command line, you can skip the rest of this section. All you need to do to -contribute is to [fork and -clone](https://guides.github.com/activities/forking/) the -[qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then -[submit a pull -request](https://help.github.com/articles/using-pull-requests/).) - -Ok, let's start. Every documentation page has a "Page Source on GitHub" button. -Depending on the size of your screen, it may either be on the side (larger -screens) or on the bottom (smaller screens). - -[![page-source-button](/attachment/doc/doc-pr_01_page-source-button.png)](/attachment/doc/doc-pr_01_page-source-button.png) - -When you click on it, you'll be taken to the source file --- usually a Markdown -(`.md`) file --- on GitHub. On this page, there will be a button to edit the -file. - -[![github-edit](/attachment/doc/doc-pr_02_github-edit.png)](/attachment/doc/doc-pr_02_github-edit.png) - -You'll be prompted to sign in with your GitHub username and password -(if you aren't already logged in). You can also create a free account from here. - -[![github-sign-in](/attachment/doc/doc-pr_03_sign-in.png)](/attachment/doc/doc-pr_03_sign-in.png) - -If this is your first contribution to the documentation, you need to "fork" the -repository (make your own copy). It's easy --- just click the big green button -on the next page. This step is only needed the first time you make a -contribution. - -[![fork](/attachment/doc/doc-pr_04_fork.png)](/attachment/doc/doc-pr_04_fork.png) - -Now you can make your modifications. You can also preview the changes to see -how they'll be formatted by clicking the "Preview changes" tab. If you want to -add images, please see [How to add images](#how-to-add-images). If you're -making formatting changes, please [render the site -locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify -that everything looks correct before submitting any changes. - -[![edit](/attachment/doc/doc-pr_05_edit.png)](/attachment/doc/doc-pr_05_edit.png) - -Once you're finished, describe your changes at the bottom and click "Propose -file change". - -[![commit](/attachment/doc/doc-pr_06_commit-msg.png)](/attachment/doc/doc-pr_06_commit-msg.png) - -After that, you'll see exactly what modifications you've made. At this stage, -those changes are still in your own copy of the documentation ("fork"). If -everything looks good, send those changes to us by pressing the "Create pull -request" button. - -[![pull-request](/attachment/doc/doc-pr_07_review-changes.png)](/attachment/doc/doc-pr_07_review-changes.png) - -You will be able to adjust the pull request message and title there. In most -cases, the defaults are ok, so you can just confirm by pressing the "Create -pull request" button again. However, if you're not ready for your PR to be -reviewed or merged yet, please [make a draft PR -instead](https://github.blog/2019-02-14-introducing-draft-pull-requests/). - -[![pull-request-confirm](/attachment/doc/doc-pr_08_create-pull-request.png)](/attachment/doc/doc-pr_08_create-pull-request.png) - -If any of your changes should be reflected in the [documentation index (a.k.a. -table of contents)](/doc/) --- for example, if you're adding a new page, -changing the title of an existing page, or removing a page --- please see [How -to edit the documentation index](#how-to-edit-the-documentation-index). - -That's all! We will review your changes. If everything looks good, we'll pull -them into the official documentation. Otherwise, we may have some questions for -you, which we'll post in a comment on your pull request. (GitHub will -automatically notify you if we do.) If, for some reason, we can't accept your -pull request, we'll post a comment explaining why we can't. - -[![done](/attachment/doc/doc-pr_09_done.png)](/attachment/doc/doc-pr_09_done.png) - -### How to edit the documentation index - -The source file for the [documentation index (a.k.a. table of contents)](/doc/) -lives here: - - - -Editing this file will change what appears on the documentation index. If your -pull request (PR) adds, removes, or edits anything that should be reflected in -the documentation index, please make sure you also submit an associated pull -request against this file. - -### How to add images - -To add an image to a page, use the following syntax in the main document. This -will make the image a hyperlink to the image file, allowing the reader to click -on the image in order to view the image by itself. - -``` -[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png) -``` - -Then, submit your image(s) in a separate pull request to the -[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository -using the same path and filename. This is the only permitted way to include -images. Do not link to images on other websites. - -## Organizational guidelines - -### Do not duplicate documentation - -Duplicating documentation is almost always a bad idea. There are many reasons -for this. The main one is that almost all documentation has to be updated as -some point. When similar documentation appears in more than one place, it is -very easy for it to get updated in one place but not the others (perhaps -because the person updating it doesn't realize it's in more than once place). -When this happens, the documentation as a whole is now inconsistent, and the -outdated documentation becomes a trap, especially for novice users. Such traps -are often more harmful than if the documentation never existed in the first -place. The solution is to **link** to existing documentation rather than -duplicating it. There are some exceptions to this policy (e.g., information -that is certain not to change for a very long time), but they are rare. - -### Core vs. external documentation - -Core documentation resides in the [Qubes OS Project's official -repositories](https://github.com/QubesOS/), mainly in -[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can -be anywhere else (such as forums, community websites, and blogs), but there is -an especially large collection in the [Qubes -Community](https://github.com/Qubes-Community) project. External documentation -should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). -If you've written a piece of documentation that is not appropriate for -[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit -it to the [Qubes Community](https://github.com/Qubes-Community) project -instead. However, *linking* to external documentation from -[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, -the maintainers of the [Qubes Community](https://github.com/Qubes-Community) -project should regularly submit PRs against the documentation index (see [How -to edit the documentation index](#how-to-edit-the-documentation-index)) to add -and update Qubes Community links in the "External Documentation" section of the -documentation table of contents. - -The main difference between **core** (or **official**) and **external** (or -**community** or **unofficial**) documentation is whether it documents software -that is officially written and maintained by the Qubes OS Project. The purpose -of this distinction is to keep the core docs maintainable and high-quality by -limiting them to the software output by the Qubes OS Project. In other words, -we take responsibility for documenting all of the software we put out into the -world, but it doesn't make sense for us to take on the responsibility of -documenting or maintaining documentation for anything else. For example, Qubes -OS may use a popular Linux distribution for an official -[TemplateVM](/doc/templates/). However, it would not make sense for a -comparatively small project like ours, with modest funding and a lean -workforce, to attempt to document software belonging to a large, richly-funded -project with an army of paid and volunteer contributors, especially when they -probably already have documentation of their own. This is particularly true -when it comes to Linux in general. Although many users who are new to Qubes are -also new to Linux, it makes absolutely no sense for our comparatively tiny -project to try to document Linux in general when there is already a plethora of -documentation out there. - -Many contributors do not realize that there is a significant amount of work -involved in *maintaining* documentation after it has been written. They may -wish to write documentation and submit it to the core docs, but they see only -their own writing process and fail to consider that it will have to be kept -up-to-date and consistent with the rest of the docs for years afterward. -Submissions to the core docs also have to go through a review process to ensure -accuracy before being merged (see [security](#security)), which takes up -valuable time from the team. We aim to maintain high quality standards for the -core docs (style and mechanics, formatting), which also takes up a lot of time. -If the documentation involves anything external to the Qubes OS Project (such -as a website, platform, program, protocol, framework, practice, or even a -reference to a version number), the documentation is likely to become outdated -when that external thing changes. It's also important to periodically review -and update this documentation, especially when a new Qubes release comes out. -Periodically, there may be technical or policy changes that affect all the core -documentation. The more documentation there is relative to maintainers, the -harder all of this will be. Since there are many more people who are willing to -write documentation than to maintain it, these individually small incremental -additions amount to a significant maintenance burden for the project. - -On the positive side, we consider the existence of community documentation to -be a sign of a healthy ecosystem, and this is quite common in the software -world. The community is better positioned to write and maintain documentation -that applies, combines, and simplifies the official documentation, e.g., -tutorials that explain how to install and use various programs in Qubes, how to -create custom VM setups, and introductory tutorials that teach basic Linux -concepts and commands in the context of Qubes. In addition, just because the -Qubes OS Project has officially written and maintains some flexible framework, -such as `qrexec`, it does not make sense to include every tutorial that says -"here's how to do something cool with `qrexec`" in the core docs. Such -tutorials generally also belong in the community documentation. - -See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more -background information. - -### Version-specific documentation - -*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential -changes to this policy.* - -We maintain only one set of documentation for Qubes OS. We do not maintain a -different set of documentation for each version of Qubes. Our single set of -Qubes OS documentation is updated on a continual, rolling basis. Our first -priority is to document all **current, stable releases** of Qubes. Our second -priority is to document the next, upcoming release (if any) that is currently -in the beta or release candidate stage. - -In cases where a documentation page covers functionality that differs -considerably between Qubes OS versions, the page should be subdivided into -clearly-labeled sections that cover the different functionality in different -versions: - -#### Incorrect Example - -``` -# Page Title # - -## How to Foo ## - -Fooing is the process by which one foos. There are both general and specific -versions of fooing, which vary in usefulness depending on your goals, but for -the most part, all fooing is fooing. - -To foo in Qubes 3.2: - - $ qvm-foo - -Note that this does not work in Qubes 4.0, where there is a special widget -for fooing, which you can find in the lower-right corner of the screen in -the Foo Manager. Alternatively, you can use the more general `qubes-baz` -command introduced in 4.0: - - $ qubes-baz --foo - -Once you foo, make sure to close the baz before fooing the next bar. -``` - -#### Correct Example - -``` -# Page Title # - -## Qubes 3.2 ## - -### How to Foo ### - -Fooing is the process by which one foos. There are both general and specific -versions of fooing, which vary in usefulness depending on your goals, but for -the most part, all fooing is fooing. - -To foo: - - $ qvm-foo - -Once you foo, make sure to close the baz before fooing the next bar. - -## Qubes 4.0 ## - -### How to Foo ### - -Fooing is the process by which one foos. There are both general and specific -versions of fooing, which vary in usefulness depending on your goals, but for -the most part, all fooing is fooing. - -There is a special widget for fooing, which you can find in the lower-right -corner of the screen in the Foo Manager. Alternatively, you can use the -general `qubes-baz` command: - - $ qubes-baz --foo - -Once you foo, make sure to close the baz before fooing the next bar. -``` - -Subdividing the page into clearly-labeled sections for each version has several -benefits: - -- It preserves good content for older (but still supported) versions. Many - documentation contributors are also people who prefer to use the latest - version. Many of them are tempted to *replace* existing content that applies - to an older, supported version with content that applies only to the latest - version. This is somewhat understandable. Since they only use the latest - version, they may be focused on their own experience, and they may even - regard the older version as deprecated, even when it's actually still - supported. However, allowing this replacement of content would do a great - disservice to those who still rely on the older, supported version. In many - cases, these users value the stability and reliability of the older, - supported version. With the older, supported version, there has been more - time to fix bugs and make improvements in both the software and the - documentation. Consequently, much of the documentation content for this - version may have gone through several rounds of editing, review, and - revision. It would be a tragedy for this content to vanish while the very set - of users who most prize stability and reliability are depending on it. -- It's easy for readers to quickly find the information they're looking for, - since they can go directly to the section that applies to their version. -- It's hard for readers to miss information they need, since it's all in one - place. In the incorrect example, information that the reader needs could be - in any paragraph in the entire document, and there's no way to tell without - reading the entire page. In the correct example, the reader can simply skim - the headings in order to know which parts of the page need to be read and - which can be safely ignored. The fact that some content is repeated in the - two version-specific sections is not a problem, since no reader has to read - the same thing twice. Moreover, as one version gets updated, it's likely that - the documentation for that version will also be updated. Therefore, content - that is initially duplicated between version-specific sections will not - necessarily stay that way, and this is a good thing: We want the - documentation for a version that *doesn't* change to stay the same, and we - want the documentation for a version that *does* change to change along with - the software. -- It's easy for documentation contributors and maintainers to know which file - to edit and update, since there's only one page for all Qubes OS versions. - Initially creating the new headings and duplicating content that applies to - both is only a one-time cost for each page, and many pages don't even require - this treatment, since they apply to all currently-supported Qubes OS - versions. - -By contrast, an alternative approach, such as segregating the documentation -into two different branches, would mean that contributions that apply to both -Qubes versions would only end up in one branch, unless someone remembered to -manually submit the same thing to the other branch and actually made the effort -to do so. Most of the time, this wouldn't happen. When it did, it would mean a -second pull request that would have to be reviewed. Over time, the different -branches would diverge in non-version-specific content. Good general content -that was submitted only to one branch would effectively disappear once that -version was deprecated. (Even if it were still on the website, no one would -look at it, since it would explicitly be in the subdirectory of a deprecated -version, and there would be a motivation to remove it from the website so that -search results wouldn't be populated with out-of-date information.) - -For further discussion about version-specific documentation in Qubes, see -[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). - -## Style guidelines - -### Correct use of terminology - -Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). -Use these terms consistently and accurately throughout your writing. - -### Variables in commands - -Syntactically distinguish variables in commands. For example, this is -ambiguous: - - $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm - -It should instead be: - - $ qvm-run --dispvm= --service qubes.StartApp+xterm - -Note that we syntactically distinguish variables in three ways: -1. Surrounding them in angled brackets (`< >`) -2. Using underscores (`_`) instead of spaces between words -3. Using all capital letters - -We have observed that many novices make the mistake of typing the surrounding -angled brackets (`< >`) on the command line, even after substituting the -desired real value between them. Therefore, in documentation aimed at novices, -we also recommend clarifying that the angled brackets should not be typed. This -can be accomplished in one of several ways: -- Explicitly say something like "without the angled brackets." -- Provide an example command using real values that excludes the angled - brackets. -- If you know that almost all users will want to use (or should use) a specific - command containing all real values and no variables, you might consider - providing exactly that command and forgoing the version with variables. - Novices may not realize which parts of the command they can substitute with - different values, but if you've correctly judged that they should use the - command you've provided as is, then this shouldn't matter. - -## Markdown conventions - -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please observe the following style conventions. If you're -not familiar with Markdown syntax, -[this](https://daringfireball.net/projects/markdown/) is a great resource. - -### Indentation - -Use spaces instead of tabs. Each indentation step should be exactly two (2) -spaces. - -### HTML and CSS - -Do not write HTML inside Markdown documents (except in rare, unavoidable cases, -such as alerts). In particular, never include HTML or CSS for styling, -formatting, or white space control. That belongs in the (S)CSS files instead. - -### Image linking - -Link only to images in -[qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see -[instructions above](#how-to-add-images)). Do not link to images on other -websites. - -### Relative vs. absolute links - -Always use relative rather than absolute paths for internal website links. For -example, use `/doc/doc-guidelines/` instead of -`https://www.qubes-os.org/doc/doc-guidelines/`. Places where it's fine to use -absolute URLs: -- External links -- URLs that appear inside code blocks (e.g., in comments and document - templates, and the plain text reproductions of [QSBs](/security/qsb/) and - [Canaries](/security/canary/)), since they're not hyperlinks -- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part - of the website itself but rather of the auxiliary infrastructure supporting - the website. - -This rule is important, because using absolute URLs for internal website links -is known to break the following: -- Serving the website offline -- Website localization -- Generating offline documentation -- Automatically redirecting Tor Browser visitors to the correct page on the - onion service mirror. - -### Source formatting and syntax - -- Do not use `h1` headings (single `#` or `======` underline). These are - automatically generated from the `title:` line in the YAML frontmatter. - -- Use Atx-style headings: , `##h 2`, `### h3`, etc. - -- Use non-reference-style links like `[website](https://example.com/)`. Do - *not* use reference links like `[website][example]`, `[website][]` or - `[website]`. - -- If appropriate, make numerals in numbered lists match between Markdown source - and HTML output. (Rationale: In the event that a user is required to read the - Markdown source directly, this will make it easier to follow, e.g., numbered - steps in a set of instructions.) - -- When writing code blocks, use [syntax - highlighting](https://github.github.com/gfm/#info-string) where - [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) - and use `[...]` for anything omitted. - -- Use hanging indentations where appropriate. - -### Writing command-line examples - -When providing command line examples: -- Tell the reader where to open a terminal (dom0 or a specific domU), and show - the command along with its output (if any) in a code block, e.g.: - - ~~~markdown - Open a terminal in dom0 and run: - ```shell_session - $ cd test - $ echo Hello - Hello - ``` - ~~~ - -- Precede each command with the appropriate command prompt: At a minimum, the - prompt should contain a trailing `#` (for the user `root`) or `$` (for other - users) on Linux systems and `>` on Windows systems, respectively. - -- Don't try to add comments inside the code block. For example, *don't* do - this: - - ~~~markdown - Open a terminal in dom0 and run: - ```shell_session - # Navigate to the new directory - $ cd test - # Generate a greeting - $ echo Hello - Hello - ``` - ~~~ - - The `#` symbol preceding each comment is ambiguous with a root command - prompt. Instead, put your comments *outside* of the code block in normal - prose. - -### Line wrapping - -Hard wrap Markdown lines at 80 characters, unless the line can't be broken -(e.g., code or a URL). - -## Coding conventions - -The following conventions apply to the website as a whole, including everything -written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep -the codebase consistent when multiple collaborators are working on it. They -should be understood as a practical set of rules for maintaining order in this -specific codebase rather than as a statement of what is objectively right or -good. - -### General practices - -- Use comments to indicate the purposes of different blocks of code. This makes - the file easier to understand and navigate. - -- Use descriptive variable names. Never use one or two letter variable names. - Avoid obscure abbreviations and made-up words. - -- In general, make it easy for others to read your code. Your future self will - thank you, and so will your collaborators! - -- [Don't Repeat Yourself - (DRY)!](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) Instead of - repeating the same block of code multiple times, abstract it out into a - separate file and `include` that file where you need it. - -### Whitespace - -- Always use spaces. Never use tabs. - -- Each indentation step should be exactly two (2) spaces. - -- Whenever you add an opening tag, indent the following line. (Exception: If - you open and close the tag on the same line, do not indent the following - line.) - -- Indent Liquid the same way as HTML. - -- In general, the starting columns of every adjacent pair of lines should be no - more than two spaces apart (example below). - -- No blank or empty lines. (Hint: When you feel you need one, add a comment on - that line instead.) - -#### Indentation example - -Here's an example that follows the indentation rules: - -{% raw %} -```html - - - - {% for item in secs.htmlsections[0].columns %} - - {% endfor %} - - {% for canary in site.data.sec-canary reversed %} - - - - - - {% endfor %} -
{{ item.title }}
{{ canary.date }}Qubes Canary #{{ canary.canary }}
-``` -{% endraw %} - -## Git conventions - -Please try to write good commit messages, according to the [instructions in our -coding style guidelines](/doc/coding-style/#commit-message-guidelines). - -## Continuous Integration (CI) - -The following commands may be useful as a way to interact with our CI -infrastructure. Note that special permissions may be required to use some of -these commands. These commands are generally issued by adding a comment to a -pull request (PR) containing only the command. - -- `PipelineRetry`: Attempts to run the entire build pipeline over again. This - can be useful if CI incorrectly uses a stale branch instead of testing the PR - as if it were merged into `master`. - -- `TestDeploy`: Deploys a test website, which is a live version of the Qubes - website as if this PR had been merged. This can be useful for previewing a PR - on a live public website. **Note:** You must wait for the site to finish - building before issuing this command, or else it will deploy an empty - website. To find the URL of the test website, look for text similar to "This - branch was successfully deployed" and a button named something like "View - deployment." Note that there are two different testing sites: `wwwtest` is - manually updated, whereas `wwwpreview` is managed by the `TestDeploy` - command. diff --git a/developer/general/documentation-style-guide.md b/developer/general/documentation-style-guide.md new file mode 100644 index 00000000..3a9f9ba0 --- /dev/null +++ b/developer/general/documentation-style-guide.md @@ -0,0 +1,440 @@ +--- +lang: en +layout: doc +permalink: /doc/documentation-style-guide/ +redirect_from: +- /doc/doc-guidelines/ +- /en/doc/doc-guidelines/ +- /wiki/DocStyle/ +- /doc/DocStyle/ +ref: 30 +title: Documentation style guide +--- + +_Also see [how to edit the documentation](/doc/how-to-edit-the-documentation/)._ + +Qubes OS documentation pages are stored as plain text Markdown files in the +[qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and +regularly pulling from this repo, users can maintain their own up-to-date +offline copy of all Qubes documentation rather than relying solely on the web. + +The documentation is a volunteer community effort. People like you are +constantly working to make it better. If you notice something that can be fixed +or improved, please [edit the +documentation](/doc/how-to-edit-the-documentation/)! + +This page explains the standards we follow for writing, formatting, and +organizing the documentation. Please follow these guidelines and conventions +when editing the documentation. For the standards governing the website as a +whole, please see the [website style guide](/doc/website-style-guide). + +## Markdown conventions + +All the documentation is written in Markdown for maximum accessibility. When +making contributions, please observe the following style conventions. If you're +not familiar with Markdown syntax, +[this](https://daringfireball.net/projects/markdown/) is a great resource. + +### Hyperlink syntax + +Use non-reference-style links like `[website](https://example.com/)`. Do *not* +use reference-style links like `[website][example]`, `[website][]` or +`[website]`. This facilitates the localization process. + +### Relative vs. absolute links + +Always use relative rather than absolute paths for internal website links. For +example, use `/doc/documentation-style-guide/` instead of +`https://www.qubes-os.org/doc/documentation-style-guide/`. + +You may use absolute URLs in the following cases: + +- External links +- URLs that appear inside code blocks (e.g., in comments and document + templates, and the plain text reproductions of [QSBs](/security/qsb/) and + [Canaries](/security/canary/)), since they're not hyperlinks +- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part + of the website itself but rather of the auxiliary infrastructure supporting + the website + +This rule is important because using absolute URLs for internal website links +breaks: + +- Serving the website offline +- Website localization +- Generating offline documentation +- Automatically redirecting Tor Browser visitors to the correct page on the + onion service mirror + +### Image linking + +See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) +for the required syntax. This will make the image a hyperlink to the image +file, allowing the reader to click on the image in order to view the full image +by itself. This is important. Following best practices, our website has a +responsive design, which allows the website to render appropriately across all +screen sizes. When viewing this page on a smaller screen, such as on a mobile +device, the image will automatically shrink down to fit the screen. If visitors +cannot click on the image to view it in full size, then, depending on their +device, they may have no way see the details in the image clearly. + +In addition, make sure to link only to images in the +[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do +not attempt to link to images hosted on other websites. + +### HTML and CSS + +Do not write HTML inside Markdown documents (except in rare, unavoidable cases, +such as alerts). In particular, never include HTML or CSS for styling, +formatting, or white space control. That belongs in the (S)CSS files instead. + +### Headings + +Do not use `h1` headings (single `#` or `======` underline). These are +automatically generated from the `title:` line in the YAML front matter. + +Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use +underlining syntax (`-----`). + +### Indentation + +Use spaces instead of tabs. Use hanging indentations where appropriate. + +### Lists + +If appropriate, make numerals in numbered lists match between Markdown source +and HTML output. Some users read the Markdown source directly, and this makes +numbered lists easier to follow. + +### Code blocks + +When writing code blocks, use [syntax +highlighting](https://github.github.com/gfm/#info-string) where possible (see +[here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) +for a list of supported languages). Use `[...]` for anything omitted. + +### Line wrapping + +Hard wrap Markdown lines at 80 characters, unless the line can't be broken +(e.g., code or a URL). + +## Writing guidelines + +### Correct use of terminology + +Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). +Use these terms consistently and accurately throughout your writing. + +### Sentence case in headings + +Use sentence case (rather than title case) in headings for the reasons +explained +[here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/). +In particular, since the authorship of the Qubes documentation is decentralized +and widely distributed among users from around the world, many contributors +come from regions with different conventions for implementing title case, not +to mention that there are often differing style guide recommendations even +within a single region. It is much easier for all of us to implement sentence +case consistently across our growing body of pages, which is very important for +managing the ongoing maintenance burden and sustainability of the +documentation. + +### Writing command-line examples + +When providing command-line examples: + +- Tell the reader where to open a terminal (dom0 or a specific domU), and show + the command along with its output (if any) in a code block, e.g.: + + ~~~markdown + Open a terminal in dom0 and run: + ```shell_session + $ cd test + $ echo Hello + Hello + ``` + ~~~ + +- Precede each command with the appropriate command prompt: At a minimum, the + prompt should contain a trailing `#` (for the user `root`) or `$` (for other + users) on Linux systems and `>` on Windows systems, respectively. + +- Don't try to add comments inside the code block. For example, *don't* do + this: + + ~~~markdown + Open a terminal in dom0 and run: + ```shell_session + # Navigate to the new directory + $ cd test + # Generate a greeting + $ echo Hello + Hello + ``` + ~~~ + + The `#` symbol preceding each comment is ambiguous with a root command + prompt. Instead, put your comments *outside* of the code block in normal + prose. + +### Variable names in commands + +Syntactically distinguish variables in commands. For example, this is +ambiguous: + + $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm + +It should instead be: + + $ qvm-run --dispvm= --service qubes.StartApp+xterm + +Note that we syntactically distinguish variables in three ways: + +1. Surrounding them in angled brackets (`< >`) +2. Using underscores (`_`) instead of spaces between words +3. Using all capital letters + +We have observed that many novices make the mistake of typing the surrounding +angled brackets (`< >`) on the command line, even after substituting the +desired real value between them. Therefore, in documentation aimed at novices, +we also recommend clarifying that the angled brackets should not be typed. This +can be accomplished in one of several ways: + +- Explicitly say something like "without the angled brackets." +- Provide an example command using real values that excludes the angled + brackets. +- If you know that almost all users will want to use (or should use) a specific + command containing all real values and no variables, you might consider + providing exactly that command and forgoing the version with variables. + Novices may not realize which parts of the command they can substitute with + different values, but if you've correctly judged that they should use the + command you've provided as is, then this shouldn't matter. + +## Organizational guidelines + +### Do not duplicate documentation + +Duplicating documentation is almost always a bad idea. There are many reasons +for this. The main one is that almost all documentation has to be updated as +some point. When similar documentation appears in more than one place, it is +very easy for it to get updated in one place but not the others (perhaps +because the person updating it doesn't realize it's in more than once place). +When this happens, the documentation as a whole is now inconsistent, and the +outdated documentation becomes a trap, especially for novice users. Such traps +are often more harmful than if the documentation never existed in the first +place. The solution is to **link** to existing documentation rather than +duplicating it. There are some exceptions to this policy (e.g., information +that is certain not to change for a very long time), but they are rare. + +### Core vs. external documentation + +Core documentation resides in the [Qubes OS Project's official +repositories](https://github.com/QubesOS/), mainly in +[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can +be anywhere else (such as forums, community websites, and blogs), but there is +an especially large collection in the [Qubes +Community](https://github.com/Qubes-Community) project. External documentation +should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). +If you've written a piece of documentation that is not appropriate for +[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit +it to the [Qubes Community](https://github.com/Qubes-Community) project +instead. However, *linking* to external documentation from +[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, +the maintainers of the [Qubes Community](https://github.com/Qubes-Community) +project should regularly submit PRs against the documentation index (see [How +to edit the documentation +index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) +to add and update Qubes Community links in the "External Documentation" section +of the documentation table of contents. + +The main difference between **core** (or **official**) and **external** (or +**community** or **unofficial**) documentation is whether it documents software +that is officially written and maintained by the Qubes OS Project. The purpose +of this distinction is to keep the core docs maintainable and high-quality by +limiting them to the software output by the Qubes OS Project. In other words, +we take responsibility for documenting all of the software we put out into the +world, but it doesn't make sense for us to take on the responsibility of +documenting or maintaining documentation for anything else. For example, Qubes +OS may use a popular Linux distribution for an official +[TemplateVM](/doc/templates/). However, it would not make sense for a +comparatively small project like ours, with modest funding and a lean +workforce, to attempt to document software belonging to a large, richly-funded +project with an army of paid and volunteer contributors, especially when they +probably already have documentation of their own. This is particularly true +when it comes to Linux in general. Although many users who are new to Qubes are +also new to Linux, it makes absolutely no sense for our comparatively tiny +project to try to document Linux in general when there is already a plethora of +documentation out there. + +Many contributors do not realize that there is a significant amount of work +involved in *maintaining* documentation after it has been written. They may +wish to write documentation and submit it to the core docs, but they see only +their own writing process and fail to consider that it will have to be kept +up-to-date and consistent with the rest of the docs for years afterward. +Submissions to the core docs also have to [undergo a review +process](/doc/how-to-edit-the-documentation#security) to ensure accuracy before +being merged, which takes up valuable time from the team. We aim to maintain +high quality standards for the core docs (style and mechanics, formatting), +which also takes up a lot of time. If the documentation involves anything +external to the Qubes OS Project (such as a website, platform, program, +protocol, framework, practice, or even a reference to a version number), the +documentation is likely to become outdated when that external thing changes. +It's also important to periodically review and update this documentation, +especially when a new Qubes release comes out. Periodically, there may be +technical or policy changes that affect all the core documentation. The more +documentation there is relative to maintainers, the harder all of this will be. +Since there are many more people who are willing to write documentation than to +maintain it, these individually small incremental additions amount to a +significant maintenance burden for the project. + +On the positive side, we consider the existence of community documentation to +be a sign of a healthy ecosystem, and this is quite common in the software +world. The community is better positioned to write and maintain documentation +that applies, combines, and simplifies the official documentation, e.g., +tutorials that explain how to install and use various programs in Qubes, how to +create custom VM setups, and introductory tutorials that teach basic Linux +concepts and commands in the context of Qubes. In addition, just because the +Qubes OS Project has officially written and maintains some flexible framework, +such as `qrexec`, it does not make sense to include every tutorial that says +"here's how to do something cool with `qrexec`" in the core docs. Such +tutorials generally also belong in the community documentation. + +See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more +background information. + +### Release-specific documentation + +*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending +changes to this policy.* + +We maintain only one set of documentation for Qubes OS. We do not maintain a +different set of documentation for each release of Qubes. Our single set of +Qubes OS documentation is updated on a continual, rolling basis. Our first +priority is to document all **current, stable releases** of Qubes. Our second +priority is to document the next, upcoming release (if any) that is currently +in the beta or release candidate stage. + +In cases where a documentation page covers functionality that differs +considerably between Qubes OS releases, the page should be subdivided into +clearly-labeled sections that cover the different functionality in different +releases: + +#### Incorrect Example + +``` +## How to Foo + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +To foo in Qubes 3.2: + + $ qvm-foo + +Note that this does not work in Qubes 4.0, where there is a special widget +for fooing, which you can find in the lower-right corner of the screen in +the Foo Manager. Alternatively, you can use the more general `qubes-baz` +command introduced in 4.0: + + $ qubes-baz --foo + +Once you foo, make sure to close the baz before fooing the next bar. +``` + +#### Correct Example + +``` +## Qubes 3.2 + +### How to Foo + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +To foo: + + $ qvm-foo + +Once you foo, make sure to close the baz before fooing the next bar. + +## Qubes 4.0 + +### How to Foo + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +There is a special widget for fooing, which you can find in the lower-right +corner of the screen in the Foo Manager. Alternatively, you can use the +general `qubes-baz` command: + + $ qubes-baz --foo + +Once you foo, make sure to close the baz before fooing the next bar. +``` + +Subdividing the page into clearly-labeled sections for each release has several +benefits: + +- It preserves good content for older (but still supported) releases. Many + documentation contributors are also people who prefer to use the latest + release. Many of them are tempted to *replace* existing content that applies + to an older, supported release with content that applies only to the latest + release. This is somewhat understandable. Since they only use the latest + release, they may be focused on their own experience, and they may even + regard the older release as deprecated, even when it's actually still + supported. However, allowing this replacement of content would do a great + disservice to those who still rely on the older, supported release. In many + cases, these users value the stability and reliability of the older, + supported release. With the older, supported release, there has been more + time to fix bugs and make improvements in both the software and the + documentation. Consequently, much of the documentation content for this + release may have gone through several rounds of editing, review, and + revision. It would be a tragedy for this content to vanish while the very set + of users who most prize stability and reliability are depending on it. +- It's easy for readers to quickly find the information they're looking for, + since they can go directly to the section that applies to their release. +- It's hard for readers to miss information they need, since it's all in one + place. In the incorrect example, information that the reader needs could be + in any paragraph in the entire document, and there's no way to tell without + reading the entire page. In the correct example, the reader can simply skim + the headings in order to know which parts of the page need to be read and + which can be safely ignored. The fact that some content is repeated in the + two release-specific sections is not a problem, since no reader has to read + the same thing twice. Moreover, as one release gets updated, it's likely that + the documentation for that release will also be updated. Therefore, content + that is initially duplicated between release-specific sections will not + necessarily stay that way, and this is a good thing: We want the + documentation for a release that *doesn't* change to stay the same, and we + want the documentation for a release that *does* change to change along with + the software. +- It's easy for documentation contributors and maintainers to know which file + to edit and update, since there's only one page for all Qubes OS releases. + Initially creating the new headings and duplicating content that applies to + both is only a one-time cost for each page, and many pages don't even require + this treatment, since they apply to all currently-supported Qubes OS + releases. + +By contrast, an alternative approach, such as segregating the documentation +into two different branches, would mean that contributions that apply to both +Qubes releases would only end up in one branch, unless someone remembered to +manually submit the same thing to the other branch and actually made the effort +to do so. Most of the time, this wouldn't happen. When it did, it would mean a +second pull request that would have to be reviewed. Over time, the different +branches would diverge in non-release-specific content. Good general content +that was submitted only to one branch would effectively disappear once that +release was deprecated. (Even if it were still on the website, no one would +look at it, since it would explicitly be in the subdirectory of a deprecated +release, and there would be a motivation to remove it from the website so that +search results wouldn't be populated with out-of-date information.) + +For further discussion about release-specific documentation in Qubes, see +[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). + +## Git conventions + +Please follow our [Git commit message +guidelines](/doc/coding-style/#commit-message-guidelines). diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index c99e5580..ef281c0a 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -5,7 +5,7 @@ permalink: /gsoc/ redirect_from: - /GSoC/ ref: 33 -title: Google Summer of Code +title: Google Summer of Code (GSoC) --- ## Information for Students diff --git a/developer/general/gsod.md b/developer/general/gsod.md index e49e950d..8d25af1c 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /gsod/ ref: 242 -title: Google Season of Docs +title: Google Season of Docs (GSoD) --- Thank you for your interest in participating in the [2021 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq). diff --git a/developer/general/how-to-edit-the-documentation.md b/developer/general/how-to-edit-the-documentation.md new file mode 100644 index 00000000..f51fe512 --- /dev/null +++ b/developer/general/how-to-edit-the-documentation.md @@ -0,0 +1,198 @@ +--- +lang: en +layout: doc +permalink: /doc/how-to-edit-the-documentation/ +title: How to edit the documentation +--- + +_Also see the [documentation style guide](/doc/documentation-style-guide/)._ + +Qubes OS documentation pages are stored as plain text Markdown files in the +[qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and +regularly pulling from this repo, users can maintain their own up-to-date +offline copy of all Qubes documentation rather than relying solely on the web. + +The documentation is a volunteer community effort. People like you are +constantly working to make it better. If you notice something that can be fixed +or improved, please follow the steps below to open a pull request! + +## How to submit a pull request + +We keep all the documentation in +[qubes-doc](https://github.com/QubesOS/qubes-doc), a dedicated Git repository +hosted on [GitHub](https://github.com/). Thanks to GitHub's easy web interface, +you can edit the documentation even if you're not familiar with Git or the +command line! All you need is a free GitHub account. + +A few notes before we get started: + +- Since Qubes is a security-oriented project, every documentation change will + be [reviewed](#security) before it's accepted. This allows us to maintain + quality control and protect our users. + +- To give your contribution a better chance of being accepted, please follow + our [documentation style guide](/doc/documentation-style-guide/). + +- We don't want you to spend time and effort on a contribution that we can't + accept. If your contribution would take a lot of time, please [file an + issue](/doc/issue-tracking/) for it first so that we can make sure we're on + the same page before significant works begins. + +- Alternatively, you may already have written content that doesn't conform to + these guidelines, but you'd be willing to modify it so that it does. In this + case, you can still submit it by following the instructions below. Just make + a note in your pull request (PR) that you're aware of the changes that need + to be made and that you're just asking for the content to be reviewed before + you spend time making those changes. + +- Finally, if you've written something that doesn't belong in qubes-doc but + that would be beneficial to the Qubes community, please consider adding it to + the [external + documentation](/doc/documentation-style-guide/#core-vs-external-documentation). + +(**Advanced users:** If you're already familiar with GitHub or wish to work +from the command line, you can skip the rest of this section. All you need to +do to contribute is to [fork and +clone](https://guides.github.com/activities/forking/) the +[qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then +[submit a pull +request](https://help.github.com/articles/using-pull-requests/).) + +Ok, let's begin. Every documentation page has a "Page Source on GitHub" button. +Depending on the size of your screen, it may either be on the side (larger +screens) or on the bottom (smaller screens). + +[![page-source-button](/attachment/doc/doc-pr_01_page-source-button.png)](/attachment/doc/doc-pr_01_page-source-button.png) + +When you click on it, you'll be taken to the source file --- usually a Markdown +(`.md`) file --- on GitHub. On this page, there will be a button to edit the +file. + +[![github-edit](/attachment/doc/doc-pr_02_github-edit.png)](/attachment/doc/doc-pr_02_github-edit.png) + +You'll be prompted to sign in with your GitHub username and password +(if you aren't already logged in). You can also create a free account from here. + +[![github-sign-in](/attachment/doc/doc-pr_03_sign-in.png)](/attachment/doc/doc-pr_03_sign-in.png) + +If this is your first contribution to the documentation, you need to "fork" the +repository (make your own copy). It's easy --- just click the big green button +on the next page. This step is only needed the first time you make a +contribution. + +[![fork](/attachment/doc/doc-pr_04_fork.png)](/attachment/doc/doc-pr_04_fork.png) + +Now you can make your modifications. You can also preview the changes to see +how they'll be formatted by clicking the "Preview changes" tab. If you want to +add images, please see [How to add images](#how-to-add-images). If you're +making formatting changes, please [render the site +locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify +that everything looks correct before submitting any changes. + +[![edit](/attachment/doc/doc-pr_05_edit.png)](/attachment/doc/doc-pr_05_edit.png) + +Once you're finished, describe your changes at the bottom and click "Propose +file change". + +[![commit](/attachment/doc/doc-pr_06_commit-msg.png)](/attachment/doc/doc-pr_06_commit-msg.png) + +After that, you'll see exactly what modifications you've made. At this stage, +those changes are still in your own copy of the documentation ("fork"). If +everything looks good, send those changes to us by pressing the "Create pull +request" button. + +[![pull-request](/attachment/doc/doc-pr_07_review-changes.png)](/attachment/doc/doc-pr_07_review-changes.png) + +You will be able to adjust the pull request message and title there. In most +cases, the defaults are ok, so you can just confirm by pressing the "Create +pull request" button again. However, if you're not ready for your PR to be +reviewed or merged yet, please [make a draft PR +instead](https://github.blog/2019-02-14-introducing-draft-pull-requests/). + +[![pull-request-confirm](/attachment/doc/doc-pr_08_create-pull-request.png)](/attachment/doc/doc-pr_08_create-pull-request.png) + +If any of your changes should be reflected in the [documentation index (a.k.a. +table of contents)](/doc/) --- for example, if you're adding a new page, +changing the title of an existing page, or removing a page --- please see [How +to edit the documentation index](#how-to-edit-the-documentation-index). + +That's all! We will review your changes. If everything looks good, we'll pull +them into the official documentation. Otherwise, we may have some questions for +you, which we'll post in a comment on your pull request. (GitHub will +automatically notify you if we do.) If, for some reason, we can't accept your +pull request, we'll post a comment explaining why we can't. + +[![done](/attachment/doc/doc-pr_09_done.png)](/attachment/doc/doc-pr_09_done.png) + +## How to edit the documentation index + +The source file for the [documentation index (a.k.a. table of contents)](/doc/) +is +[doc-index.yml](https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml). + +Editing this file will change what appears on the documentation index. If your +pull request (PR) adds, removes, or edits anything that should be reflected in +the documentation index, please make sure you also submit an associated pull +request against this file. + +## How to add images + +To add an image to a page, use the following syntax in the main document (see +[here](/doc/documentation-style-guide/#image-linking) for why this syntax is +important). + +``` +[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png) +``` + +Then, submit your image(s) in a separate pull request to the +[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository +using the same path and filename. This is the only permitted way to include +images. Do not link to images on other websites. + +## Serving the website locally + +You can serve the website offline on your local machine by following [these +instructions](https://github.com/QubesOS/qubesos.github.io#instructions). This +can be useful for making sure that your changes render the way you expect, +especially when your changes affect formatting, images, tables, styling, etc. + +## Security + +*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)* + +All pull requests (PRs) against +[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be +merged, except in the case of [external +documentation](/doc/#external-documentation) (see +[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is +designed to ensure that contributed text is accurate and non-malicious. This +process is a best effort that should provide a reasonable degree of assurance, +but it is not foolproof. For example, all text characters are checked for ANSI +escape sequences. However, binaries, such as images, are simply checked to +ensure they appear or function the way they should when the website is +rendered. They are not further analyzed in an attempt to determine whether they +are malicious. + +Once a pull request passes review, the reviewer should add a signed comment +stating, "Passed review as of ``" (or similar). The +documentation maintainer then verifies that the pull request is mechanically +sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the +documentation maintainer then merges the pull request, adds a PGP-signed tag to +the latest commit (usually the merge commit), then pushes to the remote. In +cases in which another reviewer is not required, the documentation maintainer +may review the pull request (in which case no signed comment is necessary, +since it would be redundant with the signed tag). + +## Questions, problems, and improvements + +If you have a question about something you read in the documentation or about +how to edit the documentation, please post it on the +[forum](https://forum.qubes-os.org/) or send it to the appropriate [mailing +list](/support/). If you see that something in the documentation should be +fixed or improved, please [contribute](#how-to-submit-a-pull-request) the +change yourself. To report an issue with the documentation, please follow our +standard [issue reporting guidelines](/doc/issue-tracking/). (If you report an +issue with the documentation, you will likely be asked to submit a pull request +for it, unless there is a clear indication in your report that you are not +willing or able to do so.) diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index c15cae1a..f73c9bd2 100644 --- a/developer/general/package-contributions.md +++ b/developer/general/package-contributions.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/package-contributions/ ref: 29 -title: Package Contributions +title: Package contributions --- _This page is for developers who wish to contribute packages. diff --git a/developer/general/style-guide.md b/developer/general/style-guide.md deleted file mode 100644 index ed5b0c47..00000000 --- a/developer/general/style-guide.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -lang: en -layout: doc -permalink: /doc/style-guide/ -ref: 27 -title: Style Guide ---- diff --git a/developer/general/usability-ux.md b/developer/general/usability-ux.md index 75748bcc..5e0c5359 100644 --- a/developer/general/usability-ux.md +++ b/developer/general/usability-ux.md @@ -8,7 +8,7 @@ title: Usability & UX Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! -We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review [our style guide](/doc/style-guide/) for other design related information. +We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review [our visual style guide](/doc/visual-style-guide/) for other design related information. --- diff --git a/developer/general/visual-style-guide.md b/developer/general/visual-style-guide.md new file mode 100644 index 00000000..ceef871d --- /dev/null +++ b/developer/general/visual-style-guide.md @@ -0,0 +1,9 @@ +--- +lang: en +layout: doc +permalink: /doc/visual-style-guide/ +redirect_from: +- /doc/style-guide/ +ref: 27 +title: Visual style guide +--- diff --git a/developer/general/website-style-guide.md b/developer/general/website-style-guide.md new file mode 100644 index 00000000..6c5a7de8 --- /dev/null +++ b/developer/general/website-style-guide.md @@ -0,0 +1,78 @@ +--- +lang: en +layout: doc +permalink: /doc/website-style-guide/ +title: Website style guide +--- + +This page explains the standards we follow for building and maintaining the +website. Please follow these guidelines and conventions when modifying the +website. For the standards governing the documentation in particular, please +see the [documentation style guide](/doc/documentation-style-guide/). + +## Coding conventions + +The following conventions apply to the website as a whole, including everything +written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep +the codebase consistent when multiple collaborators are working on it. They +should be understood as a practical set of rules for maintaining order in this +specific codebase rather than as a statement of what is objectively right or +good. + +### General practices + +- Use comments to indicate the purposes of different blocks of code. This makes + the file easier to understand and navigate. + +- Use descriptive variable names. Never use one or two letter variable names. + Avoid obscure abbreviations and made-up words. + +- In general, make it easy for others to read your code. Your future self will + thank you, and so will your collaborators! + +- [Don't Repeat Yourself + (DRY)!](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) Instead of + repeating the same block of code multiple times, abstract it out into a + separate file and `include` that file where you need it. + +### Whitespace + +- Always use spaces. Never use tabs. + +- Each indentation step should be exactly two (2) spaces. + +- Whenever you add an opening tag, indent the following line. (Exception: If + you open and close the tag on the same line, do not indent the following + line.) + +- Indent Liquid the same way as HTML. + +- In general, the starting columns of every adjacent pair of lines should be no + more than two spaces apart (example below). + +- No blank or empty lines. (Hint: When you feel you need one, add a comment on + that line instead.) + +#### Indentation example + +Here's an example that follows the indentation rules: + +{% raw %} +```html + + + + {% for item in secs.htmlsections[0].columns %} + + {% endfor %} + + {% for canary in site.data.sec-canary reversed %} + + + + + + {% endfor %} +
{{ item.title }}
{{ canary.date }}Qubes Canary #{{ canary.canary }}
+``` +{% endraw %} diff --git a/developer/releases/1_0/release-notes.md b/developer/releases/1_0/release-notes.md index 9681a3e6..39c6ea37 100644 --- a/developer/releases/1_0/release-notes.md +++ b/developer/releases/1_0/release-notes.md @@ -5,7 +5,7 @@ permalink: /doc/releases/1.0/release-notes/ redirect_from: - /en/doc/releases/1.0/release-notes/ ref: 18 -title: Qubes R1.0 Release Notes +title: Qubes R1.0 release notes --- Detailed release notes in [this blog post](https://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html). diff --git a/developer/releases/2_0/release-notes.md b/developer/releases/2_0/release-notes.md index a6e30028..e0a5751d 100644 --- a/developer/releases/2_0/release-notes.md +++ b/developer/releases/2_0/release-notes.md @@ -5,7 +5,7 @@ permalink: /doc/releases/2.0/release-notes/ redirect_from: - /en/doc/releases/2.0/release-notes/ ref: 25 -title: Qubes R2.0 Release Notes +title: Qubes R2.0 release notes --- Detailed release notes in [this blog post](https://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html) diff --git a/developer/releases/3_0/release-notes.md b/developer/releases/3_0/release-notes.md index 44fa79c4..e31b4a27 100644 --- a/developer/releases/3_0/release-notes.md +++ b/developer/releases/3_0/release-notes.md @@ -5,7 +5,7 @@ permalink: /doc/releases/3.0/release-notes/ redirect_from: - /en/doc/releases/3.0/release-notes/ ref: 19 -title: Qubes R3.0 Release Notes +title: Qubes R3.0 release notes --- ### Qubes R3.0 Release Notes diff --git a/developer/releases/3_0/schedule.md b/developer/releases/3_0/schedule.md index 512ee3ab..255ce708 100644 --- a/developer/releases/3_0/schedule.md +++ b/developer/releases/3_0/schedule.md @@ -5,7 +5,7 @@ permalink: /doc/releases/3.0/schedule/ redirect_from: - /en/doc/releases/3.0/schedule/ ref: 20 -title: Qubes R3.0 Release Schedule +title: Qubes R3.0 release schedule --- | Date | Stage | diff --git a/developer/releases/3_1/schedule.md b/developer/releases/3_1/schedule.md index 14481818..93cd69c7 100644 --- a/developer/releases/3_1/schedule.md +++ b/developer/releases/3_1/schedule.md @@ -5,7 +5,7 @@ permalink: /doc/releases/3.1/schedule/ redirect_from: - /en/doc/releases/3.1/schedule/ ref: 17 -title: Qubes R3.1 Release Schedule +title: Qubes R3.1 release schedule --- This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). diff --git a/developer/releases/3_2/schedule.md b/developer/releases/3_2/schedule.md index ed769eec..36cedd23 100644 --- a/developer/releases/3_2/schedule.md +++ b/developer/releases/3_2/schedule.md @@ -5,7 +5,7 @@ permalink: /doc/releases/3.2/schedule/ redirect_from: - /en/doc/releases/3.2/schedule/ ref: 22 -title: Qubes R3.2 Release Schedule +title: Qubes R3.2 release schedule --- This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). diff --git a/developer/releases/4_0/schedule.md b/developer/releases/4_0/schedule.md index 98d4c1df..6268a999 100644 --- a/developer/releases/4_0/schedule.md +++ b/developer/releases/4_0/schedule.md @@ -5,7 +5,7 @@ permalink: /doc/releases/4.0/schedule/ redirect_from: - /en/doc/releases/4.0/schedule/ ref: 24 -title: Qubes R4.0 Release Schedule +title: Qubes R4.0 release schedule --- This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). diff --git a/developer/releases/notes.md b/developer/releases/notes.md index 8059bf69..d11b05ee 100644 --- a/developer/releases/notes.md +++ b/developer/releases/notes.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/releases/notes/ ref: 13 -title: Release Notes +title: Release notes --- * [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) diff --git a/developer/releases/schedules.md b/developer/releases/schedules.md index d2af2d6e..f0129211 100644 --- a/developer/releases/schedules.md +++ b/developer/releases/schedules.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/releases/schedules/ ref: 15 -title: Release Schedules +title: Release schedules --- * [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) diff --git a/developer/releases/todo.md b/developer/releases/todo.md index 98179d89..23d370ed 100644 --- a/developer/releases/todo.md +++ b/developer/releases/todo.md @@ -5,7 +5,7 @@ permalink: /doc/releases/todo/ redirect_from: - /en/doc/releases/todo/ ref: 14 -title: Release Checklist +title: Release checklist --- *the checklist is probably unfinished* diff --git a/developer/releases/version-scheme.md b/developer/releases/version-scheme.md index da4ccf04..3a3c53e7 100644 --- a/developer/releases/version-scheme.md +++ b/developer/releases/version-scheme.md @@ -7,7 +7,7 @@ redirect_from: - /doc/VersionScheme/ - /wiki/VersionScheme/ ref: 151 -title: Version Scheme +title: Version scheme --- Beginning with R3 release, we change (and formalise) the versioning scheme. diff --git a/developer/services/admin-api-table.md b/developer/services/admin-api-table.md index d5426419..ad60fef9 100644 --- a/developer/services/admin-api-table.md +++ b/developer/services/admin-api-table.md @@ -3,7 +3,7 @@ lang: en layout: fullscreen permalink: /doc/admin-api/table/ ref: 249 -title: Admin API Table +title: Admin API table --- This page displays the fullscreen table from [Admin API](/doc/admin-api/). diff --git a/developer/services/disposablevm-implementation.md b/developer/services/disposablevm-implementation.md index 2aee1bfd..952e9cff 100644 --- a/developer/services/disposablevm-implementation.md +++ b/developer/services/disposablevm-implementation.md @@ -8,7 +8,7 @@ redirect_from: - /doc/DVMimpl/ - /wiki/DVMimpl/ ref: 34 -title: DisposableVM Implementation +title: Disposable implementation --- **Note: The content below applies to Qubes R3.2.** diff --git a/developer/services/dom0-secure-updates.md b/developer/services/dom0-secure-updates.md index b4f1bdb8..cc2a4d75 100644 --- a/developer/services/dom0-secure-updates.md +++ b/developer/services/dom0-secure-updates.md @@ -7,7 +7,7 @@ redirect_from: - /doc/Dom0SecureUpdates/ - /wiki/Dom0SecureUpdates/ ref: 43 -title: Dom0 Secure Updates +title: Dom0 secure updates --- Reasons for Dom0 updates diff --git a/developer/services/qfilecopy.md b/developer/services/qfilecopy.md index e1eb8814..b6a24bb8 100644 --- a/developer/services/qfilecopy.md +++ b/developer/services/qfilecopy.md @@ -7,7 +7,7 @@ redirect_from: - /doc/Qfilecopy/ - /wiki/Qfilecopy/ ref: 35 -title: Inter-VM File Copying (qfilecopy) +title: Inter-qube file copying (qfilecopy) --- There are two cases when we need a mechanism to copy files between VMs: diff --git a/developer/services/qfileexchgd.md b/developer/services/qfileexchgd.md index 3523f88c..ab9b1955 100644 --- a/developer/services/qfileexchgd.md +++ b/developer/services/qfileexchgd.md @@ -7,7 +7,7 @@ redirect_from: - /doc/Qfileexchgd/ - /wiki/Qfileexchgd/ ref: 40 -title: qfileexchgd (deprecated) +title: Qfileexchgd (deprecated) --- **This mechanism is obsolete as of Qubes Beta 1!** diff --git a/developer/services/qmemman.md b/developer/services/qmemman.md index d9f191a8..03495c25 100644 --- a/developer/services/qmemman.md +++ b/developer/services/qmemman.md @@ -7,7 +7,7 @@ redirect_from: - /doc/Qmemman/ - /wiki/Qmemman/ ref: 41 -title: Qubes Memory Manager (qmemman) +title: Qubes memory manager (qmemman) --- Rationale diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index b31dbd94..72a2b8c1 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -8,7 +8,7 @@ redirect_from: - /doc/Qrexec3Implementation/ - /wiki/Qrexec3Implementation/ ref: 39 -title: 'Qrexec: Qubes RPC Internals' +title: 'Qrexec: Qubes RPC internals' --- (*This page details the current implementation of qrexec (qrexec3). diff --git a/developer/services/qrexec-socket-services.md b/developer/services/qrexec-socket-services.md index 3f6d776b..1dfd9d2d 100644 --- a/developer/services/qrexec-socket-services.md +++ b/developer/services/qrexec-socket-services.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/qrexec-socket-services/ ref: 42 -title: 'Qrexec: Socket-Based Services' +title: 'Qrexec: socket-based services' --- *This page describes how to implement and use new socket-backed services for qrexec. See [qrexec](/doc/qrexec/) for general overview of the qrexec framework.* diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index 4fb0db8e..5c46ec7f 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -11,7 +11,7 @@ redirect_from: - /doc/Qrexec/ - /wiki/Qrexec/ ref: 37 -title: 'Qrexec: Secure Communication Across Domains' +title: 'Qrexec: secure communication across domains' --- (*This page is about qrexec v3. For qrexec v2, see [here](/doc/qrexec2/).*) diff --git a/developer/services/qrexec2.md b/developer/services/qrexec2.md index 2730f82a..33d0f219 100644 --- a/developer/services/qrexec2.md +++ b/developer/services/qrexec2.md @@ -8,7 +8,7 @@ redirect_from: - /doc/Qrexec2Implementation/ - /wiki/Qrexec2Implementation/ ref: 38 -title: qrexec v2 (deprecated) +title: Qrexec v2 (deprecated) --- (*This page is about qrexec v2. For qrexec v3, see [here](/doc/qrexec/).*) diff --git a/developer/system/audio.md b/developer/system/audio.md index e5abe774..889757ea 100644 --- a/developer/system/audio.md +++ b/developer/system/audio.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/audio-virtualization/ ref: 60 -title: Audio Virtualization +title: Audio virtualization --- VMs on Qubes OS have access to virtualized audio through the PulseAudio module. diff --git a/developer/system/gui.md b/developer/system/gui.md index 07399b2e..9ab6362c 100644 --- a/developer/system/gui.md +++ b/developer/system/gui.md @@ -8,7 +8,7 @@ redirect_from: - /doc/GUIdocs/ - /wiki/GUIdocs/ ref: 61 -title: GUI Virtualization +title: GUI virtualization --- qubes_gui and qubes_guid processes diff --git a/developer/system/qubes-core-admin-client.md b/developer/system/qubes-core-admin-client.md index 188b1a55..dc5907dd 100644 --- a/developer/system/qubes-core-admin-client.md +++ b/developer/system/qubes-core-admin-client.md @@ -4,5 +4,5 @@ layout: doc permalink: /doc/qubes-core-admin-client/ redirect_to: https://dev.qubes-os.org/projects/core-admin-client/en/latest/ ref: 245 -title: Qubes Core Admin Client +title: Qubes core admin client --- diff --git a/developer/system/qubes-core-admin.md b/developer/system/qubes-core-admin.md index e8763adf..1fbb5ec6 100644 --- a/developer/system/qubes-core-admin.md +++ b/developer/system/qubes-core-admin.md @@ -4,5 +4,5 @@ layout: doc permalink: /doc/qubes-core-admin/ redirect_to: https://dev.qubes-os.org/projects/core-admin/en/latest/ ref: 246 -title: Qubes Core Admin +title: Qubes core admin --- diff --git a/developer/system/qubes-core-stack.md b/developer/system/qubes-core-stack.md index cf67f14d..5fb28bdb 100644 --- a/developer/system/qubes-core-stack.md +++ b/developer/system/qubes-core-stack.md @@ -4,5 +4,5 @@ layout: doc permalink: /doc/qubes-core-stack/ redirect_to: /news/2017/10/03/core3/ ref: 247 -title: Qubes Core Stack +title: Qubes core stack --- diff --git a/developer/system/security-critical-code.md b/developer/system/security-critical-code.md index 9588d5c8..64dd4129 100644 --- a/developer/system/security-critical-code.md +++ b/developer/system/security-critical-code.md @@ -8,7 +8,7 @@ redirect_from: - /wiki/SecurityCriticalCode/ - /trac/wiki/SecurityCriticalCode/ ref: 55 -title: Security-Critical Code +title: Security-critical code --- Below is a list of security-critical (i.e., trusted) code components in Qubes OS. diff --git a/developer/system/security-design-goals.md b/developer/system/security-design-goals.md index 41b1a2a6..a8caa43a 100644 --- a/developer/system/security-design-goals.md +++ b/developer/system/security-design-goals.md @@ -9,7 +9,7 @@ redirect_from: - /doc/SecurityGoals/ - /wiki/SecurityGoals/ ref: 210 -title: Security Design Goals +title: Security design goals --- Qubes OS implements a security-by-isolation (or security-by-compartmentalization) approach by providing the ability to easily create many security domains. These domains are implemented as lightweight Virtual Machines (VMs) running under the Xen hypervisor. Qubes' main objective is to provide strong isolation between these domains, so that even if an attacker compromises one of the domains, the others are still safe. Qubes, however, does not attempt to provide any security isolation for applications running within the same domain. For example, a buggy web browser running in a Qubes domain could still be compromised just as easily as on a regular Linux distribution. The difference that Qubes makes is that now the attacker doesn't have access to all the software running in the other domains. diff --git a/developer/system/storage-pools.md b/developer/system/storage-pools.md index 7f0970aa..668ca882 100644 --- a/developer/system/storage-pools.md +++ b/developer/system/storage-pools.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/storage-pools/ ref: 57 -title: Storage Pools +title: Storage pools --- Qubes OS R3.2 introduced the concept of storage drivers and pools. This feature diff --git a/developer/system/system-doc.md b/developer/system/system-doc.md index 1bdaa997..04ab10f8 100644 --- a/developer/system/system-doc.md +++ b/developer/system/system-doc.md @@ -9,5 +9,5 @@ redirect_from: redirect_to: - /doc/#developer-documentation ref: 62 -title: System Documentation +title: System documentation --- diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md index de754f95..e4cc5303 100644 --- a/developer/system/template-implementation.md +++ b/developer/system/template-implementation.md @@ -7,7 +7,7 @@ redirect_from: - /doc/TemplateImplementation/ - /wiki/TemplateImplementation/ ref: 58 -title: Template Implementation +title: Template implementation --- Every VM has 4 block devices connected: diff --git a/external/building-guides/building-archlinux-template.md b/external/building-guides/building-archlinux-template.md index bfa42678..d6bce239 100644 --- a/external/building-guides/building-archlinux-template.md +++ b/external/building-guides/building-archlinux-template.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/BuildingArchlinuxTemplate/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md ref: 116 -title: Building Archlinux Template +title: Building Arch Linux template --- diff --git a/external/building-guides/building-non-fedora-template.md b/external/building-guides/building-non-fedora-template.md index c8a81e01..9bc8490e 100644 --- a/external/building-guides/building-non-fedora-template.md +++ b/external/building-guides/building-non-fedora-template.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/BuildingNonFedoraTemplate/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md ref: 117 -title: Building Non-Fedora Template +title: Building non-Fedora template --- diff --git a/external/building-guides/building-whonix-template.md b/external/building-guides/building-whonix-template.md index aff77445..23e29760 100644 --- a/external/building-guides/building-whonix-template.md +++ b/external/building-guides/building-whonix-template.md @@ -6,5 +6,5 @@ redirect_from: - /en/doc/building-whonix-template/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-whonix-template.md ref: 115 -title: Building Whonix Templates +title: Building Whonix templates --- diff --git a/external/configuration-guides/change-time-zone.md b/external/configuration-guides/change-time-zone.md index c2e179c9..a7666f47 100644 --- a/external/configuration-guides/change-time-zone.md +++ b/external/configuration-guides/change-time-zone.md @@ -5,5 +5,5 @@ redirect_from: - /doc/change-time-zone/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md ref: 109 -title: Changing your Time Zone +title: Changing your time zone --- diff --git a/external/configuration-guides/external-audio.md b/external/configuration-guides/external-audio.md index 33843a06..4fe19b8b 100644 --- a/external/configuration-guides/external-audio.md +++ b/external/configuration-guides/external-audio.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/ExternalAudio/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md ref: 100 -title: External Audio +title: External audio --- diff --git a/external/configuration-guides/install-nvidia-driver.md b/external/configuration-guides/install-nvidia-driver.md index ece53917..8c997052 100644 --- a/external/configuration-guides/install-nvidia-driver.md +++ b/external/configuration-guides/install-nvidia-driver.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/InstallNvidiaDriver/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md ref: 96 -title: How to Install an Nvidia Driver +title: How to install an Nvidia driver --- diff --git a/external/configuration-guides/multimedia.md b/external/configuration-guides/multimedia.md index aef82f2f..24369540 100644 --- a/external/configuration-guides/multimedia.md +++ b/external/configuration-guides/multimedia.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/Multimedia/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md ref: 105 -title: How to Make a Multimedia TemplateVM +title: How to make a multimedia template --- diff --git a/external/configuration-guides/network-bridge-support.md b/external/configuration-guides/network-bridge-support.md index cd4c15ae..5a460a6e 100644 --- a/external/configuration-guides/network-bridge-support.md +++ b/external/configuration-guides/network-bridge-support.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/NetworkBridgeSupport/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md ref: 113 -title: Network Bridge Support +title: Network bridge support --- diff --git a/external/configuration-guides/network-printer.md b/external/configuration-guides/network-printer.md index 46d73c8f..b29ae5ed 100644 --- a/external/configuration-guides/network-printer.md +++ b/external/configuration-guides/network-printer.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/NetworkPrinter/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md ref: 108 -title: Network Printer +title: Network printer --- diff --git a/external/configuration-guides/tips-and-tricks.md b/external/configuration-guides/tips-and-tricks.md index 0126f79d..099e51ab 100644 --- a/external/configuration-guides/tips-and-tricks.md +++ b/external/configuration-guides/tips-and-tricks.md @@ -5,5 +5,5 @@ redirect_from: - /doc/tips-and-tricks/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/tips-and-tricks.md ref: 110 -title: Tips and Tricks +title: Tips and tricks --- diff --git a/external/customization-guides/dark-theme.md b/external/customization-guides/dark-theme.md index 9dba4a0c..2494fca9 100644 --- a/external/customization-guides/dark-theme.md +++ b/external/customization-guides/dark-theme.md @@ -5,5 +5,5 @@ redirect_from: - /doc/dark-theme/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md ref: 74 -title: Dark Theme in Dom0 and DomU +title: Dark theme --- diff --git a/external/customization-guides/fedora-minimal-template-customization.md b/external/customization-guides/fedora-minimal-template-customization.md index cea23c7a..d9773499 100644 --- a/external/customization-guides/fedora-minimal-template-customization.md +++ b/external/customization-guides/fedora-minimal-template-customization.md @@ -5,5 +5,5 @@ redirect_from: - /en/doc/fedora-minimal-template-customization/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md ref: 76 -title: Fedora Minimal Template Customization +title: Fedora minimal template customization --- diff --git a/external/customization-guides/language-localization.md b/external/customization-guides/language-localization.md index 2c22e494..61015d39 100644 --- a/external/customization-guides/language-localization.md +++ b/external/customization-guides/language-localization.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/LanguageLocalization/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md ref: 73 -title: Language Localization +title: Language localization --- diff --git a/external/customization-guides/removing-templatevm-packages.md b/external/customization-guides/removing-templatevm-packages.md index 1d79188d..23efe5a7 100644 --- a/external/customization-guides/removing-templatevm-packages.md +++ b/external/customization-guides/removing-templatevm-packages.md @@ -5,5 +5,5 @@ redirect_from: - /doc/removing-templatevm-packages/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md ref: 75 -title: Removing TemplateVM Packages +title: Removing template packages --- diff --git a/external/customization-guides/windows-template-customization.md b/external/customization-guides/windows-template-customization.md index 8578697d..ac368c23 100644 --- a/external/customization-guides/windows-template-customization.md +++ b/external/customization-guides/windows-template-customization.md @@ -5,5 +5,5 @@ redirect_from: - /doc/windows-template-customization/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md ref: 72 -title: Windows Template Customization +title: Windows template customization --- diff --git a/external/os-guides/centos.md b/external/os-guides/centos.md index e30d69f1..68c43e11 100644 --- a/external/os-guides/centos.md +++ b/external/os-guides/centos.md @@ -5,5 +5,5 @@ redirect_from: - /doc/templates/centos/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md ref: 81 -title: CentOS Template +title: CentOS template --- diff --git a/external/os-guides/gentoo.md b/external/os-guides/gentoo.md index c0c0cb06..ac9f89c2 100644 --- a/external/os-guides/gentoo.md +++ b/external/os-guides/gentoo.md @@ -5,5 +5,5 @@ redirect_from: - /doc/templates/gentoo/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md ref: 221 -title: Gentoo Template +title: Gentoo template --- diff --git a/external/os-guides/linux-hvm-tips.md b/external/os-guides/linux-hvm-tips.md index 9cccf46d..7b1c0e3d 100644 --- a/external/os-guides/linux-hvm-tips.md +++ b/external/os-guides/linux-hvm-tips.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/LinuxHVMTips/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md ref: 82 -title: Linux HVM Tips +title: Linux HVM tips --- diff --git a/external/os-guides/netbsd.md b/external/os-guides/netbsd.md index 3ddca1e8..9e37cc5f 100644 --- a/external/os-guides/netbsd.md +++ b/external/os-guides/netbsd.md @@ -5,5 +5,5 @@ redirect_from: - /doc/netbsd/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md ref: 84 -title: How to Create a NetBSD VM +title: How to create a NetBSD qube --- diff --git a/external/os-guides/pentesting.md b/external/os-guides/pentesting.md index ebede023..8828e5d8 100644 --- a/external/os-guides/pentesting.md +++ b/external/os-guides/pentesting.md @@ -5,5 +5,5 @@ redirect_from: - /doc/pentesting/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting.md ref: 83 -title: Penetration Testing +title: Penetration testing --- diff --git a/external/os-guides/pentesting/blackarch.md b/external/os-guides/pentesting/blackarch.md index 73cae944..a353c37b 100644 --- a/external/os-guides/pentesting/blackarch.md +++ b/external/os-guides/pentesting/blackarch.md @@ -6,5 +6,5 @@ redirect_from: - /doc/blackarch/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md ref: 88 -title: How to Create a BlackArch VM +title: How to create a BlackArch qube --- diff --git a/external/os-guides/pentesting/kali.md b/external/os-guides/pentesting/kali.md index 6d9c2235..817b5aba 100644 --- a/external/os-guides/pentesting/kali.md +++ b/external/os-guides/pentesting/kali.md @@ -6,5 +6,5 @@ redirect_from: - /doc/kali/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md ref: 87 -title: How to create a Kali Linux VM +title: How to create a Kali Linux qube --- diff --git a/external/os-guides/pentesting/ptf.md b/external/os-guides/pentesting/ptf.md index 4d19db5a..440b660b 100644 --- a/external/os-guides/pentesting/ptf.md +++ b/external/os-guides/pentesting/ptf.md @@ -6,5 +6,5 @@ redirect_from: - /doc/ptf/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md ref: 89 -title: How to create Penetration Testers Framework (PTF) VM +title: How to create penetration testers framework (PTF) qube --- diff --git a/external/os-guides/ubuntu.md b/external/os-guides/ubuntu.md index d9edbaa7..3a877c8f 100644 --- a/external/os-guides/ubuntu.md +++ b/external/os-guides/ubuntu.md @@ -9,5 +9,5 @@ redirect_from: - /wiki/Templates/Ubuntu/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md ref: 80 -title: Ubuntu Template +title: Ubuntu template --- diff --git a/external/os-guides/windows/windows-tools.md b/external/os-guides/windows/windows-tools.md index 59d996de..0efce90d 100644 --- a/external/os-guides/windows/windows-tools.md +++ b/external/os-guides/windows/windows-tools.md @@ -14,5 +14,5 @@ redirect_from: - /wiki/WindowsTools/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md ref: 86 -title: Qubes Windows Tools +title: Qubes Windows tools --- diff --git a/external/os-guides/windows/windows-vm.md b/external/os-guides/windows/windows-vm.md index cc4f7c87..1b5e50e9 100644 --- a/external/os-guides/windows/windows-vm.md +++ b/external/os-guides/windows/windows-vm.md @@ -5,5 +5,5 @@ redirect_from: - /doc/windows-vm/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md ref: 85 -title: Installing a Windows VM +title: Installing a Windows qube --- diff --git a/external/privacy-guides/anonymizing-your-mac-address.md b/external/privacy-guides/anonymizing-your-mac-address.md index 140101de..b7ff2f67 100644 --- a/external/privacy-guides/anonymizing-your-mac-address.md +++ b/external/privacy-guides/anonymizing-your-mac-address.md @@ -6,5 +6,5 @@ redirect_from: - /doc/randomizing-your-mac-address/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/anonymizing-your-mac-address.md ref: 67 -title: Anonymizing your MAC Address +title: Anonymizing your MAC address --- diff --git a/external/privacy-guides/tails.md b/external/privacy-guides/tails.md index 7424942e..6de580b5 100644 --- a/external/privacy-guides/tails.md +++ b/external/privacy-guides/tails.md @@ -6,5 +6,5 @@ redirect_from: - /doc/running-tails/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md ref: 71 -title: Running Tails in Qubes +title: Running Tails in qubes --- diff --git a/external/privacy-guides/whonix.md b/external/privacy-guides/whonix.md index 30201260..8f8c7abb 100644 --- a/external/privacy-guides/whonix.md +++ b/external/privacy-guides/whonix.md @@ -18,5 +18,5 @@ redirect_from: - /doc/privacy/updating-whonix/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md ref: 69 -title: Whonix for Privacy & Anonymity +title: Whonix for privacy & anonymity --- diff --git a/external/security-guides/multifactor-authentication.md b/external/security-guides/multifactor-authentication.md index defbcc36..7912b8ed 100644 --- a/external/security-guides/multifactor-authentication.md +++ b/external/security-guides/multifactor-authentication.md @@ -7,5 +7,5 @@ redirect_from: - /doc/Multi-factorAuthentication/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md ref: 78 -title: Multifactor Authentication +title: Multifactor authentication --- diff --git a/external/security-guides/security-guidelines.md b/external/security-guides/security-guidelines.md index d08fe173..eb4d4542 100644 --- a/external/security-guides/security-guidelines.md +++ b/external/security-guides/security-guidelines.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/SecurityGuidelines/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md ref: 79 -title: Security Guidelines +title: Security guidelines --- diff --git a/external/troubleshooting/application-troubleshooting.md b/external/troubleshooting/application-troubleshooting.md index 2fc41356..5c5efb04 100644 --- a/external/troubleshooting/application-troubleshooting.md +++ b/external/troubleshooting/application-troubleshooting.md @@ -5,5 +5,5 @@ redirect_from: - /doc/application-troubleshooting/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md ref: 236 -title: Application Troubleshooting +title: Application troubleshooting --- diff --git a/external/troubleshooting/intel-igfx-troubleshooting.md b/external/troubleshooting/intel-igfx-troubleshooting.md index 52725581..f616fbda 100644 --- a/external/troubleshooting/intel-igfx-troubleshooting.md +++ b/external/troubleshooting/intel-igfx-troubleshooting.md @@ -5,5 +5,5 @@ redirect_from: - /doc/intel-igfx-troubleshooting/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md ref: 90 -title: Intel Integrated Graphics Troubleshooting +title: Intel integrated graphics troubleshooting --- diff --git a/external/troubleshooting/macbook-troubleshooting.md b/external/troubleshooting/macbook-troubleshooting.md index 922dfe12..955e21ad 100644 --- a/external/troubleshooting/macbook-troubleshooting.md +++ b/external/troubleshooting/macbook-troubleshooting.md @@ -3,5 +3,5 @@ lang: en layout: doc redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md ref: 238 -title: Apple MacBook Troubleshooting +title: Apple MacBook troubleshooting --- diff --git a/external/troubleshooting/nvidia-troubleshooting.md b/external/troubleshooting/nvidia-troubleshooting.md index aad45e44..f9d686f9 100644 --- a/external/troubleshooting/nvidia-troubleshooting.md +++ b/external/troubleshooting/nvidia-troubleshooting.md @@ -6,5 +6,5 @@ redirect_from: - /wiki/NvidiaTroubleshooting/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md ref: 91 -title: Nvidia Troubleshooting +title: Nvidia troubleshooting --- diff --git a/external/troubleshooting/sony-vaio-tinkering.md b/external/troubleshooting/sony-vaio-tinkering.md index 52360500..19fe54c4 100644 --- a/external/troubleshooting/sony-vaio-tinkering.md +++ b/external/troubleshooting/sony-vaio-tinkering.md @@ -8,5 +8,5 @@ redirect_from: - /wiki/SonyVaioTinkering/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/sony-vaio-tinkering.md ref: 93 -title: Sony Vaio Tinkering +title: Sony Vaio tinkering --- diff --git a/external/troubleshooting/tails-troubleshooting.md b/external/troubleshooting/tails-troubleshooting.md index f5c5c5f6..6b815f49 100644 --- a/external/troubleshooting/tails-troubleshooting.md +++ b/external/troubleshooting/tails-troubleshooting.md @@ -5,5 +5,5 @@ redirect_from: - /doc/tails-troubleshooting/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/tails-troubleshooting.md ref: 237 -title: Tails Troubleshooting +title: Tails troubleshooting --- diff --git a/external/troubleshooting/thinkpad-troubleshooting.md b/external/troubleshooting/thinkpad-troubleshooting.md index bf249b5a..42f25997 100644 --- a/external/troubleshooting/thinkpad-troubleshooting.md +++ b/external/troubleshooting/thinkpad-troubleshooting.md @@ -13,5 +13,5 @@ redirect_from: - /wiki/Lenovo450Tinkering/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/thinkpad-troubleshooting.md ref: 95 -title: Lenovo ThinkPad Troubleshooting +title: Lenovo ThinkPad troubleshooting --- diff --git a/introduction/code-of-conduct.md b/introduction/code-of-conduct.md index b585c996..6e18e446 100644 --- a/introduction/code-of-conduct.md +++ b/introduction/code-of-conduct.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /code-of-conduct/ ref: 118 -title: Code of Conduct +title: Code of conduct --- ## Introduction diff --git a/introduction/contributing.md b/introduction/contributing.md index e6eba1d9..2ffb4699 100644 --- a/introduction/contributing.md +++ b/introduction/contributing.md @@ -7,7 +7,7 @@ redirect_from: - /doc/ContributingHowto/ - /wiki/ContributingHowto/ ref: 125 -title: How to Contribute +title: How to contribute --- Thank you for your interest in contributing to Qubes! Here are some of the many @@ -24,7 +24,7 @@ ways in which you can help: * Record [video tours](/video-tours/) * Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes, installer themes, wallpapers, etc.) -* [Write and edit the documentation](/doc/doc-guidelines) +* [Write and edit the documentation](/doc/how-to-edit-the-documentation) * [Donate](/donate/) to the project * If you represent an organization, become a [Qubes partner](/partners/) * Add a [Qubes download mirror](/downloads/mirrors/) diff --git a/introduction/faq.md b/introduction/faq.md index 373d11c5..e46e75c9 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -12,7 +12,7 @@ redirect_from: - /doc/DevelFaq/ - /wiki/DevelFaq/ ref: 124 -title: Frequently Asked Questions (FAQ) +title: Frequently asked questions (FAQ) --- ## General & Security @@ -255,7 +255,7 @@ Please refer to [this page](/doc/vm-sudo/). Please see: - [Installing and updating software in dom0](/doc/how-to-install-software-in-dom0/) -- [Note on dom0 and EOL](/doc/supported-versions/#note-on-dom0-and-eol) +- [Note on dom0 and EOL](/doc/supported-releases/#note-on-dom0-and-eol) ### Do you recommend coreboot as an alternative to vendor BIOS? @@ -267,7 +267,9 @@ Please see the coreboot website / their IRC channel for further information. ### How should I report documentation issues? -Please see the [documentation guidelines](/doc/doc-guidelines). +If you can fix the problem yourself, please see [how to edit the +documentation](/doc/how-to-edit-the-documentation). If not, please see [issue +tracking](/doc/issue-tracking). ### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)? @@ -279,7 +281,7 @@ This website is hosted on [GitHub Pages](https://pages.github.com/) ([why?](#why Therefore, it is largely outside of our control. We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure). For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web. -Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone review per our [documentation guidelines](/doc/doc-guidelines)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/doc-guidelines/#markdown-conventions). +Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone [review](/doc/how-to-edit-the-documentation/#security)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/documentation-style-guide/#markdown-conventions). We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible. ### What does it mean to "distrust the infrastructure"? @@ -630,7 +632,7 @@ Specifically: - If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust. - If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)). -- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templates) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation). +- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-releases/#templates) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation). - If the software must be built from source, the source code and any builders must be signed. (Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 293131c0..854de34e 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -9,7 +9,7 @@ redirect_from: - /doc/GettingStarted/ - /wiki/GettingStarted/ ref: 190 -title: Getting Started +title: Getting started --- After [downloading](/downloads/) and [installing](/doc/installation-guide/) @@ -249,4 +249,4 @@ GitHub](https://github.com/QubesOS). ## Documentation Peruse our extensive library of [documentation](/doc/) for users and developers -of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)! +of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)! diff --git a/introduction/issue-tracking.md b/introduction/issue-tracking.md index 91b7c737..d11a0249 100644 --- a/introduction/issue-tracking.md +++ b/introduction/issue-tracking.md @@ -13,7 +13,7 @@ redirect_from: - /bug-report/ - /bug-reports/ ref: 121 -title: Issue Tracking +title: Issue tracking --- We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue @@ -34,9 +34,9 @@ Support, Mailing Lists, and Forum](/support/). ### I see something that should be changed in the documentation. -We encourage you to submit the change yourself! Please see the [Documentation -Guidelines](/doc/doc-guidelines/) for instructions on how to do so. If it's -something you can't do yourself, please proceed to open an issue. +We encourage you to submit the change yourself! Please see the [how to edit the +documentation](/doc/how-to-edit-the-documentation/) for instructions on how to +do so. If it's something you can't do yourself, please proceed to open an issue. ### I would like to report a security vulnerability. @@ -352,12 +352,3 @@ which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may be need to adjust it manually. - -## See also - -- [Help, Support, Mailing Lists, and Forum](/support/) -- [Testing New Releases and Updates](/doc/testing/) -- [How to Contribute](/doc/contributing/) -- [Contributing Code](/doc/contributing/#contributing-code) -- [Package Contributions](/doc/package-contributions/) -- [Documentation Guidelines](/doc/doc-guidelines/) diff --git a/introduction/privacy.md b/introduction/privacy.md index 8c949e88..97465fb9 100644 --- a/introduction/privacy.md +++ b/introduction/privacy.md @@ -7,7 +7,7 @@ redirect_from: - /doc/privacy/ - /wiki/privacy/ ref: 243 -title: Privacy Policy +title: Privacy policy --- The short version is that we try to respect your privacy as much as possible. diff --git a/introduction/support.md b/introduction/support.md index b957d521..ae97e541 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -12,7 +12,7 @@ redirect_from: - /doc/QubesLists/ - /wiki/QubesLists/ ref: 122 -title: Help, Support, Mailing Lists, and Forum +title: Help, support, mailing lists, and forum --- The Qubes community is here to help! Since Qubes is a security-oriented @@ -124,7 +124,7 @@ contributions](/doc/code-signing/). For example, you might find it easier to trust advice from someone who has a proven track record of [contributing software packages](/doc/package-contributions/) or [contributing to the -documentation](/doc/doc-guidelines/). It's unlikely that individuals who have +documentation](/doc/how-to-edit-the-documentation/). It's unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS @@ -217,7 +217,7 @@ not a discussion forum](/doc/issue-tracking/#the-issue-tracker-is-not-a-discussion-forum).) Likewise, if you see that something in the documentation should be changed, don't simply point it out in a discussion venue. Instead, [submit the -change](/doc/doc-guidelines/). +change](/doc/how-to-edit-the-documentation/). ### Moderation diff --git a/introduction/video-tours.md b/introduction/video-tours.md index 375404a3..67f6f887 100644 --- a/introduction/video-tours.md +++ b/introduction/video-tours.md @@ -3,7 +3,7 @@ lang: en layout: site permalink: /video-tours/ ref: 226 -title: Video Tours +title: Video tours --- ## Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked" diff --git a/project-security/canary-checklist.md b/project-security/canary-checklist.md index c98c5033..cb3a3c53 100644 --- a/project-security/canary-checklist.md +++ b/project-security/canary-checklist.md @@ -5,7 +5,7 @@ permalink: /security/canary/checklist/ redirect_from: - /security/canaries/checklist/ ref: 216 -title: Qubes Canary Checklist +title: Qubes canary checklist --- ## Preparation diff --git a/project-security/canary-template.md b/project-security/canary-template.md index 4963f41d..a32e6275 100644 --- a/project-security/canary-template.md +++ b/project-security/canary-template.md @@ -8,5 +8,5 @@ redirect_from: redirect_to: - https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-template.txt ref: 212 -title: Qubes Canary Template +title: Qubes canary template --- diff --git a/project-security/canary.md b/project-security/canary.md index 71cd17e2..31174f6d 100644 --- a/project-security/canary.md +++ b/project-security/canary.md @@ -6,7 +6,7 @@ redirect_from: - /security/canaries/ - /doc/canaries/ ref: 208 -title: Qubes Canaries +title: Qubes canaries --- A **Qubes Canary** is a security announcement periodically issued by the [Qubes diff --git a/project-security/qsb-checklist.md b/project-security/qsb-checklist.md index a4c2f65e..7fbf32af 100644 --- a/project-security/qsb-checklist.md +++ b/project-security/qsb-checklist.md @@ -6,7 +6,7 @@ redirect_from: - /security/bulletins/checklist/ - /doc/security-bulletins/checklist/ ref: 215 -title: Qubes Security Bulletin (QSB) Checklist +title: Qubes security bulletin (QSB) checklist --- ## Preparation diff --git a/project-security/qsb-template.md b/project-security/qsb-template.md index 1a56022c..aa128d28 100644 --- a/project-security/qsb-template.md +++ b/project-security/qsb-template.md @@ -8,5 +8,5 @@ redirect_from: redirect_to: - https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-template.txt ref: 209 -title: Qubes Security Bulletin (QSB) Template +title: Qubes security bulletin (QSB) template --- diff --git a/project-security/qsb.md b/project-security/qsb.md index b9105aac..0c956aa8 100644 --- a/project-security/qsb.md +++ b/project-security/qsb.md @@ -10,7 +10,7 @@ redirect_from: - /wiki/SecurityBulletins/ - /trac/wiki/SecurityBulletins/ ref: 218 -title: Qubes Security Bulletins (QSBs) +title: Qubes security bulletins (QSBs) --- A **Qubes Security Bulletin (QSB)** is a security announcement issued by the diff --git a/project-security/security-pack.md b/project-security/security-pack.md index e3cea666..3d6c1aad 100644 --- a/project-security/security-pack.md +++ b/project-security/security-pack.md @@ -15,7 +15,7 @@ redirect_from: - /doc/sec-pack/ - /doc/secpack/ ref: 213 -title: Qubes Security Pack (qubes-secpack) +title: Qubes security pack (qubes-secpack) --- The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that diff --git a/project-security/security.md b/project-security/security.md index 10b61f0b..c9b19e03 100644 --- a/project-security/security.md +++ b/project-security/security.md @@ -13,7 +13,7 @@ redirect_from: - /wiki/SecurityPage/ - /trac/wiki/SecurityPage/ ref: 217 -title: Qubes OS Project Security Center +title: Qubes OS project security center --- This page provides a central hub for topics pertaining to the security of the diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 0a08e61b..9625a572 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -8,7 +8,7 @@ redirect_from: - /doc/VerifyingSignatures/ - /wiki/VerifyingSignatures/ ref: 211 -title: Verifying Signatures +title: Verifying signatures --- ## What Digital Signatures Can and Cannot Prove diff --git a/project-security/xsa.md b/project-security/xsa.md index b14ae38b..d2221fd4 100644 --- a/project-security/xsa.md +++ b/project-security/xsa.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /security/xsa/ ref: 214 -title: Xen Security Advisory (XSA) Tracker +title: Xen security advisory (XSA) tracker --- This tracker shows whether Qubes OS is affected by any given [Xen Security diff --git a/user/advanced-topics/bind-dirs.md b/user/advanced-topics/bind-dirs.md index 67ca82b0..2266d91e 100644 --- a/user/advanced-topics/bind-dirs.md +++ b/user/advanced-topics/bind-dirs.md @@ -5,7 +5,7 @@ permalink: /doc/bind-dirs/ redirect_from: - /en/doc/bind-dirs/ ref: 186 -title: How to Make Any File Persistent (bind-dirs) +title: How to make any file persistent (bind-dirs) --- ## What are bind-dirs? ## diff --git a/user/advanced-topics/config-files.md b/user/advanced-topics/config-files.md index 7ab46faa..3ffdfd55 100644 --- a/user/advanced-topics/config-files.md +++ b/user/advanced-topics/config-files.md @@ -8,7 +8,7 @@ redirect_from: - /doc/UserDoc/ConfigFiles/ - /wiki/UserDoc/ConfigFiles/ ref: 180 -title: Config Files +title: Config files --- Qubes-specific VM config files diff --git a/user/advanced-topics/disposable-customization.md b/user/advanced-topics/disposable-customization.md index 2368ef67..16515a21 100644 --- a/user/advanced-topics/disposable-customization.md +++ b/user/advanced-topics/disposable-customization.md @@ -10,7 +10,7 @@ redirect_from: - /doc/UserDoc/DispVMCustomization/ - /wiki/UserDoc/DispVMCustomization/ ref: 174 -title: Disposable Customization +title: Disposable customization --- ## Introduction diff --git a/user/advanced-topics/gui-configuration.md b/user/advanced-topics/gui-configuration.md index a4420a01..2f02bbe8 100644 --- a/user/advanced-topics/gui-configuration.md +++ b/user/advanced-topics/gui-configuration.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/gui-configuration/ ref: 184 -title: GUI Configuration +title: GUI configuration --- ## Video RAM adjustment for high-resolution displays diff --git a/user/advanced-topics/how-to-install-software-in-dom0.md b/user/advanced-topics/how-to-install-software-in-dom0.md index 7850969b..ddd7f869 100644 --- a/user/advanced-topics/how-to-install-software-in-dom0.md +++ b/user/advanced-topics/how-to-install-software-in-dom0.md @@ -8,7 +8,7 @@ redirect_from: - /doc/SoftwareUpdateDom0/ - /wiki/SoftwareUpdateDom0/ ref: 194 -title: How to Install Software in Dom0 +title: How to install software in dom0 --- **Warning:** Installing software in dom0 is for advanced users only. Doing so diff --git a/user/advanced-topics/installing-contributed-packages.md b/user/advanced-topics/installing-contributed-packages.md index 8bc2e347..78a8da85 100644 --- a/user/advanced-topics/installing-contributed-packages.md +++ b/user/advanced-topics/installing-contributed-packages.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/installing-contributed-packages/ ref: 225 -title: Installing Contributed Packages +title: Installing contributed packages --- _This page is for users who wish to install contributed packages. diff --git a/user/advanced-topics/managing-vm-kernels.md b/user/advanced-topics/managing-vm-kernels.md index 6460658a..12a4949c 100644 --- a/user/advanced-topics/managing-vm-kernels.md +++ b/user/advanced-topics/managing-vm-kernels.md @@ -6,7 +6,7 @@ redirect_from: - /doc/managing-vm-kernel/ - /en/doc/managing-vm-kernel/ ref: 173 -title: Managing VM Kernels +title: Managing qube kernels --- By default, VMs kernels are provided by dom0. diff --git a/user/advanced-topics/mount-from-other-os.md b/user/advanced-topics/mount-from-other-os.md index ec0427dc..86441666 100644 --- a/user/advanced-topics/mount-from-other-os.md +++ b/user/advanced-topics/mount-from-other-os.md @@ -7,7 +7,7 @@ redirect_from: - /doc/MountFromOtherOs/ - /wiki/MountFromOtherOs/ ref: 175 -title: How to Mount a Qubes Partition from Another OS +title: How to mount a Qubes partition from another OS --- When a Qubes OS install is unbootable or booting it is otherwise undesirable, this process allows for the recovery of files stored within the system. diff --git a/user/advanced-topics/qubes-service.md b/user/advanced-topics/qubes-service.md index 87ee5d7a..d62a16c6 100644 --- a/user/advanced-topics/qubes-service.md +++ b/user/advanced-topics/qubes-service.md @@ -7,7 +7,7 @@ redirect_from: - /doc/QubesService/ - /wiki/QubesService/ ref: 138 -title: Qubes Service +title: Qubes service --- Usage documentation is in the `qvm-service` man page. There are also described predefined services. diff --git a/user/advanced-topics/resize-disk-image.md b/user/advanced-topics/resize-disk-image.md index ed41fa70..b7805bd2 100644 --- a/user/advanced-topics/resize-disk-image.md +++ b/user/advanced-topics/resize-disk-image.md @@ -10,7 +10,7 @@ redirect_from: - /wiki/ResizeDiskImage/ - /wiki/ResizeRootDiskImage/ ref: 182 -title: Resize Disk Image +title: Resize disk image --- ## Resizing Disk Images diff --git a/user/advanced-topics/rpc-policy.md b/user/advanced-topics/rpc-policy.md index 19dd9f73..d86ab1ac 100644 --- a/user/advanced-topics/rpc-policy.md +++ b/user/advanced-topics/rpc-policy.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/rpc-policy/ ref: 178 -title: RPC Policies +title: RPC policies --- This document explains the basics of RPC policies in Qubes. diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md index be01f454..10f01425 100644 --- a/user/advanced-topics/secondary-storage.md +++ b/user/advanced-topics/secondary-storage.md @@ -7,7 +7,7 @@ redirect_from: - /doc/SecondaryStorage/ - /wiki/SecondaryStorage/ ref: 187 -title: Secondary Storage +title: Secondary storage --- Suppose you have a fast but small primary SSD and a large but slow secondary HDD. diff --git a/user/advanced-topics/usb-qubes.md b/user/advanced-topics/usb-qubes.md index bc978633..ef4bf7c6 100644 --- a/user/advanced-topics/usb-qubes.md +++ b/user/advanced-topics/usb-qubes.md @@ -9,7 +9,7 @@ redirect_from: - /wiki/USBVM/ - /doc/sys-usb/ ref: 181 -title: USB Qubes +title: USB qubes --- If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so. diff --git a/user/advanced-topics/volume-backup-revert.md b/user/advanced-topics/volume-backup-revert.md index 417c93f6..50351107 100644 --- a/user/advanced-topics/volume-backup-revert.md +++ b/user/advanced-topics/volume-backup-revert.md @@ -7,7 +7,7 @@ redirect_from: - /doc/VolumeBackupRevert/ - /wiki/VolumeBackupRevert/ ref: 206 -title: Volume Backup and Revert +title: Volume backup and revert --- With Qubes, it is possible to revert one of a VM's storage volumes to a previous diff --git a/user/advanced-topics/windows.md b/user/advanced-topics/windows.md index 347f17b6..e808f95b 100644 --- a/user/advanced-topics/windows.md +++ b/user/advanced-topics/windows.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /doc/windows/ ref: 129 -title: Windows VMs +title: Windows qubes --- Like any other unmodified OSes, Windows can be installed in Qubes as an [HVM](/doc/standalone-and-hvm/) domain. diff --git a/user/downloading-installing-upgrading/custom-install.md b/user/downloading-installing-upgrading/custom-install.md index f536e6bc..e697f2e7 100644 --- a/user/downloading-installing-upgrading/custom-install.md +++ b/user/downloading-installing-upgrading/custom-install.md @@ -6,7 +6,7 @@ permalink: /doc/custom-install/ redirect_from: - /doc/encryption-config/ ref: 152 -title: Custom Installation +title: Custom installation --- In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration. diff --git a/user/downloading-installing-upgrading/download-mirrors.md b/user/downloading-installing-upgrading/download-mirrors.md index 4220ea00..e9189a0a 100644 --- a/user/downloading-installing-upgrading/download-mirrors.md +++ b/user/downloading-installing-upgrading/download-mirrors.md @@ -3,7 +3,7 @@ lang: en layout: doc permalink: /downloads/mirrors/ ref: 148 -title: Download Mirrors +title: Download mirrors --- **Note:** The Qubes OS Project has no control over or access to data collected at these mirrors. diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md index cc68bd87..e3d3e3a3 100644 --- a/user/downloading-installing-upgrading/installation-guide.md +++ b/user/downloading-installing-upgrading/installation-guide.md @@ -16,7 +16,7 @@ redirect_from: - /doc/InstallationGuideR3.0rc2/ - /doc/live-usb/ ref: 153 -title: Installation Guide +title: Installation guide --- Welcome to the Qubes OS installation guide! This guide will walk you through @@ -33,7 +33,8 @@ functional and secure. Warning: Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don't trust. - See installation security for more information. + See installation security for more + information. Qubes OS has very specific [system requirements](/doc/system-requirements/). To @@ -44,16 +45,17 @@ significant troubleshooting. You may also find it helpful to consult the Even on supported hardware, you must ensure that [IOMMU-based virtualization](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization) -is activated in the BIOS. Without it, Qubes OS won't be able to enforce +is activated in the BIOS or UEFI. Without it, Qubes OS won't be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be -activated in your computer's BIOS, alongside the standard Virtualization -(**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This [external +activated in your computer's BIOS or UEFI, alongside the standard +Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. +This [external guide](https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html) -made for Intel-based boards can help you figure out how to enter your BIOS to -locate and activate those settings. If those settings are not nested under the -Advanced tab, you might find them under the Security tab. +made for Intel-based boards can help you figure out how to enter your BIOS or +UEFI to locate and activate those settings. If those settings are not nested +under the Advanced tab, you might find them under the Security tab.