← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/python-docutils/jaunty

« back to all changes in this revision

Viewing changes to docs/ref/rst/directives.txt

  • Committer: Bazaar Package Importer
  • Author(s): Simon McVittie
  • Date: 2008-07-24 10:39:53 UTC
  • mfrom: (1.1.4 upstream) (3.1.7 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080724103953-8gh4uezg17g9ysgy
Tags: 0.5-2
http://bugs.debian.org/474941
* Upload docutils 0.5 to unstable
* Update rst.el to upstream Subversion r5596, which apparently fixes
  all its performance problems (17_speed_up_rst_el.dpatch, closes: #474941)

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/rst/directives.txt
3
3
=============================
4
4
:Author: David Goodger
5
5
:Contact: goodger@python.org
6
 
:Revision: $Revision: 4228 $
7
 
:Date: $Date: 2005-12-23 00:46:04 +0100 (Fri, 23 Dec 2005) $
 
6
:Revision: $Revision: 5015 $
 
7
:Date: $Date: 2007-03-12 21:25:40 +0100 (Mon, 12 Mär 2007) $
8
8
:Copyright: This document has been placed in the public domain.
9
9
 
10
10
.. contents::
126
126
This is a generic, titled admonition.  The title may be anything the
127
127
author desires.
128
128
 
129
 
The author-supplied title is also used as a "class" attribute value
 
129
The author-supplied title is also used as a "classes" attribute value
130
130
after being converted into a valid identifier form (down-cased;
131
131
non-alphanumeric characters converted to single hyphens; "admonition-"
132
132
prefixed).  For example, this admonition::
138
138
becomes the following document tree (pseudo-XML)::
139
139
 
140
140
    <document source="test data">
141
 
        <admonition class="admonition-and-by-the-way">
 
141
        <admonition classes="admonition-and-by-the-way">
142
142
            <title>
143
143
                And, by the way...
144
144
            <paragraph>
147
147
The following option is recognized:
148
148
 
149
149
``class`` : text
150
 
    Override the computed "class" attribute value.  See the class_
 
150
    Override the computed "classes" attribute value.  See the class_
151
151
    directive below.
152
152
 
153
153
 
243
243
    reference name with underscore suffix (e.g. ``name_``).
244
244
 
245
245
``class`` : text
246
 
    Set a "class" attribute value on the image element.  See the
 
246
    Set a "classes" attribute value on the image element.  See the
247
247
    class_ directive below.
248
248
 
249
249
 
317
317
        +---------------------------+
318
318
 
319
319
``figclass`` : text
320
 
    Set a "class" attribute value on the figure element.  See the
 
320
    Set a "classes" attribute value on the figure element.  See the
321
321
    class_ directive below.
322
322
 
323
323
``align`` : "left", "center", or "right"
362
362
The following option is recognized:
363
363
 
364
364
``class`` : text
365
 
    Set a "class" attribute value on the topic element.  See the
 
365
    Set a "classes" attribute value on the topic element.  See the
366
366
    class_ directive below.
367
367
 
368
368
 
403
403
    The sidebar's subtitle.
404
404
 
405
405
``class`` : text
406
 
    Set a "class" attribute value on the sidebar element.  See the
 
406
    Set a "classes" attribute value on the sidebar element.  See the
407
407
    class_ directive below.
408
408
 
409
409
 
447
447
The following option is recognized:
448
448
 
449
449
``class`` : text
450
 
    Set a "class" attribute value on the line_block element.  See the
 
450
    Set a "classes" attribute value on the line_block element.  See the
451
451
    class_ directive below.
452
452
 
453
453
 
488
488
The following option is recognized:
489
489
 
490
490
``class`` : text
491
 
    Set a "class" attribute value on the literal_block element.  See
 
491
    Set a "classes" attribute value on the literal_block element.  See
492
492
    the class_ directive below.
493
493
 
494
494
 
516
516
The following option is recognized:
517
517
 
518
518
``class`` : text
519
 
    Set a "class" attribute value on the rubric element.  See the
 
519
    Set a "classes" attribute value on the rubric element.  See the
520
520
    class_ directive below.
521
521
 
522
522
 
544
544
 
545
545
becomes this document tree fragment::
546
546
 
547
 
    <block_quote class="epigraph">
 
547
    <block_quote classes="epigraph">
548
548
        <paragraph>
549
549
            No matter where you go, there you are.
550
550
        <attribution>
638
638
The following option is recognized:
639
639
 
640
640
``class`` : text
641
 
    Set a "class" attribute value on the compound element.  See the
 
641
    Set a "classes" attribute value on the compound element.  See the
642
642
    class_ directive below.
643
643
 
644
644
 
655
655
 
656
656
The "container" directive surrounds its contents (arbitrary body
657
657
elements) with a generic block-level "container" element.  Combined
658
 
with the optional "class_" attribute argument(s), this is an extension
659
 
mechanism for users & applications.  For example::
 
658
with the optional "classes_" attribute argument(s), this is an
 
659
extension mechanism for users & applications.  For example::
660
660
 
661
661
    .. container:: custom
662
662
 
710
710
The following option is recognized:
711
711
 
712
712
``class`` : text
713
 
    Set a "class" attribute value on the table element.  See the
 
713
    Set a "classes" attribute value on the table element.  See the
714
714
    class_ directive below.
715
715
 
716
716
 
775
775
The following options are recognized:
776
776
 
777
777
``class`` : text
778
 
    Set a "class" attribute value on the table element.  See the
 
778
    Set a "classes" attribute value on the table element.  See the
779
779
    class_ directive below.
780
780
 
781
781
``widths`` : integer [, integer...]
873
873
The following options are recognized:
874
874
 
875
875
``class`` : text
876
 
    Set a "class" attribute value on the table element.  See the
 
876
    Set a "classes" attribute value on the table element.  See the
877
877
    class_ directive below.
878
878
 
879
879
``widths`` : integer [integer...]
951
951
    entries, the table of contents itself, or generate no backlinks.
952
952
 
953
953
``class`` : text
954
 
    Set a "class" attribute value on the topic element.  See the
 
954
    Set a "classes" attribute value on the topic element.  See the
955
955
    class_ directive below.
956
956
 
957
957
 
1077
1077
The following option is recognized:
1078
1078
 
1079
1079
``class`` : text
1080
 
    Set a "class" attribute value on all footnote_reference elements.
 
1080
    Set a "classes" attribute value on all footnote_reference elements.
1081
1081
    See the class_ directive below.
1082
1082
 
1083
1083
 
1371
1371
 
1372
1372
The following options are recognized:
1373
1373
 
 
1374
``start-after`` : text to find in the external data file
 
1375
    Only the content after the first occurrence of the specified text
 
1376
    will be included.
 
1377
 
 
1378
``end-before`` : text to find in the external data file
 
1379
    Only the content before the first occurrence of the specified text
 
1380
    (but after any ``after`` text) will be included.
 
1381
 
1374
1382
``literal`` : flag (empty)
1375
1383
    The entire included text is inserted into the document as a single
1376
1384
    literal block (useful for program listings).
1455
1463
    Defaults to the document's encoding (if specified).
1456
1464
 
1457
1465
 
 
1466
.. _classes:
 
1467
 
1458
1468
Class
1459
1469
=====
1460
1470
 
1466
1476
:Directive Content: Optional.  If present, it is interpreted as body
1467
1477
                    elements.
1468
1478
 
1469
 
The "class" directive sets the "class" attribute value on its content
 
1479
The "class" directive sets the "classes" attribute value on its content
1470
1480
or on the first immediately following non-comment element [#]_.  For
1471
 
details of the "class" attribute, see `its entry`__ in `The Docutils
 
1481
details of the "classes" attribute, see `its entry`__ in `The Docutils
1472
1482
Document Tree`_.  The directive argument consists of one or more
1473
1483
space-separated class names, which are converted to lowercase and all
1474
1484
non-alphanumeric characters are converted to hyphens.  (For the
1475
1485
rationale, see below.)
1476
1486
 
1477
 
__ ../doctree.html#class
 
1487
__ ../doctree.html#classes
1478
1488
 
1479
1489
Examples::
1480
1490
 
1497
1507
 
1498
1508
The text above is parsed and transformed into this doctree fragment::
1499
1509
 
1500
 
    <paragraph class="special">
 
1510
    <paragraph classes="special">
1501
1511
        This is a "special" paragraph.
1502
 
    <section class="exceptional remarkable">
 
1512
    <section classes="exceptional remarkable">
1503
1513
        <title>
1504
1514
            An Exceptional Section
1505
1515
        <paragraph>
1506
1516
            This is an ordinary paragraph.
1507
 
        <paragraph class="multiple">
 
1517
        <paragraph classes="multiple">
1508
1518
            First paragraph.
1509
 
        <paragraph class="multiple">
 
1519
        <paragraph classes="multiple">
1510
1520
            Second paragraph.
1511
1521
 
1512
 
.. [#] To set a "class" attribute value on a block quote, the "class"
1513
 
   directive must be followed by an empty comment::
 
1522
.. [#] To set a "classes" attribute value on a block quote, the
 
1523
   "class" directive must be followed by an empty comment::
1514
1524
 
1515
1525
       .. class:: highlights
1516
1526
       ..
1517
1527
 
1518
1528
           Block quote text.
1519
1529
 
1520
 
   The directive doesn't allow content, therefore an empty comment is
1521
 
   required to terminate the directive.  Without the empty comment,
1522
 
   the block quote text would be interpreted as the "class"
1523
 
   directive's content, and the parser would complain.
 
1530
   An empty comment is required to terminate the directive to allow
 
1531
   the indented text to be parsed as a block quote.  Without the empty
 
1532
   comment, the indented text would be interpreted as the "class"
 
1533
   directive's content, and the classes would be applied to each
 
1534
   element (paragraphi, in this case) individually, instead of to the
 
1535
   block quote as a whole.
1524
1536
 
1525
 
.. topic:: Rationale for Class Attribute Value Conversion
 
1537
.. topic:: Rationale for "classes" Attribute Value Conversion
1526
1538
 
1527
1539
    Docutils identifiers are converted to conform to the regular
1528
1540
    expression ``[a-z](-?[a-z0-9]+)*``.  For CSS compatibility,
1529
 
    identifiers (the "class" and "id" attributes) should have no
 
1541
    identifiers (the "classes" and "id" attributes) should have no
1530
1542
    underscores, colons, or periods.  Hyphens may be used.
1531
1543
 
1532
1544
    - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
1539
1551
    - However the `CSS1 spec`_ defines identifiers based on the "name"
1540
1552
      token, a tighter interpretation ("flex" tokenizer notation
1541
1553
      below; "latin1" and "escape" 8-bit characters have been replaced
1542
 
      with entities)::
 
1554
      with XML entities)::
1543
1555
 
1544
1556
          unicode     \\[0-9a-f]{1,4}
1545
1557
          latin1      [&iexcl;-&yuml;]
1548
1560
          name        {nmchar}+
1549
1561
 
1550
1562
    The CSS1 "nmchar" rule does not include underscores ("_"), colons
1551
 
    (":"), or periods ("."), therefore "class" and "id" attributes
 
1563
    (":"), or periods ("."), therefore "classes" and "id" attributes
1552
1564
    should not contain these characters.  They should be replaced with
1553
1565
    hyphens ("-").  Combined with HTML's requirements (the first
1554
1566
    character must be a letter; no "unicode", "latin1", or "escape"
1586
1598
 
1587
1599
    <paragraph>
1588
1600
        An example of using
1589
 
        <inline class="custom">
 
1601
        <inline classes="custom">
1590
1602
            interpreted text
1591
1603
 
1592
1604
The role must be declared in a document before it can be used.
1601
1613
The parsed result is as follows::
1602
1614
 
1603
1615
    <paragraph>
1604
 
        <emphasis class="custom">
 
1616
        <emphasis classes="custom">
1605
1617
            text
1606
1618
 
1607
1619
If no base role is explicitly specified, a generic custom role is
1608
1620
automatically used.  Subsequent interpreted text will produce an
1609
 
"inline" element with a "class" attribute, as in the first example
 
1621
"inline" element with a "classes" attribute, as in the first example
1610
1622
above.
1611
1623
 
1612
 
With most roles, the ":class:" option can be used to set a "class"
 
1624
With most roles, the ":class:" option can be used to set a "classes"
1613
1625
attribute that is different from the role name.  For example::
1614
1626
 
1615
1627
    .. role:: custom
1620
1632
This is the parsed result::
1621
1633
 
1622
1634
    <paragraph>
1623
 
        <inline class="special">
 
1635
        <inline classes="special">
1624
1636
            interpreted text
1625
1637
 
1626
1638
.. _role class:
1629
1641
base roles:
1630
1642
 
1631
1643
``class`` : text
1632
 
    Set a "class" attribute value on the element produced (``inline``,
1633
 
    or element associated with a base class) when the custom
1634
 
    interpreted text role is used.  If no directive options are
 
1644
    Set the "classes" attribute value on the element produced
 
1645
    (``inline``, or element associated with a base class) when the
 
1646
    custom interpreted text role is used.  If no directive options are
1635
1647
    specified, a "class" option with the directive argument (role
1636
1648
    name) as the value is implied.  See the class_ directive above.
1637
1649