Skip to content

Home

Jump to bottom Edit New page
Christophe Demko edited this page Aug 21, 2018 · 69 revisions

Numbering

Each paragraph or the first line of a description list ended by a numbering-marker will be numbered. The description preceding the numbering-marker can be used as a category name by converting it to an auto-identifier. There can be an optional title enclosed in parentheses between the description and the numbering-marker.

Thus the syntax for automatic-numbering is:

where:

  • description-category is a significant text (i.e. Exercise)
  • title is a optional title text enclosed in parentheses (i.e. (This is the first exercise))
  • numbering-marker is a special string mainly containing a # character (preceded by an optional sectioning part and followed by an optional prefix part and an optional name part). If there is a prefix part, the category is set to that prefix part.

When a new (category, sectioning) couple is parsed, a new counter is set to 1. This counter is used to number this paragraph and all the paragraphs which use the same couple.

Thus:

Exercise #

Exercise #
:   Text for the exercise

will be rendered as

**Exercise 1**

**Exercise 2**
:   Text for the exercise

The optional title will be rendered at the end of the paragraph. Thus:

Exercise (This is the first exercise) #

Exercise (This is the second exercise) #

will be rendered as

**Exercise 1** *(This is the first exercise)*

**Exercise 2** *(This is the second exercise)*

The syntax for a numbering-marker is:

The optional sectioning part is composed of a hidden-sectioning part and of a visible-sectioning part.

The hidden-sectioning part is composed of an optional sequence of -. characters

The visible-sectioning part is composed of an optional sequence of +. characters.

The sectioning part is used to

  • reset the count number for a given category when the headers change.
  • number the paragraphs.

Thus, if you use the visible-sectioning part:

First section
=============

Exercise +.#

Exercise +.#

Second section
==============

Exercise +.#

Exercise +.#

will be rendered as

First section
=============

**Exercise 1.1**

**Exercise 1.2**

Second section
==============

**Exercise 2.1**

**Exercise 2.2**

If you use the hidden-sectioning part, the header numbers are not shown. Thus:

First section
=============

Exercise -.#

Exercise -.#

Second section
==============

Exercise -.#

Exercise -.#

will be rendered as

First section
=============

**Exercise 1**

**Exercise 2**

Second section
==============

**Exercise 1**

**Exercise 2**

Note that the second section has reset the exercises' numbering that use the -. sectioning part.

If you use the hidden-sectioning part and the visible-sectioning part:

First section
=============

First sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second section
==============

First sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

will be rendered as:

First section
=============

First sub-section
-----------------

**Exercise 1.1**

**Exercise 1.2**

Second sub-section
------------------

**Exercise 2.1**

**Exercise 2.2**

Second section
==============

First sub-section
-----------------

**Exercise 1.1**

**Exercise 1.2**

Second sub-section
------------------

**Exercise 2.1**

**Exercise 2.2**

For the examples given above, the real rendering is more complex. The paragraphs are enclosed in a span element whose identifier is constructed using the category, the sectioning, the prefix and the name. This can be used to cross-refer these numbered paragraphs.

The last example is really rendered as:

First section
=============

First sub-section
-----------------

[**Exercise 1.1**]{#exercise:1.1.1 .pandoc-numbering-text .exercise}

[**Exercise 1.2**]{#exercise:1.1.2 .pandoc-numbering-text .exercise}

Second sub-section
------------------

[**Exercise 2.1**]{#exercise:1.2.1 .pandoc-numbering-text .exercise}

[**Exercise 2.2**]{#exercise:1.2.2 .pandoc-numbering-text .exercise}

Second section
==============

First sub-section
-----------------

[**Exercise 1.1**]{#exercise:2.1.1 .pandoc-numbering-text .exercise}

[**Exercise 1.2**]{#exercise:2.1.2 .pandoc-numbering-text .exercise}

Second sub-section
------------------

[**Exercise 2.1**]{#exercise:2.2.1 .pandoc-numbering-text .exercise}

[**Exercise 2.2**]{#exercise:2.2.2 .pandoc-numbering-text .exercise}

The prefix and name parts are composed of a letter followed by any number of letter, digit, . and - characters.

  • If the optional prefix and name parts are present, the identifier of the span element is set using the prefix and name parts.

    Section
=======

Subsection
----------

Exercise -.+.#myprefix:myid

    will be rendered as

    Section
=======

Subsection
----------

[**Exercise 1.1**]{#myprefix:myid .pandoc-numbering-text .myprefix}

  • If the optional prefix part is present without the name part, the identifier of the span element is set using the prefix part followed by the full numbering of the paragraph.

    Section
=======

Subsection
----------

Exercise -.+.#myprefix:

    will be rendered as

    Section
=======

Subsection
----------

[**Exercise 1.1**]{#myprefix:1.1.1 .pandoc-numbering-text .myprefix}

  • If the optional name part is present without the prefix part, the identifier of the span element is constructed using the auto-identifier of the category followed by a : character and by the name part

    Section
=======

Subsection
----------

Exercise -.+.#myid

    will be rendered as

    Section
=======

Subsection
----------

[**Exercise 1.1**]{#exercise:myid .pandoc-numbering-text .exercise}

  • If there is no name and prefix parts, the identifier of the span element is constructed using the conversion of the description into an auto-identifier (category) followed by a : character and by the full numbering of the paragraph (see preceding example). For the auto-identifier conversion:

    • all accents are removed
    • characters which are not a letter, a digit or a - character are replaced by a - character
    • all beginning characters which are not a letter are removed
    • all letters are converted to lowercase

Referencing

The information generated by the numbering step can be used anywhere in the text for cross-referencing:

[text](#identifier "caption")

  • the %T characters are replaced by the title in the text and in the caption;
  • the %t characters are replaced by the title in lower case in the text and in the caption;
  • the %D characters are replaced by the description in the text and in the caption;
  • the %d characters are replaced by the description in lower case in the text and in the caption;
  • the %s characters are replaced by the section numbering in the text and in the caption;
  • the %g characters are replaced by the global numbering in the text and in the caption;
  • the %c characters are replaced by the current count in the text and in the caption;
  • the %p characters are replaced by the page number in the text and in the caption (work only for pdf format that use a LaTeX engine);
  • the %n and # characters are replaced by the local numbering in the text and in the caption;

List of things

If you want a listing of a particular category at the top of your document, you can add a listing-title entry in the metadata:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
---
Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {#list-of-exercises .pandoc-numbering-listing .exercise .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:2)

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .exercise}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .exercise}

By default, an identifier is added to the listing title. It's possible to change the identifier using a listing-identifier entry in the metadata:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      listing-identifier: myident
---
Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {#myident .pandoc-numbering-listing .exercise .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:2)

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .exercise}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .exercise}

It's also possible not to have an identifier using the False value:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      listing-identifier: False
---
Exercise (The first exercise) #

Exercise (The second exercise) #

For controlling the format used in the pdf output, you can precise two things:

  • the tab before each entry (expressed in em LaTeX size)
  • the space used by the numbering part (expressed in em LaTeX size)
---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
    latex:
      entry-space: 3
      entry-tab: 2
---
Exercise (The first exercise) #

Exercise (The second exercise) #

Default sectioning

If the sectioning part is empty, it is possible to use a default sectioning part defined in the meta-data block using the sectioning-levels key:

---
pandoc-numbering: 
  ex:
    general:
      sectioning-levels: -.+.
---
Section
=======

Subsection
----------

Exercise #ex:

will be rendered as

Section
=======

Subsection
----------

[**Exercise 1.1**]{#ex:1.1.1 .pandoc-numbering-text .ex}

You can also use the first-section-level and last-section-level key (first section level to appear, last section level to appear):

---
pandoc-numbering: 
  ex:
    general:
      sectioning-levels: -.+.
---

is equivalent to

---
pandoc-numbering:
  ex:
    general:
      first-section-level: 2
      last-section-level: 2
---

Use of cite shortcut notation

You can also use the @identifier notation. It creates a link with default text and default caption. If cite-shortcut: False is in the meta-data block for a given category, this feature is disabled.

Formatting

Basically:

  • the text displayed for a new numbering is **Category number** *(Title)* or **Category number**;
  • the link displayed for an automatic reference is Category number using the cite shortcut notation;
  • the entry in the table of contents is Category number (Category for LaTeX document) or Title.

These behaviors can be changed by adding metadata for a given category.

  • format-text-classic is for the text displayed (you can use special characters %D, %d, %s, %g, %n, #, %c)
  • format-text-title is for the text displayed when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #, %c)
  • format-link-classicis for the link displayed using the cite shortcut notation (you can use special characters %D, %d, %s, %g, %n, #, %c, %p)
  • format-link-titleis for the link displayed when a title is present using the cite shortcut notation (you can use special characters %D, %d, %T, %t, %s, %g, %n, #, %c, %p)
  • format-entry-classic is for the entry displayed in the table of contents (you can use special characters %D, %d, %s, %g, %n, #)
  • format-entry-title is for the entry displayed in the table of contents when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #)

By default these values are equal to

---
pandoc-numbering:
  exercise:
    standard:
      format-text-classic: '**%D %n**'
      format-text-title: '**%D %n** *(%T)*'
      format-link-classic: '%D %n'
      format-link-title: '%D %n (%T)'
      format-caption-classic: '%D %n'
      format-caption-title': '%D %n (%T)'
    latex:
      format-text-classic: '**%D %n**'
      format-text-title: '**%D %n** *(%T)*'
      format-link-classic: '%D %n'
      format-link-title: '%D %n (%T)'
      format-caption-classic: '%D %n'
      format-caption-title: '%D %n (%T)'
---

Classes

The classes added to the elements can be changed using the classes keyword in the meta.

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      classes: [my-class1, my-class2]
---
Section
=======

Exercise (The first exercise) #

Exercise (The second exercise) #

See @exercise:1

will be rendered as:

List of exercises {.pandoc-numbering-listing .my-class1 .my-class2 .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry .my-class1
    .my-class2}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry .my-class1
    .my-class2}](#exercise:2)

Section
=======

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .my-class1 .my-class2}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .my-class1 .my-class2}

See [[Exercise 1 (The first exercise)]{.pandoc-numbering-link .my-class1
.my-class2}](#exercise:1 "Exercise 1 (The first exercise)")

Example

Demonstration: Using pandoc-numbering-sample.txt as input gives output files in pdf, tex, html, epub and other formats.

Add a custom footer
Add a custom sidebar
Clone this wiki locally