Skip to content

Home

Jump to bottom Edit New page
Christophe Demko edited this page Jun 2, 2016 · 69 revisions

Numbering

Each paragraph ended by a numbering-marker will be numbered. The text preceding the numbering-marker can be used as a category name. There can be an optional description enclosed in parentheses between the category and the numbering-marker.

Thus the syntax for automatic-numbering is:

where:

  • category is a significant text (i.e. Exercise)
  • description is a optional description 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 #

will be rendered as

**Exercise 1**

**Exercise 2**

The optional description 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
-----------------

<span id="exercise:1.1.1" class="pandoc-numbering-text exercise">**Exercise
1.1**</span>

<span id="exercise:1.1.2" class="pandoc-numbering-text exercise">**Exercise
1.2**</span>

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

<span id="exercise:1.2.1" class="pandoc-numbering-text exercise">**Exercise
2.1**</span>

<span id="exercise:1.2.2" class="pandoc-numbering-text exercise">**Exercise
2.2**</span>

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

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

<span id="exercise:2.1.1" class="pandoc-numbering-text exercise">**Exercise
1.1**</span>

<span id="exercise:2.1.2" class="pandoc-numbering-text exercise">**Exercise
1.2**</span>

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

<span id="exercise:2.2.1" class="pandoc-numbering-text exercise">**Exercise
2.1**</span>

<span id="exercise:2.2.2" class="pandoc-numbering-text exercise">**Exercise
2.2**</span>

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

<span id="myprefix:myid" class="pandoc-numbering-text myprefix">**Exercise
1.1**</span>

  • 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
----------

<span id="myprefix:1.1.1" class="pandoc-numbering-text myprefix">**Exercise
1.1**</span>

  • 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
----------

<span id="exercise:myid" class="pandoc-numbering-text exercise">**Exercise
1.1**</span>

  • If there is no name and prefix parts, the identifier of the span tag is constructed using the conversion of the category into an auto-identifier 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
----------

<span id="ex:1.1.1" class="pandoc-numbering-text ex">**Exercise
1.1**</span>

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 "title") the empty text is replaced by the complete numbered paragraph;
  • [text](#identifier "title")
    • 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 #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, #n and # characters are replaced by the same information in the title.

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)

<span id="exercise:1" class="pandoc-numbering-text exercise">**Exercise
1** *(The first exercise)*</span>

<span id="exercise:2" class="pandoc-numbering-text exercise">**Exercise
2** *(The second exercise)*</span>

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) #

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}
=================

-   [<span class="pandoc-numbering-toc exercise"><span
    class="description">Exercise</span><span class="title">The first
    exercise</span><span class="local">1.1</span><span
    class="global">1.1</span><span
    class="section">1</span></span>](#exercise:1.1)
-   [<span class="pandoc-numbering-toc exercise"><span
    class="description">Exercise</span><span class="title">The second
    exercise</span><span class="local">1.2</span><span
    class="global">1.2</span><span
    class="section">1</span></span>](#exercise:1.2)

Section
=======

<span id="exercise:1.1" class="pandoc-numbering-text exercise"><span
class="description">Exercise</span><span class="title">The first
exercise</span><span class="local">1.1</span><span
class="global">1.1</span><span class="section">1</span></span>

<span id="exercise:1.2" class="pandoc-numbering-text exercise"><span
class="description">Exercise</span><span class="title">The second
exercise</span><span class="local">1.2</span><span
class="global">1.2</span><span class="section">1</span></span>

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) #

wille be rendered as:

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

-   [<span class="pandoc-numbering-toc my-class1 my-class2"><span
    class="description">Exercise</span><span class="title">The first
    exercise</span><span class="local">1.1</span><span
    class="global">1.1</span><span
    class="section">1</span></span>](#exercise:1.1)
-   [<span class="pandoc-numbering-toc my-class1 my-class2"><span
    class="description">Exercise</span><span class="title">The second
    exercise</span><span class="local">1.2</span><span
    class="global">1.2</span><span
    class="section">1</span></span>](#exercise:1.2)

Section
=======

<span id="exercise:1.1"
class="pandoc-numbering-text my-class1 my-class2"><span
class="description">Exercise</span><span class="title">The first
exercise</span><span class="local">1.1</span><span
class="global">1.1</span><span class="section">1</span></span>

<span id="exercise:1.2"
class="pandoc-numbering-text my-class1 my-class2"><span
class="description">Exercise</span><span class="title">The second
exercise</span><span class="local">1.2</span><span
class="global">1.2</span><span class="section">1</span></span>

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