From 9940616e9f5f4ace3a2b0616fda781ff08bf16b3 Mon Sep 17 00:00:00 2001 From: rocky allen Date: Fri, 26 Feb 2016 02:41:07 -0700 Subject: [PATCH] resolves #480 create a dedicated table for built-in attributes --- docs/_includes/attr-builtin.adoc | 656 +++++++++++++++++++++++++++++++ docs/_includes/attr-charref.adoc | 1 + docs/user-manual.adoc | 12 +- 3 files changed, 664 insertions(+), 5 deletions(-) create mode 100644 docs/_includes/attr-builtin.adoc diff --git a/docs/_includes/attr-builtin.adoc b/docs/_includes/attr-builtin.adoc new file mode 100644 index 000000000..79529c400 --- /dev/null +++ b/docs/_includes/attr-builtin.adoc @@ -0,0 +1,656 @@ +//// +Need to update the compatibility guide with: +* numbered = sectnums +* docinfo1 = docinfo +* docinfo2 = docinfo +* toc-class = use custom theme [link:https://github.com/asciidoctor/asciidoctor.org/issues/379[issue #379] +* toc-placement = toc +* notitle = showtitle! +* encoding = ignored always UTF-8 +//// +[[builtin-attributes]] += Built-in attributes +:y: icon:check[role="green"] + +Built-in document attributes can be set anywhere in the document using an attribute entry line. +However, there are some rules to keep in mind regarding the impact of that assignment. + +* If you set an attribute from the commandline or API, it's defined for the whole document and cannot be changed in the body unless `@` is added to the end of the value. +(The one exception to this rule is the `sectnums` attribute, which can always be changed). +* If you set an attribute in the body (anywhere after the document header), the attribute is visible from the point it is set until it is unset (assuming it is not locked as a result of being set from the commandline or API). +* Many attributes can only be defined in the header or else they won't have the desired impact. +These are called _header attributes_. +This requirement is marked in the tables below. +* To set an attribute that does not accept a value, simply use an empty value (as indicated by _empty_ in the table). + +NOTE: Several attributes from AsciiDoc Python have been removed (or deprecated) in Asciidoctor and therefore are not included in this section. +See <> if you are updating an older document. + +// tag::table[] +.Built-in document attributes +[cols="20,30,15,15,^5,15"] +|==== +|Attribute name |Description |Default value^[1]^ |Allowed values |Header only |See also + +6+> + +|attribute-missing +|Controls how missing references are handled. +|skip +|skip, drop, drop-line or warn +|{y} +|<> + +|attribute-undefined +|Controls how expressions that undefine an attribute are handled. +|drop-line +|drop or drop-line +|{y} +|<> + +|experimental +|Enable experimental extensions. +Emphasises that they are subject to change and may even be removed in the next version. +Currently only applies to the interface macros. +|_not set_ +|_empty_ +|{y} +|<> + +// internationalization is over-egging it, but I dont want to say language to prevent confusion with programming language +6+>, <> + +|caution-caption +|Sets the text used to label CAUTION admonitions, if icons are not used. +|Caution +|_any_ +| +|<>, <> + +|example-caption +|Sets the text used to label example blocks. +|Example +|_any_ +| +|<> + +|figure-caption +|Sets the text used to label figures. +|Figure +|_any_ +| +|<>, <> + +|important-caption +|Sets the text used to label IMPORTANT admonitions, if icons are not used. +|Important +|_any_ +| +|<>, <> + +|lang +|Set the `lang` attribute in the DocBook backend. +|en +|A valid XML country code +|{y} +|<> + +|last-update-label +|Text label for the “Last updated” time in the footer. +Unsetting it will remove the label and time from the footer. +|Last updated +|_any_ +|{y} +|<>, <> + +|manname-title +|Label for the program name line in manpage outputs. +|NAME +|_any_ +|{y} +|<> + +|nolang +|Prevents the `lang` attribute being added to the docbook root element. +|_not set_ +|_empty_ +|{y} +| + +|note-caption +|Sets the text used to label NOTE admonitions, if icons are not used. +|Note +|_any_ +| +|<>, <> + +|table-caption +|Text of the label that is automatically prefixed to table titles. +To turn off table caption labels and numbers, add the `table-caption` attribute to the document header with an empty value. +|Table +|_any_ +| +|<> + +|tip-caption +|Sets the text used to label TIP admonitions, if icons are not used. +|Tip +|_any_ +| +|<>, <> + +|toc-title +|Title for the TOC. +|Table of Contents +|_any_ +| +|<>, <> + +|untitled-label +|The default document title when the document does not have one. +|Untitled +|_any_ +|{y} +|<> + +|version-label +|The label preceding the revnumber in a rendered document’s byline +|Version +|_any_ +|{y} +|<>, <> + +|warning-caption +|Sets the text used to label TIP admonitions, if icons are not used. +|Warning +|_any_ +| +|<> + +6+> + +|authors +|If set, add to the HTML document `` element as metadata. +|_not set_ +|_any_ +|{y} +|<> + +|copyright +|If set, add to the HTML document `` element as metadata. +|_not set_ +|_any_ +|{y} +|<> + +|description +|If set, add to the HTML document `` element as metadata. +|_not set_ +|_any_ +|{y} +|<> + +|email +|Sets the author's email address. +Can also be set implicity from the author line. +Can be any inline macro, such as a URL. +|_not set_ +|_any_ +|{y} +|<> + +|mantitle +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<> + +|manvolnum +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<> + +|manname +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<> + +|manpurpose +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<> + +|revdate +|Sets the revison date. +Can also be set implicity from the revision line. +|_not set_ +|_any_ +|{y} +|<> + +|revremark +|Sets the revison description. +Can also be set implicity from the revision line. +|_not set_ +|_any_ +|{y} +|<> + +|revnumber +|Sets the revison number. +Can also be set implicity from the revision line. +|_not set_ +|_any_ +|{y} +|<> + +6+> + +|docinfo +|Read input from one or more DocBook info files. +|_not set_ +|Comma-separated list of the following values: shared, private, shared-head, private-head, shared-footer or private-footer +|{y} +|<> + +|doctype +|Set the output document type. +|article +|article, book, inline or manpage +|{y} +|<> + +|eqnums +|Turns on equation numbering in STEM/MathJax output. +|_not set_ +|_empty_ +|{y} +|<> + +|hardbreaks +|Preserve hard line breaks in the input. +|_not set_ +|_empty_ +| +|<> + +|iconfont-remote +|If set, allows use of a CDN for resolving the icon font. +|_empty_ +|_empty_ +|{y} +| + +|icons +|Chooses icons instead of text for admonitions. +|_not set_ +|font or image +|{y} +|<> + +|iconfont-cdn +|Overrides the CDN used to resolve the Font Awesome stylesheet. +|cdnjs +|URI +|{y} +| + +|iconfont-name +|Overrides the name of the icon font stylesheet. +|font-awesome +|_any_ +|{y} +| + +|iconsdir +|Where admonition icons are stored (when `icons` is set to `image`). +|./images/icons +|Directory +|{y} +|<> + +|idprefix +|Prefix for auto-generated section IDs. +|_ +|A valid XML ID start character. +|{y} +|<> + +|idseparator +|Separates words in auto-generated section IDs. +|_ +|A valid XML ID character. +|{y} +|<> + +|imagesdir +|Where image files are resolved. +|./images +|Directory +| +|<> + +|keywords +|If set, add to the HTML document `` element as metadata. +|_any_ +| +|{y} +| + +|leveloffset +|Pushes the level of subsequent headings down, to make file inclusion more useful. +|0 +|0-5. Add a leading + or - to make them relative. +| +|<> + +|linkattrs +|Parse attributes inside the link macro. +|_not set_ (Do not parse). +|_empty_ +| +|<> + +|nofooter +|Suppresses rendering of the footer. +|_not set_ +|_empty_ +|{y} +|<> + +|nofootnotes +|Turn off display of footnotes. +|_not set_ +|_empty_ +|{y} +|<> + +|noheader +|Suppresses rendering of the header. +|_not set_ +|_empty_ +|{y} +|<> + +|noxmlns +|Remove the namespace from the DocBook 5 XML output. +|_not set_ (Namespace will be added). +|_empty_ +|{y} +|<> + +|reproducible +|If set, stops the last-updated date from being output in the HTML footer or DocBook info element. +Useful if you want to store the output in a source code control system as it prervents spurious changes every time you convert the document. +|_not set_ +|_empty_ +|{y} +| + +// NOTE: scriptsdir is not used by Asciidoctor +//|scriptsdir +//|Sets the path to JavasScript files. +//|./javascripts +//|Directory +//|{y} +//|<> + +|sectanchors +|If set, adds a floating anchor in front of the section title when it has focus. +|_not set_ (No anchors). +|_empty_ +|{y} +|<> + +|sectids +|If set, synthesises IDs for any sections that do not already have one. +|Empty string. +|_empty_ +|{y} +|<> + +|sectlinks +|Turns section titles into links. +|_not set_ +|_empty_ +|{y} +|<> + +|sectnums +|If set, numbers sections to depth specified by sectnumlevels. +|_not set_ (Sections are not numbered). +|_empty_ +|{y} +|<> + +|sectnumlevels +|controls the depth of section numbering +|3 +|0-5 +|{y} +|<> + +|showtitle +|If set, displays an embedded document's title. +Mutually exclusive with the `notitle` attribute. +|_not set_ +|_empty_ +|{y} +|<> + +|stem +|Enables mathematics processing or sets the processor used. +|asciimath +|_empty_, asciimath or latexmath +|{y} +|<> + +|toc +|Switches the table of contents on, and defines its location. +|auto +|auto, left, right, macro or preamble +|{y} +|<> + +|toclevels +|Maximum section level to display. +|2 +|1-5 +|{y} +|<> + +|webfonts +|Control how webfonts are referenced by the default stylesheet. +|_empty_ +|_empty_ +|{y} +|<> and link:https://github.com/asciidoctor/asciidoctor.org/issues/410[issue #410] + +6+> + +|highlightjsdir +|Location of the highlight.js source code highlighter library. +|_not set_ +|Directory +|{y} +|<> + +|highlightjs-theme +|Sets the name of the theme used by the highlight.js source code highlighter. +|github +|A style name recognized by highlight.js. +|{y} +|<> + +|prettifydir +|Location of the prettify source code highlighter library. +|_not set_ (Uses CDN). +|Directory +|{y} +|<> + +|prettify-theme +|Sets the name of the theme used by the prettify source code highlighter. +|prettify +|A style name recognized by prettify. +|{y} +|<> + +|pygments-css +|Controls whether Pygments uses CSS classes or inline styles. +|class +|class or style +|{y} +|<> + +|pygments-style +|Sets the name of the style used by the Pygments source code highlighter +|default +|A style name recognized by Pygments. +|{y} +|<> + +|prewrap +|Wrap wide code listings. +Sets the default behavior only; you can still switch off wrapping on specific listings. +|_empty_ (Code listing will wrap long lines, not scroll). +|_empty_ +| +|<> + +|source-highlighter +|Source code highlighter to use. +|_not set_ +|coderay, highlightjs, prettify or pygments +|{y} +|<> + +|source-indent +|Normalize block indentation in code listings. +|_not set_ (Indentation is not modified). +|Number +| +|<> + +|source-language +|Set the default language for source code listings. +|_not set_ +|Language name. +| +|<> + +6+> + +|stylesheet +|Name of a CSS stylesheet to replace the default one. +|_not set_ (The default stylesheet is used). +|File name +|{y} +|<> + +|copycss +|If set, copy the CSS files to the output. +|_empty_ (File is copied if `linkcss` is set). +|_empty_ +|{y} +|<> + +|linkcss +|If set, link to the stylesheet instead of embedding it. +|_not set_ +|_empty_ +|{y} +|<> + +|max-width +|Constrain the maximum width of the document body. +|_not set_ +|CSS length (e.g. 55em, 12cm, etc) +|{y} +| + +6+> + +|max-include-depth +|Safety feature to prevent infinite looping. +|64 +|>=0 +|CLI or API +| +|==== + +^[1]^ The default value isn't necesarily the value you will get by entering `{name}`. +It may be the "fallback" value which Asciidoctor uses if the attribute is not defined. +The effect is the same either way. +// end::table[] diff --git a/docs/_includes/attr-charref.adoc b/docs/_includes/attr-charref.adoc index c8f7e1ae3..51451daa8 100644 --- a/docs/_includes/attr-charref.adoc +++ b/docs/_includes/attr-charref.adoc @@ -1,3 +1,4 @@ +[[charref-attributes]] = Predefined attributes for character replacements // tag::table[] diff --git a/docs/user-manual.adoc b/docs/user-manual.adoc index a132ce2f6..f233f9cc6 100644 --- a/docs/user-manual.adoc +++ b/docs/user-manual.adoc @@ -1759,15 +1759,17 @@ cross reference:: a link from one location in the document to another location m list continuation:: a plus sign (`+`) on a line by itself that connects adjacent lines of text to a list item quoted text:: text which is enclosed in special punctuation to give it emphasis or special meaning -:leveloffset: 1 [[asciidoctor-vs-asciidoc]] [appendix] -include::asciidoc-asciidoctor-diffs-table.adoc[] +include::asciidoc-asciidoctor-diffs-table.adoc[leveloffset=1] -:leveloffset: 1 -[[charref-attributes]] +[[builtin-predefined-attributes]] [appendix] -include::{includedir}/attr-charref.adoc[] +== Built-in and predefined document attributes + +include::{includedir}/attr-builtin.adoc[leveloffset=2] + +include::{includedir}/attr-charref.adoc[leveloffset=2] ////