diff options
| author | Dan Allen <dan.j.allen@gmail.com> | 2021-09-19 23:53:50 -0600 |
|---|---|---|
| committer | Dan Allen <dan.j.allen@gmail.com> | 2021-09-20 01:34:02 -0600 |
| commit | 32b817a035e474e308b31e4be4da1078af4ca74c (patch) | |
| tree | 455e0c522e7f71b6c73dd5dad0a1b39b3a920126 /docs/modules | |
| parent | 8ba4e568b45540942c3c7e32585f572444b819c1 (diff) | |
replace the term tag with element to refer to an element node in HTML or XML
Diffstat (limited to 'docs/modules')
| -rw-r--r-- | docs/modules/ROOT/pages/docinfo.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/whats-new.adoc | 6 | ||||
| -rw-r--r-- | docs/modules/html-backend/pages/default-stylesheet.adoc | 8 | ||||
| -rw-r--r-- | docs/modules/html-backend/pages/favicon.adoc | 4 | ||||
| -rw-r--r-- | docs/modules/html-backend/pages/stylesheet-modes.adoc | 12 | ||||
| -rw-r--r-- | docs/modules/syntax-highlighting/pages/index.adoc | 4 |
6 files changed, 19 insertions, 17 deletions
diff --git a/docs/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc index fd355a8a..e0fa6a9d 100644 --- a/docs/modules/ROOT/pages/docinfo.adoc +++ b/docs/modules/ROOT/pages/docinfo.adoc @@ -30,7 +30,7 @@ The docinfo file for HTML output may contain valid elements to populate the HTML CAUTION: Use of the `<title>` element is not recommend as it's already emitted by the converter. -You do not need to include the enclosing `<head>` tag as it's assumed to be the envelope. +You do not need to include the enclosing `<head>` element as it's assumed to be the envelope. Here's an example: diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index 25bbc907..349e9781 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -215,10 +215,10 @@ _**Release date:** 2020.11.02_ == Compliance * Add support for `muted` option to self-hosted video (#3408) -* Move `style` tag for convert-time syntax highlighters (coderay, rouge, pygments) into head (#3462) -* Move `style` tag for client-side syntax highlighters (highlight.js, prettify) into head (#3503) +* Move `<style>` element for convert-time syntax highlighters (coderay, rouge, pygments) into head (#3462) +* Move `<style>` element for client-side syntax highlighters (highlight.js, prettify) into head (#3503) * Define entry point API methods (`load`, `convert`, `load_file`, `convert_file`) as class methods instead of `module_function` to avoid conflict with `Kernel.load` (#3625) -* Retain attribute order on HTML `code` tag for source block to remain consistent with output from Asciidoctor 1.5.x (#3786) +* Retain attribute order on HTML `code` element for source block to remain consistent with output from Asciidoctor 1.5.x (#3786) * Correct language code for Korean language file from `kr` to `ko` (#3807) (*@jnavila*) == Improvements diff --git a/docs/modules/html-backend/pages/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc index fdc9a42f..9cad94a8 100644 --- a/docs/modules/html-backend/pages/default-stylesheet.adoc +++ b/docs/modules/html-backend/pages/default-stylesheet.adoc @@ -92,7 +92,7 @@ Asciidoctor.convert_file 'document.adoc', safe: :safe == Disable or modify the web fonts -When the default stylesheet is used, the converter adds a `<link rel="stylesheet">` tag to load web fonts from Google Fonts. +When the default stylesheet is used, the converter adds a `<link>` element specialized by the attribute `rel="stylesheet"` to load web fonts from Google Fonts. You can disable this link by unsetting the `webfonts` document attribute from the CLI, API, or document header. $ asciidoctor -a webfonts! document.adoc @@ -127,10 +127,10 @@ Another way is to create a custom stylesheet, but import the default stylesheet Adding auxiliary styles is a great use case for xref:ROOT:docinfo.adoc[docinfo]. The docinfo feature in AsciiDoc allows you to inject auxiliary content from a file into various places in the HTML output. -In this case, we're interested in the "head" position, which injects content at the bottom of the `<head>` tag. +In this case, we're interested in the "head" position, which injects content at the bottom of the `<head>` element. Let's say you want to change the color of headings (and other heading-like titles) to match the color of paragraph text. -Start by creating a file named [.path]_docinfo.html_ (head is the default location) and populate it with a `<style>` tag with the necessary styles. +Start by creating a file named [.path]_docinfo.html_ (head is the default location) and populate it with a `<style>` element with the necessary styles. .docinfo.html [source,html] @@ -147,7 +147,7 @@ Now tell Asciidoctor to look for and load the docinfo file using the `docinfo` a $ asciidoctor -a docinfo=shared document.adoc -The `<style>` tag in your docinfo file will be inserted directly below the default stylesheet in the generated HTML. +The `<style>` element in your docinfo file will be inserted directly below the default stylesheet in the generated HTML. [#customize-extend] === Extend the default stylesheet diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc index a6400aff..51a0fa6b 100644 --- a/docs/modules/html-backend/pages/favicon.adoc +++ b/docs/modules/html-backend/pages/favicon.adoc @@ -15,7 +15,7 @@ By default, the processor will add a link reference of type "icon" that refers t <link rel="icon" type="image/x-icon" href="favicon.ico"> ---- -This reference gets added inside the HTML `<head>` tag (which explains why this feature is not available when generating an embeddable HTML document). +This reference gets added inside the HTML `<head>` element (which explains why this feature is not available when generating an embeddable HTML document). To modify the name or location of the icon file, simply assign a value to the favicon attribute: @@ -25,7 +25,7 @@ To modify the name or location of the icon file, simply assign a value to the fa :favicon: ./images/favicon/favicon.png ---- -This will now produce the following HTML tag: +This will now produce the following HTML element: [source,html] ---- diff --git a/docs/modules/html-backend/pages/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc index 4ce5f00e..6b5da929 100644 --- a/docs/modules/html-backend/pages/stylesheet-modes.adoc +++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc @@ -6,12 +6,12 @@ These modes are available regardless of whether you're using the xref:default-st This page covers the document attributes that control how the stylesheet is applied. IMPORTANT: The HTML converter will only apply a stylesheet when generating a standalone HTML document. -That's because the stylesheet goes in the HTML `<head>` and the converter only generates this tag for standalone output, not embedded output. +That's because the stylesheet goes inside the HTML `<head>` element, and the converter only generates that element for standalone output. [#embed] == Embed the stylesheet -When the xref:ROOT:safe-modes.adoc[safe mode] is server or lower, the default behavior of the HTML converter is to read the stylesheet file, enclose its contents in a `<style>` tag, and embed it directly into the `<head>` of the generated HTML. +When the xref:ROOT:safe-modes.adoc[safe mode] is server or lower, the default behavior of the HTML converter is to read the stylesheet file, enclose its contents in a `<style>` element, and embed it directly into the `<head>` element of the generated HTML. This default makes the HTML more portable since you don't lose the stylesheet if you move the file. However, if the safe mode is secure, the converter will <<link,link to the stylesheet file>> instead. @@ -27,7 +27,9 @@ However, it's possible to enable this behavior independent of the safe mode. This can be beneficial if you're converting numerous AsciiDoc documents to HTML and want them all to share the same stylesheet. It can also make inspecting the HTML a little simpler. -If the `linkcss` document attribute is set, the converter will take this hint to link to the stylesheet using a `<link rel="stylesheet">` tag point to a relative path reference instead of embedding it. +If the `linkcss` document attribute is set, the converter will link to the stylesheet instead of embedding it. +To link to the stylesheet, the converter uses a `<link>` element specialized by the `rel="stylesheet"` attribute. +The `href` attribute will reference the stylesheet using a relative path. The `linkcss` document attribute must be set by the end of the header to be effective. One way to do that is to set the attribute in the document header: @@ -44,7 +46,7 @@ You can also set `linkcss` using the API or CLI (shown here): $ asciidoctor -a linkcss my-document.adoc -In either case, if you inspect the `<head>` tag in the output file [.path]_my-document.html_, you'll see that the HTML links to the stylesheet. +In either case, if you inspect the `<head>` element in the output file [.path]_my-document.html_, you'll see that the HTML links to the stylesheet. .my-document.html [source,html] @@ -117,7 +119,7 @@ We'll see the `copycss` attribute come up again on the xref:custom-stylesheet.ad [#disable] == Disable the stylesheet -The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` tag. +The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` element. If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` attribute using the CLI. $ asciidoctor -a stylesheet! my-document.adoc diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc index 58aa7e4b..be8c1ea5 100644 --- a/docs/modules/syntax-highlighting/pages/index.adoc +++ b/docs/modules/syntax-highlighting/pages/index.adoc @@ -37,7 +37,7 @@ Unfortunately, Asciidoctor does not process callout numbers in the source block A [.term]*build-time syntax highlighter* performs syntax highlighting during AsciiDoc conversion. Asciidoctor does invoke the syntax highlighter in this case. It also takes care of hiding the callout numbers from the syntax highlighter, ensuring they are put back in the proper place afterwards. -What Asciidoctor emits into the output is the result produced by the syntax highlighter, which are the tokens wrapped in `<span>` tags to apply color and other formatting (either inline or via CSS classes). +What Asciidoctor emits into the output is the result produced by the syntax highlighter, which are the tokens enclosed in `<span>` elements to apply color and other formatting (either inline or via CSS classes). These syntax highlighters tend to support more features because Asciidoctor has greater control over the process. === Client-side vs build-time @@ -80,7 +80,7 @@ h|Client-side Asciidoctor does not apply syntax highlighting when generating DocBook. The assumption is that this is a task the DocBook toolchain can handle. -The DocBook converter generates a `<programlisting>` tag for the source block and passes through the source language as specified in the AsciiDoc. +The DocBook converter generates a `<programlisting>` element for the source block and passes through the source language as specified in the AsciiDoc. It's then up to the DocBook toolchain to apply syntax highlighting to the contents of that tag. You can explore these integrations in depth on the xref:highlightjs.adoc[], xref:rouge.adoc[], xref:pygments.adoc[], and xref:coderay.adoc[] pages. |