diff options
| author | Dan Allen <dan.j.allen@gmail.com> | 2022-10-21 04:45:55 -0600 |
|---|---|---|
| committer | Dan Allen <dan.j.allen@gmail.com> | 2022-10-21 04:45:55 -0600 |
| commit | fd0a3922db90bc110902ce20d12217b9725cb7dc (patch) | |
| tree | 4bbf25c622307ccbcda73b345012f683ac55007c /docs/modules | |
| parent | dea6d04e57749ebe21db6f367acd1b44519da9e7 (diff) | |
relocate docinfo page to AsciiDoc language guide
Diffstat (limited to 'docs/modules')
| -rw-r--r-- | docs/modules/ROOT/pages/docinfo.adoc | 307 |
1 files changed, 2 insertions, 305 deletions
diff --git a/docs/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc index 4fda9a24..226aaab5 100644 --- a/docs/modules/ROOT/pages/docinfo.adoc +++ b/docs/modules/ROOT/pages/docinfo.adoc @@ -1,307 +1,4 @@ = Docinfo Files -:url-docbook-info-ref: https://tdg.docbook.org/tdg/5.0/info.html -:url-docinfo-example: https://github.com/clojure-cookbook/clojure-cookbook/blob/master/book-docinfo.xml +:page-location: asciidoc:docinfo:index.adoc -Docinfo is a feature of AsciiDoc that allows you to insert custom content into the head, header, or footer of the output document. -This custom content is read from files known as docinfo files by the converter. -Docinfo files are intended as convenient way to supplement the output produced by a converter. -Examples include injecting auxiliary metadata, stylesheets, and scripting logic not already provided by the converter. - -The docinfo feature does not apply to all backends. -While it works when converting to output formats such as HTML and DocBook, it does not work when converting to PDF using Asciidoctor PDF. - -The docinfo feature must be explicitly enabled using the `docinfo` attribute (see <<enable>>). -Which docinfo files are consumed depends on the value of the `docinfo` attribute as well as the backend. - -[#head] -== Head docinfo files - -The content of head docinfo files gets injected into the top of the document. -For HTML, the content is append to the `<head>` element. -For DocBook, the content is appended to the root `<info>` element. - -The docinfo file for HTML output may contain valid elements to populate the HTML `<head>` element, including: - -* `<base>` -* `<link>` -* `<meta>` -* `<noscript>` -* `<script>` -* `<style>` - -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>` element as it's assumed to be the envelope. - -Here's an example: - -.A head docinfo file for HTML output -[source,html] ----- -<meta name="keywords" content="open source, documentation"> -<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team."> -<link rel="stylesheet" href="basejump.css"> -<script src="map.js"></script> ----- - -Docinfo files for HTML output must be saved with the `.html` file extension. -See <<naming>> for more details. - -The docinfo file for DocBook 5.0 output may include any of the {url-docbook-info-ref}[<info> element's children^], such as: - -* `<address>` -* `<copyright>` -* `<edition>` -* `<keywordset>` -* `<publisher>` -* `<subtitle>` -* `<revhistory>` - -The following example shows some of the content a docinfo file for DocBook might contain. - -.A docinfo file for DocBook 5.0 output -[source,xml] ----- -<author> - <personname> - <firstname>Karma</firstname> - <surname>Chameleon</surname> - </personname> - <affiliation> - <jobtitle>Word SWAT Team Leader</jobtitle> - </affiliation> -</author> - -<keywordset> - <keyword>open source</keyword> - <keyword>documentation</keyword> - <keyword>adventure</keyword> -</keywordset> - -<printhistory> - <para>April, 2021. Twenty-sixth printing.</para> -</printhistory> ----- - -Docinfo files for DocBook output must be saved with the `.xml` file extension. -See <<naming>> for more details. - -You can find a real-world example of a docinfo file for DocBook in the source of the {url-docinfo-example}[Clojure Cookbook^]. - -[#header] -== Header docinfo files - -Header docinfo files are differentiated from head docinfo files by the addition of `-header` to the file name. -In the HTML output, the header content is inserted immediately before the header div (i.e., `<div id="header">`). -In the DocBook output, the header content is inserted immediately after the opening tag (e.g., `<article>` or `<book>`). - -TIP: One possible use of the header docinfo file is to completely replace the default header in the standard stylesheet. -Just set the attribute `noheader`, then apply a custom header docinfo file. - -[#footer] -== Footer docinfo files - -Footer docinfo files are differentiated from head docinfo files by the addition of `-footer` to the file name. -In the HTML output, the footer content is inserted immediately after the footer div (i.e., `<div id="footer">`). -In the DocBook output, the footer content is inserted immediately before the ending tag (e.g., `</article>` or `</book>`). - -TIP: One possible use of the footer docinfo file is to completely replace the default footer in the standard stylesheet. -Just set the attribute `nofooter`, then apply a custom footer docinfo file. - -// Not here! Good info, but does nothing to clarify the previous paragraphs and could confuse. -//// -TIP: To change the text in the "Last updated" line in the footer, set the text in the attribute `last-update-label` (for example, `:last-update-label: <your text> Last Updated`). + -To disable the "Last updated" line in the footer, unassign the attribute `last-update-label` (however, this leaves an empty footer div). + -To disable the footer completely, set the attribute `nofooter`. Then having a footer docinfo file effectively replaces the default footer with your custom footer. -//// - -[#naming] -== Naming docinfo files - -The file that gets selected to provide the docinfo depends on which converter is in use (html, docbook, etc) and whether the docinfo scope is configured for a specific document ("`private`") or for all documents in the same directory ("`shared`"). -The file extension of the docinfo file must match the file extension of the output file (as specified by the `outfilesuffix` attribute, a value which always begins with a period (`.`)). - -.Docinfo file naming -[cols="<10,<20,<30,<30"] -|=== -|Mode |Location |Behavior |Docinfo file name - -.3+|Private -|Head -|Adds content to `<head>`/`<info>` for <docname>.adoc files. -|`<docname>-docinfo<outfilesuffix>` - -|Header -|Adds content to start of document for <docname>.adoc files. -|`<docname>-docinfo-header<outfilesuffix>` - -|Footer -|Adds content to end of document for <docname>.adoc files. -|`<docname>-docinfo-footer<outfilesuffix>` - -.3+|Shared -|Head -|Adds content to `<head>`/`<info>` for any document in same directory. -|`docinfo<outfilesuffix>` - -|Header -|Adds content to start of document for any document in same directory. -|`docinfo-header<outfilesuffix>` - -|Footer -|Adds content to end of document for any document in same directory. -|`docinfo-footer<outfilesuffix>` -|=== - -[#enable] -== Enabling docinfo - -To specify which file(s) you want to apply, set the `docinfo` attribute to any combination of these values: - -* `private-head` -* `private-header` -* `private-footer` -* `private` (alias for `private-head,private-header,private-footer`) -* `shared-head` -* `shared-header` -* `shared-footer` -* `shared` (alias for `shared-head,shared-header,shared-footer`) - -Setting `docinfo` with no value is equivalent to setting the value to `private`. - -For example: - -[source,asciidoc] ----- -:docinfo: shared,private-footer ----- - -This docinfo configuration will apply the shared docinfo head, header and footer files, if they exist, as well as the private footer file, if it exists. - -// NOTE migrate this NOTE to the migration guide once 1.6 is released -[NOTE] -==== - -`docinfo` attribute values were introduced in Asciidoctor 1.5.5 to replace the less descriptive `docinfo1` and `docinfo2` attributes. -Here are the equivalents of the old attributes using the new values: - -* `:docinfo:` = `:docinfo: private` -* `:docinfo1:` = `:docinfo: shared` -* `:docinfo2:` = `:docinfo: shared,private` -==== - -Let's apply this to an example: - -You have two AsciiDoc documents, [.path]_adventure.adoc_ and [.path]_insurance.adoc_, saved in the same folder. -You want to add the same content to the head of both documents when they're converted to HTML. - -. Create a docinfo file containing `<head>` elements. -. Save it as docinfo.html. -. Set the `docinfo` attribute in [.path]_adventure.adoc_ and [.path]_insurance.adoc_ to `shared`. - -You also want to include some additional content, but only to the head of [.path]_adventure.adoc_. - -. Create *another* docinfo file containing `<head>` elements. -. Save it as [.path]_adventure-docinfo.html_. -. Set the `docinfo` attribute in [.path]_adventure.adoc_ to `shared,private-head` - -If other AsciiDoc files are added to the same folder, and `docinfo` is set to `shared` in those files, only the [.path]_docinfo.html_ file will be added when converting those files. - -[#resolving] -== Locating docinfo files - -By default, docinfo files are searched for in the same directory as the document file (which can be overridden by setting the `:base_dir` API option / `--base-dir` CLI option). -If you want to load them from another location, set the `docinfodir` attribute to the directory where the files are located. -If the value of the `docinfodir` attribute is a relative path, that value is appended to the document directory. -If the value is an absolute path, that value is used as is. - -[source,asciidoc] ----- -:docinfodir: common/meta ----- - -Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document directory will no longer be found. - -[#attribute-substitution] -== Attribute substitution in docinfo files - -Docinfo files may include attribute references. -Which substitutions get applied is controlled by the `docinfosubs` attribute, which takes a comma-separated list of substitution names. -The value of this attribute defaults to `attributes`. - -For example, if you created the following docinfo file: - -.Docinfo file (docinfo.xml) containing a revnumber attribute reference -[source,xml] ----- -<edition>{revnumber}</edition> ----- - -And this source document: - -.Source document including a revision number -[,asciidoc] ----- -= Document Title -Author Name -v1.0, 2020-12-30 -:doctype: book -:backend: docbook -:docinfo: ----- - -Then the converted DocBook output would be: - -.Converted DocBook containing the docinfo -[,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<book xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" lang="en"> - <info> - <title>Document Title</title> - <date>2020-12-30</date> - <author> - <personname> - <firstname>Author</firstname> - <surname>Name</surname> - </personname> - </author> - <authorinitials>AN</authorinitials> - <revhistory> - <revision> - <revnumber>1.0</revnumber> <!--.--> - <date>2020-12-30</date> - <authorinitials>AN</authorinitials> - </revision> - </revhistory> - </info> -</book> ----- -<.> The revnumber attribute reference was replaced by the source document's revision number in the converted output. - -Another example is if you want to define the the licence link tag in the HTML head. - -.Docinfo file (docinfo.html) containing a license meta tag -[,html] ----- -<link rel="license" href="{license-url}" title="{license-title}"> ----- - -Now define these attributes in your AsciiDoc source: - -.Source document that defines license attributes -[,asciidoc] ----- -= Document Title -:license-url: https://mit-license.org -:license-title: MIT ----- - -Then the `<head>` tag in the converted HTML would include: - -.Rendered license link tag in HTML output -[,html] ----- -<link rel="license" href="https://mit-license.org" title="MIT"> ----- +Relocated to xref:{page-location}[]. |