pandoc-numbering documentation

pandoc-numbering DocumentationRelease 3.4.0.0

Christophe Demko

Feb 24, 2021

CONTENTS:

1 Numbering 1

2 Referencing 9

3 List of things 11

4 Default sectioning 13

5 Use of cite shortcut notation 15

6 Formatting 17

7 Classes 19

8 Example 21

i

CHAPTER

ONE

NUMBERING

Each paragraph or the first line of a description list ended by a numbering-marker will be numbered. The descriptionpreceding the numbering-marker can be used as a category name by converting it to an auto-identifier. There can bean 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 partand followed by an optional prefix part and an optional name part). If there is a prefix part, the category is setto that prefix part.

When a new (category, sectioning) couple is parsed, a new counter is set to 1. This counter is used to number thisparagraph 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

1

pandoc-numbering Documentation, Release 3.4.0.0

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

(continues on next page)

2 Chapter 1. Numbering


(continued from previous page)

Exercise +.#

Exercise +.#

will be rendered as


**Exercise 1.1**

**Exercise 1.2**


**Exercise 2.1**

**Exercise 2.2**

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


Exercise -.#

Exercise -.#


Exercise -.#

Exercise -.#

will be rendered as


**Exercise 1**

**Exercise 2**


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

3



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

Exercise -.+.#

Exercise -.+.#

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

Exercise -.+.#

Exercise -.+.#



Exercise -.+.#

Exercise -.+.#

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

Exercise -.+.#

Exercise -.+.#

will be rendered as:



**Exercise 1.1**

**Exercise 1.2**

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

**Exercise 2.1**

**Exercise 2.2**


First sub-section(continues on next page)




-----------------

**Exercise 1.1**

**Exercise 1.2**


**Exercise 2.1**

**Exercise 2.2**

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

The last example is really rendered as:



[**Exercise 1.1**]{#exercise:1.1.1 .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 andname parts.

5


Section=======

Subsection----------

Exercise -.+.#myprefix:myid

will be rendered as

Section=======


[**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 theprefix part followed by the full numbering of the paragraph.

Section=======


Exercise -.+.#myprefix:

will be rendered as

Section=======


[**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 constructedusing the auto-identifier of the category followed by a : character and by the name part

Section=======


Exercise -.+.#myid

will be rendered as

Section=======






[**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 ofthe description into an auto-identifier (category) followed by a : character and by the full numbering of theparagraph (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

7

CHAPTER

TWO

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 thatuse a LaTeX engine);

• the %n and # characters are replaced by the local numbering in the text and in the caption;

9


10 Chapter 2. Referencing

CHAPTER

THREE

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 inthe metadata:

---pandoc-numbering:

exercise:general:

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

Exercise (The second exercise) #


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 alisting-identifier entry in the metadata:


exercise:general:

listing-title: List of exerciseslisting-identifier: myident

---Exercise (The first exercise) #


11



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:


exercise:general:

listing-title: List of exerciseslisting-identifier: False

---Exercise (The first exercise) #


12 Chapter 3. List of things

CHAPTER

FOUR

DEFAULT SECTIONING

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


ex:general:

sectioning-levels: -.+.---Section=======


Exercise #ex:

will be rendered as

Section=======


[**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, lastsection level to appear):


ex:general:

sectioning-levels: -.+.---

is equivalent to


ex:general:

first-section-level: 2(continues on next page)

13



last-section-level: 2---

14 Chapter 4. Default sectioning

CHAPTER

FIVE

USE OF CITE SHORTCUT NOTATION

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

15


16 Chapter 5. Use of cite shortcut notation

CHAPTER

SIX

FORMATTING

Basically:

• the text displayed for a new numbering is **Category number** *(Title)* or **Categorynumber**;

• 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 char-acters %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 canuse special characters %D, %d, %T, %t, %s, %g, %n, #, %c, %p)

• format-caption-classic is for the text displayed in the captions (you can use special characters %D, %d,%s, %g, %n, # and %p for LaTeX)

• format-caption-title is for the text displayed in the captions when a title is present (you can use specialcharacters %D, %d, %T, %t, %s, %g, %n, # and %p for LaTeX)

• 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 usespecial characters %D, %d, %T, %t, %s, %g, %n, #)

By default these values are equal to


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)'format-entry-title': '%T'


17



format-entry-classic': '%D %g'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)'format-entry-title': '%T'format-entry-classic': '%D'

---

18 Chapter 6. Formatting

CHAPTER

SEVEN

CLASSES

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


exercise:general:

listing-title: List of exercisesclasses: [my-class1, my-class2]

---Section=======

Exercise (The first exercise) #


See @exercise:1


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

19


20 Chapter 7. Classes

CHAPTER

EIGHT

EXAMPLE

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

21

https://raw.githubusercontent.com/chdemko/pandoc-numbering/master/docs/images/pandoc-numbering-sample.txt

https://raw.githubusercontent.com/chdemko/pandoc-numbering/master/docs/images/pandoc-numbering-sample.pdf

https://raw.githubusercontent.com/chdemko/pandoc-numbering/master/docs/images/pandoc-numbering-sample.tex

https://raw.githubusercontent.com/chdemko/pandoc-numbering/master/docs/images/pandoc-numbering-sample.html

https://raw.githubusercontent.com/chdemko/pandoc-numbering/master/docs/images/pandoc-numbering-sample.epub

pandoc-numbering documentation

Documents