From 64ec52d2dacb0ff9c5e54ff47bc35f56a67b18ea Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 19 Nov 2020 15:45:59 -0700 Subject: create integration modules; update stylesheet pages --- docs/modules/ROOT/nav-safe-modes.adoc | 2 +- .../ROOT/pages/attributes-and-safe-modes.adoc | 46 ---------------------- docs/modules/ROOT/pages/language-support.adoc | 46 +++++++++++----------- docs/modules/ROOT/pages/reference-safe-mode.adoc | 45 +++++++++++++++++++++ docs/modules/ROOT/pages/safe-modes.adoc | 6 +-- 5 files changed, 72 insertions(+), 73 deletions(-) delete mode 100644 docs/modules/ROOT/pages/attributes-and-safe-modes.adoc create mode 100644 docs/modules/ROOT/pages/reference-safe-mode.adoc (limited to 'docs/modules/ROOT') diff --git a/docs/modules/ROOT/nav-safe-modes.adoc b/docs/modules/ROOT/nav-safe-modes.adoc index be07ed4d..2d362d52 100644 --- a/docs/modules/ROOT/nav-safe-modes.adoc +++ b/docs/modules/ROOT/nav-safe-modes.adoc @@ -1,2 +1,2 @@ * xref:safe-modes.adoc[] -** xref:attributes-and-safe-modes.adoc[] +** xref:reference-safe-mode.adoc[] diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc deleted file mode 100644 index 1d18c502..00000000 --- a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= Manage Attributes By Safe Mode -// anchor: set-safe-attrs - -Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. -Each level includes the restrictions enabled in the prior security level. - -Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes. -You can use these attributes to enable or disable content based on the current safe mode of the processor. - -The safe mode can be referenced by one of the following attributes: - -* The value of the `safe-mode-name` attribute (e.g., unsafe, safe, etc.) -* The value of the `safe-mode-level` attribute (e.g., 0, 10, etc.) -* The presence of the `safe-mode-` attribute, where `` is the safe mode name. - -The attributes in the next example define replacement text for features that are disabled in high security environments: - -[source,asciidoc] ----- -\ifdef::safe-mode-secure[] -Link to chapters instead of including them. -\endif::safe-mode-secure[] ----- - -This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure. - -You can set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and the xref:api:set-safe-mode.adoc[API]. - -//// -Allow the include directive to import a file from a URI. - -Example: - - include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] - -To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater. -Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI. - -I decided the following defaults for the standalone option make the most sense: - -true if using the cli (use -s to disable, consistent with asciidoc) -false if using the API, unless converting directly to a file, in which case true is the default -The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting. - -The reason I think the standalone default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now. -//// diff --git a/docs/modules/ROOT/pages/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc index 4af521ff..362411d0 100644 --- a/docs/modules/ROOT/pages/language-support.adoc +++ b/docs/modules/ROOT/pages/language-support.adoc @@ -39,85 +39,85 @@ If you're not using the DocBook toolchain for publishing, you must translate eac One way is to set the following attributes in the document header or by passing the attributes via the API or CLI: .Attributes that control built-in labels -[%autowidth] +[%autowidth,cols="m,,"] |=== -|Attribute name |Used for |Default +|Attribute |Default English Value |Notes |appendix-caption -|Appendix titles. |Appendix +| |caution-caption -|CAUTION admonitions (when icons are not in use). |Caution +| |chapter-label -|Prefix added to chapter titles (i.e., level-1 section titles when doctype is book). _(pdf converter only)_ |Chapter +|Applies only when `doctype` is `book`. +PDF converter only. |example-caption -|Example titles. |Example +| |figure-caption -|Automatically prefixed to figure titles. |Figure +| |important-caption -|IMPORTANT admonitions (when icons are not in use). |Important +| |last-update-label -|Label for when the document was last updated. |Last updated +| |listing-caption -|The label for listing blocks. -By default, listing blocks do not have captions. -If you specify `listing-caption`, then you also turn on captions for listing blocks. |_not set_ +|By default, listing blocks do not have captions. +Specify `listing-caption` to turn on listing block captions. |manname-title -|Label for the program name section in the man page. |NAME +|Applies only when `doctype` is `manpage`. |note-caption -|NOTE admonitions (when icons are not in use). |Note +| |preface-title -|Title text used for the anonymous preface (when the `doctype` is book). |_not set_ +|Applies only when `doctype` is `book`. |table-caption -|Automatically prefixed to table titles. |Table +| |tip-caption -|TIP admonitions (when icons are not in use). |Tip +| |toc-title -|Title of the table of contents. |Table of Contents +| |untitled-label -|The document title, for documents that have only body content. |Untitled +| |version-label -|The label preceding the revnumber in the document's byline. |Version +| |warning-caption -|WARNING admonitions (when icons are not in use). |Warning +| |=== -If you plan to support multiple languages, you'll want to define the attributes for each language inside a conditional preprocessor directive. +If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive]. For example: -[source] +[source,asciidoc] ---- \ifeval::["{lang}" == "de"] :caution-caption: Achtung diff --git a/docs/modules/ROOT/pages/reference-safe-mode.adoc b/docs/modules/ROOT/pages/reference-safe-mode.adoc new file mode 100644 index 00000000..8c5b47b2 --- /dev/null +++ b/docs/modules/ROOT/pages/reference-safe-mode.adoc @@ -0,0 +1,45 @@ += Safe Mode Specific Content +// anchor: set-safe-attrs + +Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes. +You can use these attributes to enable or disable content based on the current safe mode of the processor. + +== Referencing safe modes + +The safe mode can be referenced by one of the following attributes: + +* The value of the `safe-mode-name` attribute (e.g., unsafe, safe, etc.) +* The value of the `safe-mode-level` attribute (e.g., 0, 10, etc.) +* The presence of the `safe-mode-` attribute, where `` is the safe mode name. + +The attributes in the next example define replacement text for features that are disabled in high security environments: + +[source,asciidoc] +---- +\ifdef::safe-mode-secure[] +Link to chapters instead of including them. +\endif::safe-mode-secure[] +---- + +This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure. + +You can set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and the xref:api:set-safe-mode.adoc[API]. + +//// +Allow the include directive to import a file from a URI. + +Example: + + include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] + +To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater. +Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI. + +I decided the following defaults for the standalone option make the most sense: + +true if using the cli (use -s to disable, consistent with asciidoc) +false if using the API, unless converting directly to a file, in which case true is the default +The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting. + +The reason I think the standalone default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now. +//// diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc index 3e06f836..c8ac7d8f 100644 --- a/docs/modules/ROOT/pages/safe-modes.adoc +++ b/docs/modules/ROOT/pages/safe-modes.adoc @@ -1,6 +1,6 @@ = Safe Modes -Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. +Asciidoctor provides security levels that control the read and write access of attributes, include directives, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level. == Safe mode levels @@ -48,7 +48,7 @@ Additionally, it: * disables `docdir` and `docfile` (as these can reveal information about the host filesystem) * disables source highlighting -xref:extensions:register.adoc[Asciidoctor extensions] may still embed content into the document depending whether they honor the safe mode setting. +xref:extensions:index.adoc[Asciidoctor extensions] may still embed content into the document depending whether they honor the safe mode setting. *This is the default safe mode for the API.* Its integer value is `20`. @@ -80,4 +80,4 @@ TIP: GitHub processes AsciiDoc files using the `SECURE` level. //// The safe mode can be set from the xref:cli:set-safe-mode.adoc[CLI] and the xref:api:set-safe-mode.adoc[API]. -You can also xref:attributes-and-safe-modes.adoc[manage attributes by safe mode]. +You can also xref:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. -- cgit v1.2.3