directives.html
1 <!DOCTYPE html> 2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="generator" content="Docutils 0.20.1: https://docutils.sourceforge.io/" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1" /> 7 <meta name="author" content="David Goodger" /> 8 <meta name="dcterms.date" content="2025-07-30" /> 9 <meta name="dcterms.rights" content="This document has been placed in the public domain." /> 10 <title>reStructuredText Directives</title> 11 <link rel="schema.dcterms" href="http://purl.org/dc/terms/"/> 12 <style type="text/css"> 13 14 /* CSS3_ style sheet for the output of Docutils HTML5 writer. */ 15 /* Generic responsive design for all screen sizes. */ 16 /* */ 17 /* :Author: Günter Milde */ 18 /* */ 19 /* :Id: $Id: responsive.css 10170 2025-06-16 12:36:11Z milde $ */ 20 /* :Copyright: © 2021 Günter Milde. */ 21 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 22 /* in short: */ 23 /* */ 24 /* Copying and distribution of this file, with or without modification, */ 25 /* are permitted in any medium without royalty provided the copyright */ 26 /* notice and this notice are preserved. */ 27 /* */ 28 /* This file is offered as-is, without any warranty. */ 29 /* */ 30 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 31 /* .. _CSS3: https://www.w3.org/Style/CSS/ */ 32 33 /* Note: */ 34 /* This style sheet is provisional: */ 35 /* the API is not settled and may change with any minor Docutils version. */ 36 37 38 39 /* General Settings */ 40 /* ================ */ 41 42 43 * { box-sizing: border-box; } 44 45 body { 46 background-color: #fafaf6; 47 margin: auto; 48 --field-indent: 6.6em; /* indent of fields in field lists */ 49 --sidebar-margin-right: 0; /* adapted in media queries below */ 50 } 51 main { 52 counter-reset: figure table; 53 } 54 body > * { 55 background-color: white; 56 line-height: 1.6; 57 padding: 0.5rem calc(29% - 7.2rem); /* go from 5% to 15% (8.15em/54em) */ 58 margin: auto; 59 max-width: 100rem; 60 } 61 sup, sub { /* avoid additional inter-line space for lines with sup/sub */ 62 line-height: 1; 63 } 64 65 /* Vertical Space (Parskip) */ 66 p, ol, ul, dl, li, 67 .topic, 68 .footnote, .citation, 69 div > math, 70 table { 71 margin-top: 0.5em; 72 margin-bottom: 0.5em; 73 } 74 h1, h2, h3, h4, h5, h6, 75 dl > dd, details > p:last-child { 76 margin-bottom: 0.5em; 77 } 78 79 /* Indented Blocks */ 80 blockquote, figure, .topic { 81 margin: 1em 2%; 82 padding-left: 1em; 83 } 84 div.line-block div.line-block, 85 pre, dd, dl.option-list { 86 margin-left: calc(2% + 1em); 87 } 88 89 /* Object styling */ 90 /* ============== */ 91 92 footer, header { 93 font-size: small; 94 } 95 96 /* Frontmatter */ 97 div.dedication { 98 padding: 0; 99 margin: 1.4em 0; 100 font-style: italic; 101 font-size: large; 102 } 103 .dedication p.topic-title { 104 display: none; 105 } 106 107 blockquote p.attribution { 108 text-align: right; 109 } 110 111 /* Table of Contents */ 112 nav.contents ul { 113 padding-left: 1em; 114 } 115 ul.auto-toc > li > p { /* hanging indent */ 116 padding-left: 1em; 117 text-indent: -1em; 118 } 119 main > nav.contents ul:not(.auto-toc) { 120 list-style-type: square; 121 } 122 main > nav.contents ul ul:not(.auto-toc) { 123 list-style-type: disc; 124 } 125 main > nav.contents ul ul ul:not(.auto-toc) { 126 list-style-type: '\2B29\ '; 127 } 128 main > nav.contents ul ul ul ul:not(.auto-toc) { 129 list-style-type: '\2B1D\ '; 130 } 131 main > nav.contents ul ul ul ul ul:not(.auto-toc) { 132 list-style-type: '\2B2A\ '; 133 } 134 nav.contents ul > li::marker { 135 color: grey; 136 } 137 138 /* Transitions */ 139 hr { 140 margin: 1em 10%; 141 } 142 143 /* Lists */ 144 145 dl.field-list.narrow { 146 --field-indent: 2.4em; 147 } 148 149 ul, ol { 150 padding-left: 1.1em; /* indent by bullet width (Firefox, DejaVu fonts) */ 151 } 152 dl.field-list > dd, 153 dl.docinfo > dd { 154 margin-left: var(--field-indent); /* adapted in media queries or HTML */ 155 } 156 dl.option-list > dd { 157 margin-left: 20%; 158 } 159 /* run-in: start field-body on same line after long field names */ 160 dl.field-list.run-in > dd p { 161 display: block; 162 } 163 /* "description style" like in most dictionaries, encyclopedias etc. */ 164 dl.description { 165 display: flow-root; 166 } 167 dl.description > dt { 168 clear: left; 169 float: left; 170 margin: 0; 171 padding: 0; 172 padding-right: 0.3em; 173 font-weight: bold; 174 } 175 dl.description > dd:after { 176 display: table; 177 content: ""; 178 clear: left; /* clearfix for empty descriptions */ 179 } 180 /* start lists nested in description/field lists on new line */ 181 dd > dl:first-child, 182 dd > ul:first-child, 183 dd > ol:first-child { 184 clear: left; 185 } 186 187 /* disclosures */ 188 details { padding-left: 1em; } 189 summary { margin-left: -1em; } 190 191 /* Footnotes and Citations */ 192 .footnote { 193 font-size: small; 194 } 195 196 /* Images, Figures, and Tables */ 197 figcaption, 198 table > caption { 199 /* font-size: small; */ 200 font-style: italic; 201 } 202 figcaption > .legend { 203 font-size: small; 204 font-style: initial; 205 } 206 figure.numbered > figcaption > p:before { 207 counter-increment: figure; 208 content: "Figure " counter(figure) ": "; 209 font-weight: bold; 210 font-style: initial; 211 } 212 213 table tr { 214 text-align: left; 215 vertical-align: baseline; 216 } 217 table.booktabs { /* "booktabs" style (no vertical lines) */ 218 border-top: 2px solid; 219 border-bottom: 2px solid; 220 } 221 table.booktabs * { 222 border: 0; 223 } 224 table.booktabs th { 225 border-bottom: thin solid; 226 } 227 table.numbered > caption:before { 228 counter-increment: table; 229 content: "Table " counter(table) ": "; 230 font-weight: bold; 231 font-style: initial; 232 } 233 234 /* Admonitions and System Messages */ 235 .admonition, 236 div.system-message { 237 border: thin solid silver; 238 margin: 1em 2%; 239 padding: 0.5em 1em; 240 } 241 .caution p.admonition-title, 242 .attention p.admonition-title, 243 .danger p.admonition-title, 244 .warning p.admonition-title, 245 div.error { 246 color: maroon; 247 } 248 div.system-message > p > span.literal { 249 overflow-wrap: break-word; 250 } 251 252 /* Literal and Code */ 253 pre.literal-block, pre.doctest{ 254 padding: 0.2em; 255 overflow-x: auto; 256 } 257 .literal-block, .doctest, span.literal { 258 background-color: #f0f5f3; 259 } 260 .system-message span.literal { 261 background-color: inherit; 262 } 263 264 /* basic highlighting: for a complete scheme, see */ 265 /* https://docutils.sourceforge.io/sandbox/stylesheets/ */ 266 pre.code .comment, code .comment { color: #5C6576 } 267 pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } 268 pre.code .literal.string, code .literal.string { color: #0C5404 } 269 pre.code .name.builtin, code .name.builtin { color: #352B84 } 270 pre.code .deleted, code .deleted { background-color: #DEB0A1} 271 pre.code .inserted, code .inserted { background-color: #A3D289} 272 273 /* Hyperlink References */ 274 a { 275 text-decoration: none; /* for chromium */ 276 /* Wrap links at any place, if this is the only way to prevent overflow */ 277 overflow-wrap: break-word; 278 } 279 .contents a, a.toc-backref, a.citation-reference { 280 overflow-wrap: inherit; 281 } 282 /* Undecorated Links (see also minimal.css) */ 283 /* a.citation-reference, */ 284 .citation a.fn-backref { 285 color: inherit; 286 } 287 a:hover { 288 text-decoration: underline; 289 } 290 *:hover > a.toc-backref:after, 291 .topic-title:hover > a:after { 292 content: " \2191"; /* ↑ UPWARDS ARROW */ 293 color: grey; 294 } 295 *:hover > a.self-link:after { 296 content: "\1F517"; /* LINK SYMBOL */ 297 color: grey; 298 font-size: smaller; 299 margin-left: 0.2em; 300 } 301 /* highlight specific targets of the current URL */ 302 section:target > h2, section:target > h3, section:target > h4, 303 section:target > h5, section:target > h6, 304 span:target + h2, span:target + h3, span:target + h4, 305 span:target + h5, span:target + h6, 306 dt:target, span:target, p:target, 307 .contents :target, 308 .contents:target > .topic-title, 309 aside.system-message:target, 310 [role="doc-biblioentry"]:target, 311 [role="doc-biblioref"]:target, 312 [role="note"]:target, /* Docutils 0.18 and 0.19 */ 313 [role="doc-footnote"]:target, /* Docutils >= 0.20 */ 314 [role="doc-noteref"]:target { 315 background-color: #d2e6ec; 316 } 317 318 /* Block Alignment */ 319 /* Let content flow to the side of aligned images and figures */ 320 321 /* no floats around this elements */ 322 footer, header, hr, 323 h1, h2, h3 { 324 clear: both; 325 } 326 327 img.align-left, 328 svg.align-left, 329 video.align-left, 330 figure.align-left, 331 div.align-left, 332 table.align-left { 333 margin-left: 0; 334 padding-left: 0; 335 margin-right: 0.5em; 336 clear: left; 337 float: left; 338 } 339 img.align-right, 340 svg.align-right, 341 video.align-right, 342 figure.align-right, 343 div.align-right, 344 table.align-right { 345 margin-left: 0.5em; 346 margin-right: 0; 347 clear: right; 348 float: right; 349 } 350 351 /* Margin Elements */ 352 /* see below for screen size dependent rules */ 353 .sidebar, 354 .marginal, 355 .admonition.marginal { 356 max-width: 40%; 357 border: none; 358 background-color: #efefea; 359 margin: 0.5em var(--sidebar-margin-right) 0.5em 1em; 360 padding: 0.5em; 361 padding-left: 0.7em; 362 clear: right; 363 float: right; 364 font-size: small; 365 } 366 .sidebar { 367 width: 40%; 368 } 369 370 /* Adaptive page layout */ 371 /* ==================== */ 372 373 @media (max-width: 30em) { 374 /* Smaller margins and no floating elements for small screens */ 375 /* (main text less than 40 characters/line) */ 376 body > * { 377 padding: 0.5rem 5%; 378 line-height: 1.4 379 } 380 .sidebar, 381 .marginal, 382 .admonition.marginal { 383 width: auto; 384 max-width: 100%; 385 float: none; 386 } 387 dl.option-list, 388 pre { 389 margin-left: 0; 390 } 391 body { 392 --field-indent: 4em; 393 } 394 dl.docinfo { 395 --field-indent: 5%; 396 } 397 pre, pre * { 398 font-size: 0.9em; 399 /* overflow: auto; */ 400 } 401 } 402 403 @media (min-width: 54em) { 404 /* Move ToC to the left */ 405 /* Main text width before: 70% ≙ 35em ≙ 75…95 chrs (Dejavu/Times) */ 406 /* after: ≳ 30em ≙ 54…70 chrs (Dejavu/Times) */ 407 body.with-toc { 408 padding-left: 8%; 409 } 410 body.with-toc > * { 411 margin-left: 0; 412 padding-left: 22rem; /* fallback for webkit */ 413 padding-left: min(22%, 22rem); 414 padding-right: 7%; 415 } 416 main > nav.contents { /* global ToC */ 417 position: fixed; 418 top: 0; 419 left: 0; 420 width: min(25%, 25em); 421 height: 100vh; 422 margin: 0; 423 background-color: #fafaf6; 424 padding: 1em 2% 0 2%; 425 overflow: auto; 426 } 427 main > nav.contents > * { 428 padding-left: 0; 429 line-height: 1.4; 430 } 431 main > nav.contents a { 432 color: inherit; 433 } 434 } 435 436 @media (min-width: 70em) { 437 body { 438 --field-indent: 9em; 439 } 440 } 441 442 @media (min-width: 77em) { 443 /* Move marginalia to 6rem from right border */ 444 /* .sidebar, */ 445 /* .marginal, */ 446 /* .admonition.marginal { */ 447 /* margin-right: calc(6rem - 15%); */ 448 /* } */ 449 /* BUG: margin is calculated for break point width */ 450 /* workaround: variable + many breakpoints */ 451 body > * { 452 padding-left: 18%; 453 padding-right: 28%; /* fallback for webkit */ 454 padding-right: min(28%, 28rem); 455 --sidebar-margin-right: -20rem; 456 } 457 /* limit main text to ~ 50em ≙ 85…100 characters DejaVu rsp. …120 Times */ 458 body.with-toc > * { 459 padding-left: min(22%, 22rem); 460 padding-right: calc(78% - 50rem); /* fallback for webkit */ 461 padding-right: min(78% - 50rem, 28rem); 462 --sidebar-margin-right: 0; 463 } 464 } 465 466 @media (min-width: 85em) { 467 body.with-toc > * { 468 --sidebar-margin-right: -9rem; 469 } 470 } 471 472 @media (min-width: 90em) { 473 /* move marginalia into the margin */ 474 body > * { 475 padding-left: min(22%, 22rem); 476 --sidebar-margin-right: -23rem; 477 } 478 body.with-toc > * { 479 --sidebar-margin-right: -14rem; 480 } 481 } 482 483 @media (min-width: 99em) { 484 /* move marginalia out of main text area */ 485 body.with-toc > * { 486 --sidebar-margin-right: -20rem; 487 } 488 body > *, body.with-toc > * { /* for webkit */ 489 padding-left: 22rem; 490 padding-right: 28rem; 491 } 492 .admonition.marginal, 493 .marginal { 494 width: 40%; /* make marginal figures, ... "full width" */ 495 } 496 } 497 498 @media (min-width: 104em) { 499 body.with-toc > * { 500 --sidebar-margin-right: -23rem; 501 } 502 } 503 504 </style> 505 <style type="text/css"> 506 507 /* Minimal style sheet for the HTML output of Docutils. */ 508 /* */ 509 /* :Author: Günter Milde, based on html4css1.css by David Goodger */ 510 /* :Id: $Id: minimal.css 10018 2025-03-06 16:19:15Z milde $ */ 511 /* :Copyright: © 2015, 2021 Günter Milde. */ 512 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 513 /* in short: */ 514 /* */ 515 /* Copying and distribution of this file, with or without modification, */ 516 /* are permitted in any medium without royalty provided the copyright */ 517 /* notice and this notice are preserved. */ 518 /* */ 519 /* This file is offered as-is, without any warranty. */ 520 /* */ 521 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 522 523 /* This CSS3 stylesheet defines rules for Docutils elements without */ 524 /* HTML equivalent. It is required to make the document semantics visible. */ 525 /* */ 526 /* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */ 527 528 /* titles */ 529 p.topic-title, 530 p.admonition-title, 531 p.system-message-title { 532 font-weight: bold; 533 } 534 p.sidebar-title, 535 p.rubric { 536 font-weight: bold; 537 font-size: larger; 538 } 539 p.rubric { 540 color: maroon; 541 } 542 p.subtitle, 543 p.section-subtitle, 544 p.sidebar-subtitle { 545 font-weight: bold; 546 margin-top: -0.5em; 547 } 548 h1 + p.subtitle { 549 font-size: 1.6em; 550 } 551 a.toc-backref { 552 color: inherit; 553 text-decoration: none; 554 } 555 556 /* Warnings, Errors */ 557 .system-messages h2, 558 .system-message-title, 559 pre.problematic, 560 span.problematic { 561 color: red; 562 } 563 564 /* Inline Literals */ 565 .docutils.literal { 566 font-family: monospace; 567 white-space: pre-wrap; 568 } 569 /* do not wrap at hyphens and similar: */ 570 .literal > span.pre { white-space: nowrap; } 571 572 /* keep line-breaks (\n) visible */ 573 .pre-wrap { white-space: pre-wrap; } 574 575 /* Lists */ 576 577 /* compact and simple lists: no margin between items */ 578 .simple li, .simple ul, .simple ol, .simple > li p, 579 .compact li, .compact ul, .compact ol, .compact > li p, 580 dl.simple > dd, dl.compact > dd, dl.docinfo > dd { 581 margin-top: 0; 582 margin-bottom: 0; 583 } 584 /* Nested Paragraphs */ 585 p:first-child { margin-top: 0; } 586 p:last-child { margin-bottom: 0; } 587 details > p:last-child { margin-bottom: 1em; } 588 589 /* Table of Contents */ 590 .contents ul.auto-toc { /* section numbers present */ 591 list-style-type: none; 592 } 593 594 /* Enumerated Lists */ 595 ol.arabic { list-style: decimal } 596 ol.loweralpha { list-style: lower-alpha } 597 ol.upperalpha { list-style: upper-alpha } 598 ol.lowerroman { list-style: lower-roman } 599 ol.upperroman { list-style: upper-roman } 600 601 /* Definition Lists and Derivatives */ 602 dt .classifier { font-style: italic } 603 dt .classifier:before { 604 font-style: normal; 605 margin: 0.5em; 606 content: ":"; 607 } 608 /* Field Lists and similar */ 609 /* bold field name, content starts on the same line */ 610 dl.field-list, 611 dl.option-list, 612 dl.docinfo { 613 display: flow-root; 614 } 615 dl.field-list > dt, 616 dl.option-list > dt, 617 dl.docinfo > dt { 618 font-weight: bold; 619 clear: left; 620 float: left; 621 margin: 0; 622 padding: 0; 623 padding-right: 0.25em; 624 } 625 /* Offset for field content (corresponds to the --field-name-limit option) */ 626 dl.field-list > dd, 627 dl.option-list > dd, 628 dl.docinfo > dd { 629 margin-left: 9em; /* ca. 14 chars in the test examples, fit all Docinfo fields */ 630 } 631 /* start nested lists on new line */ 632 dd > dl:first-child, 633 dd > ul:first-child, 634 dd > ol:first-child { 635 clear: left; 636 } 637 /* start field-body on a new line after long field names */ 638 dl.field-list > dd > *:first-child, 639 dl.option-list > dd > *:first-child 640 { 641 display: inline-block; 642 width: 100%; 643 margin: 0; 644 } 645 646 /* Bibliographic Fields (docinfo) */ 647 dl.docinfo pre.address { 648 font: inherit; 649 margin: 0; 650 } 651 dl.docinfo > dd.authors > p { margin: 0; } 652 653 /* Option Lists */ 654 dl.option-list > dt { font-weight: normal; } 655 span.option { white-space: nowrap; } 656 657 /* Footnotes and Citations */ 658 659 .footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */ 660 /* hanging indent */ 661 .citation { padding-left: 2em; } 662 .footnote { padding-left: 1.7em; } 663 .footnote.superscript { padding-left: 1.0em; } 664 .citation > .label { margin-left: -2em; } 665 .footnote > .label { margin-left: -1.7em; } 666 .footnote.superscript > .label { margin-left: -1.0em; } 667 668 .footnote > .label + *, 669 .citation > .label + * { 670 display: inline-block; 671 margin-top: 0; 672 vertical-align: top; 673 } 674 .footnote > .backrefs + *, 675 .citation > .backrefs + * { 676 margin-top: 0; 677 } 678 .footnote > .label + p, .footnote > .backrefs + p, 679 .citation > .label + p, .citation > .backrefs + p { 680 display: inline; 681 vertical-align: inherit; 682 } 683 684 .backrefs { user-select: none; } 685 .backrefs > a { font-style: italic; } 686 687 /* superscript footnotes */ 688 a[role="doc-noteref"].superscript, 689 .footnote.superscript > .label, 690 .footnote.superscript > .backrefs { 691 vertical-align: super; 692 font-size: smaller; 693 line-height: 1; 694 } 695 a[role="doc-noteref"].superscript > .fn-bracket, 696 .footnote.superscript > .label > .fn-bracket { 697 /* hide brackets in display but leave for copy/paste */ 698 display: inline-block; 699 width: 0; 700 overflow: hidden; 701 } 702 [role="doc-noteref"].superscript + [role="doc-noteref"].superscript { 703 padding-left: 0.15em; /* separate consecutive footnote references */ 704 /* TODO: unfortunately, "+" also selects with text between the references. */ 705 } 706 707 /* Alignment */ 708 .align-left { 709 text-align: left; 710 margin-right: auto; 711 } 712 .align-center { 713 text-align: center; 714 margin-left: auto; 715 margin-right: auto; 716 } 717 .align-right { 718 text-align: right; 719 margin-left: auto; 720 } 721 .align-top { vertical-align: top; } 722 .align-middle { vertical-align: middle; } 723 .align-bottom { vertical-align: bottom; } 724 725 /* reset inner alignment in figures and tables */ 726 figure.align-left, figure.align-right, 727 table.align-left, table.align-center, table.align-right { 728 text-align: inherit; 729 } 730 731 /* Text Blocks */ 732 .topic { margin: 1em 2em; } 733 .sidebar, 734 .admonition, 735 .system-message { 736 margin: 1em 2em; 737 border: thin solid; 738 padding: 0.5em 1em; 739 } 740 div.line-block { display: block; } 741 div.line-block div.line-block, pre { margin-left: 2em; } 742 743 /* Code line numbers: don't copy with drag-and-drop */ 744 pre.code .ln { display: none; } 745 pre.code code:before { 746 content: attr(data-lineno); 747 font-size: small; 748 color: gray; 749 } 750 751 /* Tables */ 752 table { 753 border-collapse: collapse; 754 } 755 td, th { 756 border: thin solid silver; 757 padding: 0 1ex; 758 } 759 .borderless td, .borderless th { 760 border: 0; 761 padding: 0; 762 padding-right: 0.5em /* separate table cells */ 763 } 764 765 table > caption, figcaption { 766 text-align: left; 767 margin-top: 0.2em; 768 margin-bottom: 0.2em; 769 } 770 table.captionbelow { 771 caption-side: bottom; 772 } 773 774 /* MathML (see "math.css" for --math-output=HTML) */ 775 math .boldsymbol { font-weight: bold; } 776 math.boxed, math .boxed {padding: 0.25em; border: thin solid; } 777 /* style table similar to AMS "align" or "aligned" environment: */ 778 mtable.cases > mtr > mtd { text-align: left; } 779 mtable.ams-align > mtr > mtd { padding-left: 0; padding-right: 0; } 780 mtable.ams-align > mtr > mtd:nth-child(2n) { text-align: left; } 781 mtable.ams-align > mtr > mtd:nth-child(2n+1) { text-align: right; } 782 mtable.ams-align > mtr > mtd:nth-child(2n+3) { padding-left: 2em; } 783 .mathscr mi, mi.mathscr { 784 font-family: STIX, XITSMathJax_Script, rsfs10, 785 "Asana Math", Garamond, cursive; 786 } 787 788 /* Document Header and Footer */ 789 header { border-bottom: 1px solid black; } 790 footer { border-top: 1px solid black; } 791 792 /* Images are block-level by default in Docutils */ 793 /* New HTML5 block elements: set display for older browsers */ 794 img, svg, header, footer, main, aside, nav, section, figure, video, details { 795 display: block; 796 } 797 svg { width: auto; height: auto; } /* enable scaling of SVG images */ 798 /* inline images */ 799 800 p img, p svg, p video, 801 h1 img, h2 img, h3 img, h4 img, h5 img, h6 img, 802 h1 svg, h2 svg, h3 svg, h4 svg, h5 svg, h6 svg { 803 display: inline; 804 } 805 806 </style> 807 <style type="text/css"> 808 809 /* italic-field-name.css: */ 810 /* Alternative style for Docutils field-lists */ 811 812 /* :Copyright: © 2023 Günter Milde. */ 813 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 814 /* in short: */ 815 /* */ 816 /* Copying and distribution of this file, with or without modification, */ 817 /* are permitted in any medium without royalty provided the copyright */ 818 /* notice and this notice are preserved. */ 819 /* */ 820 /* This file is offered as-is, without any warranty. */ 821 /* */ 822 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 823 824 /* In many contexts, a **bold** field name is too heavy styling. */ 825 /* Use *italic* instead:: */ 826 827 dl.field-list > dt { 828 font-weight: normal; 829 font-style: italic; 830 } 831 dl.field-list > dt > .colon { 832 font-style: normal; 833 padding-left: 0.05ex; 834 } 835 836 </style> 837 </head> 838 <body class="with-toc"> 839 <header> 840 <p>[ anon.fail: <a class="reference external" href="/">Homepage</a> | <a class="reference external" href="/news.html">News</a> ] [ Guides: <a class="reference external" href="/guides/tor.html">Tor</a> | <a class="reference external" href="/guides/hidden-service.html">Hidden Service</a> | <a class="reference external" href="/guides/kvm.html">KVM</a> | <a class="reference external" href="/guides/monero.html">Monero</a> | <a class="reference external" href="/guides/simplex-chat.html">SimpleX</a> ] [ Dangers: <a class="reference external" href="/dangers/kyc.html">KYC</a> ]</p> 841 </header> 842 <main id="restructuredtext-directives"> 843 <h1 class="title">reStructuredText Directives</h1> 844 <dl class="docinfo"> 845 <dt class="author">Author<span class="colon">:</span></dt> 846 <dd class="author"><p>David Goodger</p></dd> 847 <dt class="contact">Contact<span class="colon">:</span></dt> 848 <dd class="contact"><a class="reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></dd> 849 <dt class="revision">Revision<span class="colon">:</span></dt> 850 <dd class="revision">10190</dd> 851 <dt class="date">Date<span class="colon">:</span></dt> 852 <dd class="date">2025-07-30</dd> 853 <dt class="copyright">Copyright<span class="colon">:</span></dt> 854 <dd class="copyright">This document has been placed in the public domain.</dd> 855 </dl> 856 <!-- Minimal menu bar for inclusion in documentation sources 857 in ``docutils/docs/*/`` sub-sub-diretories. 858 859 Attention: this is not a standalone document. --> 860 <nav class="contents" id="contents" role="doc-toc"> 861 <p class="topic-title">Contents</p> 862 <ul class="simple"> 863 <li><p><a class="reference internal" href="#admonitions" id="toc-entry-1">Admonitions</a></p> 864 <ul> 865 <li><p><a class="reference internal" href="#specific-admonitions" id="toc-entry-2">Specific Admonitions</a></p></li> 866 <li><p><a class="reference internal" href="#generic-admonition" id="toc-entry-3">Generic Admonition</a></p></li> 867 </ul> 868 </li> 869 <li><p><a class="reference internal" href="#images" id="toc-entry-4">Images</a></p> 870 <ul> 871 <li><p><a class="reference internal" href="#image" id="toc-entry-5">Image</a></p></li> 872 <li><p><a class="reference internal" href="#figure" id="toc-entry-6">Figure</a></p></li> 873 </ul> 874 </li> 875 <li><p><a class="reference internal" href="#body-elements" id="toc-entry-7">Body Elements</a></p> 876 <ul> 877 <li><p><a class="reference internal" href="#topic" id="toc-entry-8">Topic</a></p></li> 878 <li><p><a class="reference internal" href="#sidebar" id="toc-entry-9">Sidebar</a></p></li> 879 <li><p><a class="reference internal" href="#line-block" id="toc-entry-10">Line Block</a></p></li> 880 <li><p><a class="reference internal" href="#parsed-literal-block" id="toc-entry-11">Parsed Literal Block</a></p></li> 881 <li><p><a class="reference internal" href="#code" id="toc-entry-12">Code</a></p></li> 882 <li><p><a class="reference internal" href="#math" id="toc-entry-13">Math</a></p></li> 883 <li><p><a class="reference internal" href="#rubric" id="toc-entry-14">Rubric</a></p></li> 884 <li><p><a class="reference internal" href="#epigraph" id="toc-entry-15">Epigraph</a></p></li> 885 <li><p><a class="reference internal" href="#highlights" id="toc-entry-16">Highlights</a></p></li> 886 <li><p><a class="reference internal" href="#pull-quote" id="toc-entry-17">Pull-Quote</a></p></li> 887 <li><p><a class="reference internal" href="#compound-paragraph" id="toc-entry-18">Compound Paragraph</a></p></li> 888 <li><p><a class="reference internal" href="#container" id="toc-entry-19">Container</a></p></li> 889 </ul> 890 </li> 891 <li><p><a class="reference internal" href="#tables" id="toc-entry-20">Tables</a></p> 892 <ul> 893 <li><p><a class="reference internal" href="#table" id="toc-entry-21">Table</a></p></li> 894 <li><p><a class="reference internal" href="#csv-table-1" id="toc-entry-22">CSV Table</a></p></li> 895 <li><p><a class="reference internal" href="#list-table-1" id="toc-entry-23">List Table</a></p></li> 896 </ul> 897 </li> 898 <li><p><a class="reference internal" href="#document-parts" id="toc-entry-24">Document Parts</a></p> 899 <ul> 900 <li><p><a class="reference internal" href="#table-of-contents" id="toc-entry-25">Table of Contents</a></p></li> 901 <li><p><a class="reference internal" href="#automatic-section-numbering" id="toc-entry-26">Automatic Section Numbering</a></p></li> 902 <li><p><a class="reference internal" href="#document-header-footer" id="toc-entry-27">Document Header & Footer</a></p></li> 903 </ul> 904 </li> 905 <li><p><a class="reference internal" href="#references" id="toc-entry-28">References</a></p> 906 <ul> 907 <li><p><a class="reference internal" href="#target-footnotes" id="toc-entry-29">Target Footnotes</a></p></li> 908 <li><p><a class="reference internal" href="#footnotes" id="toc-entry-30">Footnotes</a></p></li> 909 <li><p><a class="reference internal" href="#citations" id="toc-entry-31">Citations</a></p></li> 910 </ul> 911 </li> 912 <li><p><a class="reference internal" href="#directives-for-substitution-definitions" id="toc-entry-32">Directives for Substitution Definitions</a></p> 913 <ul> 914 <li><p><a class="reference internal" href="#inline-images" id="toc-entry-33">Inline Images</a></p></li> 915 <li><p><a class="reference internal" href="#replacement-text" id="toc-entry-34">Replacement Text</a></p></li> 916 <li><p><a class="reference internal" href="#unicode-character-codes" id="toc-entry-35">Unicode Character Codes</a></p></li> 917 <li><p><a class="reference internal" href="#date" id="toc-entry-36">Date</a></p></li> 918 </ul> 919 </li> 920 <li><p><a class="reference internal" href="#miscellaneous" id="toc-entry-37">Miscellaneous</a></p> 921 <ul> 922 <li><p><a class="reference internal" href="#including-an-external-document-fragment" id="toc-entry-38">Including an External Document Fragment</a></p></li> 923 <li><p><a class="reference internal" href="#raw-data-pass-through" id="toc-entry-39">Raw Data Pass-Through</a></p></li> 924 <li><p><a class="reference internal" href="#class" id="toc-entry-40">Class</a></p></li> 925 <li><p><a class="reference internal" href="#custom-interpreted-text-roles" id="toc-entry-41">Custom Interpreted Text Roles</a></p></li> 926 <li><p><a class="reference internal" href="#setting-the-default-interpreted-text-role" id="toc-entry-42">Setting the Default Interpreted Text Role</a></p></li> 927 <li><p><a class="reference internal" href="#metadata" id="toc-entry-43">Metadata</a></p></li> 928 <li><p><a class="reference internal" href="#metadata-document-title" id="toc-entry-44">Metadata Document Title</a></p></li> 929 <li><p><a class="reference internal" href="#restructuredtext-test-directive" id="toc-entry-45">Restructuredtext-Test-Directive</a></p></li> 930 </ul> 931 </li> 932 <li><p><a class="reference internal" href="#common-options" id="toc-entry-46">Common Options</a></p></li> 933 <li><p><a class="reference internal" href="#common-option-value-types" id="toc-entry-47">Common Option Value Types</a></p></li> 934 </ul> 935 </nav> 936 <p>This document describes the directives implemented in the reference 937 reStructuredText parser.</p> 938 <p>Directives have the following syntax:</p> 939 <pre class="literal-block">+-------+-------------------------------+ 940 | ".. " | directive type "::" directive | 941 +-------+ block | 942 | | 943 +-------------------------------+</pre> 944 <p>Directives begin with an explicit markup start (two periods and a 945 space), followed by the directive type and two colons (collectively, 946 the "directive marker"). The directive block begins immediately after 947 the directive marker, and includes all subsequent indented lines. The 948 directive block is divided into arguments, options (a field list), and 949 content (in that order), any of which may appear. See the <a class="reference external" href="restructuredtext.html#directives">Directives</a> 950 section in the <a class="reference external" href="restructuredtext.html">reStructuredText Markup Specification</a> for syntax 951 details.</p> 952 <p>Descriptions below list "doctree elements" (document tree element 953 names; XML DTD generic identifiers) corresponding to individual directives. 954 For details on the hierarchy of elements, please see <a class="reference external" href="../doctree.html">The Docutils 955 Document Tree</a> and the <a class="reference external" href="../docutils.dtd">Docutils Generic DTD</a> XML document type definition. 956 For directive implementation details, see <a class="reference external" href="../../howto/rst-directives.html">Creating reStructuredText 957 Directives</a> and the <a class="reference external" href="../../../docutils/parsers/rst/directives">source</a>.</p> 958 <section id="admonitions"> 959 <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Admonitions</a></h2> 960 <p>Admonitions ("safety messages" or "hazard statements") can appear anywhere 961 an ordinary body element can. They contain arbitrary body elements. 962 Typically, an admonition is rendered as an offset block in a document, 963 sometimes outlined or shaded.</p> 964 <p>Docutils defines a <a class="reference internal" href="#generic-admonition">generic admonition</a> as well as a set of 965 <a class="reference internal" href="#specific-admonitions">specific admonitions</a>.</p> 966 <section id="specific-admonitions"> 967 <span id="warning"></span><span id="tip"></span><span id="note"></span><span id="important"></span><span id="hint"></span><span id="error"></span><span id="danger"></span><span id="caution"></span><span id="attention"></span><h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Specific Admonitions</a></h3> 968 <dl class="field-list simple" style="--field-indent: 13em;"> 969 <dt>Directive Types<span class="colon">:</span></dt> 970 <dd><p>"attention", "caution", "danger", "error", "hint", 971 "important", "note", "tip", "warning"</p> 972 </dd> 973 <dt>Doctree Elements<span class="colon">:</span></dt> 974 <dd><p><a class="reference external" href="../doctree.html#attention"><attention></a>, <a class="reference external" href="../doctree.html#caution"><caution></a>, <a class="reference external" href="../doctree.html#danger"><danger></a>, 975 <a class="reference external" href="../doctree.html#error"><error></a>, <a class="reference external" href="../doctree.html#hint"><hint></a>, <a class="reference external" href="../doctree.html#important"><important></a>, 976 <a class="reference external" href="../doctree.html#note"><note></a>, <a class="reference external" href="../doctree.html#tip"><tip></a>, <a class="reference external" href="../doctree.html#warning"><warning></a></p> 977 </dd> 978 <dt>Directive Arguments<span class="colon">:</span></dt> 979 <dd><p>none</p> 980 </dd> 981 <dt>Directive Options<span class="colon">:</span></dt> 982 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 983 </dd> 984 <dt>Directive Content<span class="colon">:</span></dt> 985 <dd><p>Interpreted as body elements.</p> 986 </dd> 987 </dl> 988 <p>Specific admonitions are rendered with a title matching the admonition type. 989 For example:</p> 990 <pre class="literal-block">.. DANGER:: 991 Beware killer rabbits!</pre> 992 <p>This directive might be rendered something like this:</p> 993 <pre class="literal-block">+------------------------+ 994 | !DANGER! | 995 | | 996 | Beware killer rabbits! | 997 +------------------------+</pre> 998 <p>Any text immediately following the directive indicator (on the same 999 line and/or indented on following lines) is interpreted as a directive 1000 block and is parsed for normal body elements. For example, the 1001 following "note" admonition directive contains one paragraph and a 1002 bullet list consisting of two list items:</p> 1003 <pre class="literal-block">.. note:: This is a note admonition. 1004 This is the second line of the first paragraph. 1005 1006 - The note contains all indented body elements 1007 following. 1008 - It includes this bullet list.</pre> 1009 </section> 1010 <section id="generic-admonition"> 1011 <span id="admonition"></span><h3><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Generic Admonition</a></h3> 1012 <dl class="field-list simple" style="--field-indent: 13em;"> 1013 <dt>Directive Type<span class="colon">:</span></dt> 1014 <dd><p>"admonition"</p> 1015 </dd> 1016 <dt>Doctree Elements<span class="colon">:</span></dt> 1017 <dd><p><a class="reference external" href="../doctree.html#admonition"><admonition></a>, <a class="reference external" href="../doctree.html#title"><title></a></p> 1018 </dd> 1019 <dt>Directive Arguments<span class="colon">:</span></dt> 1020 <dd><p>one, required (admonition title)</p> 1021 </dd> 1022 <dt>Directive Options<span class="colon">:</span></dt> 1023 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1024 </dd> 1025 <dt>Directive Content<span class="colon">:</span></dt> 1026 <dd><p>Interpreted as body elements.</p> 1027 </dd> 1028 </dl> 1029 <p>This is a generic, titled admonition. The title may be anything the 1030 author desires.</p> 1031 <p>The author-supplied title is also used as a <a class="reference external" href="../doctree.html#classes">classes attribute</a> value 1032 after <a class="reference internal" href="#identifier-normalization">identifier normalization</a> and adding the prefix "admonition-". 1033 For example, this admonition:</p> 1034 <pre class="literal-block">.. admonition:: And, by the way... 1035 1036 You can make up your own admonition too.</pre> 1037 <p>becomes the following document tree (pseudo-XML):</p> 1038 <pre class="literal-block"><document source="test data"> 1039 <admonition classes="admonition-and-by-the-way"> 1040 <title> 1041 And, by the way... 1042 <paragraph> 1043 You can make up your own admonition too.</pre> 1044 <p>The <a class="reference internal" href="#class-option">class</a> option overrides the generated 1045 <a class="reference external" href="../doctree.html#classes">classes attribute</a> value.</p> 1046 </section> 1047 </section> 1048 <section id="images"> 1049 <h2><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Images</a></h2> 1050 <p>There are two directives to include images: <a class="reference internal" href="#image">image</a> and <a class="reference internal" href="#figure">figure</a>. 1051 The table below provides a non exhaustive overview of 1052 supported image formats.</p> 1053 <aside class="admonition attention"> 1054 <p class="admonition-title">Attention!</p> 1055 <p>It is up to the author to ensure compatibility of the image data format 1056 with the output format or user agent (LaTeX engine, <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types">HTML browser</a>, …).</p> 1057 </aside> 1058 <table id="image-formats"> 1059 <thead> 1060 <tr><th class="head"><!-- --> 1061 </th> 1062 <th class="head"><p>SVG</p></th> 1063 <th class="head"><p>PDF</p></th> 1064 <th class="head"><p>PNG</p></th> 1065 <th class="head"><p>JPG</p></th> 1066 <th class="head"><p>GIF</p></th> 1067 <th class="head"><p>APNG</p></th> 1068 <th class="head"><p>AVIF</p></th> 1069 <th class="head"><p>WebM</p></th> 1070 <th class="head"><p>MP4</p></th> 1071 <th class="head"><p>OGG</p></th> 1072 </tr> 1073 </thead> 1074 <tbody> 1075 <tr><td><!-- --> 1076 </td> 1077 <td colspan="2"><p>vector</p></td> 1078 <td colspan="5"><p>raster</p></td> 1079 <td colspan="3"><p>video <a class="footnote-reference brackets" href="#video" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></td> 1080 </tr> 1081 <tr><td><p><a class="reference external" href="../../user/html.html#html4css1">HTML4</a> <a class="footnote-reference brackets" href="#footnote-1" id="footnote-reference-2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p></td> 1082 <td><p>✓</p></td> 1083 <td></td> 1084 <td><p>✓</p></td> 1085 <td><p>✓</p></td> 1086 <td><p>✓</p></td> 1087 <td><p>(✓)</p></td> 1088 <td><p>(✓)</p></td> 1089 <td><p>(✓)</p></td> 1090 <td><p>(✓)</p></td> 1091 <td><p>(✓)</p></td> 1092 </tr> 1093 <tr><td><p><a class="reference external" href="../../user/html.html#html5">HTML5</a></p></td> 1094 <td><p>✓</p></td> 1095 <td></td> 1096 <td><p>✓</p></td> 1097 <td><p>✓</p></td> 1098 <td><p>✓</p></td> 1099 <td><p>✓</p></td> 1100 <td><p>✓</p></td> 1101 <td><p>✓</p></td> 1102 <td><p>✓</p></td> 1103 <td><p>✓</p></td> 1104 </tr> 1105 <tr><td><p><a class="reference external" href="../../user/latex.html">LaTeX</a> <a class="footnote-reference brackets" href="#footnote-2" id="footnote-reference-3" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p></td> 1106 <td><p>✓ <a class="footnote-reference brackets" href="#footnote-3" id="footnote-reference-4" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p></td> 1107 <td><p>✓</p></td> 1108 <td><p>✓</p></td> 1109 <td><p>✓</p></td> 1110 <td></td> 1111 <td></td> 1112 <td></td> 1113 <td></td> 1114 <td></td> 1115 <td></td> 1116 </tr> 1117 <tr><td><p><a class="reference external" href="../../user/manpage.html">manpage</a></p></td> 1118 <td></td> 1119 <td></td> 1120 <td></td> 1121 <td></td> 1122 <td></td> 1123 <td></td> 1124 <td></td> 1125 <td></td> 1126 <td></td> 1127 <td></td> 1128 </tr> 1129 <tr><td><p><a class="reference external" href="../../user/odt.html">ODT</a></p></td> 1130 <td><p>✓</p></td> 1131 <td><p>✓</p></td> 1132 <td><p>✓</p></td> 1133 <td><p>✓</p></td> 1134 <td><p>✓</p></td> 1135 <td></td> 1136 <td></td> 1137 <td></td> 1138 <td></td> 1139 <td></td> 1140 </tr> 1141 </tbody> 1142 </table> 1143 <aside class="footnote-list brackets"> 1144 <aside class="footnote brackets" id="video" role="doc-footnote"> 1145 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">1</a><span class="fn-bracket">]</span></span> 1146 <p>The <a class="reference external" href="../../user/html.html#html5">html5 writer</a> uses the <span class="docutils literal"><video></span> tag if the image URI 1147 ends with an extension matching one of the listed video formats 1148 (since Docutils 0.17).</p> 1149 </aside> 1150 <aside class="footnote brackets" id="footnote-1" role="doc-footnote"> 1151 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-2">2</a><span class="fn-bracket">]</span></span> 1152 <p>The html4 writer uses an <span class="docutils literal"><object></span> tag for SVG images and 1153 videos for compatibility with older browsers and for XHTML1.1 1154 conformance respectively.</p> 1155 </aside> 1156 <aside class="footnote brackets" id="footnote-2" role="doc-footnote"> 1157 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-3">3</a><span class="fn-bracket">]</span></span> 1158 <p>When compiling with <span class="docutils literal">pdflatex</span>, <span class="docutils literal">xelatex</span>, or <span class="docutils literal">lualatex</span>. 1159 The original <span class="docutils literal">latex</span> engine supports only the EPS image format. 1160 Some build systems, e.g. <a class="reference external" href="https://gitlab.com/latex-rubber/rubber">rubber</a> support additional formats 1161 via on-the-fly image conversion. For details, see section 1162 <a class="reference external" href="../../user/latex.html#image-inclusion">image inclusion</a> in the LaTeX writer documentation.</p> 1163 </aside> 1164 <aside class="footnote brackets" id="footnote-3" role="doc-footnote"> 1165 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-4">4</a><span class="fn-bracket">]</span></span> 1166 <p>New in Docutils 0.22. 1167 The <a class="reference external" href="https://ctan.org/pkg/svg">"svg" package</a> must be listed in the <a class="reference external" href="../../user/config.html#stylesheet-latex-writers">stylesheet</a> setting.</p> 1168 </aside> 1169 </aside> 1170 <section id="image"> 1171 <h3><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Image</a></h3> 1172 <dl class="field-list simple" style="--field-indent: 13em;"> 1173 <dt>Directive Type<span class="colon">:</span></dt> 1174 <dd><p>"image"</p> 1175 </dd> 1176 <dt>Doctree Elements<span class="colon">:</span></dt> 1177 <dd><p><a class="reference external" href="../doctree.html#image"><image></a>, <a class="reference external" href="../doctree.html#reference"><reference></a> (only with option "<a class="reference internal" href="#target">target</a>")</p> 1178 </dd> 1179 <dt>Directive Arguments<span class="colon">:</span></dt> 1180 <dd><p>one, required (image <a class="reference internal" href="#uri">URI</a>)</p> 1181 </dd> 1182 <dt>Directive Options<span class="colon">:</span></dt> 1183 <dd><p><a class="reference internal" href="#image-options">see below</a></p> 1184 </dd> 1185 <dt>Directive Content<span class="colon">:</span></dt> 1186 <dd><p>none</p> 1187 </dd> 1188 <dt>Configuration Setting<span class="colon">:</span></dt> 1189 <dd><p><a class="reference external" href="../../user/config.html#image-loading">image_loading</a> (only <a class="reference external" href="../../user/html.html#html5">HTML5 writer</a>)</p> 1190 </dd> 1191 </dl> 1192 <p>An "image" is a simple picture:</p> 1193 <pre class="literal-block">.. image:: picture.png</pre> 1194 <p>A <a class="reference internal" href="#uri-reference">URI reference</a> to the image source file is specified in the directive 1195 argument. As with hyperlink targets, the image URI may begin on the 1196 same line as the explicit markup start and target name, or it may 1197 begin in an indented text block immediately following, with no 1198 intervening blank lines. If there are multiple lines in the link 1199 block, they are stripped of leading and trailing whitespace and joined 1200 together.</p> 1201 <p>Optionally, the image link block may contain a flat field list, the 1202 <a class="reference internal" href="#image-options">image options</a>. For example:</p> 1203 <pre class="literal-block">.. image:: picture.jpeg 1204 :height: 100px 1205 :width: 200 px 1206 :scale: 50 % 1207 :loading: embed 1208 :alt: alternate text 1209 :align: right</pre> 1210 <p><em>Inline images</em> can be defined with an "image" directive in a <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution 1211 definition</a>, e.g.</p> 1212 <pre class="literal-block">|Red light| means stop, |green light| means go. 1213 1214 .. |red light| image:: red_light.png 1215 :align: top 1216 .. |green light| image:: green_light.png 1217 :align: bottom</pre> 1218 <p id="image-options">The "image" directive recognizes the common options <a class="reference internal" href="#class-option">class</a> 1219 and <a class="reference internal" href="#name">name</a> as well as</p> 1220 <dl> 1221 <dt><span class="docutils literal">align</span><span class="classifier">"top", "middle", "bottom", "left", "center", or "right"</span></dt> 1222 <dd><p>The alignment of the image, equivalent to the HTML <span class="docutils literal"><img></span> tag's 1223 deprecated "align" attribute or the corresponding "vertical-align" and 1224 "text-align" CSS properties. 1225 The values "top", "middle", and "bottom" 1226 control an image's vertical alignment (relative to the text 1227 baseline); they are only useful for inline images (substitutions). 1228 The values "left", "center", and "right" control an image's 1229 horizontal alignment, allowing the image to float and have the 1230 text flow around it. The specific behaviour depends upon the 1231 browser or rendering software used.</p> 1232 </dd> 1233 <dt><span class="docutils literal">alt</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 1234 <dd><p>Alternate text: a short description of the image, displayed by 1235 applications that cannot display images, or spoken by applications 1236 for visually impaired users.</p> 1237 </dd> 1238 <dt><span class="docutils literal">height</span><span class="classifier"><a class="reference internal" href="#length">length</a></span></dt> 1239 <dd><p>The desired height of the image. 1240 Used to reserve space or scale the image vertically. When the <a class="reference internal" href="#scale">scale</a> 1241 option is also specified, they are combined. For example, a height of 1242 200px and a scale of 50 is equivalent to a height of 100px with no scale.</p> 1243 </dd> 1244 <dt id="loading"><span class="docutils literal">loading</span><span class="classifier">"embed", "link", or "lazy"</span></dt> 1245 <dd><p>Set the <a class="reference external" href="../doctree.html#loading">loading attribute</a> to indicate the 1246 preferred handling by the Docutils Writer. <a class="footnote-reference brackets" href="#footnote-4" id="footnote-reference-5" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a></p> 1247 <dl class="field-list simple"> 1248 <dt>embed<span class="colon">:</span></dt> 1249 <dd><p>Embed the image into the output document. <a class="footnote-reference brackets" href="#footnote-5" id="footnote-reference-6" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a></p> 1250 </dd> 1251 <dt>link<span class="colon">:</span></dt> 1252 <dd><p>Refer to the image via its URI.</p> 1253 </dd> 1254 <dt>lazy<span class="colon">:</span></dt> 1255 <dd><p>Refer to the image. The HTML5 writer additionally 1256 specifies the "<a class="reference external" href="https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes">lazy loading attribute</a>".</p> 1257 </dd> 1258 </dl> 1259 <p>(New in Docutils 0.21.)</p> 1260 </dd> 1261 <dt id="scale"><span class="docutils literal">scale</span><span class="classifier">integer percentage (the "%" symbol is optional)</span></dt> 1262 <dd><p>The uniform scaling factor of the image. The default is "100 %", 1263 i.e. no scaling. 1264 If the output format does not support a scaling attribute (e.g. HTML), 1265 the Docutils writer tries to determine missing size specifications from 1266 the image file (requires the <a class="reference external" href="https://pypi.org/project/Pillow/">Python Imaging Library</a>).</p> 1267 </dd> 1268 <dt id="target"><span class="docutils literal">target</span><span class="classifier"><a class="reference internal" href="#uri">URI</a> or <a class="reference external" href="restructuredtext.html#reference-names">reference name</a></span></dt> 1269 <dd><p>Nest the image in a hyperlink reference element (make it "clickable"). 1270 The option argument may be a URI reference or a reference name 1271 with underscore suffix (e.g. <span class="docutils literal">`a name`_</span>).</p> 1272 </dd> 1273 <dt><span class="docutils literal">width</span><span class="classifier"><a class="reference internal" href="#length">length</a> or <a class="reference internal" href="#percentage">percentage</a> of the current line width</span></dt> 1274 <dd><p>The width of the image. 1275 Used to reserve space or scale the image horizontally. As with <span class="docutils literal">height</span> 1276 above, when the <a class="reference internal" href="#scale">scale</a> option is also specified, they are combined.</p> 1277 </dd> 1278 </dl> 1279 <aside class="footnote-list brackets"> 1280 <aside class="footnote brackets" id="footnote-4" role="doc-footnote"> 1281 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-5">5</a><span class="fn-bracket">]</span></span> 1282 <p>Currently only recognized by the <a class="reference external" href="../../user/html.html#html5">HTML5 writer</a> 1283 (overriding the <a class="reference external" href="../../user/config.html#image-loading">image_loading</a> configuration setting). 1284 The ODF/ODT writer always embeds images in the 1285 <span class="docutils literal">*.odt</span> document, XML and LaTeX writers link to the image. 1286 The behaviour may change for the ODT and XML writers but 1287 images cannot be embedded in a LaTeX source.</p> 1288 </aside> 1289 <aside class="footnote brackets" id="footnote-5" role="doc-footnote"> 1290 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-6">6</a><span class="fn-bracket">]</span></span> 1291 <p>The <a class="reference external" href="../../user/html.html#html5">HTML5 writer</a>, embeds SVG images directly and other images 1292 as <a class="reference external" href="https://en.wikipedia.org/wiki/Base64">base64</a> encoded <a class="reference external" href="https://en.wikipedia.org/wiki/Data_URI_scheme">data URI</a>.</p> 1293 </aside> 1294 </aside> 1295 </section> 1296 <section id="figure"> 1297 <h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">Figure</a></h3> 1298 <dl class="field-list simple" style="--field-indent: 13em;"> 1299 <dt>Directive Type<span class="colon">:</span></dt> 1300 <dd><p>"figure"</p> 1301 </dd> 1302 <dt>Doctree Elements<span class="colon">:</span></dt> 1303 <dd><p><a class="reference external" href="../doctree.html#figure"><figure></a>, <a class="reference external" href="../doctree.html#image"><image></a>, 1304 <a class="reference external" href="../doctree.html#caption"><caption></a>, <a class="reference external" href="../doctree.html#legend"><legend></a></p> 1305 </dd> 1306 <dt>Directive Arguments<span class="colon">:</span></dt> 1307 <dd><p>one, required (image <a class="reference internal" href="#uri">URI</a>)</p> 1308 </dd> 1309 <dt>Directive Options<span class="colon">:</span></dt> 1310 <dd><p><a class="reference internal" href="#figure-options">see below</a></p> 1311 </dd> 1312 <dt>Directive Content<span class="colon">:</span></dt> 1313 <dd><p>Interpreted as the figure caption and an optional 1314 legend.</p> 1315 </dd> 1316 </dl> 1317 <p>A "figure" consists of <a class="reference internal" href="#image">image</a> data (including <a class="reference internal" href="#image-options">image options</a>), an optional 1318 caption (a single paragraph), and an optional legend (arbitrary body 1319 elements). On paged output media, figures may float to a different 1320 position if this helps the page layout.</p> 1321 <pre class="literal-block">.. figure:: picture.png 1322 :scale: 50 % 1323 :alt: map to buried treasure 1324 1325 This is the caption of the figure (a simple paragraph). 1326 1327 The legend consists of all elements after the caption. In this 1328 case, the legend consists of this paragraph and the following 1329 table: 1330 1331 +-----------------------+-----------------------+ 1332 | Symbol | Meaning | 1333 +=======================+=======================+ 1334 | .. image:: tent.png | Campground | 1335 +-----------------------+-----------------------+ 1336 | .. image:: waves.png | Lake | 1337 +-----------------------+-----------------------+ 1338 | .. image:: peak.png | Mountain | 1339 +-----------------------+-----------------------+</pre> 1340 <p>There must be blank lines before the caption paragraph and before the 1341 legend. To specify a legend without a caption, use an empty comment 1342 ("..") in place of the caption.</p> 1343 <p id="figure-options">The "figure" directive supports the <a class="reference internal" href="#common-options">common options</a> and all 1344 <a class="reference internal" href="#image-options">options of the "image" directive</a>. 1345 These options (except <span class="docutils literal">align</span>) are passed on to the contained image.</p> 1346 <dl class="simple"> 1347 <dt><span class="docutils literal">align</span><span class="classifier">"left", "center", or "right"</span></dt> 1348 <dd><p>The horizontal alignment of the figure. The specific behaviour 1349 depends upon the browser or rendering software used. In HTML, the 1350 values "left" and "right" allow text to flow around the figure.</p> 1351 </dd> 1352 </dl> 1353 <p>In addition, the following options are recognized:</p> 1354 <dl> 1355 <dt><span class="docutils literal">figclass</span><span class="classifier">space separated list of <a class="reference external" href="../doctree.html#class-names">class names</a></span></dt> 1356 <dd><p>Set a <a class="reference external" href="../doctree.html#classes">classes attribute</a> value on the <figure> element 1357 (the "<a class="reference internal" href="#class-option">class</a>" option is applied to the nested <image>).</p> 1358 </dd> 1359 <dt><span class="docutils literal">figname</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 1360 <dd><p>Add <em>text</em> to the <a class="reference external" href="../doctree.html#names">names attribute</a> of the <figure> element 1361 (the "<a class="reference internal" href="#name">name</a>" option is applied to the nested <image>). 1362 New in Docutils 0.22.</p> 1363 </dd> 1364 <dt><span class="docutils literal">figwidth</span><span class="classifier">"image", <a class="reference internal" href="#length">length</a>, or <a class="reference internal" href="#percentage">percentage</a> of current line width</span></dt> 1365 <dd><p>The width of the figure. 1366 Limits the horizontal space used by the figure. 1367 A special value of "image" is allowed, in which case the 1368 included image's actual width is used (requires the <a class="reference external" href="https://pypi.org/project/Pillow/">Python Imaging 1369 Library</a>). If the image file is not found or the required software is 1370 unavailable, this option is ignored.</p> 1371 <p>Sets the <a class="reference external" href="../doctree.html#width">width attribute</a> of the <a class="reference external" href="../doctree.html#figure"><figure></a> doctree element.</p> 1372 <p>This option does not scale the included image; use the <span class="docutils literal">width</span> 1373 <a class="reference internal" href="#image-options">image option</a> for that.</p> 1374 <pre class="literal-block">+---------------------------+ 1375 | figure | 1376 | | 1377 |<------ figwidth --------->| 1378 | | 1379 | +---------------------+ | 1380 | | image | | 1381 | | | | 1382 | |<--- width --------->| | 1383 | +---------------------+ | 1384 | | 1385 |The figure's caption should| 1386 |wrap at this width. | 1387 +---------------------------+</pre> 1388 </dd> 1389 </dl> 1390 </section> 1391 </section> 1392 <section id="body-elements"> 1393 <h2><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Body Elements</a></h2> 1394 <section id="topic"> 1395 <h3><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Topic</a></h3> 1396 <dl class="field-list simple" style="--field-indent: 13em;"> 1397 <dt>Directive Type<span class="colon">:</span></dt> 1398 <dd><p>"topic"</p> 1399 </dd> 1400 <dt>Doctree Element<span class="colon">:</span></dt> 1401 <dd><p><a class="reference external" href="../doctree.html#topic"><topic></a></p> 1402 </dd> 1403 <dt>Directive Arguments<span class="colon">:</span></dt> 1404 <dd><p>one, required (topic title)</p> 1405 </dd> 1406 <dt>Directive Options<span class="colon">:</span></dt> 1407 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1408 </dd> 1409 <dt>Directive Content<span class="colon">:</span></dt> 1410 <dd><p>Interpreted as the topic body.</p> 1411 </dd> 1412 </dl> 1413 <p>A topic is like a block quote with a title, or a self-contained 1414 section with no subsections. Use the "topic" directive to indicate a 1415 self-contained idea that is separate from the flow of the document. 1416 Topics may occur anywhere a section or transition may occur. Body 1417 elements and topics may not contain nested topics.</p> 1418 <p>The directive's sole argument is interpreted as the topic title; the 1419 next line must be blank. All subsequent lines make up the topic body, 1420 interpreted as body elements. For example:</p> 1421 <pre class="literal-block">.. topic:: Topic Title 1422 1423 Subsequent indented lines comprise 1424 the body of the topic, and are 1425 interpreted as body elements.</pre> 1426 </section> 1427 <section id="sidebar"> 1428 <h3><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">Sidebar</a></h3> 1429 <dl class="field-list simple" style="--field-indent: 13em;"> 1430 <dt>Directive Type<span class="colon">:</span></dt> 1431 <dd><p>"sidebar"</p> 1432 </dd> 1433 <dt>Doctree Element<span class="colon">:</span></dt> 1434 <dd><p><a class="reference external" href="../doctree.html#sidebar"><sidebar></a></p> 1435 </dd> 1436 <dt>Directive Arguments<span class="colon">:</span></dt> 1437 <dd><p>one, optional (sidebar title)</p> 1438 </dd> 1439 <dt>Directive Options<span class="colon">:</span></dt> 1440 <dd><p><a class="reference internal" href="#sidebar-options">see below</a></p> 1441 </dd> 1442 <dt>Directive Content<span class="colon">:</span></dt> 1443 <dd><p>Interpreted as the sidebar body.</p> 1444 </dd> 1445 </dl> 1446 <p>Sidebars are like miniature, parallel documents that occur inside 1447 other documents, providing related or reference material. A sidebar 1448 is typically offset by a border and "floats" to the side of the page; 1449 the document's main text may flow around it. Sidebars can also be 1450 likened to super-footnotes; their content is outside of the flow of 1451 the document's main text.</p> 1452 <p>Sidebars may occur anywhere a section or transition may occur. Body 1453 elements (including sidebars) may not contain nested sidebars.</p> 1454 <p>The directive's sole argument is interpreted as the sidebar title, 1455 which may be followed by a subtitle option (see below); the next line 1456 must be blank. All subsequent lines make up the sidebar body, 1457 interpreted as body elements. For example:</p> 1458 <pre class="literal-block">.. sidebar:: Optional Sidebar Title 1459 :subtitle: Optional Sidebar Subtitle 1460 1461 Subsequent indented lines comprise 1462 the body of the sidebar, and are 1463 interpreted as body elements.</pre> 1464 <p id="sidebar-options">Recognizes the common options <a class="reference internal" href="#class-option">class</a> and <a class="reference internal" href="#name">name</a> as well as</p> 1465 <dl> 1466 <dt><span class="docutils literal">subtitle</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 1467 <dd><p>The sidebar's subtitle.</p> 1468 </dd> 1469 </dl> 1470 </section> 1471 <section id="line-block"> 1472 <h3><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">Line Block</a></h3> 1473 <aside class="admonition admonition-deprecated"> 1474 <p class="admonition-title">Deprecated</p> 1475 <p>The "line-block" directive is deprecated. Use the <a class="reference external" href="restructuredtext.html#line-blocks">line block 1476 syntax</a> instead.</p> 1477 </aside> 1478 <dl class="field-list simple" style="--field-indent: 13em;"> 1479 <dt>Directive Type<span class="colon">:</span></dt> 1480 <dd><p>"line-block"</p> 1481 </dd> 1482 <dt>Doctree Element<span class="colon">:</span></dt> 1483 <dd><p><a class="reference external" href="../doctree.html#line-block"><line_block></a></p> 1484 </dd> 1485 <dt>Directive Arguments<span class="colon">:</span></dt> 1486 <dd><p>none</p> 1487 </dd> 1488 <dt>Directive Options<span class="colon">:</span></dt> 1489 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1490 </dd> 1491 <dt>Directive Content<span class="colon">:</span></dt> 1492 <dd><p>Becomes the body of the line block.</p> 1493 </dd> 1494 </dl> 1495 <p>The "line-block" directive constructs an element where line breaks and 1496 initial indentation is significant and inline markup is supported. It 1497 is equivalent to a <a class="reference internal" href="#parsed-literal-block">parsed literal block</a> with different rendering: 1498 typically in an ordinary serif typeface instead of a 1499 typewriter/monospaced face, and not automatically indented. (Have the 1500 line-block directive begin a block quote to get an indented line 1501 block.) Line blocks are useful for address blocks and verse (poetry, 1502 song lyrics), where the structure of lines is significant. For 1503 example, here's a classic:</p> 1504 <pre class="literal-block">"To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by 1505 Ewan McTeagle (for Lassie O'Shea): 1506 1507 .. line-block:: 1508 1509 Lend us a couple of bob till Thursday. 1510 I'm absolutely skint. 1511 But I'm expecting a postal order and I can pay you back 1512 as soon as it comes. 1513 Love, Ewan.</pre> 1514 </section> 1515 <section id="parsed-literal-block"> 1516 <span id="parsed-literal"></span><h3><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">Parsed Literal Block</a></h3> 1517 <dl class="field-list simple" style="--field-indent: 13em;"> 1518 <dt>Directive Type<span class="colon">:</span></dt> 1519 <dd><p>"parsed-literal"</p> 1520 </dd> 1521 <dt>Doctree Element<span class="colon">:</span></dt> 1522 <dd><p><a class="reference external" href="../doctree.html#literal-block"><literal_block></a></p> 1523 </dd> 1524 <dt>Directive Arguments<span class="colon">:</span></dt> 1525 <dd><p>none</p> 1526 </dd> 1527 <dt>Directive Options<span class="colon">:</span></dt> 1528 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1529 </dd> 1530 <dt>Directive Content<span class="colon">:</span></dt> 1531 <dd><p>Becomes the body of the literal block.</p> 1532 </dd> 1533 </dl> 1534 <p>Unlike an ordinary literal block, the "parsed-literal" directive 1535 constructs a literal block where the text is parsed for inline markup. 1536 It is equivalent to a <a class="reference internal" href="#line-block">line block</a> with different rendering: 1537 typically in a typewriter/monospaced typeface, like an ordinary 1538 literal block. Parsed literal blocks are useful for adding hyperlinks 1539 to code examples.</p> 1540 <p>However, care must be taken with the text, because inline markup is 1541 recognized and there is no protection from parsing. Backslash-escapes 1542 may be necessary to prevent unintended parsing. And because the 1543 markup characters are removed by the parser, care must also be taken 1544 with vertical alignment. Parsed "ASCII art" is tricky, and extra 1545 whitespace may be necessary.</p> 1546 <p>For example, all the element names in this content model are links:</p> 1547 <pre class="literal-block">.. parsed-literal:: 1548 1549 ( (title_, subtitle_?)?, 1550 decoration_?, 1551 (docinfo_, transition_?)?, 1552 `%structure.model;`_ )</pre> 1553 </section> 1554 <section id="code"> 1555 <h3><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">Code</a></h3> 1556 <dl class="field-list simple" style="--field-indent: 13em;"> 1557 <dt>Directive Type<span class="colon">:</span></dt> 1558 <dd><p>"code"</p> 1559 </dd> 1560 <dt>Doctree Elements<span class="colon">:</span></dt> 1561 <dd><p><a class="reference external" href="../doctree.html#literal-block"><literal_block></a>, <a class="reference external" href="../doctree.html#inline-elements">inline elements</a></p> 1562 </dd> 1563 <dt>Directive Arguments<span class="colon">:</span></dt> 1564 <dd><p>one, optional (formal language)</p> 1565 </dd> 1566 <dt>Directive Options<span class="colon">:</span></dt> 1567 <dd><p><a class="reference internal" href="#code-options">see below</a></p> 1568 </dd> 1569 <dt>Directive Content<span class="colon">:</span></dt> 1570 <dd><p>Becomes the body of the literal block.</p> 1571 </dd> 1572 <dt>Configuration Setting<span class="colon">:</span></dt> 1573 <dd><p><a class="reference external" href="../../user/config.html#syntax-highlight">syntax_highlight</a></p> 1574 </dd> 1575 </dl> 1576 <p>The "code" directive constructs a literal block. If the code language is 1577 specified, the content is parsed by the <a class="reference external" href="https://pygments.org/">Pygments</a> syntax highlighter and 1578 tokens are stored in nested <a class="reference external" href="../doctree.html#inline-elements">inline elements</a> with class arguments 1579 according to their syntactic category. The actual highlighting requires 1580 a custom style-sheet, see the <a class="reference external" href="https://docutils.sourceforge.io/sandbox/stylesheets/">sandbox/stylesheets</a> for examples.</p> 1581 <p>For example, the content of the following directive</p> 1582 <pre class="literal-block">.. code:: python 1583 :number-lines: 1584 1585 def my_function(): 1586 "just a test" 1587 print(8/2)</pre> 1588 <p>is parsed and marked up as Python source code.</p> 1589 <p>The parsing can be turned off with the <a class="reference external" href="../../user/config.html#syntax-highlight">syntax_highlight</a> configuration 1590 setting and command line option or by specifying the language as 1591 <a class="reference internal" href="#class-option">class</a> option instead of directive argument. 1592 This also avoids warnings when <a class="reference external" href="https://pygments.org/">Pygments</a> is not installed or the language 1593 is not in the <a class="reference external" href="https://pygments.org/languages/">supported languages and markup formats</a>.</p> 1594 <p>For code in external files, use the "<a class="reference internal" href="#include">include</a>" directive with the 1595 <span class="docutils literal">code</span> option. For inline code, use the <a class="reference external" href="roles.html#code">"code" role</a>.</p> 1596 <p id="code-options">Recognizes the common options <a class="reference internal" href="#class-option">class</a> and <a class="reference internal" href="#name">name</a> as well as</p> 1597 <dl> 1598 <dt><span class="docutils literal"><span class="pre">number-lines</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a> (start line number, optional)</span></dt> 1599 <dd><p>Precede every line with a line number. 1600 The optional argument is the number of the first line (default 1).</p> 1601 </dd> 1602 </dl> 1603 </section> 1604 <section id="math"> 1605 <h3><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">Math</a></h3> 1606 <dl class="field-list simple" style="--field-indent: 13em;"> 1607 <dt>Directive Type<span class="colon">:</span></dt> 1608 <dd><p>"math"</p> 1609 </dd> 1610 <dt>Doctree Element<span class="colon">:</span></dt> 1611 <dd><p><a class="reference external" href="../doctree.html#math-block"><math_block></a></p> 1612 </dd> 1613 <dt>Directive Arguments<span class="colon">:</span></dt> 1614 <dd><p>none</p> 1615 </dd> 1616 <dt>Directive Options<span class="colon">:</span></dt> 1617 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1618 </dd> 1619 <dt>Directive Content<span class="colon">:</span></dt> 1620 <dd><p>Becomes the body of the math block. 1621 (Content blocks separated by a blank line are put in 1622 adjacent math blocks.)</p> 1623 </dd> 1624 <dt>Configuration Setting<span class="colon">:</span></dt> 1625 <dd><p><a class="reference external" href="../../user/config.html#math-output">math_output</a></p> 1626 </dd> 1627 </dl> 1628 <p>The "math" directive inserts blocks with mathematical content 1629 (display formulas, equations) into the document. The input format is 1630 <a class="reference external" href="../../ref/rst/mathematics.html">LaTeX math syntax</a> with support for Unicode symbols, for example:</p> 1631 <pre class="literal-block">.. math:: 1632 1633 α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)</pre> 1634 <p>Support is limited to a subset of <em>LaTeX math</em> by the conversion 1635 required for many output formats. For HTML, the <a class="reference external" href="../../user/config.html#math-output">math_output</a> 1636 configuration setting (or the corresponding <span class="docutils literal"><span class="pre">--math-output</span></span> 1637 command line option) select between alternative output formats with 1638 different subsets of supported elements. If a writer does not 1639 support math typesetting, the content is inserted verbatim.</p> 1640 <p>For inline formulas, use the <a class="reference external" href="roles.html#math">"math" role</a>.</p> 1641 </section> 1642 <section id="rubric"> 1643 <h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink">Rubric</a></h3> 1644 <dl class="field-list simple" style="--field-indent: 13em;"> 1645 <dt>Directive Type<span class="colon">:</span></dt> 1646 <dd><p>"rubric"</p> 1647 </dd> 1648 <dt>Doctree Element<span class="colon">:</span></dt> 1649 <dd><p><a class="reference external" href="../doctree.html#rubric"><rubric></a></p> 1650 </dd> 1651 <dt>Directive Arguments<span class="colon">:</span></dt> 1652 <dd><p>one, required (rubric text)</p> 1653 </dd> 1654 <dt>Directive Options<span class="colon">:</span></dt> 1655 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1656 </dd> 1657 <dt>Directive Content<span class="colon">:</span></dt> 1658 <dd><p>none</p> 1659 </dd> 1660 </dl> 1661 <!-- --> 1662 <blockquote> 1663 <p>rubric n. 1. a title, heading, or the like, in a manuscript, 1664 book, statute, etc., written or printed in red or otherwise 1665 distinguished from the rest of the text. ...</p> 1666 <p class="attribution">—Random House Webster's College Dictionary, 1991</p> 1667 </blockquote> 1668 <p>The "rubric" directive inserts a "rubric" element into the document 1669 tree. A rubric is like an informal heading that doesn't correspond to 1670 the document's structure.</p> 1671 </section> 1672 <section id="epigraph"> 1673 <h3><a class="toc-backref" href="#toc-entry-15" role="doc-backlink">Epigraph</a></h3> 1674 <dl class="field-list simple" style="--field-indent: 13em;"> 1675 <dt>Directive Type<span class="colon">:</span></dt> 1676 <dd><p>"epigraph"</p> 1677 </dd> 1678 <dt>Doctree Element<span class="colon">:</span></dt> 1679 <dd><p><a class="reference external" href="../doctree.html#block-quote"><block_quote></a></p> 1680 </dd> 1681 <dt>Directive Arguments<span class="colon">:</span></dt> 1682 <dd><p>none</p> 1683 </dd> 1684 <dt>Directive Options<span class="colon">:</span></dt> 1685 <dd><p>none</p> 1686 </dd> 1687 <dt>Directive Content<span class="colon">:</span></dt> 1688 <dd><p>Interpreted as the body of the block quote.</p> 1689 </dd> 1690 </dl> 1691 <p>An epigraph is an apposite (suitable, apt, or pertinent) short 1692 inscription, often a quotation or poem, at the beginning of a document 1693 or section.</p> 1694 <p>The "epigraph" directive produces an "epigraph"-class block quote. 1695 For example, this input:</p> 1696 <pre class="literal-block">.. epigraph:: 1697 1698 No matter where you go, there you are. 1699 1700 -- Buckaroo Banzai</pre> 1701 <p>becomes this document tree fragment:</p> 1702 <pre class="literal-block"><block_quote classes="epigraph"> 1703 <paragraph> 1704 No matter where you go, there you are. 1705 <attribution> 1706 Buckaroo Banzai</pre> 1707 </section> 1708 <section id="highlights"> 1709 <h3><a class="toc-backref" href="#toc-entry-16" role="doc-backlink">Highlights</a></h3> 1710 <dl class="field-list simple" style="--field-indent: 13em;"> 1711 <dt>Directive Type<span class="colon">:</span></dt> 1712 <dd><p>"highlights"</p> 1713 </dd> 1714 <dt>Doctree Element<span class="colon">:</span></dt> 1715 <dd><p><a class="reference external" href="../doctree.html#block-quote"><block_quote></a></p> 1716 </dd> 1717 <dt>Directive Arguments<span class="colon">:</span></dt> 1718 <dd><p>none</p> 1719 </dd> 1720 <dt>Directive Options<span class="colon">:</span></dt> 1721 <dd><p>none</p> 1722 </dd> 1723 <dt>Directive Content<span class="colon">:</span></dt> 1724 <dd><p>Interpreted as the body of the block quote.</p> 1725 </dd> 1726 </dl> 1727 <p>Highlights summarize the main points of a document or section, often 1728 consisting of a list.</p> 1729 <p>The "highlights" directive produces a "highlights"-class block quote. 1730 See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p> 1731 </section> 1732 <section id="pull-quote"> 1733 <h3><a class="toc-backref" href="#toc-entry-17" role="doc-backlink">Pull-Quote</a></h3> 1734 <dl class="field-list simple" style="--field-indent: 13em;"> 1735 <dt>Directive Type<span class="colon">:</span></dt> 1736 <dd><p>"pull-quote"</p> 1737 </dd> 1738 <dt>Doctree Element<span class="colon">:</span></dt> 1739 <dd><p><a class="reference external" href="../doctree.html#block-quote"><block_quote></a></p> 1740 </dd> 1741 <dt>Directive Arguments<span class="colon">:</span></dt> 1742 <dd><p>none</p> 1743 </dd> 1744 <dt>Directive Options<span class="colon">:</span></dt> 1745 <dd><p>none</p> 1746 </dd> 1747 <dt>Directive Content<span class="colon">:</span></dt> 1748 <dd><p>Interpreted as the body of the block quote.</p> 1749 </dd> 1750 </dl> 1751 <p>A pull-quote is a small selection of text "pulled out and quoted", 1752 typically in a larger typeface. Pull-quotes are used to attract 1753 attention, especially in long articles.</p> 1754 <p>The "pull-quote" directive produces a "pull-quote"-class block quote. 1755 See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p> 1756 <!-- compound: --> 1757 </section> 1758 <section id="compound-paragraph"> 1759 <h3><a class="toc-backref" href="#toc-entry-18" role="doc-backlink">Compound Paragraph</a></h3> 1760 <dl class="field-list simple" style="--field-indent: 13em;"> 1761 <dt>Directive Type<span class="colon">:</span></dt> 1762 <dd><p>"compound"</p> 1763 </dd> 1764 <dt>Doctree Element<span class="colon">:</span></dt> 1765 <dd><p><a class="reference external" href="../doctree.html#compound"><compound></a></p> 1766 </dd> 1767 <dt>Directive Arguments<span class="colon">:</span></dt> 1768 <dd><p>none</p> 1769 </dd> 1770 <dt>Directive Options<span class="colon">:</span></dt> 1771 <dd><p><a class="reference internal" href="#class-option">class</a>, <a class="reference internal" href="#name">name</a></p> 1772 </dd> 1773 <dt>Directive Content<span class="colon">:</span></dt> 1774 <dd><p>Interpreted as body elements.</p> 1775 </dd> 1776 </dl> 1777 <p>The "compound" directive is used to create a compound paragraph, which 1778 is a single logical paragraph containing multiple physical body 1779 elements such as simple paragraphs, literal blocks, tables, lists, 1780 etc., instead of directly containing text and inline elements. For 1781 example:</p> 1782 <pre class="literal-block">.. compound:: 1783 1784 The 'rm' command is very dangerous. If you are logged 1785 in as root and enter :: 1786 1787 cd / 1788 rm -rf * 1789 1790 you will erase the entire contents of your file system.</pre> 1791 <p>In the example above, a literal block is "embedded" within a sentence 1792 that begins in one physical paragraph and ends in another.</p> 1793 <aside class="admonition note"> 1794 <p class="admonition-title">Note</p> 1795 <p>The "compound" directive is <em>not</em> a generic block-level container 1796 like HTML's <span class="docutils literal"><div></span> element. Do not use it only to group a 1797 sequence of elements, or you may get unexpected results.</p> 1798 <p>If you need a generic block-level container, please use the 1799 <a class="reference internal" href="#container">container</a> directive, described below.</p> 1800 </aside> 1801 <p>Compound paragraphs are typically rendered as multiple distinct text 1802 blocks, with the possibility of variations to emphasize their logical 1803 unity:</p> 1804 <ul class="simple"> 1805 <li><p>If paragraphs are rendered with a first-line indent, only the first 1806 physical paragraph of a compound paragraph should have that indent 1807 -- second and further physical paragraphs should omit the indents;</p></li> 1808 <li><p>vertical spacing between physical elements may be reduced;</p></li> 1809 <li><p>and so on.</p></li> 1810 </ul> 1811 </section> 1812 <section id="container"> 1813 <h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink">Container</a></h3> 1814 <dl class="field-list simple" style="--field-indent: 13em;"> 1815 <dt>Directive Type<span class="colon">:</span></dt> 1816 <dd><p>"container"</p> 1817 </dd> 1818 <dt>Doctree Element<span class="colon">:</span></dt> 1819 <dd><p><a class="reference external" href="../doctree.html#container"><container></a></p> 1820 </dd> 1821 <dt>Directive Arguments<span class="colon">:</span></dt> 1822 <dd><p>one or more, optional (<a class="reference external" href="../doctree.html#class-names">class names</a>)</p> 1823 </dd> 1824 <dt>Directive Options<span class="colon">:</span></dt> 1825 <dd><p><a class="reference internal" href="#name">name</a></p> 1826 </dd> 1827 <dt>Directive Content<span class="colon">:</span></dt> 1828 <dd><p>Interpreted as body elements.</p> 1829 </dd> 1830 </dl> 1831 <p>The "container" directive surrounds its contents (arbitrary body 1832 elements) with a generic block-level "container" element. 1833 Combined with the optional argument, this is an 1834 extension mechanism for users & applications. For example:</p> 1835 <pre class="literal-block">.. container:: custom 1836 1837 This paragraph might be rendered in a custom way.</pre> 1838 <p>Parsing the above results in the following pseudo-XML:</p> 1839 <pre class="literal-block"><container classes="custom"> 1840 <paragraph> 1841 This paragraph might be rendered in a custom way.</pre> 1842 <p>The "container" directive is the equivalent of HTML's <span class="docutils literal"><div></span> 1843 element. It may be used to group a sequence of elements for user- or 1844 application-specific purposes.</p> 1845 </section> 1846 </section> 1847 <section id="tables"> 1848 <h2><a class="toc-backref" href="#toc-entry-20" role="doc-backlink">Tables</a></h2> 1849 <p>Formal tables need more structure than the reStructuredText <a class="reference external" href="restructuredtext.html#tables">table syntax</a> 1850 supplies. Tables may be given titles with the "<a class="reference internal" href="#table">table</a>" directive. 1851 Sometimes reStructuredText tables are inconvenient to write, or table 1852 data in a standard format is readily available. The "<a class="reference internal" href="#csv-table">csv-table</a>" 1853 directive supports CSV <a class="footnote-reference brackets" href="#csv" id="footnote-reference-7" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a> data, the "<a class="reference internal" href="#list-table">list-table</a>" directive uses 1854 a list-based input format.</p> 1855 <section id="table"> 1856 <h3><a class="toc-backref" href="#toc-entry-21" role="doc-backlink">Table</a></h3> 1857 <dl class="field-list simple" style="--field-indent: 13em;"> 1858 <dt>Directive Type<span class="colon">:</span></dt> 1859 <dd><p>"table"</p> 1860 </dd> 1861 <dt>Doctree Element<span class="colon">:</span></dt> 1862 <dd><p><a class="reference external" href="../doctree.html#table"><table></a></p> 1863 </dd> 1864 <dt>Directive Arguments<span class="colon">:</span></dt> 1865 <dd><p>one, optional (table caption)</p> 1866 </dd> 1867 <dt>Directive Options<span class="colon">:</span></dt> 1868 <dd><p><a class="reference internal" href="#table-options">see below</a></p> 1869 </dd> 1870 <dt>Directive Content<span class="colon">:</span></dt> 1871 <dd><p>one reStructuredText <a class="reference external" href="restructuredtext.html#grid-tables">grid table</a> or <a class="reference external" href="restructuredtext.html#simple-tables">simple table</a></p> 1872 </dd> 1873 <dt>Configuration Setting<span class="colon">:</span></dt> 1874 <dd><p><a class="reference external" href="../../user/config.html#table-style">table_style</a></p> 1875 </dd> 1876 </dl> 1877 <p>The "table" directive is used to provide a table caption 1878 or specify options, e.g.:</p> 1879 <pre class="literal-block">.. table:: Truth table for "not" 1880 :widths: auto 1881 1882 ===== ===== 1883 A not A 1884 ===== ===== 1885 False True 1886 True False 1887 ===== =====</pre> 1888 <p id="table-options">Recognizes the common options <a class="reference internal" href="#class-option">class</a> and <a class="reference internal" href="#name">name</a> as well as</p> 1889 <dl> 1890 <dt><span class="docutils literal">align</span><span class="classifier">"left", "center", or "right"</span></dt> 1891 <dd><p>The horizontal alignment of the table (new in Docutils 0.13).</p> 1892 </dd> 1893 <dt><span class="docutils literal">width</span><span class="classifier"><a class="reference internal" href="#length">length</a> or <a class="reference internal" href="#percentage">percentage</a> of the current line width</span></dt> 1894 <dd><p>The width of the table. 1895 By default, the renderer determines the width of a table 1896 from its contents. <a class="footnote-reference brackets" href="#width-from-widths" id="footnote-reference-8" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a></p> 1897 </dd> 1898 <dt><span class="docutils literal">widths</span><span class="classifier">"auto", "grid", or a <a class="reference internal" href="#list-of-integers">list of integers</a></span></dt> 1899 <dd><p>Table column widths. 1900 Possible values:</p> 1901 <dl class="run-in field-list simple" style="--field-indent: 7ex;"> 1902 <dt>"auto"<span class="colon">:</span></dt> 1903 <dd><p>Delegate the determination of column widths to the backend 1904 (LaTeX, the HTML browser, ...).</p> 1905 </dd> 1906 <dt>"grid"<span class="colon">:</span></dt> 1907 <dd><p>Relative column widths match the widths of the columns 1908 in the reStructuredText table markup.</p> 1909 </dd> 1910 <dt>list of integers<span class="colon">:</span></dt> 1911 <dd><p>Specifies relative column widths. 1912 Must match the number of table columns.</p> 1913 </dd> 1914 </dl> 1915 <p>The default depends on the writer. 1916 The <a class="reference external" href="../../user/html.html#html5">HTML5</a> and <a class="reference external" href="../../user/manpage.html">manpage</a> writers default to <em>"auto"</em>, 1917 the <a class="reference external" href="../../user/html.html#html4css1">html4</a> and <a class="reference external" href="../../user/latex.html">LaTeX</a> writers default to <em>"grid"</em>. <a class="footnote-reference brackets" href="#widths-default" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p> 1918 </dd> 1919 </dl> 1920 <aside class="footnote-list brackets"> 1921 <aside class="footnote brackets" id="width-from-widths" role="doc-footnote"> 1922 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-8">7</a><span class="fn-bracket">]</span></span> 1923 <p>The LaTeX writer determines the <a class="reference external" href="../../user/latex.html#table-width">table width 1924 from column widths</a> unless the <span class="docutils literal">widths</span> option is set to <em>"auto"</em>.</p> 1925 </aside> 1926 <aside class="footnote brackets" id="widths-default" role="doc-footnote"> 1927 <span class="label"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></span> 1928 <span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-9">1</a>,<a role="doc-backlink" href="#footnote-reference-14">2</a>,<a role="doc-backlink" href="#footnote-reference-16">3</a>)</span> 1929 <p>The <span class="docutils literal">widths</span> default of the HTML and LaTeX 1930 writers can be configured with the <a class="reference external" href="../../user/config.html#table-style">table_style</a> configuration 1931 setting using the special class values "colwidths-auto" or 1932 "colwidths-grid".</p> 1933 </aside> 1934 </aside> 1935 </section> 1936 <section id="csv-table-1"> 1937 <span id="csv-table"></span><h3><a class="toc-backref" href="#toc-entry-22" role="doc-backlink">CSV Table</a></h3> 1938 <dl class="field-list simple" style="--field-indent: 13em;"> 1939 <dt>Directive Type<span class="colon">:</span></dt> 1940 <dd><p>"csv-table"</p> 1941 </dd> 1942 <dt>Doctree Element<span class="colon">:</span></dt> 1943 <dd><p><a class="reference external" href="../doctree.html#table"><table></a></p> 1944 </dd> 1945 <dt>Directive Arguments<span class="colon">:</span></dt> 1946 <dd><p>one, optional (table caption)</p> 1947 </dd> 1948 <dt>Directive Options<span class="colon">:</span></dt> 1949 <dd><p><a class="reference internal" href="#csv-table-options">see below</a></p> 1950 </dd> 1951 <dt>Directive Content<span class="colon">:</span></dt> 1952 <dd><p>A CSV (comma-separated values) table 1953 or (with the <a class="reference internal" href="#file">file</a> or <a class="reference internal" href="#url">url</a> options) none.</p> 1954 </dd> 1955 <dt>Configuration Settings<span class="colon">:</span></dt> 1956 <dd><p><a class="reference external" href="../../user/config.html#table-style">table_style</a>, <a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>, <a class="reference external" href="../../user/config.html#root-prefix">root_prefix</a></p> 1957 </dd> 1958 </dl> 1959 <aside class="admonition warning"> 1960 <p class="admonition-title">Warning</p> 1961 <p>The "csv-table" directive's <a class="reference internal" href="#file">file</a> and <a class="reference internal" href="#url">url</a> options represent 1962 potential security holes. They can be disabled with the 1963 "<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" runtime setting.</p> 1964 </aside> 1965 <p>The "csv-table" directive is used to create a table from CSV 1966 (comma-separated values) <a class="footnote-reference brackets" href="#csv" id="footnote-reference-10" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a> data. The data may be internal 1967 (an integral part of the document) or external (a separate file).</p> 1968 <ul class="simple"> 1969 <li><p>Block markup and inline markup within cells is supported. 1970 Line ends are recognized within quoted cells.</p></li> 1971 <li><p>There is no support for checking that the number of columns in each 1972 row is the same. The directive automatically adds empty entries at 1973 the end of short rows.</p> 1974 <!-- TODO 1975 Add option ``missing-cells`` with keywords "strict", "fill", "span"? 1976 (cf. [feature-requests:#103]) --> 1977 </li> 1978 </ul> 1979 <p>Example:</p> 1980 <pre class="literal-block">.. csv-table:: Frozen Delights! 1981 :header: "Treat", "Quantity", "Description" 1982 :widths: 15, 10, 30 1983 1984 "Albatross", 2.99, "On a stick!" 1985 "Crunchy Frog", 1.49, "If we took the bones out, 1986 it wouldn't be crunchy, now would it?" 1987 "Gannet Ripple", 1.99, "On a stick!"</pre> 1988 <p id="csv-table-options">Recognizes the common options <a class="reference internal" href="#class-option">class</a> and <a class="reference internal" href="#name">name</a> as well as</p> 1989 <dl> 1990 <dt><span class="docutils literal">align</span><span class="classifier">"left", "center", or "right"</span></dt> 1991 <dd><p>The horizontal alignment of the table. (New in Docutils 0.13)</p> 1992 </dd> 1993 <dt id="delimiter"><span class="docutils literal">delim</span><span class="classifier"><a class="reference internal" href="#character">character</a>, "tab", or "space"</span></dt> 1994 <dd><p>The character used to separate data fields. 1995 The special values "tab" and "space" are converted to the respective 1996 whitespace characters. <a class="footnote-reference brackets" href="#tab-expansion" id="footnote-reference-11" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a> 1997 Defaults to "<span class="docutils literal">,</span>" (comma).</p> 1998 </dd> 1999 <dt><span class="docutils literal">encoding</span><span class="classifier"><a class="reference internal" href="#encoding">encoding</a></span></dt> 2000 <dd><p>The text encoding of the external CSV data (file or URL). 2001 Defaults to the document's <a class="reference external" href="../../user/config.html#input-encoding">input_encoding</a>.</p> 2002 </dd> 2003 <dt><span class="docutils literal">escape</span><span class="classifier"><a class="reference internal" href="#character">character</a></span></dt> 2004 <dd><p>A character used to escape the <a class="reference internal" href="#delimiter">delimiter</a> or <a class="reference internal" href="#quote">quote</a> characters from 2005 the CSV parser. The default is no escape character -- fields may 2006 contain delimiter or newline characters if they are quoted, two <a class="reference internal" href="#quote">quote</a> 2007 characters stand for a literal one, e.g., <span class="docutils literal"><span class="pre">"""Hi!"",</span> he said."</span>.</p> 2008 <aside class="admonition caution"> 2009 <p class="admonition-title">Caution!</p> 2010 <p>Setting <span class="docutils literal">escape</span> to <span class="docutils literal">\</span> (backslash) interferes with 2011 the reStructuredText <a class="reference external" href="restructuredtext.html#escaping-mechanism">escaping mechanism</a> (applied after CSV 2012 parsing). You will need two backslashes to escape reStructuredText 2013 markup and four backslashes for a literal one.</p> 2014 </aside> 2015 </dd> 2016 <dt id="file"><span class="docutils literal">file</span><span class="classifier"><a class="reference internal" href="#path">path</a></span></dt> 2017 <dd><p>The local filesystem path to a CSV data file.</p> 2018 </dd> 2019 <dt><span class="docutils literal">header</span><span class="classifier"><a class="reference internal" href="#text">text</a> (CSV data)</span></dt> 2020 <dd><p>Supplemental data for the table header, added independently of and 2021 before any <span class="docutils literal"><span class="pre">header-rows</span></span> from the main CSV data. Must use the 2022 same CSV format as the main CSV data. <a class="footnote-reference brackets" href="#footnote-6" id="footnote-reference-12" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a></p> 2023 </dd> 2024 <dt><span class="docutils literal"><span class="pre">header-rows</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2025 <dd><p>The number of rows of CSV data to use in the table header. 2026 Defaults to 0.</p> 2027 </dd> 2028 <dt><span class="docutils literal">keepspace</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2029 <dd><p>Treat whitespace immediately following the delimiter as 2030 significant. The default is to ignore such whitespace.</p> 2031 </dd> 2032 <dt id="quote"><span class="docutils literal">quote</span><span class="classifier"><a class="reference internal" href="#character">character</a></span></dt> 2033 <dd><p>The character used to quote fields containing special characters, 2034 such as the <a class="reference internal" href="#delimiter">delimiter</a>, quote, or new-line characters. 2035 Defaults to <span class="docutils literal">"</span> (quote).</p> 2036 </dd> 2037 <dt><span class="docutils literal"><span class="pre">stub-columns</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2038 <dd><p>The number of table columns to use as stubs (row titles, on the left). 2039 Defaults to 0.</p> 2040 </dd> 2041 <dt id="url"><span class="docutils literal">url</span><span class="classifier"><a class="reference internal" href="#uri">URI</a></span></dt> 2042 <dd><p>A URI reference to a CSV data file.</p> 2043 </dd> 2044 <dt><span class="docutils literal">width</span><span class="classifier"><a class="reference internal" href="#length">length</a> or <a class="reference internal" href="#percentage">percentage</a> of the current line width</span></dt> 2045 <dd><p>The width of the table. 2046 By default, the renderer determines the width of a table 2047 from its contents. <a class="footnote-reference brackets" href="#width-from-widths2" id="footnote-reference-13" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a></p> 2048 </dd> 2049 <dt><span class="docutils literal">widths</span><span class="classifier"><a class="reference internal" href="#list-of-integers">list of integers</a> or "auto"</span></dt> 2050 <dd><p>A list of relative column widths. The special value 2051 "auto" delegates the determination of column widths to the backend 2052 (LaTeX, the HTML browser, ...).</p> 2053 <p>The default depends on the writer. 2054 The <a class="reference external" href="../../user/html.html#html5">html5</a> and <a class="reference external" href="../../user/manpage.html">manpage</a> writers default to <em>"auto"</em>, the <a class="reference external" href="../../user/html.html#html4css1">html4</a> and 2055 <a class="reference external" href="../../user/latex.html">LaTeX</a> writers default to equal-width columns. <a class="footnote-reference brackets" href="#widths-default" id="footnote-reference-14" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p> 2056 </dd> 2057 </dl> 2058 <aside class="footnote-list brackets"> 2059 <aside class="footnote brackets" id="csv" role="doc-footnote"> 2060 <span class="label"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></span> 2061 <span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-7">1</a>,<a role="doc-backlink" href="#footnote-reference-10">2</a>)</span> 2062 <p>CSV (comma separated values) is a common data format generated 2063 by spreadsheet applications and commercial databases. Despite the 2064 "comma" in its name, the field <a class="reference internal" href="#delimiter">delimiter</a> may be any Unicode character.</p> 2065 </aside> 2066 <aside class="footnote brackets" id="tab-expansion" role="doc-footnote"> 2067 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-11">10</a><span class="fn-bracket">]</span></span> 2068 <p>Note, that <em>tabs</em> can be used as separator only in 2069 external files because hard tabs in the reStructuredText source are 2070 <a class="reference external" href="restructuredtext.html#whitespace">converted to spaces</a> before parsing.</p> 2071 </aside> 2072 <aside class="footnote brackets" id="footnote-6" role="doc-footnote"> 2073 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-12">11</a><span class="fn-bracket">]</span></span> 2074 <p>Before Docutils 0.21, the header option used a hard-coded 2075 CSV dialect with the backslash as escape character.</p> 2076 </aside> 2077 <aside class="footnote brackets" id="width-from-widths2" role="doc-footnote"> 2078 <span class="label"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></span> 2079 <span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-13">1</a>,<a role="doc-backlink" href="#footnote-reference-15">2</a>)</span> 2080 <p>The <a class="reference external" href="../../user/latex.html#table-width">LaTeX writer defaults to a table width 2081 of 100%</a> unless the <span class="docutils literal">width</span> or <span class="docutils literal">widths</span> option is set.</p> 2082 </aside> 2083 </aside> 2084 </section> 2085 <section id="list-table-1"> 2086 <span id="list-table"></span><h3><a class="toc-backref" href="#toc-entry-23" role="doc-backlink">List Table</a></h3> 2087 <dl class="field-list simple" style="--field-indent: 13em;"> 2088 <dt>Directive Type<span class="colon">:</span></dt> 2089 <dd><p>"list-table"</p> 2090 </dd> 2091 <dt>Doctree Element<span class="colon">:</span></dt> 2092 <dd><p><a class="reference external" href="../doctree.html#table"><table></a></p> 2093 </dd> 2094 <dt>Directive Arguments<span class="colon">:</span></dt> 2095 <dd><p>one, optional (table caption)</p> 2096 </dd> 2097 <dt>Directive Options<span class="colon">:</span></dt> 2098 <dd><p><a class="reference internal" href="#list-table-options">see below</a></p> 2099 </dd> 2100 <dt>Directive Content<span class="colon">:</span></dt> 2101 <dd><p>A uniform two-level bullet list.</p> 2102 </dd> 2103 <dt>Configuration Setting<span class="colon">:</span></dt> 2104 <dd><p><a class="reference external" href="../../user/config.html#table-style">table_style</a></p> 2105 </dd> 2106 </dl> 2107 <p>(This is an initial implementation; <a class="reference external" href="../../dev/rst/alternatives.html#list-driven-tables">further ideas</a> may be implemented 2108 in the future.)</p> 2109 <p>The "list-table" directive is used to create a table from data in a 2110 uniform two-level bullet list. "Uniform" means that each sublist 2111 (second-level list) must contain the same number of list items.</p> 2112 <p>Example:</p> 2113 <pre class="literal-block">.. list-table:: Frozen Delights! 2114 :widths: 15 10 30 2115 :header-rows: 1 2116 2117 * - Treat 2118 - Quantity 2119 - Description 2120 * - Albatross 2121 - 2.99 2122 - On a stick! 2123 * - Crunchy Frog 2124 - 1.49 2125 - If we took the bones out, it wouldn't be 2126 crunchy, now would it? 2127 * - Gannet Ripple 2128 - 1.99 2129 - On a stick!</pre> 2130 <p id="list-table-options">Recognizes the common options <a class="reference internal" href="#class-option">class</a> and <a class="reference internal" href="#name">name</a> as well as</p> 2131 <dl> 2132 <dt><span class="docutils literal">align</span><span class="classifier">"left", "center", or "right"</span></dt> 2133 <dd><p>The horizontal alignment of the table. 2134 (New in Docutils 0.13)</p> 2135 </dd> 2136 <dt><span class="docutils literal"><span class="pre">header-rows</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2137 <dd><p>The number of rows of list data to use in the table header. 2138 Defaults to 0.</p> 2139 </dd> 2140 <dt><span class="docutils literal"><span class="pre">stub-columns</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2141 <dd><p>The number of table columns to use as stubs (row titles, on the 2142 left). Defaults to 0.</p> 2143 </dd> 2144 <dt id="table-width"><span class="docutils literal">width</span><span class="classifier"><a class="reference internal" href="#length">length</a> or <a class="reference internal" href="#percentage">percentage</a> of the current line width</span></dt> 2145 <dd><p>The width of the table. 2146 By default, the renderer determines the width of a table 2147 from its contents. <a class="footnote-reference brackets" href="#width-from-widths2" id="footnote-reference-15" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a></p> 2148 </dd> 2149 <dt><span class="docutils literal">widths</span><span class="classifier"><a class="reference internal" href="#list-of-integers">list of integers</a> or "auto"</span></dt> 2150 <dd><p>A list of relative column widths. The special value 2151 "auto" delegates the determination of column widths to the backend 2152 (LaTeX, the HTML browser, ...).</p> 2153 <p>The default depends on the writer. 2154 The <a class="reference external" href="../../user/html.html#html5">HTML5</a> and <a class="reference external" href="../../user/manpage.html">manpage</a> writers default to <em>"auto"</em>, the <a class="reference external" href="../../user/html.html#html4css1">html4</a> and 2155 <a class="reference external" href="../../user/latex.html">LaTeX</a> writers default to equal-width columns. <a class="footnote-reference brackets" href="#widths-default" id="footnote-reference-16" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a></p> 2156 </dd> 2157 </dl> 2158 <!-- TODO 2159 Add option ``missing-cells`` with keywords "strict", "fill", "span"? 2160 (cf. [feature-requests:#103]) --> 2161 </section> 2162 </section> 2163 <section id="document-parts"> 2164 <h2><a class="toc-backref" href="#toc-entry-24" role="doc-backlink">Document Parts</a></h2> 2165 <!-- A ``_contents:`` hyperlink here became id "contents-1" 2166 (name clash with the generated ToC) --> 2167 <section id="table-of-contents"> 2168 <h3><a class="toc-backref" href="#toc-entry-25" role="doc-backlink">Table of Contents</a></h3> 2169 <dl class="field-list simple" style="--field-indent: 13em;"> 2170 <dt>Directive Type<span class="colon">:</span></dt> 2171 <dd><p>"contents"</p> 2172 </dd> 2173 <dt>Doctree Elements<span class="colon">:</span></dt> 2174 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a>, <a class="reference external" href="../doctree.html#topic"><topic></a></p> 2175 </dd> 2176 <dt>Directive Arguments<span class="colon">:</span></dt> 2177 <dd><p>one, optional: title</p> 2178 </dd> 2179 <dt>Directive Options<span class="colon">:</span></dt> 2180 <dd><p><a class="reference internal" href="#contents-options">see below</a></p> 2181 </dd> 2182 <dt>Directive Content<span class="colon">:</span></dt> 2183 <dd><p>none</p> 2184 </dd> 2185 <dt>Configuration Settings<span class="colon">:</span></dt> 2186 <dd><p><a class="reference external" href="../../user/config.html#toc-backlinks">toc_backlinks</a>, <a class="reference external" href="../../user/config.html#use-latex-toc">use_latex_toc</a>, <a class="reference external" href="../../user/config.html#generate-oowriter-toc">generate_oowriter_toc</a></p> 2187 </dd> 2188 </dl> 2189 <p>The "contents" directive generates a table of contents (TOC) in 2190 a <a class="reference external" href="../doctree.html#topic"><topic></a> element. Topics, and therefore tables of contents, 2191 may occur anywhere a section or transition may occur. 2192 Body elements and topics may not contain tables of contents.</p> 2193 <p>Here's the directive in its simplest form:</p> 2194 <pre class="literal-block">.. contents::</pre> 2195 <p>Language-dependent boilerplate text will be used for the title. The 2196 English default title text is "Contents".</p> 2197 <p>An explicit title may be specified:</p> 2198 <pre class="literal-block">.. contents:: Table of Contents</pre> 2199 <p>The title may span lines, although it is not recommended:</p> 2200 <pre class="literal-block">.. contents:: Here's a very long Table of 2201 Contents title</pre> 2202 <p>Directive options may be specified using a field list:</p> 2203 <pre class="literal-block">.. contents:: Table of Contents 2204 :depth: 2</pre> 2205 <p>If the default title is to be used, the options field list may begin 2206 on the same line as the directive marker:</p> 2207 <pre class="literal-block">.. contents:: :depth: 2</pre> 2208 <p id="contents-options">The "contents" directive recognizes the common option 2209 <a class="reference internal" href="#class-option">class</a> as well as</p> 2210 <dl> 2211 <dt><span class="docutils literal">backlinks</span><span class="classifier">"entry" or "top" or "none"</span></dt> 2212 <dd><p>Generate links from section headers back to the table of contents 2213 entries, the table of contents itself, or generate no back-links.</p> 2214 </dd> 2215 <dt><span class="docutils literal">depth</span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2216 <dd><p>The number of section levels that are collected in the table of 2217 contents. The default is unlimited depth.</p> 2218 </dd> 2219 <dt><span class="docutils literal">local</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2220 <dd><p>Generate a local table of contents. Entries will only include 2221 subsections of the section in which the directive is given. If no 2222 explicit title is given, the table of contents will not be titled.</p> 2223 </dd> 2224 </dl> 2225 </section> 2226 <section id="automatic-section-numbering"> 2227 <span id="sectnum"></span><h3><a class="toc-backref" href="#toc-entry-26" role="doc-backlink">Automatic Section Numbering</a></h3> 2228 <dl class="field-list simple" style="--field-indent: 13em;"> 2229 <dt>Directive Type<span class="colon">:</span></dt> 2230 <dd><p>"sectnum" or "section-numbering" (synonyms)</p> 2231 </dd> 2232 <dt>Doctree Elements<span class="colon">:</span></dt> 2233 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a>, <a class="reference external" href="../doctree.html#generated"><generated></a></p> 2234 </dd> 2235 <dt>Directive Arguments<span class="colon">:</span></dt> 2236 <dd><p>none</p> 2237 </dd> 2238 <dt>Directive Options<span class="colon">:</span></dt> 2239 <dd><p><a class="reference internal" href="#sectnum-options">see below</a></p> 2240 </dd> 2241 <dt>Directive Content<span class="colon">:</span></dt> 2242 <dd><p>none</p> 2243 </dd> 2244 <dt>Configuration Setting<span class="colon">:</span></dt> 2245 <dd><p><a class="reference external" href="../../user/config.html#sectnum-xform">sectnum_xform</a></p> 2246 </dd> 2247 </dl> 2248 <p>The "sectnum" (or "section-numbering") directive automatically numbers 2249 sections and subsections in a document (if not disabled by the 2250 <span class="docutils literal"><span class="pre">--no-section-numbering</span></span> command line option or the <a class="reference external" href="../../user/config.html#sectnum-xform">sectnum_xform</a> 2251 configuration setting).</p> 2252 <p>Section numbers are of the "multiple enumeration" form, where each 2253 level has a number, separated by periods. For example, the title of section 2254 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.</p> 2255 <p>The directive does its work in two passes: the initial parse 2256 and a transform. During the initial parse, a <pending> element is 2257 generated which acts as a placeholder, storing any options internally. 2258 At a later stage in the processing, the <pending> element triggers a 2259 transform, which adds section numbers to titles. Section numbers are 2260 enclosed in a <generated> element, and titles have their <a class="reference external" href="../doctree.html#auto">auto attribute</a> 2261 set to "1".</p> 2262 <p id="sectnum-options">The "sectnum" directive recognizes the following options:</p> 2263 <dl> 2264 <dt><span class="docutils literal">depth</span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2265 <dd><p>The number of section levels that are numbered by this directive. 2266 The default is unlimited depth.</p> 2267 </dd> 2268 <dt><span class="docutils literal">prefix</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 2269 <dd><p>An arbitrary string that is prefixed to the automatically 2270 generated section numbers. It may be something like "3.2.", which 2271 will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that 2272 any separating punctuation (in the example, a period, ".") must be 2273 explicitly provided. The default is no prefix.</p> 2274 </dd> 2275 <dt><span class="docutils literal">suffix</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 2276 <dd><p>An arbitrary string that is appended to the automatically 2277 generated section numbers. The default is no suffix.</p> 2278 </dd> 2279 <dt><span class="docutils literal">start</span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2280 <dd><p>The value that will be used for the first section number. 2281 Combined with <span class="docutils literal">prefix</span>, this may be used to force the right 2282 numbering for a document split over several source files. The 2283 default is 1.</p> 2284 </dd> 2285 </dl> 2286 </section> 2287 <section id="document-header-footer"> 2288 <span id="footer"></span><span id="header"></span><h3><a class="toc-backref" href="#toc-entry-27" role="doc-backlink">Document Header & Footer</a></h3> 2289 <dl class="field-list simple"> 2290 <dt>Directive Types<span class="colon">:</span></dt> 2291 <dd><p>"header" and "footer"</p> 2292 </dd> 2293 <dt>Doctree Elements<span class="colon">:</span></dt> 2294 <dd><p><a class="reference external" href="../doctree.html#decoration"><decoration></a>, <a class="reference external" href="../doctree.html#header"><header></a>, <a class="reference external" href="../doctree.html#footer"><footer></a></p> 2295 </dd> 2296 <dt>Directive Arguments<span class="colon">:</span></dt> 2297 <dd><p>none</p> 2298 </dd> 2299 <dt>Directive Options<span class="colon">:</span></dt> 2300 <dd><p>none</p> 2301 </dd> 2302 <dt>Directive Content<span class="colon">:</span></dt> 2303 <dd><p>Interpreted as body elements.</p> 2304 </dd> 2305 </dl> 2306 <p>The "header" and "footer" directives create document decorations, 2307 useful for page navigation, notes, time/datestamp, etc. For example:</p> 2308 <pre class="literal-block">.. header:: This space for rent.</pre> 2309 <p>This will add a paragraph to the document header, which will appear at 2310 the top of the generated web page or at the top of every printed page.</p> 2311 <p>These directives may be used multiple times, cumulatively. There is 2312 currently support for only one header and footer.</p> 2313 <aside class="admonition tip"> 2314 <p class="admonition-title">Tip</p> 2315 <p>While it is possible to use the "header" and "footer" directives to 2316 create navigational elements for web pages, you should be aware 2317 that Docutils is meant to be used for <em>document</em> processing, and 2318 that a navigation bar is not typically part of a document.</p> 2319 <p>Thus, you may soon find Docutils' abilities to be insufficient for 2320 these purposes. At that time, you should consider using a 2321 documentation generator like <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> rather than the "header" and 2322 "footer" directives.</p> 2323 </aside> 2324 <p>In addition to the use of these directives to populate header and 2325 footer content, content may also be added automatically by the 2326 processing system. For example, if certain runtime settings are 2327 enabled, the document footer is populated with processing information 2328 such as a datestamp, a link to <a class="reference external" href="https://docutils.sourceforge.io">the Docutils website</a>, etc.</p> 2329 </section> 2330 </section> 2331 <section id="references"> 2332 <h2><a class="toc-backref" href="#toc-entry-28" role="doc-backlink">References</a></h2> 2333 <section id="target-footnotes"> 2334 <span id="target-notes"></span><h3><a class="toc-backref" href="#toc-entry-29" role="doc-backlink">Target Footnotes</a></h3> 2335 <dl class="field-list simple" style="--field-indent: 13em;"> 2336 <dt>Directive Type<span class="colon">:</span></dt> 2337 <dd><p>"target-notes"</p> 2338 </dd> 2339 <dt>Doctree Elements<span class="colon">:</span></dt> 2340 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a>, <a class="reference external" href="../doctree.html#footnote"><footnote></a>, <a class="reference external" href="../doctree.html#footnote-reference"><footnote_reference></a></p> 2341 </dd> 2342 <dt>Directive Arguments<span class="colon">:</span></dt> 2343 <dd><p>none</p> 2344 </dd> 2345 <dt>Directive Options<span class="colon">:</span></dt> 2346 <dd><p><a class="reference internal" href="#class-option">class</a></p> 2347 </dd> 2348 <dt>Directive Content<span class="colon">:</span></dt> 2349 <dd><p>none</p> 2350 </dd> 2351 </dl> 2352 <p>The "target-notes" directive generates a list of referenced URIs. 2353 This ensures the information is not lost in a hardcopy.</p> 2354 <p>For every explicit <a class="footnote-reference brackets" href="#footnote-7" id="footnote-reference-17" role="doc-noteref"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a> <a class="reference external" href="restructuredtext.html#external-hyperlink-targets">external hyperlink target</a> in the document, 2355 the "target-notes" directive inserts a <a class="reference external" href="../doctree.html#footnote"><footnote></a> showing the URL 2356 at the place of the directive and a <a class="reference external" href="../doctree.html#footnote-reference"><footnote_reference></a> after each 2357 matching <a class="reference external" href="restructuredtext.html#hyperlink-references">hyperlink reference</a>.</p> 2358 <p>The value of the <a class="reference internal" href="#class-option">class option</a> is passed to the generated footnote 2359 references.</p> 2360 <aside class="footnote-list brackets"> 2361 <aside class="footnote brackets" id="footnote-7" role="doc-footnote"> 2362 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-17">13</a><span class="fn-bracket">]</span></span> 2363 <p><a class="reference external" href="restructuredtext.html#embedded-uris-and-aliases">Embedded URIs</a> like <span class="docutils literal">`this <span class="pre"><http://example.org>`_</span></span> are skipped.</p> 2364 </aside> 2365 </aside> 2366 </section> 2367 <section id="footnotes"> 2368 <h3><a class="toc-backref" href="#toc-entry-30" role="doc-backlink">Footnotes</a></h3> 2369 <p><strong>NOT IMPLEMENTED YET</strong></p> 2370 <dl class="field-list simple" style="--field-indent: 13em;"> 2371 <dt>Directive Type<span class="colon">:</span></dt> 2372 <dd><p>"footnotes"</p> 2373 </dd> 2374 <dt>Doctree Elements<span class="colon">:</span></dt> 2375 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a>, <a class="reference external" href="../doctree.html#topic"><topic></a></p> 2376 </dd> 2377 <dt>Directive Arguments<span class="colon">:</span></dt> 2378 <dd><p>none?</p> 2379 </dd> 2380 <dt>Directive Options<span class="colon">:</span></dt> 2381 <dd><p>Possible?</p> 2382 </dd> 2383 <dt>Directive Content<span class="colon">:</span></dt> 2384 <dd><p>none</p> 2385 </dd> 2386 </dl> 2387 <p>@@@</p> 2388 </section> 2389 <section id="citations"> 2390 <h3><a class="toc-backref" href="#toc-entry-31" role="doc-backlink">Citations</a></h3> 2391 <p><strong>NOT IMPLEMENTED YET</strong></p> 2392 <dl class="field-list simple" style="--field-indent: 13em;"> 2393 <dt>Directive Type<span class="colon">:</span></dt> 2394 <dd><p>"citations"</p> 2395 </dd> 2396 <dt>Doctree Elements<span class="colon">:</span></dt> 2397 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a>, <a class="reference external" href="../doctree.html#topic"><topic></a></p> 2398 </dd> 2399 <dt>Directive Arguments<span class="colon">:</span></dt> 2400 <dd><p>none?</p> 2401 </dd> 2402 <dt>Directive Options<span class="colon">:</span></dt> 2403 <dd><p>Possible?</p> 2404 </dd> 2405 <dt>Directive Content<span class="colon">:</span></dt> 2406 <dd><p>none</p> 2407 </dd> 2408 </dl> 2409 <p>@@@</p> 2410 <!-- - - - - - - - - - - - - - - - 2411 HTML-Specific 2412 - - - - - - - - - - - - - - - 2413 2414 Imagemap 2415 ======== 2416 2417 **NOT IMPLEMENTED YET** 2418 2419 Non-standard element: imagemap. --> 2420 </section> 2421 </section> 2422 <section id="directives-for-substitution-definitions"> 2423 <h2><a class="toc-backref" href="#toc-entry-32" role="doc-backlink">Directives for Substitution Definitions</a></h2> 2424 <p>The directives introduced in this section may only be used in 2425 <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution definitions</a>. They may not be used directly, 2426 in standalone context.</p> 2427 <section id="inline-images"> 2428 <h3><a class="toc-backref" href="#toc-entry-33" role="doc-backlink">Inline Images</a></h3> 2429 <p>The <a class="reference internal" href="#image">image</a> directive can be used both, stand-alone (to define 2430 block-level images) and in substitution definitions to define 2431 inline images.</p> 2432 </section> 2433 <section id="replacement-text"> 2434 <span id="replace"></span><h3><a class="toc-backref" href="#toc-entry-34" role="doc-backlink">Replacement Text</a></h3> 2435 <dl class="field-list simple" style="--field-indent: 13em;"> 2436 <dt>Directive Type<span class="colon">:</span></dt> 2437 <dd><p>"replace"</p> 2438 </dd> 2439 <dt>Doctree Element<span class="colon">:</span></dt> 2440 <dd><p>Text & <a class="reference external" href="../doctree.html#inline-elements">inline elements</a></p> 2441 </dd> 2442 <dt>Directive Arguments<span class="colon">:</span></dt> 2443 <dd><p>none</p> 2444 </dd> 2445 <dt>Directive Options<span class="colon">:</span></dt> 2446 <dd><p>none</p> 2447 </dd> 2448 <dt>Directive Content<span class="colon">:</span></dt> 2449 <dd><p>A single paragraph; may contain inline markup.</p> 2450 </dd> 2451 </dl> 2452 <p>The "replace" directive is used to indicate replacement text for a 2453 substitution reference. It may be used within <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution 2454 definitions</a> only. For example, this directive can be used to expand 2455 abbreviations:</p> 2456 <pre class="literal-block">.. |reST| replace:: reStructuredText 2457 2458 Yes, |reST| is a long word, so I can't blame anyone for wanting to 2459 abbreviate it.</pre> 2460 <p id="hyperlink-workaround">As reStructuredText doesn't support nested inline markup, the only way 2461 to create a reference with styled text is to use substitutions with 2462 the "replace" directive:</p> 2463 <pre class="literal-block">I recommend you try |Python|_. 2464 2465 .. |Python| replace:: Python, *the* best language around 2466 .. _Python: https://www.python.org/</pre> 2467 </section> 2468 <section id="unicode-character-codes"> 2469 <span id="unicode"></span><h3><a class="toc-backref" href="#toc-entry-35" role="doc-backlink">Unicode Character Codes</a></h3> 2470 <dl class="field-list simple" style="--field-indent: 13em;"> 2471 <dt>Directive Type<span class="colon">:</span></dt> 2472 <dd><p>"unicode"</p> 2473 </dd> 2474 <dt>Doctree Element<span class="colon">:</span></dt> 2475 <dd><p>Text</p> 2476 </dd> 2477 <dt>Directive Arguments<span class="colon">:</span></dt> 2478 <dd><p>one or more, required (Unicode character codes, 2479 optional text, and comments)</p> 2480 </dd> 2481 <dt>Directive Options<span class="colon">:</span></dt> 2482 <dd><p><a class="reference internal" href="#unicode-options">see below</a></p> 2483 </dd> 2484 <dt>Directive Content<span class="colon">:</span></dt> 2485 <dd><p>none</p> 2486 </dd> 2487 </dl> 2488 <p>The "unicode" directive converts Unicode character codes (numerical 2489 values) to characters, and may be used in <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution definitions</a> 2490 only.</p> 2491 <p>The arguments, separated by spaces, can be:</p> 2492 <ul class="simple" id="character-code"> 2493 <li><p><strong>character codes</strong> as</p> 2494 <ul> 2495 <li><p>decimal numbers or</p></li> 2496 <li><p>hexadecimal numbers, prefixed by <span class="docutils literal">0x</span>, <span class="docutils literal">x</span>, <span class="docutils literal">\x</span>, <span class="docutils literal">U+</span>, 2497 <span class="docutils literal">u</span>, or <span class="docutils literal">\u</span> or as XML-style hexadecimal character entities, 2498 e.g. <span class="docutils literal">&#x1a2b;</span></p></li> 2499 </ul> 2500 </li> 2501 <li><p><strong>text</strong>, which is used as-is.</p></li> 2502 </ul> 2503 <p>Text following " .. " is a comment and is ignored. The spaces between 2504 the arguments are ignored and thus do not appear in the output. 2505 Hexadecimal codes are case-insensitive.</p> 2506 <p>For example, the following text:</p> 2507 <pre class="literal-block">Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| 2508 all rights reserved. 2509 2510 .. |copy| unicode:: 0xA9 .. copyright sign 2511 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 2512 .. with trademark sign 2513 .. |---| unicode:: U+02014 .. em dash 2514 :trim:</pre> 2515 <p>results in:</p> 2516 <blockquote> 2517 <p>Copyright © 2003, BogusMegaCorp™—all rights reserved.</p> 2518 </blockquote> 2519 <p>Docutils comes with a set of character substitution 2520 definitions in the <a class="reference external" href="definitions.html">reStructuredText Standard Definition Files</a>.</p> 2521 <p id="unicode-options">The "unicode" directive recognizes the following options:</p> 2522 <dl> 2523 <dt><span class="docutils literal">ltrim</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2524 <dd><p>Whitespace to the left of the substitution reference is removed.</p> 2525 </dd> 2526 <dt><span class="docutils literal">rtrim</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2527 <dd><p>Whitespace to the right of the substitution reference is removed.</p> 2528 </dd> 2529 <dt><span class="docutils literal">trim</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2530 <dd><p>Equivalent to <span class="docutils literal">ltrim</span> plus <span class="docutils literal">rtrim</span>; whitespace on both sides 2531 of the substitution reference is removed.</p> 2532 </dd> 2533 </dl> 2534 </section> 2535 <section id="date"> 2536 <h3><a class="toc-backref" href="#toc-entry-36" role="doc-backlink">Date</a></h3> 2537 <dl class="field-list simple" style="--field-indent: 13em;"> 2538 <dt>Directive Type<span class="colon">:</span></dt> 2539 <dd><p>"date"</p> 2540 </dd> 2541 <dt>Doctree Element<span class="colon">:</span></dt> 2542 <dd><p>Text</p> 2543 </dd> 2544 <dt>Directive Arguments<span class="colon">:</span></dt> 2545 <dd><p>one, optional (date format)</p> 2546 </dd> 2547 <dt>Directive Options<span class="colon">:</span></dt> 2548 <dd><p>none</p> 2549 </dd> 2550 <dt>Directive Content<span class="colon">:</span></dt> 2551 <dd><p>none</p> 2552 </dd> 2553 </dl> 2554 <p>The "date" directive generates the current local date and inserts it 2555 into the document as text. This directive may be used in substitution 2556 definitions only.</p> 2557 <p>The optional directive content is interpreted as the desired date 2558 format, using the same codes as Python's <a class="reference external" href="https://docs.python.org/3/library/time.html#time.strftime">time.strftime()</a> function. The 2559 default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also 2560 be used. Examples:</p> 2561 <pre class="literal-block">.. |date| date:: 2562 .. |time| date:: %H:%M 2563 2564 Today's date is |date|. 2565 2566 This document was generated on |date| at |time|.</pre> 2567 </section> 2568 </section> 2569 <section id="miscellaneous"> 2570 <h2><a class="toc-backref" href="#toc-entry-37" role="doc-backlink">Miscellaneous</a></h2> 2571 <section id="including-an-external-document-fragment"> 2572 <span id="include"></span><h3><a class="toc-backref" href="#toc-entry-38" role="doc-backlink">Including an External Document Fragment</a></h3> 2573 <dl class="field-list simple" style="--field-indent: 13em;"> 2574 <dt>Directive Type<span class="colon">:</span></dt> 2575 <dd><p>"include"</p> 2576 </dd> 2577 <dt>Doctree Elements<span class="colon">:</span></dt> 2578 <dd><p>Depend on data being included; 2579 <a class="reference external" href="../doctree.html#literal-block"><literal_block></a> with <span class="docutils literal">code</span> or <span class="docutils literal">literal</span> option.</p> 2580 </dd> 2581 <dt>Directive Arguments<span class="colon">:</span></dt> 2582 <dd><p>one, required (<a class="reference internal" href="#path">path</a> to the file to include)</p> 2583 </dd> 2584 <dt>Directive Options<span class="colon">:</span></dt> 2585 <dd><p><a class="reference internal" href="#include-options">see below</a></p> 2586 </dd> 2587 <dt>Directive Content<span class="colon">:</span></dt> 2588 <dd><p>none</p> 2589 </dd> 2590 <dt>Configuration Setting<span class="colon">:</span></dt> 2591 <dd><p><a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>, <a class="reference external" href="../../user/config.html#root-prefix">root_prefix</a></p> 2592 </dd> 2593 </dl> 2594 <aside class="admonition warning"> 2595 <p class="admonition-title">Warning</p> 2596 <p>The "include" directive represents a potential security hole. It 2597 can be disabled with the "<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" runtime setting.</p> 2598 </aside> 2599 <p>The "include" directive reads a text file. The directive argument is 2600 the path to the file to be included, relative to the document containing 2601 the directive. Unless the options <span class="docutils literal">literal</span>, <span class="docutils literal">code</span>, or <span class="docutils literal">parser</span> 2602 are given, the file is parsed in the current document's context at the 2603 point of the directive. For example:</p> 2604 <pre class="literal-block">This first example will be parsed at the document level, and can 2605 thus contain any construct, including section headers. 2606 2607 .. include:: inclusion.rst 2608 2609 Back in the main document. 2610 2611 This second example will be parsed in a block quote context. 2612 Therefore it may only contain body elements. It may not 2613 contain section headers. 2614 2615 .. include:: inclusion.rst</pre> 2616 <p>If an included document fragment contains section structure, the title 2617 adornments must match those of the master document.</p> 2618 <p>Standard data files intended for inclusion in reStructuredText 2619 documents are distributed with the Docutils source code, located in 2620 the "docutils" package in the <span class="docutils literal">docutils/parsers/rst/include</span> 2621 directory. To access these files, use the special syntax for standard 2622 "include" data files, angle brackets around the file name:</p> 2623 <pre class="literal-block">.. include:: <isonum.txt></pre> 2624 <p>The current set of standard "include" data files consists of sets of 2625 substitution definitions. See <a class="reference external" href="definitions.html">reStructuredText Standard Definition 2626 Files</a> for details.</p> 2627 <p id="include-options">The "include" directive recognizes the following options:</p> 2628 <dl> 2629 <dt><span class="docutils literal">code</span><span class="classifier"><a class="reference internal" href="#text">text</a> (formal language, optional)</span></dt> 2630 <dd><p>The argument and the included content are passed to 2631 the <a class="reference internal" href="#code">code</a> directive (useful for program listings).</p> 2632 </dd> 2633 <dt><span class="docutils literal">encoding</span><span class="classifier"><a class="reference internal" href="#encoding">encoding</a></span></dt> 2634 <dd><p>The text encoding of the external file. 2635 Defaults to the document's <a class="reference external" href="../../user/config.html#input-encoding">input_encoding</a>.</p> 2636 </dd> 2637 <dt><span class="docutils literal"><span class="pre">end-before</span></span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 2638 <dd><p>Only the content before the first occurrence of the specified <em>text</em> 2639 in the external data file (but after any <span class="docutils literal"><span class="pre">start-after</span></span> text) 2640 will be included.</p> 2641 </dd> 2642 <dt><span class="docutils literal"><span class="pre">end-line</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2643 <dd><p>Only the content up to (but excluding) this line will be included.</p> 2644 </dd> 2645 <dt><span class="docutils literal">literal</span><span class="classifier"><a class="reference internal" href="#flag">flag</a></span></dt> 2646 <dd><p>The entire included text is inserted into the document as a single 2647 literal block.</p> 2648 </dd> 2649 <dt><span class="docutils literal"><span class="pre">number-lines</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a> (start line number, optional)</span></dt> 2650 <dd><p>Precede every included line with a line number. 2651 The optional argument is the number of the first line (default 1). 2652 Works only with <span class="docutils literal">code</span> or <span class="docutils literal">literal</span>.</p> 2653 </dd> 2654 <dt><span class="docutils literal">parser</span><span class="classifier"><a class="reference internal" href="#text">text</a> (parser name)</span></dt> 2655 <dd><p>Parse the included content with the specified parser. 2656 See the <a class="reference external" href="../../user/config.html#parser">"parser" configuration setting</a> for available parsers.</p> 2657 <aside class="admonition caution"> 2658 <p class="admonition-title">Caution!</p> 2659 <p>There is is no check whether the inserted elements are valid at the 2660 point of insertion. It is recommended to <a class="reference external" href="../../user/config.html#validate">validate</a> the document.</p> 2661 </aside> 2662 <p>(New in Docutils 0.17. Provisional.)</p> 2663 </dd> 2664 <dt><span class="docutils literal"><span class="pre">start-after</span></span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 2665 <dd><p>Only the content after the first occurrence of the specified <em>text</em> 2666 in the external data file will be included.</p> 2667 </dd> 2668 <dt><span class="docutils literal"><span class="pre">start-line</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2669 <dd><p>Only the content starting from this line will be included. 2670 (As usual in Python, the first line has index 0 and negative values 2671 count from the end.)</p> 2672 </dd> 2673 <dt><span class="docutils literal"><span class="pre">tab-width</span></span><span class="classifier"><a class="reference internal" href="#integer">integer</a></span></dt> 2674 <dd><p>Number of spaces for hard tab expansion. 2675 Must be a positive integer, except for literal inclusions and code, 2676 where a negative value prevents expansion of hard tabs. 2677 Defaults to the <a class="reference external" href="../../user/config.html#tab-width">tab_width</a> configuration setting.</p> 2678 </dd> 2679 </dl> 2680 <p>With <span class="docutils literal">code</span> or <span class="docutils literal">literal</span>, the common options <a class="reference internal" href="#class-option">class</a> 2681 and <a class="reference internal" href="#name">name</a> are recognized as well.</p> 2682 <p>Combining <span class="docutils literal"><span class="pre">start-line</span></span>/<span class="docutils literal"><span class="pre">end-line</span></span> and <span class="docutils literal"><span class="pre">start-after</span></span>/<span class="docutils literal"><span class="pre">end-before</span></span> 2683 is possible. The text markers will be searched in the specified lines 2684 (further limiting the included content).</p> 2685 </section> 2686 <section id="raw-data-pass-through"> 2687 <span id="raw"></span><h3><a class="toc-backref" href="#toc-entry-39" role="doc-backlink">Raw Data Pass-Through</a></h3> 2688 <dl class="field-list simple" style="--field-indent: 13em;"> 2689 <dt>Directive Type<span class="colon">:</span></dt> 2690 <dd><p>"raw"</p> 2691 </dd> 2692 <dt>Doctree Element<span class="colon">:</span></dt> 2693 <dd><p><a class="reference external" href="../doctree.html#raw"><raw></a></p> 2694 </dd> 2695 <dt>Directive Arguments<span class="colon">:</span></dt> 2696 <dd><p>one or more, required (output format types)</p> 2697 </dd> 2698 <dt>Directive Options<span class="colon">:</span></dt> 2699 <dd><p><a class="reference internal" href="#raw-options">see below</a></p> 2700 </dd> 2701 <dt>Directive Content<span class="colon">:</span></dt> 2702 <dd><p>Stored verbatim, uninterpreted. 2703 None (empty) if a <span class="docutils literal">file</span> or <span class="docutils literal">url</span> option given.</p> 2704 </dd> 2705 <dt>Configuration Settings<span class="colon">:</span></dt> 2706 <dd><p><a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a>, <a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>, <a class="reference external" href="../../user/config.html#root-prefix">root_prefix</a></p> 2707 </dd> 2708 </dl> 2709 <aside class="admonition warning"> 2710 <p class="admonition-title">Warning</p> 2711 <p>The "raw" directive represents a potential security hole. It can 2712 be disabled with the "<a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a>" runtime setting. 2713 Insertion of external files can be disabled with the 2714 "<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" runtime setting.</p> 2715 </aside> 2716 <aside class="admonition caution"> 2717 <p class="admonition-title">Caution!</p> 2718 <p>The "raw" directive is a stop-gap measure allowing the author to 2719 bypass reStructuredText's markup. It is a "power-user" feature 2720 that should not be overused or abused. The use of "raw" ties 2721 documents to specific output formats and makes them less portable.</p> 2722 <p>If you often need to use the "raw" directive or a "raw"-derived 2723 interpreted text role, that is a sign either of overuse/abuse or 2724 that functionality may be missing from reStructuredText. Please 2725 describe your situation in a message to the <a class="reference external" href="../../user/mailing-lists.html#docutils-users">Docutils-users</a> mailing 2726 list.</p> 2727 </aside> 2728 <p>The "raw" directive indicates non-reStructuredText data that is to be 2729 passed untouched to the Writer. The names of the output formats are 2730 given in the directive arguments. The interpretation of the raw data 2731 is up to the Writer. A Writer may ignore any raw output not matching 2732 its format.</p> 2733 <p>For example, the following input would be passed untouched by an HTML 2734 writer:</p> 2735 <pre class="literal-block">.. raw:: html 2736 2737 <hr width=50 size=10></pre> 2738 <p>A LaTeX Writer could insert the following raw content into its 2739 output stream:</p> 2740 <pre class="literal-block">.. raw:: latex 2741 2742 \setlength{\parindent}{0pt}</pre> 2743 <p>Raw data can also be read from an external file, specified in the 2744 <span class="docutils literal">file</span> or <span class="docutils literal">url</span> directive option. 2745 In this case, the content block must be empty. 2746 For example:</p> 2747 <pre class="literal-block">.. raw:: html 2748 :file: inclusion.html</pre> 2749 <p>Inline equivalents of the "raw" directive can be defined via 2750 <a class="reference internal" href="#custom-interpreted-text-roles">custom interpreted text roles</a> derived from the <a class="reference external" href="roles.html#raw">"raw" role</a>.</p> 2751 <p id="raw-options">The "raw" directive recognizes the common option <a class="reference internal" href="#class-option">class</a> 2752 as well as</p> 2753 <dl> 2754 <dt><span class="docutils literal">encoding</span><span class="classifier"><a class="reference internal" href="#encoding">encoding</a></span></dt> 2755 <dd><p>The text encoding of the external raw data (with <span class="docutils literal">file</span> or <span class="docutils literal">url</span>). 2756 Defaults to the main document's <a class="reference external" href="../../user/config.html#input-encoding">input_encoding</a>.</p> 2757 </dd> 2758 <dt><span class="docutils literal">file</span><span class="classifier"><a class="reference internal" href="#path">path</a></span></dt> 2759 <dd><p>The local filesystem path of a raw data file to be included.</p> 2760 </dd> 2761 <dt><span class="docutils literal">url</span><span class="classifier"><a class="reference internal" href="#uri">URI</a></span></dt> 2762 <dd><p>A URI reference to a raw data file to be included.</p> 2763 </dd> 2764 </dl> 2765 </section> 2766 <section id="class"> 2767 <span id="rst-class"></span><span id="class-directive"></span><h3><a class="toc-backref" href="#toc-entry-40" role="doc-backlink">Class</a></h3> 2768 <dl class="field-list simple" style="--field-indent: 13em;"> 2769 <dt>Directive Type<span class="colon">:</span></dt> 2770 <dd><p>"class" or "rst-class" (synonyms) <a class="footnote-reference brackets" href="#footnote-8" id="footnote-reference-18" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></a></p> 2771 </dd> 2772 <dt>Doctree Element<span class="colon">:</span></dt> 2773 <dd><p><a class="reference external" href="../doctree.html#pending"><pending></a></p> 2774 </dd> 2775 <dt>Directive Arguments<span class="colon">:</span></dt> 2776 <dd><p>one or more, required 2777 (class names / attribute values)</p> 2778 </dd> 2779 <dt>Directive Options<span class="colon">:</span></dt> 2780 <dd><p>none</p> 2781 </dd> 2782 <dt>Directive Content<span class="colon">:</span></dt> 2783 <dd><p>Optional. If present, it is interpreted as body 2784 elements.</p> 2785 </dd> 2786 </dl> 2787 <p>The "class" directive sets the <a class="reference external" href="../doctree.html#classes">classes attribute</a> value on its content 2788 or on the next visible <a class="footnote-reference brackets" href="#footnote-9" id="footnote-reference-19" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a> element. <a class="footnote-reference brackets" href="#footnote-10" id="footnote-reference-20" role="doc-noteref"><span class="fn-bracket">[</span>16<span class="fn-bracket">]</span></a> 2789 The directive argument consists of one or more space-separated class 2790 names. The names are transformed to conform to the regular expression 2791 <span class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></span> (see <a class="reference internal" href="#identifier-normalization">Identifier Normalization</a> below).</p> 2792 <aside class="admonition tip"> 2793 <p class="admonition-title">Tip</p> 2794 <p>For reStructuredText directives, the <a class="reference internal" href="#class-option">class option</a> provides 2795 a more compact markup alternative.</p> 2796 </aside> 2797 <p>Examples:</p> 2798 <pre class="literal-block">.. class:: special 2799 2800 This is a "special" paragraph. 2801 2802 .. class:: exceptional remarkable 2803 2804 An Exceptional Section 2805 ====================== 2806 2807 This is an ordinary paragraph. 2808 2809 .. class:: multiple 2810 2811 First paragraph. 2812 2813 Second paragraph.</pre> 2814 <p>The text above is parsed and transformed into this <a class="reference external" href="../doctree.html">doctree</a> fragment:</p> 2815 <pre class="literal-block"><paragraph classes="special"> 2816 This is a "special" paragraph. 2817 <section classes="exceptional remarkable"> 2818 <title> 2819 An Exceptional Section 2820 <paragraph> 2821 This is an ordinary paragraph. 2822 <paragraph classes="multiple"> 2823 First paragraph. 2824 <paragraph classes="multiple"> 2825 Second paragraph.</pre> 2826 <p>Indented text after the directive is interpreted as content block. 2827 To set a classes attribute value on a <a class="reference external" href="restructuredtext.html#block-quotes">block quote</a>, the 2828 "class" directive must be followed by a comment:</p> 2829 <pre class="literal-block">.. class:: special 2830 .. 2831 2832 Special block quote.</pre> 2833 <p>results in this <a class="reference external" href="../doctree.html">doctree</a> fragment:</p> 2834 <pre class="literal-block"><comment xml:space="preserve"> 2835 <block_quote classes="special"> 2836 <paragraph> 2837 Special block quote.</pre> 2838 <aside class="footnote-list brackets"> 2839 <aside class="footnote brackets" id="footnote-8" role="doc-footnote"> 2840 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-18">14</a><span class="fn-bracket">]</span></span> 2841 <p><a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> uses the directive name "class" for <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/domains/">domain specific</a> 2842 directives (by default "<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/domains/python.html#directive-py-class">py:class</a>"). 2843 The "rst-class" synonym is compatible with Sphinx.</p> 2844 </aside> 2845 <aside class="footnote brackets" id="footnote-9" role="doc-footnote"> 2846 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-19">15</a><span class="fn-bracket">]</span></span> 2847 <p>Elements that are not shown in the output (<a class="reference external" href="restructuredtext.html#comments">comments</a>, 2848 <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution definitions</a>, <a class="reference external" href="restructuredtext.html#hyperlink-targets">hyperlink targets</a>, ...) as well as 2849 "<a class="reference internal" href="#header">header</a>" and "<a class="reference internal" href="#footer">footer</a>" directives are skipped.</p> 2850 </aside> 2851 <aside class="footnote brackets" id="footnote-10" role="doc-footnote"> 2852 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-20">16</a><span class="fn-bracket">]</span></span> 2853 <p>This also works if the class directive is "nested" at the end of 2854 an indented text block. 2855 This allows the "classification" of individual list items (except the 2856 first, as a preceding class directive applies to the list as a whole):</p> 2857 <pre class="literal-block">* bullet list 2858 2859 .. class:: classy-item 2860 2861 * second item, with class argument</pre> 2862 </aside> 2863 </aside> 2864 <section id="identifier-normalization"> 2865 <h4>Identifier Normalization</h4> 2866 <p>Docutils normalizes <a class="reference external" href="../doctree.html#class-names">class names</a> and <a class="reference external" href="../doctree.html#identifiers">identifiers</a> to conform 2867 to the regular expression "<span class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></span>" by converting</p> 2868 <ul class="simple"> 2869 <li><p>alphabetic characters to lowercase,</p></li> 2870 <li><p>accented characters to the base character,</p></li> 2871 <li><p>non-alphanumeric characters to hyphens,</p></li> 2872 <li><p>consecutive hyphens into one hyphen</p></li> 2873 </ul> 2874 <p>and stripping</p> 2875 <ul class="simple"> 2876 <li><p>leading hyphens and number characters, and</p></li> 2877 <li><p>trailing hyphens.</p></li> 2878 </ul> 2879 <p>For example <span class="docutils literal"><span class="pre">"Rot.Gelb&Grün::2008+"</span></span> becomes <span class="docutils literal"><span class="pre">"rot-gelb-grun-2008"</span></span> and 2880 <span class="docutils literal">"1000_Steps!"</span> becomes <span class="docutils literal">"steps"</span>.</p> 2881 <aside class="topic"> 2882 <p class="topic-title">Rationale:</p> 2883 <p>Identifier keys must be valid in all supported output formats.</p> 2884 <p>For HTML 4.1 + CSS1 compatibility, identifiers should have no 2885 underscores, colons, or periods. Hyphens may be used.</p> 2886 <ul> 2887 <li><p>The <a class="reference external" href="https://www.w3.org/TR/html401/">HTML 4.01 spec</a> defines identifiers based on SGML tokens:</p> 2888 <blockquote> 2889 <p>ID and NAME tokens must begin with a letter ([A-Za-z]) and 2890 may be followed by any number of letters, digits ([0-9]), 2891 hyphens ("-"), underscores ("_"), colons (":"), and periods 2892 (".").</p> 2893 <p class="attribution">—<a class="reference external" href="https://www.w3.org/TR/html401/types.html#type-name">https://www.w3.org/TR/html401/types.html#type-name</a></p> 2894 </blockquote> 2895 </li> 2896 <li><p>The <a class="reference external" href="https://www.w3.org/TR/REC-CSS1">CSS1 spec</a> defines identifiers based on the "name" token 2897 ("flex" tokenizer notation below):</p> 2898 <pre class="literal-block">unicode \\[0-9a-f]{1,4} 2899 latin1 [¡-ÿ] 2900 escape {unicode}|\\[ -~¡-ÿ] 2901 nmchar [-a-z0-9]|{latin1}|{escape} 2902 name {nmchar}+</pre> 2903 </li> 2904 </ul> 2905 <p>The CSS1 rule requires underscores ("_"), colons (":"), and 2906 periods (".") to be escaped <a class="footnote-reference brackets" href="#footnote-11" id="footnote-reference-21" role="doc-noteref"><span class="fn-bracket">[</span>17<span class="fn-bracket">]</span></a>, 2907 therefore <a class="reference external" href="../doctree.html#classes">classes</a> and <a class="reference external" href="../doctree.html#ids">ids attribute</a>s should not 2908 contain these characters. Combined with HTML4.1 requirements (the 2909 first character must be a letter; no "unicode", "latin1", or 2910 "escape" characters), this results in the regular expression 2911 <span class="docutils literal"><span class="pre">[A-Za-z][-A-Za-z0-9]*</span></span>. Docutils adds a normalization by 2912 downcasing and merge of consecutive hyphens.</p> 2913 <aside class="footnote-list brackets"> 2914 <aside class="footnote brackets" id="footnote-11" role="doc-footnote"> 2915 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-21">17</a><span class="fn-bracket">]</span></span> 2916 <p>CSS identifiers may use underscores ("_") directly in 2917 <a class="reference external" href="https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier">CSS Level 1</a>, <a class="reference external" href="https://www.w3.org/TR/CSS/#css-level-1">CSS2.1</a>, <a class="reference external" href="https://www.w3.org/TR/CSS22/syndata.html">CSS2.2</a>, and <a class="reference external" href="https://www.w3.org/TR/css-syntax-3/#typedef-ident-token">CSS3</a>.</p> 2918 </aside> 2919 </aside> 2920 </aside> 2921 </section> 2922 </section> 2923 <section id="custom-interpreted-text-roles"> 2924 <span id="role"></span><h3><a class="toc-backref" href="#toc-entry-41" role="doc-backlink">Custom Interpreted Text Roles</a></h3> 2925 <dl class="field-list simple" style="--field-indent: 13em;"> 2926 <dt>Directive Type<span class="colon">:</span></dt> 2927 <dd><p>"role"</p> 2928 </dd> 2929 <dt>Doctree Element<span class="colon">:</span></dt> 2930 <dd><p>none; affects subsequent parsing</p> 2931 </dd> 2932 <dt>Directive Arguments<span class="colon">:</span></dt> 2933 <dd><p>two; one required (new <a class="reference internal" href="#role-name">role name</a>), one optional 2934 (base role name, in parentheses)</p> 2935 </dd> 2936 <dt>Directive Options<span class="colon">:</span></dt> 2937 <dd><p><a class="reference internal" href="#role-options">see below</a></p> 2938 </dd> 2939 <dt>Directive Content<span class="colon">:</span></dt> 2940 <dd><p>depends on base role.</p> 2941 </dd> 2942 </dl> 2943 <p>The "role" directive dynamically creates a custom <a class="reference external" href="roles.html">interpreted text 2944 role</a> and registers it with the parser. This means that after 2945 declaring a role like this:</p> 2946 <pre class="literal-block">.. role:: custom</pre> 2947 <p>the document may use the new "custom" role:</p> 2948 <pre class="literal-block">An example of using :custom:`interpreted text`</pre> 2949 <p>This will be parsed into the following document tree fragment:</p> 2950 <pre class="literal-block"><paragraph> 2951 An example of using 2952 <inline classes="custom"> 2953 interpreted text</pre> 2954 <p id="role-name"><em>Role names</em> are case insensitive and must conform to the rules of 2955 simple <a class="reference external" href="restructuredtext.html#reference-names">reference names</a> (but do not share a namespace with 2956 hyperlinks, footnotes, and citations).</p> 2957 <p>The new role may be based on an existing role, specified as a second 2958 argument in parentheses (whitespace optional):</p> 2959 <pre class="literal-block">.. role:: custom(emphasis) 2960 2961 :custom:`text`</pre> 2962 <p>The parsed result is as follows:</p> 2963 <pre class="literal-block"><paragraph> 2964 <emphasis classes="custom"> 2965 text</pre> 2966 <p>A special case is the <a class="reference external" href="roles.html#raw">"raw" role</a>: derived roles enable 2967 inline <a class="reference internal" href="#raw-data-pass-through">raw data pass-through</a>, e.g.:</p> 2968 <pre class="literal-block">.. role:: raw-role(raw) 2969 :format: html latex 2970 2971 :raw-role:`raw text`</pre> 2972 <p>If no base role is explicitly specified, a generic custom role is 2973 automatically used. Subsequent interpreted text will produce an 2974 <a class="reference external" href="../doctree.html#inline"><inline></a> element with a <a class="reference external" href="../doctree.html#classes">classes attribute</a>, as in the first 2975 example above.</p> 2976 <p id="role-options">Depending on the base role, the following options may be recognized by the 2977 "role" directive:</p> 2978 <dl id="role-directive-class-option"> 2979 <dt>class<span class="classifier">space separated list of <a class="reference external" href="../doctree.html#class-names">class names</a></span></dt> 2980 <dd><p>Set the <a class="reference external" href="../doctree.html#classes">classes attribute</a> value on the element produced 2981 when the custom interpreted text role is used. 2982 Default value is the directive argument (role name).</p> 2983 <p>For example</p> 2984 <pre class="literal-block">.. role:: custom 2985 :class: special 2986 2987 :custom:`interpreted text`</pre> 2988 <p>is parsed as</p> 2989 <pre class="literal-block"><paragraph> 2990 <inline classes="special"> 2991 interpreted text</pre> 2992 <p>The "class" option is recognized with all interpreted text roles.</p> 2993 </dd> 2994 <dt><span class="target" id="format">format</span><span class="classifier">space-separated list of output format names (<a class="reference external" href="../../user/config.html#writer-docutils-application">writer names</a>)</span></dt> 2995 <dd><p>Specify the generated <raw> element's <a class="reference external" href="../doctree.html#format">format attribute</a>.</p> 2996 <p>Only recognized with the <a class="reference external" href="roles.html#raw">"raw"</a> base role.</p> 2997 </dd> 2998 <dt><span class="target" id="language">language</span><span class="classifier"><a class="reference internal" href="#text">text</a> (formal language)</span></dt> 2999 <dd><p>Name of a formal language, passed to <a class="reference external" href="https://pygments.org/">Pygments</a> for syntax highlighting. 3000 See <a class="reference external" href="https://pygments.org/languages/">supported languages and markup formats</a> for recognized values.</p> 3001 <p>Only recognized with the <a class="reference external" href=""code"role">"code"</a> base role.</p> 3002 </dd> 3003 </dl> 3004 </section> 3005 <section id="setting-the-default-interpreted-text-role"> 3006 <span id="default-role"></span><h3><a class="toc-backref" href="#toc-entry-42" role="doc-backlink">Setting the Default Interpreted Text Role</a></h3> 3007 <dl class="field-list simple" style="--field-indent: 13em;"> 3008 <dt>Directive Type<span class="colon">:</span></dt> 3009 <dd><p>"default-role"</p> 3010 </dd> 3011 <dt>Doctree Element<span class="colon">:</span></dt> 3012 <dd><p>none; affects subsequent parsing</p> 3013 </dd> 3014 <dt>Directive Arguments<span class="colon">:</span></dt> 3015 <dd><p>one, optional (new default role name)</p> 3016 </dd> 3017 <dt>Directive Options<span class="colon">:</span></dt> 3018 <dd><p>none</p> 3019 </dd> 3020 <dt>Directive Content<span class="colon">:</span></dt> 3021 <dd><p>none</p> 3022 </dd> 3023 </dl> 3024 <p>The "default-role" directive sets the default interpreted text role, 3025 the role that is used for interpreted text without an explicit role. 3026 For example, after setting the default role like this:</p> 3027 <pre class="literal-block">.. default-role:: subscript</pre> 3028 <p>any subsequent use of implicit-role interpreted text in the document 3029 will use the "subscript" role:</p> 3030 <pre class="literal-block">An example of a `default` role.</pre> 3031 <p>This will be parsed into the following document tree fragment:</p> 3032 <pre class="literal-block"><paragraph> 3033 An example of a 3034 <subscript> 3035 default 3036 role.</pre> 3037 <p>Custom roles may be used (see the "<a class="reference internal" href="#role">role</a>" directive above), but it 3038 must have been declared in a document before it can be set as the 3039 default role. See the <a class="reference external" href="roles.html">reStructuredText Interpreted Text Roles</a> 3040 document for details of built-in roles.</p> 3041 <p>The directive may be used without an argument to restore the initial 3042 default interpreted text role, which is application-dependent. The 3043 initial default interpreted text role of the standard reStructuredText 3044 parser is "title-reference".</p> 3045 </section> 3046 <section id="metadata"> 3047 <span id="meta"></span><h3><a class="toc-backref" href="#toc-entry-43" role="doc-backlink">Metadata</a></h3> 3048 <dl class="field-list simple" style="--field-indent: 13em;"> 3049 <dt>Directive Type<span class="colon">:</span></dt> 3050 <dd><p>"meta"</p> 3051 </dd> 3052 <dt>Doctree Element<span class="colon">:</span></dt> 3053 <dd><p><a class="reference external" href="../doctree.html#meta"><meta></a></p> 3054 </dd> 3055 <dt>Directive Arguments<span class="colon">:</span></dt> 3056 <dd><p>none</p> 3057 </dd> 3058 <dt>Directive Options<span class="colon">:</span></dt> 3059 <dd><p>none</p> 3060 </dd> 3061 <dt>Directive Content<span class="colon">:</span></dt> 3062 <dd><p>Must contain a flat <a class="reference external" href="restructuredtext.html#field-lists">field list</a>.</p> 3063 </dd> 3064 </dl> 3065 <p>The "meta" directive is used to specify metadata <a class="footnote-reference brackets" href="#footnote-12" id="footnote-reference-22" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a> to be stored 3066 in, e.g., <a class="reference external" href="https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element">HTML meta elements</a> or as <a class="reference external" href="https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Metadata">ODT file properties</a>. The 3067 LaTeX writer passes it to the <span class="docutils literal">pdfinfo</span> option of the <a class="reference external" href="https://ctan.org/pkg/hyperref">hyperref</a> 3068 package. If an output format does not support "invisible" metadata, 3069 content is silently dropped by the writer.</p> 3070 <aside class="admonition note"> 3071 <p class="admonition-title">Note</p> 3072 <p>Data from some <a class="reference external" href="restructuredtext.html#bibliographic-fields">bibliographic fields</a> is automatically 3073 extracted and stored as metadata, too. However, Bibliographic 3074 Fields are also displayed in the document's screen rendering or 3075 printout.</p> 3076 <p>For an "invisible" <em>document title</em>, see the <a class="reference internal" href="#metadata-document-title">metadata document 3077 title</a> directive below.</p> 3078 </aside> 3079 <p>Within the directive block, a flat field list provides the syntax for 3080 metadata. The field name becomes the contents of the "name" attribute 3081 of the META tag, and the field body (interpreted as a single string 3082 without inline markup) becomes the contents of the "content" 3083 attribute. For example:</p> 3084 <pre class="literal-block">.. meta:: 3085 :description: The reStructuredText plaintext markup language 3086 :keywords: plaintext, markup language</pre> 3087 <p>This would be converted to the following HTML:</p> 3088 <pre class="literal-block"><meta name="description" 3089 content="The reStructuredText plaintext markup language"> 3090 <meta name="keywords" content="plaintext, markup language"></pre> 3091 <p>Support for other META attributes ("http-equiv", "scheme", "lang", 3092 "dir") are provided through field arguments, which must be of the form 3093 "attr=value":</p> 3094 <pre class="literal-block">.. meta:: 3095 :description lang=en: An amusing story 3096 :description lang=fr: Une histoire amusante</pre> 3097 <p>And their HTML equivalents:</p> 3098 <pre class="literal-block"><meta name="description" lang="en" content="An amusing story"> 3099 <meta name="description" lang="fr" content="Une histoire amusante"></pre> 3100 <p>Some META tags use an "http-equiv" attribute instead of the "name" 3101 attribute. To specify "http-equiv" META tags, simply omit the name:</p> 3102 <pre class="literal-block">.. meta:: 3103 :http-equiv=Content-Type: text/html; charset=ISO-8859-1</pre> 3104 <p>HTML equivalent:</p> 3105 <pre class="literal-block"><meta http-equiv="Content-Type" 3106 content="text/html; charset=ISO-8859-1"></pre> 3107 <aside class="footnote-list brackets"> 3108 <aside class="footnote brackets" id="footnote-12" role="doc-footnote"> 3109 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-22">18</a><span class="fn-bracket">]</span></span> 3110 <p>"Metadata" is data about data, in this case data about the 3111 document. Metadata is, e.g., used to describe and classify web 3112 pages in the World Wide Web, in a form that is easy for search 3113 engines to extract and collate.</p> 3114 </aside> 3115 </aside> 3116 </section> 3117 <section id="metadata-document-title"> 3118 <span id="title"></span><h3><a class="toc-backref" href="#toc-entry-44" role="doc-backlink">Metadata Document Title</a></h3> 3119 <dl class="field-list simple" style="--field-indent: 13em;"> 3120 <dt>Directive Type<span class="colon">:</span></dt> 3121 <dd><p>"title"</p> 3122 </dd> 3123 <dt>Doctree Element<span class="colon">:</span></dt> 3124 <dd><p>sets the <a class="reference external" href="../doctree.html#document"><document></a> element's <a class="reference external" href="../doctree.html#title-attribute">title attribute</a>)</p> 3125 </dd> 3126 <dt>Directive Arguments<span class="colon">:</span></dt> 3127 <dd><p>one, required (the title text)</p> 3128 </dd> 3129 <dt>Directive Options<span class="colon">:</span></dt> 3130 <dd><p>none</p> 3131 </dd> 3132 <dt>Directive Content<span class="colon">:</span></dt> 3133 <dd><p>none</p> 3134 </dd> 3135 <dt>Configuration Setting<span class="colon">:</span></dt> 3136 <dd><p><a class="reference external" href="../../user/config.html#title">title</a></p> 3137 </dd> 3138 </dl> 3139 <p>The "title" directive specifies the document title as metadata, which 3140 does not become part of the document body. It overrides the 3141 document-supplied <a class="reference external" href="restructuredtext.html#document-title">document title</a> and the <a class="reference external" href="../../user/config.html#title">"title" configuration 3142 setting</a>.</p> 3143 </section> 3144 <section id="restructuredtext-test-directive"> 3145 <h3><a class="toc-backref" href="#toc-entry-45" role="doc-backlink">Restructuredtext-Test-Directive</a></h3> 3146 <dl class="field-list simple" style="--field-indent: 13em;"> 3147 <dt>Directive Type<span class="colon">:</span></dt> 3148 <dd><p>"restructuredtext-test-directive"</p> 3149 </dd> 3150 <dt>Doctree Element<span class="colon">:</span></dt> 3151 <dd><p><a class="reference external" href="../doctree.html#system-message"><system_message></a></p> 3152 </dd> 3153 <dt>Directive Arguments<span class="colon">:</span></dt> 3154 <dd><p>none</p> 3155 </dd> 3156 <dt>Directive Options<span class="colon">:</span></dt> 3157 <dd><p>none</p> 3158 </dd> 3159 <dt>Directive Content<span class="colon">:</span></dt> 3160 <dd><p>Interpreted as a literal block.</p> 3161 </dd> 3162 </dl> 3163 <p>This directive is provided for test purposes only. (Nobody is 3164 expected to type in a name <em>that</em> long!) It is converted into a 3165 level-1 (info) system message showing the directive data, possibly 3166 followed by a literal block containing the rest of the directive 3167 block.</p> 3168 </section> 3169 </section> 3170 <section id="common-options"> 3171 <h2><a class="toc-backref" href="#toc-entry-46" role="doc-backlink">Common Options</a></h2> 3172 <p>Most of the directives that generate doctree elements support the following 3173 options:</p> 3174 <dl id="class-option"> 3175 <dt><span class="docutils literal">class</span><span class="classifier"><a class="reference internal" href="#text">text</a> (space separated list of <a class="reference external" href="../doctree.html#class-names">class names</a>)</span></dt> 3176 <dd><p>Set a <a class="reference external" href="../doctree.html#classes">classes attribute</a> value on the doctree element generated by 3177 the directive. For example,</p> 3178 <pre class="literal-block">.. image:: bild.png 3179 :alt: example picture 3180 :class: large-pics</pre> 3181 <p>is the recommended syntax alternative to a preceding 3182 <a class="reference internal" href="#class-directive">class directive</a></p> 3183 <pre class="literal-block">.. class:: large-pics 3184 .. image:: bild.png 3185 :alt: example picture</pre> 3186 </dd> 3187 <dt id="name"><span class="docutils literal">name</span><span class="classifier"><a class="reference internal" href="#text">text</a></span></dt> 3188 <dd><p>Add <em>text</em> to the <a class="reference external" href="../doctree.html#names">names attribute</a> of the doctree element generated 3189 by the directive. This allows <a class="reference external" href="restructuredtext.html#hyperlink-references">hyperlink references</a> to the element 3190 using <cite>text</cite> as <a class="reference external" href="restructuredtext.html#reference-names">reference name</a>. For example,</p> 3191 <pre class="literal-block">.. image:: bild.png 3192 :alt: example picture 3193 :name: my picture</pre> 3194 <p>is the recommended syntax alternative to a preceding 3195 <a class="reference external" href="restructuredtext.html#hyperlink-targets">hyperlink target</a></p> 3196 <pre class="literal-block">.. _my picture: 3197 .. image:: bild.png 3198 :alt: example picture</pre> 3199 </dd> 3200 </dl> 3201 </section> 3202 <section id="common-option-value-types"> 3203 <h2><a class="toc-backref" href="#toc-entry-47" role="doc-backlink">Common Option Value Types</a></h2> 3204 <dl class="run-in narrow field-list"> 3205 <dt>"keyword"<span class="colon">:</span></dt> 3206 <dd><p>recognized keywords</p> 3207 <p>Used without quotes in the reStructuredText source.</p> 3208 </dd> 3209 <dt><span class="target" id="character">character</span><span class="colon">:</span></dt> 3210 <dd><p>single character</p> 3211 <p>May be specified as literal character or as Unicode <a class="reference internal" href="#character-code">character code</a> 3212 (cf. the <a class="reference internal" href="#unicode">unicode</a> directive).</p> 3213 </dd> 3214 <dt><span class="target" id="encoding">encoding</span><span class="colon">:</span></dt> 3215 <dd><p>text encoding name</p> 3216 <p>Docutils looks it up in the list of registered <a class="reference external" href="https://docs.python.org/3/library/codecs.html">codecs</a> 3217 (see also <a class="reference external" href="https://docs.python.org/3/library/codecs.html#standard-encodings">Standard Encodings</a>).</p> 3218 </dd> 3219 <dt><span class="target" id="flag">flag</span><span class="colon">:</span></dt> 3220 <dd><p>no value</p> 3221 </dd> 3222 <dt><span class="target" id="integer">integer</span><span class="colon">:</span></dt> 3223 <dd><p>integer number</p> 3224 <p>A <span class="target" id="list-of-integers">list of integers</span> may be comma- or whitespace-separated.</p> 3225 </dd> 3226 <dt><span class="target" id="length">length</span><span class="colon">:</span></dt> 3227 <dd><p>number, optionally followed by one of the 3228 <a class="reference external" href="restructuredtext.html#length-units">supported length units</a></p> 3229 <p>Handling of values without unit depends on the writer/output format. 3230 See the writer specific documentation in the <a class="reference external" href="../../index.html#introductory-tutorial-material-for-end-users">user doc</a> for details.</p> 3231 </dd> 3232 <dt><span class="target" id="path">path</span><span class="colon">:</span></dt> 3233 <dd><p>local filesystem path</p> 3234 <p>Newlines are removed. 3235 The <a class="reference external" href="../../user/config.html#root-prefix">root_prefix</a> configuration setting can be used to tell Docutils 3236 to interpret paths starting with "/" relative to a "project directory".</p> 3237 </dd> 3238 <dt><span class="target" id="percentage">percentage</span><span class="colon">:</span></dt> 3239 <dd><p>number followed by the percent sign '%'</p> 3240 <p>Percentage values are relative to other values, depending on the 3241 context in which they occur.</p> 3242 </dd> 3243 <dt><span class="target" id="text">text</span><span class="colon">:</span></dt> 3244 <dd><p>free text</p> 3245 <p>Possible restrictions are given in parentheses.</p> 3246 </dd> 3247 <dt><span class="target" id="uri">URI</span><span class="colon">:</span></dt> 3248 <dd><p><span class="target" id="uri-reference">URI reference</span></p> 3249 <p>Full URI or <a class="reference external" href="https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2">relative reference</a> 3250 (absolute or relative path reference, cf. <a class="reference external" href="https://tools.ietf.org/html/rfc3986.html">RFC 3986</a>). 3251 Whitespace is removed (cf. <a class="reference external" href="restructuredtext.html#external-hyperlink-targets">external hyperlink targets</a> in the 3252 reStructuredText specification).</p> 3253 </dd> 3254 </dl> 3255 <!-- References --> 3256 <!-- Docutils Configuration --> 3257 <!-- Emacs settings 3258 3259 Local Variables: 3260 mode: indented-text 3261 mode: rst 3262 indent-tabs-mode: nil 3263 sentence-end-double-space: t 3264 fill-column: 70 3265 End: --> 3266 </section> 3267 </main> 3268 </body> 3269 </html>