Giter Club home page Giter Club logo

pandoc-secnos's Introduction

New in 2.2.2: Updated for pandoc 2.10.1. Fixed section number offset problem for html output (Issue #2).

more...

pandoc-secnos 2.2.2

pandoc-secnos is a pandoc filter for numbering section references when converting markdown to other formats. It is part of the pandoc-xnos filter suite. LaTeX/pdf, html, and epub output have native support. Native support for docx output is a work in progress.

Demonstration: Processing demo3.md with pandoc + pandoc-secos gives numbered section references in pdf, tex, html, epub, docx and other formats.

This version of pandoc-secnos was tested using pandoc 1.15.2 - 2.10.1,1 and may be used with linux, macOS, and Windows. Bug reports and feature requests may be posted on the project's Issues tracker. If you find pandoc-secnos useful, then please kindly give it a star on GitHub.

See also: pandoc-fignos, pandoc-eqnos, pandoc-tablenos
Other filters: pandoc-comments, pandoc-latex-extensions

Contents

  1. Installation
  2. Usage
  3. Markdown Syntax
  4. Customization
  5. Technical Details
  6. Getting Help
  7. Development
  8. What's New

Installation

Pandoc-secnos requires python. It is easily installed -- see here.2 Either python 2.7 or 3.x will do.

Pandoc-secnos may be installed using the shell command

pip install pandoc-secnos --user

and upgrade by appending --upgrade to the above command. Pip is a program that downloads and installs software from the Python Package Index, PyPI. It normally comes installed with a python distribution.3

Instructions for installing from source are given in DEVELOPERS.md.

Usage

Pandoc-secnos is activated by using the

--filter pandoc-secnos

option with pandoc. Alternatively, use

--filter pandoc-xnos

to activate all of the filters in the pandoc-xnos suite (if installed).

Any use of --filter pandoc-citeproc or --bibliography=FILE should come after the pandoc-secnos or pandoc-xnos filter calls.

Markdown Syntax

The cross-referencing syntax used by pandoc-secnos was developed in pandoc Issue #813 -- see this post by @scaramouche1.

For LaTeX/pdf, html, and epub output, sections are numbered using pandoc's --number-sections option.

To reference a section, use

@sec:id

or

{@sec:id}

The prefix @sec: is required. id should be replaced with a unique identifier for the section, composed of letters, numbers, dashes and underscores. Curly braces protect a reference and are stripped from the output.

Pandoc automatically assigns an identifier to each section title in a document. For example, the identifier for

Section One
===========

is section-one; a reference to it would be @sec:section-one. An identifier may be explicitly assigned to the section title using attributes as follows:

Section Two {#sec:2}
===========

A reference to this would be @sec:2.

Demonstration: Processing demo.md with pandoc + pandoc-secnos gives numbered section references in pdf, tex, html, epub, docx and other formats.

Clever References

Writing markdown like

See sec. @sec:id.

seems a bit redundant. Pandoc-secnos supports "clever references" via single-character modifiers in front of a reference. Users may write

 See +@sec:id.

to have the reference name (i.e., "section") automatically generated. The above form is used mid-sentence; at the beginning of a sentence, use

 *@sec:id

instead. If clever references are enabled by default (see Customization, below), then users may disable it for a given reference using4

!@sec:id

Demonstration: Processing demo2.md with pandoc + pandoc-secnos gives numbered section references in pdf, tex, html, epub, docx and other formats.

Note: When using *@sec:id and emphasis (e.g., *italics*) in the same sentence, the * in the clever reference must be backslash-escaped; i.e., \*@sec:id.

Disabling Links

To disable a link on a reference, set nolink=True in the reference's attributes:

@sec:id{nolink=True}

Customization

Pandoc-secnos may be customized by setting variables in the metadata block or on the command line (using -M KEY=VAL). The following variables are supported:

  • secnos-warning-level or xnos-warning-level - Set to 0 for no warnings, 1 for critical warnings, or 2 (default) for all warnings. Warning level 2 should be used when troubleshooting.

  • secnos-cleveref or xnos-cleveref - Set to True to assume "+" clever references by default;

  • xnos-capitalise - Capitalises the names of "+" clever references (e.g., change from "section" to "Section");

  • secnos-plus-name - Sets the name of a "+" clever reference (e.g., change it from "section" to "sec."). Settings here take precedence over xnos-capitalise;

  • secnos-star-name - Sets the name of a "*" clever reference (e.g., change it from "Section" to "Sec.");

  • xnos-number-offset - Set to an integer to offset the section numbers in references. For html and epub output, this feature should be used together with pandoc's --number-offset option set to the same integer value. For LaTeX/PDF, this option offsets the actual section numbers as required.

Note that variables beginning with secnos- apply to only pandoc-secnos, whereas variables beginning with xnos- apply to all all of the pandoc-fignos/eqnos/tablenos/secnos filters.

Demonstration: Processing demo3.md with pandoc + pandoc-secnos gives numbered section references in pdf, tex, html, epub, docx and other formats.

Technical Details

LaTeX/pdf Output

During processing, pandoc-secnos inserts packages and supporting LaTeX into the header-includes metadata field. To see what is inserted, set the secnos-warning-level meta variable to 2. Note that any use of pandoc's --include-in-header option overrides all header-includes.

An example reference in LaTeX looks like

See \cref{sec:1}.

Other details:

  • The cleveref and caption packages are used for clever references and caption control, respectively;
  • The \label and \ref macros are used for section labels and references, respectively (\Cref and \cref are used for clever references);
  • Clever reference names are set with \Crefname and \crefname;

Html/Epub Output

An example reference in html looks like

See section <a href="#sec:1">1</a>.

Docx Output

Docx OOXML output is under development and subject to change. Native capabilities will be used wherever possible.

Getting Help

If you have any difficulties with pandoc-secnos, or would like to see a new feature, then please submit a report to our Issues tracker.

Development

Pandoc-secnos will continue to support pandoc 1.15-onward and python 2 & 3 for the foreseeable future. The reasons for this are that a) some users cannot upgrade pandoc and/or python; and b) supporting all versions tends to make pandoc-secnos more robust.

Developer notes are maintained in DEVELOPERS.md.

What's New

New in 2.2.2: Updated for pandoc 2.10.1. Fixed section number offset problem for html output (Issue #2).

New in 2.1.1: Warnings are now given for duplicate reference targets.

New in 2.0.0: Pandoc-secnos is a new filter. It has been marked with version number 2.0.0 in keeping with the major version number of the underlying pandoc-xnos library.

Footnotes

1: Pandoc 2.4 broke how references are parsed, and so is not supported.

2: For MacOS, my preferred install method is to use the package available from python.org.

3: Anaconda users may be tempted to use conda instead. This is not advised. The packages distributed on the Anaconda cloud are unofficial, are not posted by me, and in some cases are ancient. Some tips on using pip in a conda environment may be found here.

4: The disabling modifier "!" is used instead of "-" because pandoc drops minus signs in front of references.

pandoc-secnos's People

Contributors

jschlatow avatar tomduck avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar

Forkers

jschlatow lazybricklayerman ppenguin elnull kmjaimes

pandoc-secnos's Issues

cleveref must be loaded after hyperref!

With pandoc 2.19.2 within pandoc/latex image (476a9c7ce3ec) plus pip3 install pandoc-secnos in a Dockerfile, I am using this minimal example test.md:

# Introduction

Test +@sec:introduction) asdf.

When running pandoc --filter "pandoc-secnos" --output="paper.pdf" test.md I get this error:

Error producing PDF.
! Package cleveref Error: cleveref must be loaded after hyperref!.

What can I do to fix this?

I also reported this here because I don't know what is causing it.

Broken for PDF

Problem

When running the commands below using demo.md, the pdf output using cleverref shows ?? on the place of the references (indicating a missing label?) and the output without cleverref just doesn't show anything at all, effectively printing section . (with a single space, as copy-pasted from the generated pdf). The markdown output for both with and without cleverref is just fine (pasted below).

Commands

$ pandoc demo.md --filter pandoc-xnos -M xnos-warning-level=2 --to pdf > stupid.pdf 
$ pandoc demo.md --filter pandoc-xnos -M xnos-warning-level=2 -M xnos-cleveref=true --to pdf > clever.pdf

pandoc-secnos: Wrote the following blocks to header-includes.  If you
use pandoc's --include-in-header option then you will need to manually
include these yourself.

    %% pandoc-secnos: required package
    \usepackage{cleveref}

$ pandoc demo.md --filter pandoc-xnos -M xnos-warning-level=2 --to markdown | less
$ pandoc demo.md --filter pandoc-xnos -M xnos-warning-level=2 -M xnos-cleveref=true --to markdown | less

Versions

$ python3 --version
Python 3.6.9
$ pip3 list | grep pandoc
pandoc-eqnos          2.1.1
pandoc-fignos         2.2.0
pandoc-secnos         2.1.1
pandoc-tablenos       2.1.1
pandoc-xnos           2.3.0
pandocfilters         1.4.2
$ pandoc --version
pandoc 2.9.2
Compiled with pandoc-types 1.20, texmath 0.12.0.1, skylighting 0.8.3.2
Default user data directory: /home/<username>/.local/share/pandoc or /home/<username>/.pandoc
Copyright (C) 2006-2019 John MacFarlane
Web:  https://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

Stupid Markdown Output

Section One
===========

Reference to section [2](#sec:2).

Section Two {#sec:2}
===========

Reference to section [1](#section-one). Section [2.1](#subsection) comes
next.

Subsection
----------

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est laborum.

Clever Markdown Output

Section One
===========

Reference to section section [2](#sec:2).

Section Two {#sec:2}
===========

Reference to section section [1](#section-one). Section section
[2.1](#subsection) comes next.

Subsection
----------

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est laborum.

Check for exe breaks pip install

This check in setup.py for presence of the pandoc-secnos executable breaks local installs with pip.

pandoc-secnos/setup.py

Lines 67 to 74 in 1cf95f8

# Check that the pandoc-secnos script is on the PATH
if not shutil.which('pandoc-secnos'):
msg = """
ERROR: `pandoc-secnos` script not found. This will need to
be corrected. If you need help, please file an Issue at
https://github.com/tomduck/pandoc-secnos/issues.\n"""
print(textwrap.dedent(msg))
sys.exit(-1)

In other words, running pip install . (or pip install -e .) from repository root will error out with:

    ERROR: `pandoc-secnos` script not found. This will need to
    be corrected.  If you need help, please file an Issue at
    https://github.com/tomduck/pandoc-secnos/issues.

    ----------------------------------------
ERROR: Command errored out with exit status 4294967295: python setup.py egg_info Check the logs for full command output.

It's true that one can do python setup.py develop for a local editable install, but using pip is pretty standard and ought to be supported. Is there a particularly good reason that this check should live in setup.py and not in the primary module?

Cannot get pandoc-secnos to work, all other pandoc-xnos filters work as described.

Hi,
I'm using Ulysses as my markdown editor, and using Pandoc to generate a PDF via LaTeX. I'm using the pandoc-xnos filter and have the following in my pandoc YAML

  xnos-cleveref: true
  xnos-capitalise: true

I'm also using --number-sections in my pandoc command.

If I output a .tex file using exactly the same settings, the chapters and sections have a hypertarget and label seemingly generated by pandoc, e.g., if my section title is 'Selecting some data', then then LaTeX file shows:

\hypertarget{selecting-some-data}{%
\section{Selecting some data}\label{selecting-some-data}}

None of @sec:selecting-some-data, +@sec:selecting-some-data or @selecting-some-data work

If I add {#sec:select-data} after the section, the .tex file shows:

\hypertarget{sec:select-data}{%
\section{Selecting some data}\label{sec:select-data}}

but putting +@sec:hydro-data or @sec:hydro-data in the markdown text gives +(\textbf{sec:hydro-data?}) in the .tex file, rather than a \cref{} entry.

Any suggestions? It's frustrating as all the other filters work great.

Thanks

xnos-number-offset not working in html output

Here is a markdown file check.md:

---
xnos-number-offset: 10
---

# This is a test {#sec:first}

This is the first section, and we should see an offset reference to +@sec:first.

Here is the pandoc command:

$ pandoc --version
pandoc 2.9.2.1
Compiled with pandoc-types 1.20, texmath 0.12.0.1, skylighting 0.8.3.2
$ pandoc -N --number-offset=10 --filter pandoc-secnos -t html -o check.html check.md

and here is the resulting html file -- note the reference link:

<section id="sec:first" data-number="1">
<h1 data-number="11"><span class="header-section-number">11</span> This is a test</h1>
<p>This is the first section, and we should see an offset reference to section <a href="#sec:first">1</a>.</p>
</section>

The offset works as advertised in the latex file:

(header omitted)
%% pandoc-secnos: required package
\usepackage{cleveref}

% pandoc-secnos: section number offset
\setcounter{section}{10}

\author{}
\date{}

\begin{document}

\hypertarget{sec:first}{%
\section{This is a test}\label{sec:first}}

This is the first section, and we should see an offset reference to
\cref{sec:first}.

\end{document}

Section numbers with trailing zeros

When a section has a preceding sibling with lower level sections, the section's number is displayed with too many levels and a trailing 0. This may lead to a section numbered 2.0, although it really should be 2.

Here's an almost-minimal example. Source:

# First Section {#sec:sectionI}

## A subsection

# Second Section {#sec:sectionII}

# Third Section

This is all explained in Sections @sec:sectionI and @sec:sectionII.

Result:

[...]
This is all explained in Sections 1 and 2.0.

Maybe this can be resolved by always removing trailing zeros?

pandoc-secnos: 2.1.1

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.