Migration: fix indented lists and raw html tables

All raw directives have been removed or replaced by reStructuredText
list-tables.

developer/building/qubes-builder-v2.rst

@@ -2,7 +2,6 @@
 Qubes builder v2
 ================
 
-
 This is a brief introduction to using Qubes Builder v2 to work with Qubes OS sources. It will walk you through installing and configuring Builder v2, and using it to fetch and build Qubes OS packages.
 
 For details and customization, use `Qubes OS v2 builder documentation <https://github.com/QubesOS/qubes-builderv2/>`__.
@@ -10,13 +9,11 @@ For details and customization, use `Qubes OS v2 builder documentation <https://g
 Overview
 --------
 
-
 In the second generation of Qubes OS builder, container or disposable qube isolation is used to perform every stage of the build and release process. From fetching sources to building, everything is executed inside an isolated *cage* (either a disposable or a container) using an *executor*. For every command that needs to perform an action on sources, like cloning and verifying Git repos, rendering a SPEC file, generating SRPM or Debian source packages, a new cage is used. Only the signing, publishing, and uploading stages are executed locally outside a cage.
 
 Setup
 -----
 
-
 This is a simple setup using a docker executor. This is a good default choice; if you don’t know which executor to use, use docker.
 
 1. First, decide what qube you are going to use when working with Qubes Builder v2. It can be an AppVM or a Standalone qube, with some steps different between the two.
@@ -25,30 +22,21 @@ This is a simple setup using a docker executor. This is a good default choice; i
 
    - If you want to use an app qube for developing, install dependencies in the template. If you are using a standalone, install them in the qube itself. Dependencies are specified in ``dependencies-*. txt`` files in the main builder directory, and you can install them easily in the following ways:
 
+      - for Fedora, use:
 
+         .. code:: bash
 
-   1. for Fedora, use:
+               $ sudo dnf install $(cat dependencies-fedora.txt)
+               $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
 
+      - for Debian (note: some Debian packages require Debian version 13 or later), use:
 
+         .. code:: bash
 
-   .. code:: bash
+               $ sudo apt install $(cat dependencies-debian.txt)
+               $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
 
-         $ sudo dnf install $(cat dependencies-fedora.txt)
-         $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
-
-
-   2. for Debian (note: some Debian packages require Debian version 13 or later), use:
-
-
-
-
-
-   .. code:: bash
-
-         $ sudo apt install $(cat dependencies-debian.txt)
-         $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
-
-   If you have installed dependencies in the template, close it, and (re)start the development qube.
+   - If you have installed dependencies in the template, close it, and (re)start the development qube.
 
 3. Clone the qubes-builder v2 repository into a location of your choice:
 
@@ -57,7 +45,6 @@ This is a simple setup using a docker executor. This is a good default choice; i
          git clone https://github.com/QubesOS/qubes-builderv2
          cd qubes-builderv2/
 
-
 4. If you haven’t previously used docker in the current qube, you need to set up some permissions. In particular, the user has to be added to the ``docker`` group:
 
    .. code:: bash
@@ -78,14 +65,9 @@ This is a simple setup using a docker executor. This is a good default choice; i
 
          binds+=( '/var/lib/docker' )
 
-
-
-
-
 Configuration
 -------------
 
-
 To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration file. You can use one of the sample files from the ``example-configs/`` directory; for a more readable ``builder.yml``, you can also include one of the files from that directory in your ``builder.yml``. An example ``builder.yml`` is:
 
 .. code:: bash
@@ -93,42 +75,38 @@ To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration fil
       # include configuration relevant for the current release
       include:
       - example-configs/qubes-os-r4.2.yml
-      
+
       # which repository to use to fetch sources
       use-qubes-repo:
         version: 4.2
         testing: true
-      
+
       # each package built will have local build number appended to package release
       # number. It makes it easier to update in testing environment
       increment-devel-versions: true
-      
+
       # reduce output
       debug: false
-      
+
       # this can be set to true if you do not want sources to be automatically
       # fetched from git
       skip-git-fetch: false
-      
+
       # executor configuration
       executor:
         type: docker
         options:
           image: "qubes-builder-fedora:latest"
 
-
-
 Using Builder v2
 ----------------
 
-
 To fetch sources - in this example, for the ``core-admin-client`` package, you can use the following command:
 
 .. code:: bash
 
       $ ./qb -c core-admin-client package fetch
 
-
 This will fetch the sources for the listed package and place them in ``artifacts/sources`` directory.
 
 To build a package (from sources in the ``artifacts/sources`` directory), use:
@@ -137,19 +115,16 @@ To build a package (from sources in the ``artifacts/sources`` directory), use:
 
       $ ./qb -c core-admin-client package fetch prep build
 
-
 or, if you want to build for a specific target (``host-fc37`` is a ``dom0`` using Fedora 37, ``vm-fc40`` would be a qube using Fedora 40 etc.), use:
 
 .. code:: bash
 
       $ ./qb -c core-admin-client -d host-fc37 package fetch prep build
 
-
 If you want to fetch the entire Qubes OS source use the following:
 
 .. code:: bash
 
       $ ./qb package fetch
 
-
 **caution**: some repositories might have additional requirements. You can disable repositories that are not needed in the ``example-configs/*.yml`` file you are using by commenting them out. In particular, ``python-fido2``, ``lvm`` and ``windows``-related repositories have special requirements.

developer/code/code-signing.rst

@@ -19,26 +19,26 @@ Alex Cabal has written an excellent `guide <https://alexcabal.com/creating-the-p
       gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
       This is free software: you are free to change and redistribute it.
       There is NO WARRANTY, to the extent permitted by law.
-      
+
       gpg: directory '/home/user/.gnupg' created
       gpg: keybox '/home/user/.gnupg/pubring.kbx' created
       **Note:** Use "gpg --full-generate-key" for a full featured key generation dialog.
-      
+
       GnuPG needs to construct a user ID to identify your key.
-      
+
       Real name: Bilbo Baggins
       Email address: bilbo@shire.org
       You selected this USER-ID:
           "Bilbo Baggins <bilbo@shire.org>"
-      
+
       Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
       We need to generate a lot of random bytes. It is a good idea to perform
       some other action (type on the keyboard, move the mouse, utilize the
       disks) during the prime generation; this gives the random number
       generator a better chance to gain enough entropy.
-      
+
       <type your passphrase>
-      
+
       We need to generate a lot of random bytes. It is a good idea to perform
       some other action (type on the keyboard, move the mouse, utilize the
       disks) during the prime generation; this gives the random number
@@ -48,7 +48,7 @@ Alex Cabal has written an excellent `guide <https://alexcabal.com/creating-the-p
       gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
       gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/87975838063F97A968D503266E2F4E7AF50A5827.rev'
       public and secret key created and signed.
-      
+
       pub   rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
             87975838063F97A968D503266E2F4E7AF50A5827
       uid                      Bilbo Baggins <bilbo@shire.org>
@@ -111,6 +111,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
 
 
 3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check.
+
    This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history.
 
    .. code:: bash

developer/code/source-code.rst

@@ -61,6 +61,7 @@ How to Send Patches
 If you want to :ref:`contribute code <introduction/contributing:contributing code>` to the project, there are two ways. Whichever method you choose, you must :doc:`sign your code </developer/code/code-signing>` before it can be accepted.
 
 - **Preferred**: Use GitHub’s `fork & pull requests <https://guides.github.com/activities/forking/>`__.
+
   Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it’s a good idea to send a message to the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` in order to notify people who do not receive GitHub notifications.
 
 - Send a patch to the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` (``git format-patch``).

developer/general/usability-ux.rst

@@ -2,19 +2,15 @@
 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 visual style guide <https://www.qubes-os.org/doc/visual-style-guide/>`__ for other design related information.
 
-
 ----
 
-
 Easy To Use
 -----------
 
-
 An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal.
 
 |redx| **Interfaces Should Not**
@@ -27,8 +23,6 @@ An ideal user experience is friendly, and it beckons a new user to explore the i
 
 - Overwhelm the user with too much information and cognitive load
 
-
-
 Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user’s experience, choose a safe and smart default then tuck this setting in an ``Advanced Settings`` panel.
 
 |checkmark| **Interfaces Should**
@@ -41,18 +35,13 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura
 
 - Choose intelligent defaults for settings
 
-
-
 In making software easy to use, it is crucial to be mindful of `cognitive load <https://en.wikipedia.org/wiki/Cognitive_load>`__ which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
 
-
 ----
 
-
 Easy to Understand
 ------------------
 
-
 There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims!
 
 |redx| **Avoid Acronyms**
@@ -67,8 +56,6 @@ Acronyms are compact and make good names for command line tools. They do not mak
 
 - ``NetVM`` - Networking Virtual Machine
 
-
-
 Despite this rule, some acronyms like ``USB`` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms when the full words like ``Universal Serial Bus`` are more likely to confuse users.
 
 |checkmark| **Use Simple Words**
@@ -83,12 +70,8 @@ Use the minimum amount of words needed to be descriptive, but also informative.
 
 - Use ``Networking`` or ``Networking Qube`` instead of ``NetVM`` given context
 
-
-
-
 ----
 
-
 |redx| **Avoid Technical Words**
 
 Technical words are usually more accurate, but they often *only* make sense to technical users and are confusing and unhelpful to non-technical users. Examples of technical words that might show up in Qubes OS are:
@@ -99,8 +82,6 @@ Technical words are usually more accurate, but they often *only* make sense to t
 
 - ``qrexec-daemon``
 
-
-
 These are all terms that have at some point showed up in users’ notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
 
 |checkmark| **Use Common Concepts**
@@ -113,14 +94,10 @@ Large amounts of the global population have been using computers for one or two
 
 - Use ``Qubes`` instead of ``qrexec-daemon`` as it gives better context on what is happening
 
-
-
 These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes).
 
-
 ----
 
-
 |redx| **Avoid Inconsistencies**
 
 It is easy to start abbreviating (or making acronyms) of long terms like ``Disposable Virtual Machine`` depending on where the term shows up in an interface.
@@ -131,8 +108,6 @@ It is easy to start abbreviating (or making acronyms) of long terms like ``Dispo
 
 - ``DisposableVM``
 
-
-
 This variation in terms can cause new users to question or second guess what the three different variations mean, which can lead to inaction or mistakes.
 
 |checkmark| **Make Things Consistent**
@@ -141,14 +116,10 @@ Always strive to keep things consistent in the interfaces as well as documentati
 
 - Use ``Disposable Qube`` at all times as it meets other criteria as well.
 
-
-
 By using the same term throughout an interface, a user can create a mental model and relationship with that term allowing them to feel empowered.
 
-
 ----
 
-
 |redx| **Avoid Duplicate Words**
 
 It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as:
@@ -160,8 +131,6 @@ It is easy to add words like ``Domain`` before items in a list or menu in an att
       - Domain: banking
       - Domain: personal
 
-
-
 The repeated use of the word ``Domain`` requires a user to read it for each item in the list, which makes extra work for the eye in parsing out the relevant word like ``work, banking, or personal``. This also affects horizontal space on fixed width lines.
 
 |checkmark| **Create Groups & Categories**
@@ -175,16 +144,11 @@ It is more efficient to group things under headings instead as this allows the e
       - Banking
       - Personal
 
-
-
-
 ----
 
-
 Easy To Complete
 ----------------
 
-
 Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action.
 
 |redx| **Don’t Leave Users Stranded**
@@ -195,8 +159,6 @@ Consider the following notifications:
 
 - ``There was an error saving Qube "Personal"``
 
-
-
 Instead of displaying solvable errors like these and neglecting to provide a fix:
 
 |checkmark| **Offer Actionable Solutions**
@@ -207,14 +169,10 @@ Error messages and limits such as those in the previous example can be greatly i
 
 - Add a link to a documentation page called ``Troubleshoot saving data``
 
-
-
 In adhering to these principles, you’ll make undesirable situations more manageable for users instead of feeling stranded.
 
-
 ----
 
-
 |checkmark| **Minimize Repetitive Steps**
 
 There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as:
@@ -223,26 +181,18 @@ There are many cases where a user wants to perform an action on more than one fi
 
 2. Navigate through file system
 
+   - Click Folder One
 
+   - Click Folder Two
 
-- Click Folder One
-
-- Click Folder Two
-
-- Click Folder Three
-
-- Click Folder Four
-
+   - Click Folder Three
 
+   - Click Folder Four
 
 3. Select proper file
 
 4. Complete task on file
 
-
-
-
-
 That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process:
 
 1. Click on ``Open File`` from a menu or button
@@ -253,18 +203,13 @@ That subtle act of clicking through a file system can prove to be significant if
 
 4. Complete task
 
-
-
 Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like ``Open Multiple Files`` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do!
 
-
 ----
 
-
 GNOME, KDE, and Xfce
 --------------------
 
-
 The desktop GUIs that QubesOS versions 1 - 4.1 offer are `KDE <https://kde.org>`__ and `Xfce <https://xfce.org>`__. We are currently migrating towards using `GNOME <https://www.gnome.org>`__. We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
 
 This change means you should use `GTK <https://gtk.org/>`__ rather than Qt for new GUIs.
@@ -277,16 +222,11 @@ All three of these mentioned desktop environments have their own `human interfac
 
 - `Xfce UI Guidlines <https://wiki.xfce.org/dev/hig/general>`__
 
-
-
-
 ----
 
-
 Further Learning & Inspiration
 ------------------------------
 
-
 Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources:
 
 - `Learn Design Principles <https://web.archive.org/web/20180101172357/http://learndesignprinciples.com/>`__ by Melissa Mandelbaum
@@ -301,7 +241,5 @@ Learning to make well designing intuitive interfaces and software is specialized
 
 - `Hack Design <https://hackdesign.org/>`__ - online learning program
 
-
-
 .. |checkmark| image:: /attachment/doc/checkmark.png
-.. |redx| image:: /attachment/doc/red_x.png
+.. |redx| image:: /attachment/doc/red_x.png

developer/services/admin-api.rst

@@ -75,7 +75,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      - ``<class>\n``
-     - 
+     -
    * - ``admin.vm.List``
      - ``dom0|<vm>``
      - `-`
@@ -130,7 +130,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - ``<label-index>``
      -
-   * - ``admin.label.Remove`` 
+   * - ``admin.label.Remove``
      - ``dom0``
      - label
      - `-`
@@ -187,10 +187,10 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.property.List``
      - vm
      - `-`
-     - `-` 
+     - `-`
      - ``<property>\n``
      -
-   * - ``admin.vm.property.Get`` 
+   * - ``admin.vm.property.Get``
      - vm
      - property
      - `-`
@@ -223,7 +223,7 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.property.Reset``
      - vm
      - property
-     - `-` 
+     - `-`
      - `-`
      -
    * - ``admin.vm.property.Set``
@@ -262,7 +262,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - value
      -
-   * - ``admin.vm.feature.CheckWithTemplateAndAdminVM``  
+   * - ``admin.vm.feature.CheckWithTemplateAndAdminVM``
      - vm
      - feature
      - `-`
@@ -297,7 +297,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      - ``<tag>\n``
-     - 
+     -
    * - ``admin.vm.tag.Get``
      - vm
      - tag
@@ -318,7 +318,7 @@ it easy to set the policy using current mechanism.
      -
    * - ``admin.vm.firewall.Get``
      - vm
-     - `-` 
+     - `-`
      - `-`
      - ``<rule>\n``
      - rules syntax as in :doc:`firewall interface </developer/debugging/vm-interface>` (Firewall Rules in 4x) with addition of ``expire=`` and ``comment=`` options; ``comment=`` (if present) must be the last option
@@ -363,11 +363,11 @@ it easy to set the policy using current mechanism.
      - device
      - `-`
      - `-`
-     - ``device`` is in form ``<backend-name>+<device-ident>`` 
+     - ``device`` is in form ``<backend-name>+<device-ident>``
    * - ``admin.vm.device.<class>.Set.required``
      - vm
      - device
-     - ``True|False``  
+     - ``True|False``
      - `-`
      - ``device`` is in form ``<backend-name>+<device-ident>``
    * - ``admin.vm.deviceclass.List``
@@ -430,7 +430,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      -
-   * - ``admin.pool.volume.List`` 
+   * - ``admin.pool.volume.List``
      - ``dom0``
      - pool
      - `-`
@@ -483,12 +483,12 @@ it easy to set the policy using current mechanism.
      - pool
      - vid
      - token, to be used in ``admin.pool.volume.CloneTo``
-     - obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails 
+     - obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails
    * - ``admin.pool.volume.CloneTo``
      - ``dom0``
      - pool
      - ``<vid> <token>``
-     - `-` 
+     - `-`
      - copy volume pointed by a token to volume ``vid`` in ``pool``
    * - ``admin.vm.volume.List``
      - vm
@@ -498,7 +498,7 @@ it easy to set the policy using current mechanism.
      - ``<volume>`` is per-VM volume name (``root``, ``private``, etc), ``<vid>`` is pool-unique volume id
    * - ``admin.vm.volume.Info``
      - vm
-     - volume 
+     - volume
      - `-`
      - ``<property>=<value>\n``
      -
@@ -608,7 +608,7 @@ it easy to set the policy using current mechanism.
      - ``dom0``
      - config id
      - `-`
-     - backup info 
+     - backup info
      - info what would be included in the backup
    * - ``admin.backup.Cancel``
      - ``dom0``
@@ -921,6 +921,3 @@ TODO
 -  maybe some generator for ``.desktop`` for appmenus, which would wrap
    calls in ``qrexec-client-vm``
 
-.. raw:: html
-
-   <!-- vim: set ts=4 sts=4 sw=4 et : -->

developer/services/qrexec.rst

@@ -113,7 +113,10 @@ Answering an RPC call
 ^^^^^^^^^^^^^^^^^^^^^
 
 
-In other for a RPC call to be answered in the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself – in which case it must have executable permission set (``chmod +x``): - ``/etc/qubes-rpc/RPC_ACTION_NAME`` when you make it in the template qube; - ``/usr/local/etc/qubes-rpc/RPC_ACTION_NAME`` for making it only in an app qube.
+In other for a RPC call to be answered in the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself – in which case it must have executable permission set (``chmod +x``):
+
+- ``/etc/qubes-rpc/RPC_ACTION_NAME`` when you make it in the template qube;
+- ``/usr/local/etc/qubes-rpc/RPC_ACTION_NAME`` for making it only in an app qube.
 
 The source VM name can then be accessed in the server process via ``QREXEC_REMOTE_DOMAIN`` environment variable. (Note the source VM has *no* control over the name provided in this variable–the name of the VM is provided by dom0, and so is trusted.)