From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=-1.8 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_LOW,SPF_HELO_PASS, T_SCC_BODY_TEXT_LINE,WEIRD_PORT autolearn=unavailable autolearn_force=no version=3.4.6 Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 39EACBC7A8; Sat, 27 May 2023 15:12:27 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id E1F0DBC7A3; Sat, 27 May 2023 15:12:24 +0000 (UTC) Received: from out5-smtp.messagingengine.com (out5-smtp.messagingengine.com [66.111.4.29]) by atuin.qyliss.net (Postfix) with ESMTPS id C2B4BBC7A2 for ; Sat, 27 May 2023 15:12:22 +0000 (UTC) Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id 2EAD85C00C6; Sat, 27 May 2023 11:12:22 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Sat, 27 May 2023 11:12:22 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=alyssa.is; h=cc :cc:content-transfer-encoding:content-type:content-type:date :date:from:from:in-reply-to:message-id:mime-version:reply-to :sender:subject:subject:to:to; s=fm3; t=1685200342; x= 1685286742; bh=oB8rG3azkLPeX3JHSMnB2Y0Mn6zNQGInKmnD4+aNsng=; b=n aQbM+lut6LWSYve9TOIzAZQ5mDzzw/lnuilanVJpV/c4jULY+30anQBPU/FdhiRX ZLRZwY/eEcNhN4atrONd3/eYSnI55VgVNRm1ypwBpVp/Pw4UNFS5Gz1MDbCM+f+Z 9J8oZlsUOpIBN3a0XuZWNbJ3JxXx1BGnK3o5wz/qdWUZgmAOLwsdcmZg5ZZAaBSq dw10oBWJ708CzkpJ6dWGHvq8hZCBm5r3QSfh3/Tscus/A9NHiVtJ2b4tF8UQCfej sz2vPInOD8t0A24GBj/xVsAJrySfDNDSrLjqBDrqjW0D4o+CU1B2At+GiQtdzyeT +rDYdWBrkr2k9CshrWsXw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-transfer-encoding :content-type:content-type:date:date:feedback-id:feedback-id :from:from:in-reply-to:message-id:mime-version:reply-to:sender :subject:subject:to:to:x-me-proxy:x-me-proxy:x-me-sender :x-me-sender:x-sasl-enc; s=fm1; t=1685200342; x=1685286742; bh=o B8rG3azkLPeX3JHSMnB2Y0Mn6zNQGInKmnD4+aNsng=; b=s6bqh7F84GwBgE+6X ziI6+LQEbWAIGCm6bXiJ6S5yEpCPGcZOaxcvJpF/aC/Goyq776hHGi4lh06/Ji3g XbXy6eIBggoYwAoNy67/l3Wm3fSK9tb1Pg7zVpTqiUCZdLdEcQjD80QKb0vYrMR3 37Hq4/ahGWbukBBSwxF/mgt0k7icZBogcYkjbPX7Nzj+URSiHfAtrF+zVa23KcBL 6DwHRdTKf9QnTPezXk84a9xmzlnLXgWl+CttruSxf8t70uRX1N4mHHfqagDtwkgS hGaDdtrdkSpRtD53Wlad5uRghwdqzmh03gf77cUK+US9bpZdBIlLfOvPQT8BWI98 7NOIQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrfeekuddgkeehucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne gfrhhlucfvnfffucdluddumdenucfjughrpefhvfevufffkffogggtgfesthekredtredt jeenucfhrhhomheptehlhihsshgrucftohhsshcuoehhihesrghlhihsshgrrdhisheqne cuggftrfgrthhtvghrnhepfeeikeeuvedvveeutddtheehjeeuheefvdduhfeifeetuefg hfekfedtveevfeegnecuffhomhgrihhnpehsphgvtghtrhhumhdqohhsrdhorhhgpdhlih gsvghrrgdrtghhrghtpdhmrghtrhhigidrohhrghdpmhgrthhrihigrdhtohdpnhhigiho shdrohhrghdpghhithhhuhgsrdgtohhmpdgrshgtihhiughotghtohhrrdhorhhgnecuve hluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhephhhisegrlhih shhsrgdrihhs X-ME-Proxy: Feedback-ID: i12284293:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Sat, 27 May 2023 11:12:21 -0400 (EDT) Received: by x220.qyliss.net (Postfix, from userid 1000) id BA1DC54B8; Sat, 27 May 2023 15:12:20 +0000 (UTC) From: Alyssa Ross To: devel@spectrum-os.org Subject: [PATCH v2] Documentation: fix accidental anchor links Date: Sat, 27 May 2023 15:11:53 +0000 Message-Id: <20230527151152.2016164-1-hi@alyssa.is> X-Mailer: git-send-email 2.37.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Message-ID-Hash: OXIN54KXD42ZDVJ3YAYGFW5KE7TJUGFN X-Message-ID-Hash: OXIN54KXD42ZDVJ3YAYGFW5KE7TJUGFN X-MailFrom: hi@alyssa.is X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-devel.spectrum-os.org-0; header-match-devel.spectrum-os.org-1; header-match-devel.spectrum-os.org-2; header-match-devel.spectrum-os.org-3; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Ryan Lahfa X-Mailman-Version: 3.3.5 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: The xref macro is for cross references to internal links within the documentation, not external links. xref:https://… results in an anchor link. The existing doc-links test didn't catch this, because it operates at the HTTP level. But the problem is easy to spot in the sources, so I've added a new check that just greps for this pattern. Reported-by: Ryan Lahfa Fixes: 97cceff ("Documentation: add contributing information") Signed-off-by: Alyssa Ross --- v1: https://spectrum-os.org/lists/archives/spectrum-devel/20230527151106.2015901-1-hi@alyssa.is/ doc-anchors.nix didn't actually ever succeed in v1, oops. Documentation/contributing/communication.adoc | 26 +++++++++---------- Documentation/contributing/index.adoc | 2 +- .../contributing/writing_documentation.adoc | 18 ++++++------- release/checks/default.nix | 2 ++ release/checks/doc-anchors.nix | 12 +++++++++ 5 files changed, 37 insertions(+), 23 deletions(-) create mode 100644 release/checks/doc-anchors.nix diff --git a/Documentation/contributing/communication.adoc b/Documentation/contributing/communication.adoc index 506fa28..8288c99 100644 --- a/Documentation/contributing/communication.adoc +++ b/Documentation/contributing/communication.adoc @@ -27,17 +27,17 @@ Spectrum's developers, subscribe to *announce@spectrum-os.org*. You can discuss Spectrum and related topics in real time on IRC, or more long-form on spectrum-announce (_discuss@spectrum-os.org_). Finally, development work happens in Spectrum's -xref:https://spectrum-os.org/git/[source repositories], and is -discussed on spectrum-devel (_devel@spectrum-os.org_). +https://spectrum-os.org/git/[source repositories], and is discussed on +spectrum-devel (_devel@spectrum-os.org_). == Internet Relay Chat There is a single Internet Relay Chat (IRC) channel, -xref:ircs://irc.libera.chat:6697/spectrum[#spectrum] -on xref:https://libera.chat/[Libera.Chat], for all kinds of Spectrum -discussions. You can also join through xref:https://matrix.org/[Matrix] as -xref:https://matrix.to/#/#spectrum:libera.chat[#spectrum:libera.chat]. +link:ircs://irc.libera.chat:6697/spectrum[#spectrum] on +https://libera.chat/[Libera.Chat], for all kinds of Spectrum +discussions. You can also join through https://matrix.org/[Matrix] as +https://matrix.to/#/#spectrum:libera.chat[#spectrum:libera.chat]. If you are new to IRC, you might find Matrix the easiest way to get started. The channel is *logged*, but the logs are not available online yet. @@ -49,11 +49,11 @@ following along with it, the best thing to do is subscribe to one or more of the Spectrum mailing lists. If mailing lists are not your thing, that is okay! Try the -xref:https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows -you to interact with the mailing lists much like a modern web forum. +https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows you to +interact with the mailing lists much like a modern web forum. -Each list has xref:https://spectrum-os.org/lists/archives/[archives] -that can also be accessed via the web, NNTP or Atom. You are strongly +Each list has https://spectrum-os.org/lists/archives/[archives] that +can also be accessed via the web, NNTP or Atom. You are strongly encouraged to mirror them. [cols="1,1"] @@ -64,14 +64,14 @@ encouraged to mirror them. from Spectrum's developers will be posted. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web], +https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web], or by sending mail to *announce-subscribe@spectrum-os.org*. |discuss@spectrum-os.org |This list contains high-level discussion about the project. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web], +https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web], or by sending mail to *discuss-subscribe@spectrum-os.org*. |devel@spectrum-os.org @@ -84,6 +84,6 @@ For more information, see xref:working-with-patches.adoc[Working with Patches]. You can subscribe -xref:https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. +https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. |=== diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc index 48255d8..03eac68 100644 --- a/Documentation/contributing/index.adoc +++ b/Documentation/contributing/index.adoc @@ -48,7 +48,7 @@ There is also a web interface https://spectrum-os.org/lists/hyperkitty/ that you can use to browse or even post to the mailing list. Add a Signed-off-by line to each patch you submit, to indicate your -certification of the xref:https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch. +certification of the https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch. The easiest way to do this is with `git commit's -s` flag. Do not be too afraid of getting it wrong the first couple of times. diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc index f8a69ef..cb09241 100644 --- a/Documentation/contributing/writing_documentation.adoc +++ b/Documentation/contributing/writing_documentation.adoc @@ -11,11 +11,11 @@ formatting, and organizing the Spectrum documentation. Please follow these guidelines and conventions when editing the documentation. -We use xref:https://nixos.org/manual/nix/stable/introduction.html[Nix] -and xref:https://github.com/just-the-docs/just-the-docs[Just the Docs] -for building the documentation. Sources are written in AsciiDoc -If you are new with it, -see xref:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]. +We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and +https://github.com/just-the-docs/just-the-docs[Just the Docs] for +building the documentation. Sources are written in AsciiDoc If you are +new with it, see +https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]. If you want to test your changes, see xref:../contributing/building-documentation.adoc[Building Documentation]. @@ -38,7 +38,7 @@ to suit your changing needs. == Document Layout -* xref:https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]: +* https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]: include your name and a revision line following the author line. Example: = Document Title @@ -64,15 +64,15 @@ abbreviations are used. ** Keep text hard-wrapped at 70-80 characters. (Most editors should be able to do this automatically.) This makes it easier to pick out specific parts in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.) -** Keep the text in the description attribute hard-wrapped as well. For more information, see the xref:https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs. +** Keep the text in the description attribute hard-wrapped as well. For more information, see the https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs. -* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see xref:https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices]. +* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices]. == Structure * Use subheading to organize information. * One topic per article. -* To make accents, use xref:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions]. +* To make accents, use https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions]. * Use numbered lists for actions that happen in sequence. * Do not use parenthesis for additional information, make a separate sentence instead. diff --git a/release/checks/default.nix b/release/checks/default.nix index f8a3f9b..100de9a 100644 --- a/release/checks/default.nix +++ b/release/checks/default.nix @@ -8,6 +8,8 @@ import ../../lib/eval-config.nix ({ ... } @ args: doc-links = import ./doc-links.nix args; + doc-anchors = import ./doc-anchors.nix args; + pkg-tests = import ./pkg-tests.nix args; reuse = import ./reuse.nix args; diff --git a/release/checks/doc-anchors.nix b/release/checks/doc-anchors.nix new file mode 100644 index 0000000..1fae7e3 --- /dev/null +++ b/release/checks/doc-anchors.nix @@ -0,0 +1,12 @@ +# SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: 2023 Alyssa Ross + +import ../../lib/eval-config.nix ({ config, ... }: +config.pkgs.callPackage ({ runCommand }: + +runCommand "spectrum-doc-anchors" {} '' + cd ${(import ../../Documentation { inherit config; }).src} + ! grep --color=always -r xref:http + touch $out +'' +) { }) base-commit: 1c6893145bdf023cd03b7675a18749ce8ed3803f -- 2.37.1