Merge pull request #2040 from vyos/yuriy/common-references-cleanup-sagitta

docs: drop unused {include} of _include/common-references.txt from 11 sagitta MD pages + rewrap long lines

11 files changed, 109 insertions, 84 deletions

diff --git a/docs/configuration/interfaces/openvpn.md b/docs/configuration/interfaces/openvpn.md
index 926cb42c..5bd78695 100644
--- a/docs/configuration/interfaces/openvpn.md
+++ b/docs/configuration/interfaces/openvpn.md
@@ -41,14 +41,16 @@ remains a relatively obscure feature, and many router appliances
 still don't support it. However, it's very useful for quickly setting up
 tunnels between routers.
 
-As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
+As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys
+or x.509 certificates.
 
-The pre-shared key mode is deprecated and will be removed from future OpenVPN versions,
-so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys
-is significantly less secure than using TLS.
+The pre-shared key mode is deprecated and will be removed from future
+OpenVPN versions, so VyOS will have to remove support for that option as
+well. The reason is that using pre-shared keys is significantly less
+secure than using TLS.
 
-We'll configure OpenVPN using self-signed certificates, and then discuss the legacy
-pre-shared key mode.
+We'll configure OpenVPN using self-signed certificates, and then discuss
+the legacy pre-shared key mode.
 
 In both cases, we will use the following settings:
 
@@ -68,16 +70,20 @@ In both cases, we will use the following settings:
 
 ### Setting up certificates
 
-Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose
-of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity,
-compared to server setups that need to support multiple clients.
+Setting up a full-blown PKI with a CA certificate would arguably defeat
+the purpose of site-to-site OpenVPN, since its main goal is supposed to
+be configuration simplicity, compared to server setups that need to
+support multiple clients.
 
 However, since VyOS 1.4, it is possible to verify self-signed certificates using
 certificate fingerprints.
 
-On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type.
-You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode.
-Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree.
+On both sides, you need to generate a self-signed certificate,
+preferably using the "ec" (elliptic curve) type. You can generate them
+by executing command
+`run generate pki certificate self-signed install <name>` in the
+configuration mode. Once the command is complete, it will add the
+certificate to the configuration session, to the `pki` subtree.
 You can then review the proposed changes and commit them.
 
 ```none
@@ -111,15 +117,20 @@ vyos@vyos# compare
 vyos@vyos# commit
 ```
 
-You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint.
-OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command:
+You do **not** need to copy the certificate to the other router.
+Instead, you need to retrieve its SHA-256 fingerprint. OpenVPN only
+supports SHA-256 fingerprints at the moment, so you need to use the
+following command:
 
+% stop_vyoslinter
 ```none
 vyos@vyos# run show pki certificate openvpn-local fingerprint sha256
 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79
 ```
+% start_vyoslinter
 
-Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary.
+Note: certificate names don't matter, we use 'openvpn-local' and
+'openvpn-remote' but they can be arbitrary.
 
 Repeat the procedure on the other router.
 
@@ -161,12 +172,15 @@ set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint>
 
 ### Pre-shared keys
 
-Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys.
-That option is still available but it is deprecated and will be removed in the future.
-However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN,
-you need to still need to know how to use it.
+Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI
+was to use pre-shared keys. That option is still available but it is
+deprecated and will be removed in the future. However, if you need to
+set up a tunnel to an older VyOS version or a system with older
+OpenVPN, you need to still need to know how to use it.
 
-First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode.
+First, you need to generate a key by running
+`run generate pki openvpn shared-secret install <name>`
+from configuration mode.
 You can use any name, we will use `s2s`.
 
 ```none
@@ -346,9 +360,10 @@ set interfaces openvpn vtun10 persistent-tunnel
 set interfaces openvpn vtun10 protocol udp
 ```
 
-Then we need to generate, add and specify the names of the cryptographic materials.
-Each of the install command should be applied to the configuration and commited
-before using under the openvpn interface configuration.
+Then we need to generate, add and specify the names of the cryptographic
+materials. Each of the install command should be applied to the
+configuration and commited before using under the openvpn interface
+configuration.
 
 ```none
 run generate pki ca install ca-1                                # Follow the instructions to generate CA cert.
@@ -404,12 +419,13 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves:
 set protocols static route 10.23.0.0/20 interface vtun10
 ```
 
-Additionally, each client needs a copy of ca cert and its own client key and
-cert files. The files are plaintext so they may be copied either manually from the CLI.
-Client key and cert files should be signed with the proper ca cert and generated on the
-server side.
+Additionally, each client needs a copy of ca cert and its own client
+key and cert files. The files are plaintext so they may be copied
+either manually from the CLI. Client key and cert files should be
+signed with the proper ca cert and generated on the server side.
 
-HQ's router requires the following steps to generate crypto materials for the Branch 1:
+HQ's router requires the following steps to generate crypto materials
+for the Branch 1:
 
 ```none
 run generate pki certificate sign ca-1 install branch-1            # Follow the instructions to generate client
@@ -862,6 +878,3 @@ The following commands let you reset OpenVPN.
 
 
 ```
-
-```{include} /_include/common-references.txt
-```
diff --git a/docs/configuration/service/ipoe-server.md b/docs/configuration/service/ipoe-server.md
index bdb55973..f5d02e6f 100644
--- a/docs/configuration/service/ipoe-server.md
+++ b/docs/configuration/service/ipoe-server.md
@@ -275,15 +275,17 @@ the CLI configuration, refer to the explanation below.
 
 ### Allocation clients ip addresses by RADIUS
 
-If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
-address will be allocated to the client and the option `default-pool` within the CLI
-config is being ignored.
+If the RADIUS server sends the attribute `Framed-IP-Address` then this
+IP address will be allocated to the client and the option `default-pool`
+within the CLI config is being ignored.
 
-If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated
-from a predefined IP pool whose name equals the attribute value.
+If the RADIUS server sends the attribute `Framed-Pool`, IP address will
+be allocated from a predefined IP pool whose name equals the attribute
+value.
 
-If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address
-will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value.
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`,
+IPv6 address will be allocated from a predefined IPv6 pool `prefix`
+whose name equals the attribute value.
 
 If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6
 delegation pefix will be allocated from a predefined IPv6 pool `delegate`
@@ -294,8 +296,9 @@ whose name equals the attribute value.
 RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
 :::
 
-User interface can be put to VRF context via RADIUS Access-Accept packet, or change
-it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute].
+User interface can be put to VRF context via RADIUS Access-Accept
+packet, or change it via RADIUS CoA. `Accel-VRF-Name` is used for
+these purposes. It is custom [ACCEL-PPP attribute].
 Define it in your RADIUS server.
 
 ## IPv6
@@ -524,8 +527,8 @@ Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started
 Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>]
 ```
 
-```{include} /_include/common-references.txt
-```
 
+% stop_vyoslinter
 [accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
 [dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
+% start_vyoslinter
diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md
index d0c72f00..1dc6be3c 100644
--- a/docs/configuration/service/pppoe-server.md
+++ b/docs/configuration/service/pppoe-server.md
@@ -782,8 +782,8 @@ vyos@pppoe-server:~$ sh pppoe-server sessions
  ppp0   | test     | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb |            | active | 00:00:49 | 875 B    | 2.1 KiB
 ```
 
-```{include} /_include/common-references.txt
-```
 
+% stop_vyoslinter
 [accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
 [dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
+% start_vyoslinter
diff --git a/docs/configuration/system/lcd.md b/docs/configuration/system/lcd.md
index c857ae34..1956c73b 100644
--- a/docs/configuration/system/lcd.md
+++ b/docs/configuration/system/lcd.md
@@ -41,6 +41,3 @@ connectivity of the display to your system. This can be any serial port
    .. note:: We can't support all displays from the beginning. If your display
       type is missing, please create a feature request via Phabricator_.
 ```
-
-```{include} /_include/common-references.txt
-```
diff --git a/docs/configuration/vpn/sstp.md b/docs/configuration/vpn/sstp.md
index 3574a904..28520e20 100644
--- a/docs/configuration/vpn/sstp.md
+++ b/docs/configuration/vpn/sstp.md
@@ -21,7 +21,8 @@ certificates or private PKI is required.
 
 ### Certificates
 
-Using our documentation chapter - {ref}`pki` generate and install CA and Server certificate
+Using our documentation chapter - {ref}`pki` generate and install CA
+and Server certificate
 
 ```none
 vyos@vyos:~$ generate pki ca install CA
@@ -598,7 +599,8 @@ Once you have setup your SSTP server there comes the time to do some basic
 testing. The Linux client used for testing is called [sstpc]. [sstpc] requires a
 PPP configuration/peer file.
 
-If you use a self-signed certificate, do not forget to install CA on the client side.
+If you use a self-signed certificate, do not forget to install CA on
+the client side.
 
 The following PPP configuration tests MSCHAP-v2:
 
@@ -757,9 +759,9 @@ Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0'
 Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started
 ```
 
-```{include} /_include/common-references.txt
-```
 
+% stop_vyoslinter
 [accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
 [dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
 [sstpc]: https://github.com/reliablehosting/sstp-client
+% start_vyoslinter
diff --git a/docs/configuration/vrf/index.md b/docs/configuration/vrf/index.md
index b0c86bda..a9100ada 100644
--- a/docs/configuration/vrf/index.md
+++ b/docs/configuration/vrf/index.md
@@ -71,9 +71,10 @@ can be used to filter which routes zebra will install in the kernel.
 
 ### Nexthop Tracking
 
-Nexthop tracking resolve nexthops via the default route by default. This is enabled
-by default for a traditional profile of FRR which we use. It and can be disabled if
-you do not wan't to e.g. allow BGP to peer across the default route.
+Nexthop tracking resolve nexthops via the default route by default.
+This is enabled by default for a traditional profile of FRR which we
+use. It can be disabled if you do not want to e.g. allow BGP to
+peer across the default route.
 
 ```{eval-rst}
 .. cfgcmd:: set vrf name <name> ip nht no-resolve-via-default
@@ -288,6 +289,7 @@ VRF route leaking
 
 #### Configuration
 
+% stop_vyoslinter
 > ```none
 > set interfaces bridge br10 address '10.30.0.254/24'
 > set interfaces bridge br10 member interface eth3
@@ -314,6 +316,7 @@ VRF route leaking
 > set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default'
 > set vrf name red table '2000'
 > ```
+% start_vyoslinter
 
 ### VRF and NAT
 
@@ -321,6 +324,7 @@ VRF route leaking
 
 #### Configuration
 
+% stop_vyoslinter
 > ```none
 > set interfaces ethernet eth0 address '172.16.50.12/24'
 > set interfaces ethernet eth0 vrf 'red'
@@ -350,6 +354,7 @@ VRF route leaking
 > set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue'
 > set vrf name red table '2020'
 > ```
+% start_vyoslinter
 
 (vrf-example-operation)=
 
@@ -378,6 +383,7 @@ installed, and try to ICMP ping PC1 from PC3.
 
 ##### VRF default routing table
 
+% stop_vyoslinter
 > ```none
 > vyos@R1:~$ show ip route
 > Codes: K - kernel route, C - connected, S - static, R - RIP,
@@ -390,9 +396,11 @@ installed, and try to ICMP ping PC1 from PC3.
 > S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38
 > S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38
 > ```
+% start_vyoslinter
 
 ##### VRF red routing table
 
+% stop_vyoslinter
 > ```none
 > vyos@R1:~$ show ip route vrf red
 > Codes: K - kernel route, C - connected, S - static, R - RIP,
@@ -406,9 +414,11 @@ installed, and try to ICMP ping PC1 from PC3.
 > S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40
 > C>* 10.30.0.0/24 is directly connected, br10, 00:07:54
 > ```
+% start_vyoslinter
 
 ##### VRF blue routing table
 
+% stop_vyoslinter
 > ```none
 > vyos@R1:~$ show ip route vrf blue
 > Codes: K - kernel route, C - connected, S - static, R - RIP,
@@ -422,6 +432,7 @@ installed, and try to ICMP ping PC1 from PC3.
 > S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44
 > C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53
 > ```
+% start_vyoslinter
 
 # L3VPN VRFs
 
@@ -596,6 +607,3 @@ are in place.
     10.0.0.7        4      65001      2860      2870        0    0    0 1d23h34m            2       10
 
 ```
-
-```{include} /_include/common-references.txt
-```
diff --git a/docs/contributing/debugging.md b/docs/contributing/debugging.md
index 73b622c6..4671c748 100644
--- a/docs/contributing/debugging.md
+++ b/docs/contributing/debugging.md
@@ -183,9 +183,7 @@ you can use the `/opt/vyatta/sbin/priority.pl` script which lists to you
 the execution order of the scripts.
 
 
-```{include} /_include/common-references.txt
-```
-
-
+% stop_vyoslinter
 [bootchart.conf]: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf
+% start_vyoslinter
 [vyatta-cfg]: https://github.com/vyos/vyatta-cfg
diff --git a/docs/contributing/development.md b/docs/contributing/development.md
index dcfe257a..42a1bb97 100644
--- a/docs/contributing/development.md
+++ b/docs/contributing/development.md
@@ -99,7 +99,8 @@ It is also worth reading <https://chris.beams.io/posts/git-commit/>
 
 Limits:
 
-- We only accept bugfixes in packages other than <https://github.com/vyos/vyos-1x>
+- We only accept bugfixes in packages other than
+  <https://github.com/vyos/vyos-1x>
   as no new functionality should use the old style templates (`node.def` and
   Perl/BASH code. Use the new style XML/Python interface instead.
 
@@ -158,8 +159,8 @@ record them in your created Git commit:
 
 Follow the above steps on how to "Fork repository to submit a Patch". Instead
 of uploading "pushing" your changes to GitHub you can export the patches/
-commits and send it to <mailto:maintainers@vyos.net> or attach it directly to the bug
-(preferred over email)
+commits and send it to <mailto:maintainers@vyos.net> or attach it
+directly to the bug (preferred over email)
 
 - Export last commit to patch file: `git format-patch` or export the last two
   commits into its appropriate patch files: `git format-patch -2`
@@ -651,6 +652,7 @@ C++ backend library \[vyatta-cfg\](<https://github.com/vyos/vyatta-cfg>). This
 section is a reference of common CLI commands and the respective entry point
 in the C/C++ code.
 
+% stop_vyoslinter
 - `set`
 
   - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352>
@@ -659,6 +661,7 @@ in the C/C++ code.
 - `commit`
 
   - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252>
+% start_vyoslinter
 
 ## Continuous Integration
 
@@ -678,17 +681,19 @@ to our Debian repository which is used during build time. It is located here:
 <http://dev.packages.vyos.net/repositories/>.
 
 
-```{include} /_include/common-references.txt
-```
-
-
 [dockerhub]: https://hub.docker.com/u/vyos/
+% stop_vyoslinter
 [ipv4, ipv6]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i
 [ipv4, ipv6 and dhcp(v6)]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i
+% start_vyoslinter
 [jenkins]: https://jenkins.io/
 [jinja2]: https://jinja.palletsprojects.com/
+% stop_vyoslinter
 [mac address]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/mac.xml.i
+% start_vyoslinter
 [process]: https://blog.vyos.io/vyos-development-digest-10
+% stop_vyoslinter
 [vlan (vif)]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/vif.xml.i
+% start_vyoslinter
 [vyconf]: https://github.com/vyos/vyconf/tree/master/data/schemata
 [vyos-1x]: https://github.com/vyos/vyos-1x/tree/current/schema
diff --git a/docs/contributing/issues-features.md b/docs/contributing/issues-features.md
index 6a748f36..7c5d52cb 100644
--- a/docs/contributing/issues-features.md
+++ b/docs/contributing/issues-features.md
@@ -65,8 +65,6 @@ please search [Phabricator] if there is already a request pending. You can
 enhance it or if you don't find one, create a new one by use the quick link in
 the left side under the specific project.
 
-```{include} /_include/common-references.txt
-```
 
 [documentation]: https://docs.vyos.io
 [forum]: https://forum.vyos.io
diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md
index b2929936..5ef8b919 100644
--- a/docs/contributing/testing.md
+++ b/docs/contributing/testing.md
@@ -155,8 +155,9 @@ as member ports.
 
 ## Config Load Tests
 
-The other part of our tests are called "config load tests". The config load tests
-will load - one after another - arbitrary configuration files to test if the
+The other part of our tests are called "config load tests". The config
+load tests will load - one after another - arbitrary configuration
+files to test if the
 configuration migration scripts work as designed and that a given set of
 functionality still can be loaded with a fresh VyOS ISO image.
 
@@ -165,8 +166,9 @@ as a testcase but also as reference if one wants to enable a certain feature.
 The configurations can be found here:
 <https://github.com/vyos/vyos-1x/tree/current/smoketest/configs>
 
-The entire test is controlled by the main wrapper script `/usr/bin/vyos-configtest`
-which behaves in the same way as the main smoketest script. It scans the folder
+The entire test is controlled by the main wrapper script
+`/usr/bin/vyos-configtest` which behaves in the same way as the main
+smoketest script. It scans the folder
 for potential configuration files and issues a `load` command one after another.
 
 ### Manual config load test
@@ -209,6 +211,3 @@ can be applied - you will get a commit error otherwise. If you are interested
 how those preconditions are fulfilled check the [vyos-build] repository and
 the `scripts/check-qemu-install` file.
 :::
-
-```{include} /_include/common-references.txt
-```
diff --git a/docs/documentation.md b/docs/documentation.md
index 9493f807..0f6ff1be 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -45,7 +45,8 @@ The following is a quick summary of the rules:
   your text through a grammar and spell checker, such as [Grammarly].
 - Don't forget to update `index.rst` when adding a new node.
 - Try not to exceed 80 characters per line, but don't break URLs over this.
-- Properly quote commands, filenames and brief code snippets with double backticks.
+- Properly quote commands, filenames and brief code snippets with
+  double backticks.
 - Use literal blocks for longer snippets.
 - Leave a newline before and after a header.
 - Indent with two spaces.
@@ -89,8 +90,9 @@ pull-request. This requires you already have a GitHub account.
 - Make all your changes - please keep our commit rules in mind
   ({ref}`prepare_commit`). This mainly applies to proper commit messages
   describing your change (how and why). Please check out the documentation of
-  [Sphinx-doc] or [reStructuredText] if you are not familiar with it. This is used
-  for writing our docs. Additional directives how to write in RST can be
+  [Sphinx-doc] or [reStructuredText] if you are not familiar with it.
+  This is used for writing our docs. Additional directives how to
+  write in RST can be
   obtained from [reStructuredTextDirectives].
 
 - Check your changes by locally building the documentation `$ make livehtml`.
@@ -418,13 +420,13 @@ Anything else that is not a configuration or an operation command has no
 predefined structure.
 
 
-```{include} /_include/common-references.txt
-```
-
-
+% stop_vyoslinter
 [dockerfile]: https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile
+% start_vyoslinter
 [grammarly]: https://www.grammarly.com/
 [readme.md]: https://github.com/vyos/vyos-documentation/blob/master/README.md
+% stop_vyoslinter
 [restructuredtext]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 [restructuredtextdirectives]: https://docutils.sourceforge.io/docs/ref/rst/directives.html
+% start_vyoslinter
 [sphinx-doc]: https://www.sphinx-doc.org