Skip to content

Commit

Permalink
docs: remove line block markup (#2729)
Browse files Browse the repository at this point in the history 
I don't see a point in using [line blocks][1] anywhere in the
documentation. Note that mandoc consequently renders it with a `<pre>`
tag which looks ugly on [man.archlinux.org][2].

Also simplified the URL in `index.rst` which can be written verbatim
without any special markup.

See this [archmanweb issue][3] for details.

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
[2]: https://man.archlinux.org/man/archinstall.1
[3]: https://gitlab.archlinux.org/archlinux/archmanweb/-/issues/49#note_213730

Co-authored-by: Jakub Klinkovský <[email protected]>
  • Loading branch information
@lahwaacz
lahwaacz and lahwaacz authored Oct 13, 2024
1 parent e452804 commit fa0cd4f
Show file tree
Hide file tree
Showing 7 changed files with 39 additions and 39 deletions.
10 changes: 5 additions & 5 deletions docs/cli_parameters/config/custom_commands.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Custom Commands
===============

| Custom commands is a configuration entry that allows for executing custom commands post-installation.
| The commands are executed with `arch-chroot <https://man.archlinux.org/man/extra/arch-install-scripts/arch-chroot.8.en>`_.
Custom commands is a configuration entry that allows for executing custom commands post-installation.
The commands are executed with `arch-chroot <https://man.archlinux.org/man/extra/arch-install-scripts/arch-chroot.8.en>`_.

The option takes a list of arguments, an example is:

Expand All @@ -16,7 +16,7 @@ The option takes a list of arguments, an example is:
]
}
| The following example will set a new hostname in the installed system.
| The example is just to illustrate that the command is not run in the ISO but inside the installed system after the base system is installed.
The following example will set a new hostname in the installed system.
The example is just to illustrate that the command is not run in the ISO but inside the installed system after the base system is installed.

More examples can be found in the code repository under `examples/ <https://github.com/archlinux/archinstall/tree/e6344f93f7e476d05bbcd642f2ed91fdde545870/examples>`_
More examples can be found in the code repository under `examples/ <https://github.com/archlinux/archinstall/tree/e6344f93f7e476d05bbcd642f2ed91fdde545870/examples>`_
4 changes: 2 additions & 2 deletions docs/help/discord.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ Discord

There's a discord channel which is frequented by some `contributors <https://github.com/archlinux/archinstall/graphs/contributors>`_.

| To join the server, head over to `https://discord.gg/cqXU88y <https://discord.gg/cqXU88y>`_ and join in.
| There's not many rules other than common sense and to treat others with respect. The general chat is for off-topic things as well.
To join the server, head over to `https://discord.gg/cqXU88y <https://discord.gg/cqXU88y>`_ and join in.
There's not many rules other than common sense and to treat others with respect. The general chat is for off-topic things as well.

There's the ``@Party Animals`` role if you want notifications of new releases which is posted in the ``#Release Party`` channel.
Another thing is the ``@Contributors`` role can be activated by contributors by writing ``!verify`` and follow the verification process.
Expand Down
42 changes: 21 additions & 21 deletions docs/help/known_issues.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,17 @@
Known Issues
============

| Some issues are out of the `archinstall`_ projects scope, and the ones we know of are listed below.
Some issues are out of the `archinstall`_ projects scope, and the ones we know of are listed below.

.. _waiting for time sync:

Waiting for time sync `#2144`_
------------------------------

| The usual root cause of this is the network topology.
| More specifically `timedatectl show`_ cannot perform a proper time sync against the default servers.
The usual root cause of this is the network topology.
More specifically `timedatectl show`_ cannot perform a proper time sync against the default servers.

| Restarting ``systemd-timesyncd.service`` might work but most often you need to configure ``/etc/systemd/timesyncd.conf`` to match your network design.
Restarting ``systemd-timesyncd.service`` might work but most often you need to configure ``/etc/systemd/timesyncd.conf`` to match your network design.

.. note::

Expand All @@ -22,34 +22,34 @@ Waiting for time sync `#2144`_
Missing Nvidia Proprietary Driver `#2002`_
------------------------------------------

| In some instances, the nvidia driver might not have all the necessary packages installed.
| This is due to the kernel selection and/or hardware setups requiring additional packages to work properly.
In some instances, the nvidia driver might not have all the necessary packages installed.
This is due to the kernel selection and/or hardware setups requiring additional packages to work properly.

A common workaround is to install the package `linux-headers`_ and `nvidia-dkms`_

ARM, 32bit and other CPU types error out `#1686`_, `#2185`_
-----------------------------------------------------------

| This is a bit of a catch-all known issue.
| Officially `x86_64`_ is only supported by Arch Linux.
| Hence little effort have been put into supporting other platforms.
This is a bit of a catch-all known issue.
Officially `x86_64`_ is only supported by Arch Linux.
Hence little effort have been put into supporting other platforms.

| In theory, other architectures should work but small quirks might arise.
In theory, other architectures should work but small quirks might arise.

| PR's are welcome but please be respectful of the delays in merging.
| Other fixes, issues or features will be prioritized for the above reasons.
PR's are welcome but please be respectful of the delays in merging.
Other fixes, issues or features will be prioritized for the above reasons.

Keyring is out of date `#2213`_
-------------------------------

| Missing key-issues tend to be that the `archlinux-keyring`_ package is out of date, usually as a result of an outdated ISO.
| There is an attempt from upstream to fix this issue, and it's the `archlinux-keyring-wkd-sync.service`_
Missing key-issues tend to be that the `archlinux-keyring`_ package is out of date, usually as a result of an outdated ISO.
There is an attempt from upstream to fix this issue, and it's the `archlinux-keyring-wkd-sync.service`_

| The service starts almost immediately during boot, and if network is not configured in time — the service will fail.
| Subsequently the ``archinstall`` run might operate on a old keyring despite there being an update service for this.
The service starts almost immediately during boot, and if network is not configured in time — the service will fail.
Subsequently the ``archinstall`` run might operate on a old keyring despite there being an update service for this.

| There is really no way to reliably over time work around this issue in ``archinstall``.
| Instead, efforts to the upstream service should be considered the way forward. And/or keys not expiring between a sane amount of ISO's.
There is really no way to reliably over time work around this issue in ``archinstall``.
Instead, efforts to the upstream service should be considered the way forward. And/or keys not expiring between a sane amount of ISO's.

.. note::

Expand All @@ -62,10 +62,10 @@ Keyring is out of date `#2213`_
AUR packages
------------

| This is also a catch-all issue.
| `AUR is unsupported <https://wiki.archlinux.org/title/Arch_User_Repository#Updating_packages>`_, and until that changes we cannot use AUR packages to solve feature requests in ``archinstall``.
This is also a catch-all issue.
`AUR is unsupported <https://wiki.archlinux.org/title/Arch_User_Repository#Updating_packages>`_, and until that changes we cannot use AUR packages to solve feature requests in ``archinstall``.

| This means that feature requests like supporting filesystems such as `ZFS`_ can not be added, and issues cannot be solved by using AUR packages either.
This means that feature requests like supporting filesystems such as `ZFS`_ can not be added, and issues cannot be solved by using AUR packages either.

.. note::

Expand Down
6 changes: 3 additions & 3 deletions docs/help/report_bug.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ For quick issues or if you need help, head over to the Discord server which has
Log files
---------

| When submitting a help ticket, please include the :code:`/var/log/archinstall/install.log`.
| It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in.
When submitting a help ticket, please include the :code:`/var/log/archinstall/install.log`.
It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in.

.. tip::
| An easy way to submit logs is ``curl -F'file=@/var/log/archinstall/install.log' https://0x0.st``.
| Use caution when submitting other log files, but ``archinstall`` pledges to keep ``install.log`` safe for posting publicly!
| There are additional log files under ``/var/log/archinstall/`` that can be useful:
There are additional log files under ``/var/log/archinstall/`` that can be useful:

- ``/var/log/archinstall/user_configuration.json`` - Stores most of the guided answers in the installer
- ``/var/log/archinstall/user_credentials.json`` - Stores any usernames or passwords, can be passed to ``--creds``
Expand Down
8 changes: 4 additions & 4 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
archinstall Documentation
=========================

| **archinstall** is library which can be used to install Arch Linux.
| The library comes packaged with different pre-configured installers, such as the default :ref:`guided` installer.
|
| A demo of the :ref:`guided` installer can be seen here: `https://www.youtube.com/watch?v=9Xt7X_Iqg6E <https://www.youtube.com/watch?v=9Xt7X_Iqg6E>`_.
**archinstall** is library which can be used to install Arch Linux.
The library comes packaged with different pre-configured installers, such as the default :ref:`guided` installer.

A demo of the :ref:`guided` installer can be seen here: https://www.youtube.com/watch?v=9Xt7X_Iqg6E.

Some of the features of Archinstall are:

Expand Down
4 changes: 2 additions & 2 deletions docs/installing/guided.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,8 +238,8 @@ The contents of :code:`https://domain.lan/config.json`:
Options for ``--creds``
-----------------------

| Creds is a separate configuration file to separate normal options from more sensitive data like passwords.
| Below is an example of how to set the root password and below that are description of other values that can be set.
Creds is a separate configuration file to separate normal options from more sensitive data like passwords.
Below is an example of how to set the root password and below that are description of other values that can be set.

.. code-block:: json
Expand Down
4 changes: 2 additions & 2 deletions docs/installing/python.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ The basic concept of PyPI applies using `pip`.
Install using source code
-------------------------

| You can also install using the source code.
| For sake of simplicity we will use ``git clone`` in this example.
You can also install using the source code.
For sake of simplicity we will use ``git clone`` in this example.

.. code-block:: console
Expand Down

0 comments on commit fa0cd4f

Please sign in to comment.