Commit 89e2bc84 authored by Guido Gunther's avatar Guido Gunther

Merge branch 'intro-doc-style-conventions' into 'master'

Add information to documentation conventions to the introduction

See merge request Librem5/developer.puri.sm!194
parents 740e331d 9c950976
Pipeline #4071 passed with stages
in 9 minutes and 36 seconds
......@@ -11,18 +11,19 @@ focus on user privacy. Key features include:
* Separates the CPU from baseband components for additional privacy.
* Provides hardware kill switches for microphone, camera and radio components.
See the :ref:`software_reference` chapter for information about the software
components that are supplied with the phone. See the :ref:`hardware_reference`
chapter for details of the hardware used in the phone.
This document aims to provide information needed by developers who want to
This documentation aims to provide information needed by developers who want to
create applications to run on the Librem 5. It also contains information for
those interested in the underlying software platform and hardware, as well as
developers of alternative software platforms who wish to deploy those on the
phone.
See the :ref:`software_reference` chapter for information about the software
components that are supplied with the phone. See the :ref:`hardware_reference`
chapter for details of the hardware used in the phone.
.. toctree::
Introduction/Conventions
Introduction/History
.. include:: /links.txt
Document Conventions
====================
We have tried to be consistent with the way we write the documentation. To this
end, we have adopted some conventions with the styles used for different kinds
of information. We have also assumed that readers are using a GNU/Linux system
based on Debian.
Style
-----
Names of executables, files and directories are typically written in a
monospaced font. This is also the case for usernames. Here are some examples:
* ``apt`` is a tool for package management.
* ``README.md`` is a file.
* ``/boot/dtbs`` is a path to the ``dtbs`` directory.
* ``purism`` is the default user on the development board.
Command lines are written in a monospaced font and may include a shell prompt
to give context and indicate the user that is issuing commands. In this example
the ``root`` user runs the ``apt`` tool on the development board::
root@pureos:~# apt update
In some cases, the user who is issuing a command is not given because it will
depend on the configuration of your system. For example, when you install some
packages on your workstation you will usually issue a command like this::
$ sudo apt install virt-manager
In this case, we include the shell prompt. However, in some situations we may
omit the shell prompt when it is obvious that we are issuing shell commands::
sudo apt install virt-manager
Where a name of a program is used instead of the executable name, we use a
normal font. For example, we would run GNOME Builder from the command line
using the ``gnome-builder`` executable.
Distributions and Versions
--------------------------
Where we show command lines containing shell commands, the shell being used is
almost always ``bash``. Tools used on the command line are those that are
available in GNU/Linux distributions based on Debian, such as Ubuntu and
PureOS, unless we explicitly state otherwise.
In particular, any Debian packages that we mention are available in Debian
Buster. The packages available in other versions of Debian or in other
Debian-based distributions may also be usable, and we try to indicate where a
minimum version of a package is required.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment