From nobody Sun Jan 08 14:01:09 2023 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Nqdys2NPvz2p3SH for ; Sun, 8 Jan 2023 14:01:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Nqdys1rLSz3v00; Sun, 8 Jan 2023 14:01:09 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1673186469; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5Mt48Y7FsyCpr9u2Gpbv1obJDisLd2zSqQdbxlJT+lU=; b=D4mozMiL5/zcuiuNltCGtP0inFKw1r9TMSND35iPdryp5uduiz0Hz0kQes/ZJoCzW1VseV 4u2Brv+g3RaR9mxzX3clhijgIrYG8bm796NYazznDqtJo6Qa9jUr8Jmy0NOEk+I/aJE3yo UVxn7aY+nA3mUJS1yBUwxKZVaPwG6bJ298Agtba2k6r2CpyjOpyOWDCsDgw7JcbAO7YMpA JJVf1jhlX0vE9ZApf0/ez9Zhbnw+R6/m3fcm/UwNUU73Mcxd/jnFsYVY4kYv8vtwpfEfNw uSCCCcyV+LSYd4HnzVfB4OPuqM96yhg21Fltwr+1TqRLpaRXgBeADvlZ0dAPNA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1673186469; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5Mt48Y7FsyCpr9u2Gpbv1obJDisLd2zSqQdbxlJT+lU=; b=qVXN2tr1CJ+mC+JmsEVuvwfRMvSuPKzO7miP4aOm3NbkRNgzOntd1PVhIwqDi98MP+6Pb/ xNwDq2UYrqUbMM8mHwT0Ky6SoR4yvbKNr5iAaj1VEpwplflLTUl+ubVJiYSX6p3PryLNUz Z02cE3RmCxhc3EFUyWpfLgAEE8XEiCFMzY2R0jah+ORhXxyD0aw8QoBImE0ZF1taznH9AB oNAXxS2GH89ZK5VI1H3sLf9CV8tvhWPVvpPF1GN9a6TOPaL0ERj12gEZuc92/vbnWk/du7 I3jaF5uH3lRbpFo6HDlN0QQeYzrEf+EFg/DRAeXotMXrOQRD/BTjjtu07+1vpg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1673186469; a=rsa-sha256; cv=none; b=YR3L4DzkeBbSoq5h/dGbH5r3z+tRYkOVqZodcNpCzWc3muqde1fdx5RcPC0/lZxfq4DU4a yuewKtfS/cV4hfxiV/NKrpj66ZMec658j/0a+hV9lQKdmK4K0kjPu/i39s2NiZpbbhHASt Q2+vCTt04IOWlLBDQeT/yC73NCds8BsnWzzecFRNkDsDcveq/YFAm1FrgMOqgtw/nZCwec dIXGsmXkTGsRNIiQ59/YH9KOUXPQL1kI5aQxh9YEx4OqQZqqW5qFSotYVGuEFdqY3OBTl4 OzxaxXxMWan4DjrXoBQs0rJWZUp1YaM6vsgdRY3QLJHp5vLHfxh/AS/R/Lihww== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Nqdys0w2rzrqW; Sun, 8 Jan 2023 14:01:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 308E19SL084733; Sun, 8 Jan 2023 14:01:09 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 308E19va084732; Sun, 8 Jan 2023 14:01:09 GMT (envelope-from git) Date: Sun, 8 Jan 2023 14:01:09 GMT Message-Id: <202301081401.308E19va084732@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: 64328973c9 - main - Changes in FDP primer List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 64328973c9c005699fbfa7ae776486d24d00f5f0 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=64328973c9c005699fbfa7ae776486d24d00f5f0 commit 64328973c9c005699fbfa7ae776486d24d00f5f0 Author: Jethro Nederhof AuthorDate: 2023-01-08 13:57:23 +0000 Commit: Sergio Carlavilla Delgado CommitDate: 2023-01-08 14:00:40 +0000 Changes in FDP primer * Minor grammar tweaks * Improvements in AsciiDoc syntax * Improvements in css code blocks * Display language on hover in code blocks * Use console instead shell in some code blocks[1] * Add link for Flycheck PR: 268764 [1] https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-highlighter/#shell-vs-console --- .../en/books/fdp-primer/editor-config/_index.adoc | 50 ++++++++++++++-------- .../en/books/fdp-primer/structure/_index.adoc | 10 ++--- .../en/books/fdp-primer/writing-style/_index.adoc | 2 +- .../themes/beastie/assets/styles/global.scss | 18 ++++++-- 4 files changed, 52 insertions(+), 28 deletions(-) diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc index 1b0797132a..1b822380ed 100644 --- a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc +++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc @@ -59,33 +59,35 @@ More advanced users can use a proper linter like link:https://github.com/dense-a === Use Manual page writers can use the following keyboard shortcuts to reformat: ++ * Press kbd:[P] to reformat paragraphs or text that has been selected in Visual mode. * Press kbd:[T] to replace groups of eight spaces with a tab. A linter named link:https://vale.sh[Vale] has been introduced to check grammatical and cosmetic errors on the documents. Vale has support for various editors and IDEs. -Install package:textproc/vale[] +Vale may already be installed as a dependency of the package:textproc/docproj[] meta-port. +If not, install package:textproc/vale[] with: -[source,shell] +[source,console] .... $ pkg install vale .... Install link:https://github.com/dense-analysis/ale[Ale] to integrate into package:editors/vim[], for using package:textproc/vale[] -[source,shell] +[source,console?prompt=%] .... % mkdir -p ~/.vim/pack/vendor/start % git clone --depth 1 https://github.com/dense-analysis/ale.git ~/.vim/pack/vendor/start/ale .... -Users who are using plugin managers for package:editors/vim[] do not need the above and should follow the instructions of the plugin manager to install link:https://github.com/dense-analysis/ale[Ale] +Users who are using plugin managers for package:editors/vim[] do not need the above and should follow the instructions of that plugin manager to install link:https://github.com/dense-analysis/ale[Ale]. -At this moment due to a bug in the link:https://vale.sh[Vale] it is necessary to copy the link:https://vale.sh[Vale] configurations to the home directory. +At this moment due to a bug in link:https://vale.sh[Vale] it is necessary to copy the link:https://vale.sh[Vale] configuration to the home directory. Considering the repository was cloned into [.filename]#~/doc# copy as following: -[source,shell] +[source,console?prompt=%] .... % cp -R ~/doc/.vale* ~/ .... @@ -95,7 +97,8 @@ Considering the repository was cloned into [.filename]#~/doc# copy as following: Edit [.filename]#~/.vimrc#, adding these lines to the end of the file: -[.programlisting] +[source.programlisting,viml] +.`~/.vimrc` .... if has("autocmd") au BufNewFile,BufRead *.adoc call Set_ADOC() @@ -179,22 +182,25 @@ Emacs's nxml-mode uses compact relax NG schemas for validating XML. A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository. To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file: +[source,xml] +.`~/.emacs.d/schema/schemas.xml` .... -locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0" - documentElement localName="section" typeId="DocBook" - documentElement localName="chapter" typeId="DocBook" - documentElement localName="article" typeId="DocBook" - documentElement localName="book" typeId="DocBook" - typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc" -locatingRules + + + + + + + .... [[editor-config-emacs-igor]] === Automated Proofreading with Flycheck and Igor -The Flycheck package is available from Milkypostman's Emacs Lisp Package Archive (MELPA). +The link:https://www.flycheck.org/[Flycheck] package is available from link:https://melpa.org/[Milkypostman's Emacs Lisp Package Archive] (MELPA). If MELPA is not already in Emacs's packages-archives, it can be added by evaluating +[source,emacs-lisp] .... (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t) .... @@ -203,12 +209,14 @@ Add the line to Emacs's initialization file (one of [.filename]#~/.emacs#, [.fil To install Flycheck, evaluate +[source,emacs-lisp] .... (package-install 'flycheck) .... Create a Flycheck checker for package:textproc/igor[] by evaluating +[source,emacs-lisp] .... (flycheck-define-checker igor "FreeBSD Documentation Project sanity checker. @@ -251,8 +259,11 @@ Install from package:editors/nano[] or package:editors/nano-devel[]. [[editor-config-nano-config]] === Configuration -Currently there is no adoc/asciidoc syntax highlight file with nano distribution. So let's create one from scratch and use an editor to create new file or add lines in the [.filename]#~/.nanorc# with these contents: +Currently there is no adoc/asciidoc syntax highlight file with nano distribution. +So let's create one from scratch and use an editor to create new file or add lines in the [.filename]#~/.nanorc# with these contents: +[source] +.`~/.nanorc` .... syntax "asciidoc" "\.(adoc|asc|asciidoc)$" # main header @@ -306,7 +317,7 @@ color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" Process the file to create embedded tabs: -[source,shell] +[source,console?prompt=%] .... % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc .... @@ -316,20 +327,21 @@ Process the file to create embedded tabs: Specify additional helpful options when running the editor: -[source,shell] +[source,console?prompt=%] .... % nano -AKipwz -T8 _index.adoc .... Users of man:csh[1] can define an alias in [.filename]#~/.cshrc# to automate these options: +[source,shell] .... alias nano "nano -AKipwz -r 70 -T8" .... After the alias is defined, the options will be added automatically: -[source,shell] +[source,console?prompt=%] .... % nano _index.adoc .... diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc index b35fb23373..25f3ad19f4 100644 --- a/documentation/content/en/books/fdp-primer/structure/_index.adoc +++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc @@ -166,17 +166,17 @@ There are a number of files and directories within the books directory, all with [[structure-document-books-physical-index]] ==== _index.adoc -The *_index.adoc* defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section. +The *_index.adoc* file defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section. [[structure-document-books-physical-book]] ==== book.adoc -The *_index.adoc* defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. +The *book.adoc* file defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. This file is used to generate the PDF with `asciidoctor-pdf` and to generate the book in one `html` page. [[structure-document-books-physical-part]] ==== part*.adoc -The *part*.adoc* files stores a brief introduction of one part of the book. +The **part*.adoc** files store a brief introduction of one part of the book. [[structure-document-handbook-physical-chapters]] ==== directory/_index.adoc @@ -185,7 +185,7 @@ Each chapter in the Handbook is stored in a file called *_index.adoc* in a separ For example, this is an example of the header of one chapter: -[.programlisting] +[source.programlisting,asciidoc] .... --- title: Chapter 8. Configuring the FreeBSD Kernel @@ -230,7 +230,7 @@ The *_index.adoc* file contains all the AsciiDoc variables and the content. For example, this is an example of one article, the structure is pretty similar to one book chapter: -[.programlisting] +[source.programlisting,asciidoc] .... --- title: Why you should use a BSD style license for your Open Source Project diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc index 215d5d30eb..95f38f0c3b 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -256,7 +256,7 @@ If a character is not on this list, ask about it on the {freebsd-doc}. [[writing-style-linting-vale]] == Linting with Vale -To maintain clarity and consistency across all documentation and website link:https://vale.sh[Vale] styles has been introduced in the documentation tree. +To maintain clarity and consistency across all documentation and website pages, link:https://vale.sh[Vale] styles have been introduced in the documentation tree. link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios. At this moment link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipeline and integrated into editor of choice. diff --git a/documentation/themes/beastie/assets/styles/global.scss b/documentation/themes/beastie/assets/styles/global.scss index fb1fc6e687..a4b4c3ced8 100644 --- a/documentation/themes/beastie/assets/styles/global.scss +++ b/documentation/themes/beastie/assets/styles/global.scss @@ -641,17 +641,29 @@ table.stretch { position: relative; } +.listingblock .title { + position: absolute; + top: -1em; + left: 1em; +} + .highlight { - padding-top: 1.5rem; - padding-bottom: 1.5rem; + padding: 1.5em 2em; code { font-size: 0.75rem; - padding: inherit; + padding: 0; border-radius: inherit; background-color: transparent; color: inherit; } + + &:hover code::before { + content: attr(data-lang); + position: absolute; + top: 0.5em; + right: 3em; + } } code {