git: 64328973c9 - main - Changes in FDP primer
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sun, 08 Jan 2023 14:01:09 UTC
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=64328973c9c005699fbfa7ae776486d24d00f5f0
commit 64328973c9c005699fbfa7ae776486d24d00f5f0
Author: Jethro Nederhof <jethro@jethron.id.au>
AuthorDate: 2023-01-08 13:57:23 +0000
Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
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
+<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 {