Skip to content

Version 2

Jump to bottom Edit New page
Christophe Demko edited this page Jan 10, 2018 · 3 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 HTML span tag 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 tag 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 tag 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 tag 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 tag 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

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 key:

---
pandoc-numbering:
  - category: ex
    sectioning: -.+.
---
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 and last key (first section level to appear, last section level to appear):

---
pandoc-numbering:
  - category: ex
    sectioning: -.+.
---

is equivalent to

---
pandoc-numbering:
  - category: ex
    first: 2
    last: 2
---

Referencing

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

  • [](#identifier "caption") the empty text is replaced by the complete numbered paragraph;
  • [text](#identifier "caption")
    • the %T characters are replaced by the title in the text;
    • the %t characters are replaced by the title in lower case in the text;
    • the %D characters are replaced by the description in the text;
    • the %d characters are replaced by the description in lower case in the text;
    • the %s characters are replaced by the section numbering in the text;
    • the %g characters are replaced by the global numbering in the text;
    • the %c characters are replaced by the current count in the text;
    • the %p characters are replaced by the page number in the text (work only for pdf format that use a LaTeX engine);
    • the %n and # characters are replaced by the local numbering in the text;
  • @identifier is a shortcut for [#](#identifier) if cite-shortcut: true is in the meta-data block (see example below)

In all cases, the %T, %t, %D, %d, %s, %g, %c, %p, %n and # characters are replaced by the same information 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 entry in the metadata:

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

Exercise (The second exercise) #

will be rendered as:

List of exercises {.unnumbered}
=================

-   [1 The first exercise](#exercise:1)
-   [2 The second 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}

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:
  - category: exercise
    listing: List of exercises
    tab: 2
    space: 3
---
Exercise (The first exercise) #

Exercise (The second exercise) #

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
  • the entry in the table of contents is Category or Title

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

  • text is for the text displayed (you can use special characters %D, %d, %s, %g, %n, #)
  • text-titleis for the text displayed when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #)
  • linkis for the link displayed (you can use special characters %D, %d, %s, %g, %n, #)
  • link-titleis for the link displayed when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #)
  • toc is for the entry displayed in the table of contents (you can use special characters %D, %d)
  • toc-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)

By default these values are equal to

  • text: '**%D %n**'
  • text-title: '**%D %n** *(%T)*'
  • link: '%D %n'
  • link-title: '%D %n'
  • toc: '%D'
  • toc-title: '%T'

Unformatting

It's possible to not format the output of the filter using format key in the metadata. In that case, you will have to write additional filter for the final formatting

---
pandoc-numbering:
  - category: exercise
    listing: List of exercises
    format: false
    sectioning: +.
---
Section
=======

Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {.unnumbered}
=================

-   [[[Exercise]{.description}[The first
    exercise]{.title}[1.1]{.local}[1.1]{.global}[1]{.section}]{.pandoc-numbering-toc
    .exercise}](#exercise:1.1)
-   [[[Exercise]{.description}[The second
    exercise]{.title}[1.2]{.local}[1.2]{.global}[1]{.section}]{.pandoc-numbering-toc
    .exercise}](#exercise:1.2)

Section
=======

[[Exercise]{.description}[The first
exercise]{.title}[1.1]{.local}[1.1]{.global}[1]{.section}]{#exercise:1.1
.pandoc-numbering-text .exercise}

[[Exercise]{.description}[The second
exercise]{.title}[1.2]{.local}[1.2]{.global}[1]{.section}]{#exercise:1.2
.pandoc-numbering-text .exercise}

Classes

The classes add to the span tags can be changed using the classes keyword in the meta.

---
pandoc-numbering:
  - category: exercise
    listing: List of exercises
    format: false
    classes: [my-class1, my-class2]
    sectioning: +.
---
Section
=======

Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {.unnumbered}
=================

-   [[[Exercise]{.description}[The first
    exercise]{.title}[1.1]{.local}[1.1]{.global}[1]{.section}]{.pandoc-numbering-toc
    .my-class1 .my-class2}](#exercise:1.1)
-   [[[Exercise]{.description}[The second
    exercise]{.title}[1.2]{.local}[1.2]{.global}[1]{.section}]{.pandoc-numbering-toc
    .my-class1 .my-class2}](#exercise:1.2)

Section
=======

[[Exercise]{.description}[The first
exercise]{.title}[1.1]{.local}[1.1]{.global}[1]{.section}]{#exercise:1.1
.pandoc-numbering-text .my-class1 .my-class2}

[[Exercise]{.description}[The second
exercise]{.title}[1.2]{.local}[1.2]{.global}[1]{.section}]{#exercise:1.2
.pandoc-numbering-text .my-class1 .my-class2}

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