bpj/pandoc-quote-styles.pl

## pandoc-quote-styles.pl
#!/usr/bin/env perl

# version 0.4

use utf8;
use autodie 2.29;
use 5.010001;
use strict;
use warnings;
use warnings qw(FATAL utf8);

sub _msg {
    my $msg = shift;
    $msg = sprintf $msg, @_ if @_;
    $msg =~ s/\n\z//;
    return $msg;
}

sub _error { die _msg( @_ ), "\n"; }

use Pandoc::Elements 0.33;
use Pandoc::Walker 0.27 qw[ action transform ];
use Path::Tiny 0.104 qw[ path cwd ];
use Try::Tiny 0.28;
use HTML::HTML5::Entities 0.004 qw[ decode_entities ];

# which quotes should numeric style keys default to?
my %default = qw(
  6   ‘
  9   ’
  66  “
  99  ”
  1   ’
  11  ”
);

# which numeric style keys should dumb quotes default to?
my %num4quote = qw( 11 " 1 ' );

my $configfile = 'pandoc-quote-styles.yaml';

unless ( @ARGV ) {
    my $prog = path( $0 )->basename;
    say "$prog would look for $configfile in:";
    my @paths = cwd->child($configfile);
    if ( try { require File::HomeDir; 1; } ) {
        my $path = try {path( File::HomeDir->my_documents )->realpath->child($configfile)};
        push @paths, $path if $path;
    }
    push @paths, path( '~' )->realpath->child($configfile);
    my %seen;
    for my $path ( @paths ) {
        next if $seen{$path}++;
        say qq[    $path];
    }
    exit 0;
}

our $quote_style;

my $out_format = shift @ARGV;
my $json       = <>;
my $doc        = pandoc_json( $json );
my $meta       = $doc->meta;

my $use_style = $meta->value( 'quote_style' ) // $ENV{PANDOC_QUOTE_STYLE} // do {
    print $json;
    exit 0;
};

my $subst = $meta->value( 'quote_styles_string_subst' )
  // $ENV{PANDOC_QUOTE_STYLES_STRING_SUBST} // 0;

my $quote_styles = $meta->value( 'quote_styles' ) // $ENV{PANDOC_QUOTE_STYLES};

my $map_in_meta = 'HASH' eq uc ref $quote_styles;

my $styles_name = 'metadata quote_styles';

unless ( 'HASH' eq uc ref $quote_styles ) {
    my $file;
    try { require YAML::Any }
    catch {
        _error "The YAML::Any module couldn't be loaded\n$_";
    };
    unless ( defined $quote_styles ) {
        my @dirs = cwd;
        if ( try { require File::HomeDir; 1; } ) {
            push @dirs, path File::HomeDir->my_documents;
        }
        push @dirs, path '~';
        my @files = map { ; $_->child( $configfile ) } @dirs;
        ( $file ) = grep { $_->is_file } @files;
        defined $file or do {
            local $" = q{ and };
            _error "Couldn't find any pandoc-quote-styles.yaml (tried @files)";
        };
        $styles_name = $file;
    }
    else {
        $file = path $styles_name = $quote_styles;
    }
    $file->is_file or _error "Not a file: $file";
    $quote_styles = try {
        YAML::Any->implementation->can( 'LoadFile' )->( "$file" )
    }
    catch { _error "Error loading $file:\n$_" };
}

if ( 'HASH' eq uc ref $quote_styles ) {
    my $temp = $quote_styles;
    for my $style ( values %$temp ) {
        next if 'HASH' eq uc ref $style;
        $quote_styles = undef;
        last;
    }
    if ( defined $quote_styles ) {
        for my $style ( values %$quote_styles ) {
            $style = +{ map => $style };
        }
    }
}

'HASH' eq uc ref $quote_styles
  or _error "Expected $styles_name to be mapping of mappings";

$quote_style = get_style($use_style);

my %style_seen;

sub get_style {
    no warnings qw[ uninitialized numeric ];
    my ( $name ) = @_;
    my $style = $quote_styles->{$name} // _error "No such quote style: $name";
    $style_seen{$name}++ and return $style;
    for my $map ( $style->{map} ) {    # get alias
        while ( my ( $n, $q ) = each %default ) {
            $map->{$n} //= $q;
        }
        unless ( $map_in_meta ) {
            %$map = map { ; decode_entities( $_ ) } %$map;
        }
        else {
          KEY:
            for my $k ( keys %$map ) {
                # decode key, because pandoc doesn't
                my $dk = decode_entities( $k );
                next KEY if $dk eq $k;
                $map->{$dk} = delete $map->{$k};
            }
        }
        if ( $subst and not defined $style->{regex} ) {
            while ( my ( $n, $q ) = each %num4quote ) {
                $map->{$q} //= $map->{$n} // $default{$n};
            }
            for my $re ( $style->{regex} ) {    # get alias
                $re = join '|',
                  map  { quotemeta $_ }
                  sort { length( $b ) <=> length( $a ) }
                  grep { length( $_ ) and $_ =~ /[^0-9]/ } keys %{$map};
                $re = qr/($re)/ if length $re;
            }
        }
    }
    return $style;
}

my %type2nums = ( SingleQuote => [qw( 6 9 )], DoubleQuote => [qw( 66 99 )], );

my %actions = (
    Str => sub {
        no warnings qw[ uninitialized numeric ];
        return unless $quote_style->{regex};
        my ( $elem ) = @_;
        ( my $str = $elem->content )
          =~ s/$quote_style->{regex}/$quote_style->{map}{$1}/g
          or return;
        return unless defined $1;    # unless the regex captured anything;
        return Str $str;
    },
    'Div|Span' => sub {
        my ( $elem, $action ) = @_;
        my $name = $elem->keyvals->{quotes};
        # localize $quote_style if needed before transforming content
        # this causes the chosen local style to be applied to content
        local $quote_style = get_style( $name ) if defined $name;
        transform $elem->content, $action, $action;
        return $elem;
    },
    Quoted => sub {
        no warnings qw[ uninitialized numeric ];
        my ( $elem, $action ) = @_;
        my $content = transform $elem->content, $action, $action;
        my $type = $type2nums{ $elem->type->name };
        my ( $open, $close )
          = map { ; Str $_ } grep { defined $_ } @{ $quote_style->{map} }{@$type};
        return $elem unless defined $open and defined $close;
        return [ grep { defined $_ } $open, @$content, $close ];
    },
);

delete $actions{Str} unless $subst;

my $action = action \%actions;

# Allow applying the action recursively
$doc->transform($action, $action);

print $doc->to_json;


__END__

pandoc-quote-styles.pl
2017-11-12

=encoding UTF-8

=head1 NAME

pandoc-quote-styles.pl - Use custom smart quotes in Pandoc

=head1 VERSION

0.003

=head1 SYNOPSIS

    pandoc -F pandoc-quote-styles.pl [OPTIONS] [FILENAME]

=head1 DESCRIPTION

Out of the box L<< Pandoc|http://pandoc.org/ >> (as of version 2.0.2) only provides
English-style L<< smart quotes|http://www.pensee.com/dunham/smartQuotes.html >>, but different languages use different
quote styles — some languages even allow several alternative quote
styles or have changed their preferred quote style over time –, and
hence requests for configurable smart quotes are rather frequent.

This program is a Pandoc filter aiming at filling this niche. It allows you
to define one or more alternate smart quotes styles either in the metadata
of a Markdown document, or in a per-project or per-user configuration file
in YAML format. You choose the quote style to use by setting a metadata
value or an environment variable, and you can even use different quote
styles in different parts of a document by setting a custom attribute on
span and div elements. Optionally you can also substitute another string
for any substrings of printable characters in the text of your document (of
course excluding code and code blocks!) so that you for example can wrap
certain punctuation marks in narrow no-break spaces as required by French
orthography, or implement custom smart punctuation by substituting special
punctuation characters for sequences of more easily typed punctuation
characters.

=head1 USAGE

When you use this filter you I<< must >> enable Pandoc’s C<< +smart >> extension
(before Pandoc 2 you use the C<< --smart >> option instead), since the filter
relies on Pandoc’s marking of quoted passages as such in its AST.

To activate the filter you set the metadata field C<< quote_style >> to a
Perl true value — anything other than null, an empty string or a digit
zero —, which should be the name of the quote style you want to use in
your document. If this metadata field is missing or has a false value
the filter will check the environment variable C<< PANDOC_QUOTE_STYLE >>. If
that is also unset or a (Perl) false value the filter will simply print
out the JSON AST it received from Pandoc and exit without an error.

Once the C<< quote_style >> metadata field is set to a true value the filter
expects that one of the following is true:

=over

=item 1.

The metadata field C<< quote_styles >> (note the -s!) is a mapping, or

=item 2.

The metadata field C<< quote_styles >> is a relative or absolute file
pathE<0x2f>name, or

=item 3.

The environment variable C<< PANDOC_QUOTE_STYLES >> (again note the -S!)
is a relative or absolute file pathE<0x2f>name, or

=item 4.

A file C<< pandoc-quote-styles.yaml >> exists in one of the following
places:

=over

=item *

The current directory,

=item *

The current user’s documents folder, if any

=over

=item *

the so-called C<< My Documents >> on Windows,

=item *

C<< E<0x2f>homeE<0x2f>«username»E<0x2f>Documents >> on many Linux systems,

=item *

C<< E<0x2f>UsersE<0x2f>«username»E<0x2f>Documents >> on Mac, or their localized
equivalent.

=back

This lookup is skipped if the L<< File::HomeDir|File::HomeDir >> module is not
installed, or if there is no separate documents folder.

=item *

The current user’s home directory or its equivalent.

=back

To learn which directories the filter would look in you can run the
filter script directly I<< without any arguments >> and it will print out
a message showing the paths to the directories it would look in. On
my current system:

    $ perl pandoc-quote-styles.pl
    pandoc-quote-styles.pl would look for pandoc-quote-styles.yaml in:
        /home/benct/Dropbox/new-pdc/quote-styles/pandoc-quote-styles.yaml
        /home/benct/Dokument/pandoc-quote-styles.yaml
        /home/benct/pandoc-quote-styles.yaml

=back

In the case of (2) or (3) the file must exist and be a YAML file, and
the L<< YAML::Any|YAML::Any >> module and a suitable backend module must be installed
and able to load the file. The file must contain a mapping of mappings
as described below.

=head1 THE QUOTE STYLES DEFINITIONS

The quote styles definitions, whether included in the metadata or loaded
from a file, should be a mapping of mappings something like this:

    english:
      66: '&ldquo;'  # HTML entities work!
      99: '&rdquo;'
      6:  '&lsquo;'
      9:  '&rsquo;'
      1:  '&rsquo;'
      11: '&rdquo;'
    english-reversed:
      66: ‘
      99: ’
      6:  “
      9:  ”
      1:  ’
      11: ’
    german:
      66: „
      99: ”
      6:  ‚
      9:  ’
      1:  ’
      11: ”
    french:
      66: '«&#x202f;'
      99: '&#x202f;»'
      6:  '“&#x202f;'
      9:  '&#x202f;”'
      1:  '’'
      11: '»&#x202f;'
      ';': '&#x202f;;'
      ':': '&#x202f;:'
      '?': '&#x202f;?'
      '€': '€&#x202f;'
      '%': '&#x202f;%'

The rules are as follows:

=over

=item *

The quote styles definitions is a mapping of mappings.

=item *

The keys in the outer mapping are the names of the quote styles.
These can be any string which works as a key in YAML, but you may
want to stick to strings which consist of ASCII alphanumerics,
underscores and hyphens and start with a letter, so that you can use
them as unquoted attribute values when using the L<< DIV- AND
SPAN-LOCAL QUOTE STYLES|/"4DIV- AND SPAN-LOCAL QUOTE STYLES4" >> feature.

=item *

The values corresponding to the style names are mappings, each being
the definition of a quote style.

=item *

In each style definition mapping there are three kinds of keys:

=over

=item 1.

The keys C<< 66 >>, C<< 99 >>, C<< 6 >> and C<< 9 >> correspond to the values which
shall replace the opening and closing double and single quotes
respectively in the C<< Quoted >> elements which are included in
Pandoc’s AST if you run with the C<< +smart >> extension (before
Pandoc 2 you use the C<< --smart >> option instead). Think of how the
English typographic quotes resemble these digits! Each of these
defaults to the respective English typographic quote, so the key
for each quote which you want to replace must be defined!

=item 2.

Keys which contain any character other than the digits 0-9
represent substrings which you want to replace with some other
substring in Pandoc’s text elements — that is virtually
everywhere except in code and code blocks. The replacements are
the values of the respective keys. This feature exists mainly so
that certain punctuation characters can be padded with the
L<< narrow no-break space|https://en.wikipedia.org/w/index.php?title=Non-breaking_space&oldid=808337900#Width_variation >> characters required for them in French
orthography, but you could for example use them to replace the
sequences C<< -+ >> and C<< +-+ >> with dagger characters († and ‡).
However this feature slows Pandoc down, so you must set the
metadata field C<< quote_styles_string_subst >> to C<< true >>
or the evironment variable C<< PANDOC_QUOTE_STYLES_STRING_SUBST >>
to a Perl true value for this to work!

=item 3.

The keys C<< 1 >> and C<< 11 >> represent a kind of middle ground between
the two previous kinds.

If the metadata field C<< quote_styles_string_subst >> is set to C<< true >>
or the evironment variable C<< PANDOC_QUOTE_STYLES_STRING_SUBST >> to a
Perl true value the keys for the ‘dumb’ quotes C<< ' >> and C<< " >>
will be set to the values of these fields, or default to the typographic
apostrophe — identical to the typographic 9 quote — and the
typographic 99 quote, unless the actual C<< ' >> and C<< " >> mapping fields are
defined. This will do so that wherever you type C<< \' >> and C<< \" >>
in your Markdown you will get the values of these keys. This is
useful because when running in I<< smart >> mode Pandoc will assume all
C<< ' >> characters in positions where an opening single quote would
be normal in English to be opening single quotes, but with this
feature you can type C<< \' >> to force a typographic apostrophe. The
C<< 11 >> or C<< " >> key can be used to implement the feature found in
the orthographies of some languages — sometimes in English too
— where a closing punctuation mark is put at the I<< beginning >> of
each new paragraph in a quote. This is shown in the C<< french >> style
in the example above.

=back

=item *

Since you probably use this filter because you have trouble typing
the various quote and other special characters the filter does some
fudging so that you can use HTML entities anywhere in both keys and
values in the definitions. Note however that this is done before
everything else, so that you can’t for example use C<< &#x36; >> to force
substitution of the C<< 6 >> character!

=item *

You can’t use Markdown formatting in definition values in metadata,
since that will be stripped. On the other hand you should use the
HTML entity C<< &#x2a; >> to ensure a literal C<< * >> and so on for other
Markdown special characters.

=back

If you are unsure which typographic quotes to use for a particular
language L<< https:E<0x2f>E<0x2f>en.wikipedia.orgE<0x2f>wikiE<0x2f>Quotation_mark|https://en.wikipedia.org/wiki/Quotation_mark >> has a
L<< summary table|https://en.wikipedia.org/w/index.php?title=Quotation_mark&oldid=809551203#Summary_table >> with information for many languages, which is handy not
least because you can copy-paste the correct Unicode characters there!

=head1 DIV- AND SPAN-LOCAL QUOTE STYLES

You can use another quote style locally inside a specific Pandoc native
span or div element by specifying a C<< quotes=STYLE-NAME >> attribute on the
element. Note that this does I<< not >> work for link elements; wrap the link
in a span if you really need that!

=head1 PREREQUISITES

In addition to L<< Pandoc|http://pandoc.org/ >> itself this filter requires L<< perl|https://www.perl.org/about.html >> 5.10.1 or
greater and the following L<< CPAN|https://www.cpan.org/ >> modules (and their
prerequisites):

=over

=item *

File::HomeDir

=item *

HTML::HTML5::Entities 0.004

=item *

Pandoc::Elements 0.33

=item *

Pandoc::Walker 0.27

=item *

Path::Tiny 0.104

=item *

Try::Tiny 0.28

=item *

YAML::Any

=item *

autodie 2.29

=back

=head2 New to Perl?

=over

=item B<< TL;DR: >>

If you already have perl (on Windows: Strawberry Perl) installed run
these commands on the command line to install all CPAN dependencies
of this program:

    cpan App::cpanminus
    cpanm Perl::PrereqScanner
    scan-perl-prereqs pandoc-quote-styles.pl | cpanm

In the last line you may need to replace C<< pandoc-quote-styles.pl >>
with the path to the program, either relative to the directory
(folder) you are in, or an absolute path.

=back

This program requires L<< perl|https://www.perl.org/about.html >> (minimum version as given above) and the
Perl modules listed above to function. If you haven’t used Perl before
information on how to getE<0x2f>install perl andE<0x2f>or Perl modules can be found
at the URLS below, which lead to the official information on these
topics.

Don’t worry! If your operating system is Linux or Mac you probably
already have a new enough version of perl installed. If you don’t or if
your operating system is Windows it is easy to install a recent version,
and once you have perl installed installing modules is very easy. Just
follow the instructions linked to below.

=over

=item Getting perl

L<< https:E<0x2f>E<0x2f>www.perl.orgE<0x2f>get.html|https://www.perl.org/get.html >>

(For Windows I recommend Strawberry Perl as module installation is
easier there.)

=item Installing Perl modules

L<< http:E<0x2f>E<0x2f>www.cpan.orgE<0x2f>modulesE<0x2f>INSTALL.html|http://www.cpan.org/modules/INSTALL.html >>

=back

=head1 AUTHOR

Benct Philip Jonsson (bpjonsson@gmail.com, L<< https:E<0x2f>E<0x2f>github.comE<0x2f>bpj|https://github.com/bpj >>)

=head1 COPYRIGHT

Copyright 2017- Benct Philip Jonsson

=head1 LICENSE

This is free software; you can redistribute it andE<0x2f>or modify it under
the same terms as the Perl 5 programming language system itself. See
L<< http:E<0x2f>E<0x2f>dev.perl.orgE<0x2f>licensesE<0x2f>|http://dev.perl.org/licenses/ >>.

=cut


## pandoc-quote-styles.pod

      
    Raw
  

              pandoc-quote-styles.pod
            
          
NAME


VERSION


SYNOPSIS


DESCRIPTION


USAGE


THE QUOTE STYLES DEFINITIONS


DIV- AND SPAN-LOCAL QUOTE STYLES


PREREQUISITES


New to Perl?


AUTHOR


COPYRIGHT


LICENSE


NAME


pandoc-quote-styles.pl - Use custom smart quotes in Pandoc

VERSION


0.004

SYNOPSIS


pandoc -F pandoc-quote-styles.pl [OPTIONS] [FILENAME] 

DESCRIPTION


Out of the box Pandoc (as of version 2.0.1.1) only provides English-style smart quotes, but different languages use different quote styles â€” some languages even allow several alternative quote styles or have changed their preferred quote style over time â€“, and hence requests for configurable smart quotes are rather frequent.

This program is a Pandoc filter aiming at filling this niche. It allows you to define one or more alternate smart quotes styles either in the metadata of a Markdown document, or in a per-project or per-user configuration file in YAML format. You choose the quote style to use by setting a metadata value or an environment variable, and you can even use different quote styles in different parts of a document by setting a custom attribute on span and div elements. Optionally you can also substitute another string for any substrings of printable characters in the text of your document (of course excluding code and code blocks!) so that you for example can wrap certain punctuation marks in narrow no-break spaces as required by French orthography, or implement custom smart punctuation by substituting special punctuation characters for sequences of more easily typed punctuation characters.

USAGE


When you use this filter you must enable Pandocâ€™s +smart extension (before Pandoc 2 you use the --smart option instead), since the filter relies on Pandocâ€™s marking of quoted passages as such in its AST.

To activate the filter you set the metadata field quote_style to a Perl true value â€” anything other than null, an empty string or a digit zero â€”, which should be the name of the quote style you want to use in your document. If this metadata field is missing or has a false value the filter will check the environment variable PANDOC_QUOTE_STYLE. If that is also unset or a (Perl) false value the filter will simply print out the JSON AST it received from Pandoc and exit without an error.

Once the quote_style metadata field is set to a true value the filter expects that one of the following is true:


The metadata field quote_styles (note the -s!) is a mapping, or


The metadata field quote_styles is a relative or absolute file path/name, or


The environment variable PANDOC_QUOTE_STYLES (again note the -S!) is a relative or absolute file path/name, or


A file pandoc-quote-styles.yaml exists in one of the following places:


The current directory,


The current userâ€™s documents folder, if any


the so-called My Documents on Windows,


/home/«username»/Documents on many Linux systems,


/Users/«username»/Documents on Mac, or their localized equivalent.


This lookup is skipped if the File::HomeDir module is not installed, or if there is no separate documents folder.


The current userâ€™s home directory or its equivalent.


To learn which directories the filter would look in you can run the filter script directly without any arguments and it will print out a message showing the paths to the directories it would look in. On my current system:

$ perl pandoc-quote-styles.pl
pandoc-quote-styles.pl would look for pandoc-quote-styles.yaml in:
    /home/benct/Dropbox/new-pdc/quote-styles/pandoc-quote-styles.yaml
    /home/benct/Dokument/pandoc-quote-styles.yaml
    /home/benct/pandoc-quote-styles.yaml


In the case of (2) or (3) the file must exist and be a YAML file, and the YAML::Any module and a suitable backend module must be installed and able to load the file. The file must contain a mapping of mappings as described below.

THE QUOTE STYLES DEFINITIONS


The quote styles definitions, whether included in the metadata or loaded from a file, should be a mapping of mappings something like this:

english:
  66: '&ldquo;'  # HTML entities work!
  99: '&rdquo;'
  6:  '&lsquo;'
  9:  '&rsquo;'
  1:  '&rsquo;'
  11: '&rdquo;'
english-reversed:
  66: â€˜
  99: â€™
  6:  â€œ
  9:  â€�
  1:  â€™
  11: â€™
german:
  66: â€ž
  99: â€�
  6:  â€š
  9:  â€™
  1:  â€™
  11: â€�
french:
  66: 'Â«&#x202f;'
  99: '&#x202f;Â»'
  6:  'â€œ&#x202f;'
  9:  '&#x202f;â€�'
  1:  'â€™'
  11: 'Â»&#x202f;'
  ';': '&#x202f;;'
  ':': '&#x202f;:'
  '?': '&#x202f;?'
  'â‚¬': 'â‚¬&#x202f;'
  '%': '&#x202f;%'

The rules are as follows:


The quote styles definitions is a mapping of mappings.


The keys in the outer mapping are the names of the quote styles. These can be any string which works as a key in YAML, but you may want to stick to strings which consist of ASCII alphanumerics, underscores and hyphens and start with a letter, so that you can use them as unquoted attribute values when using the DIV- AND SPAN-LOCAL QUOTE STYLES feature.


The values corresponding to the style names are mappings, each being the definition of a quote style.


In each style definition mapping there are three kinds of keys:


The keys 66, 99, 6 and 9 correspond to the values which shall replace the opening and closing double and single quotes respectively in the Quoted elements which are included in Pandocâ€™s AST if you run with the +smart extension (before Pandoc 2 you use the --smart option instead). Think of how the English typographic quotes resemble these digits! Each of these defaults to the respective English typographic quote, so the key for each quote which you want to replace must be defined!


Keys which contain any character other than the digits 0-9 represent substrings which you want to replace with some other substring in Pandocâ€™s text elements â€” that is virtually everywhere except in code and code blocks. The replacements are the values of the respective keys. This feature exists mainly so that certain punctuation characters can be padded with the narrow no-break space characters required for them in French orthography, but you could for example use them to replace the sequences -+ and +-+ with dagger characters (â€  and â€¡). However this feature slows Pandoc down, so you must set the metadata field quote_styles_string_subst to true or the evironment variable PANDOC_QUOTE_STYLES_STRING_SUBST to a Perl true value for this to work!


The keys 1 and 11 represent a kind of middle ground between the two previous kinds.

If the metadata field quote_styles_string_subst is set to true or the evironment variable PANDOC_QUOTE_STYLES_STRING_SUBST to a Perl true value the keys for the â€˜dumbâ€™ quotes ' and " will be set to the values of these fields, or default to the typographic apostrophe â€” identical to the typographic 9 quote â€” and the typographic 99 quote, unless the actual ' and " mapping fields are defined. This will do so that wherever you type \' and \" in your Markdown you will get the values of these keys. This is useful because when running in smart mode Pandoc will assume all ' characters in positions where an opening single quote would be normal in English to be opening single quotes, but with this feature you can type \' to force a typographic apostrophe. The 11 or " key can be used to implement the feature found in the orthographies of some languages â€” sometimes in English too â€” where a closing punctuation mark is put at the beginning of each new paragraph in a quote. This is shown in the french style in the example above.


Since you probably use this filter because you have trouble typing the various quote and other special characters the filter does some fudging so that you can use HTML entities anywhere in both keys and values in the definitions. Note however that this is done before everything else, so that you canâ€™t for example use &#x36; to force substitution of the 6 character!


You canâ€™t use Markdown formatting in definition values in metadata, since that will be stripped. On the other hand you should use the HTML entity &#x2a; to ensure a literal * and so on for other Markdown special characters.


If you are unsure which typographic quotes to use for a particular language https://en.wikipedia.org/wiki/Quotation_mark has a summary table with information for many languages, which is handy not least because you can copy-paste the correct Unicode characters there!

DIV- AND SPAN-LOCAL QUOTE STYLES


You can use another quote style locally inside a specific Pandoc native span or div element by specifying a quotes=STYLE-NAME attribute on the element. Note that this does not work for link elements; wrap the link in a span if you really need that!

PREREQUISITES


In addition to Pandoc itself this filter requires perl 5.10.1 or greater and the following CPAN modules (and their prerequisites):


File::HomeDir


HTML::HTML5::Entities 0.004


Pandoc::Elements 0.33


Pandoc::Walker 0.27


Path::Tiny 0.104


Try::Tiny 0.28


YAML::Any


autodie 2.29


New to Perl?


TL;DR:


If you already have perl (on Windows: Strawberry Perl) installed run these commands on the command line to install all CPAN dependencies of this program:

cpan App::cpanminus
cpanm Perl::PrereqScanner
scan-perl-prereqs pandoc-quote-styles.pl | cpanm

In the last line you may need to replace pandoc-quote-styles.pl with the path to the program, either relative to the directory (folder) you are in, or an absolute path.


This program requires perl (minimum version as given above) and the Perl modules listed above to function. If you havenâ€™t used Perl before information on how to get/install perl and/or Perl modules can be found at the URLS below, which lead to the official information on these topics.

Donâ€™t worry! If your operating system is Linux or Mac you probably already have a new enough version of perl installed. If you donâ€™t or if your operating system is Windows it is easy to install a recent version, and once you have perl installed installing modules is very easy. Just follow the instructions linked to below.


Getting perl


https://www.perl.org/get.html

(For Windows I recommend Strawberry Perl as module installation is easier there.)


Installing Perl modules


http://www.cpan.org/modules/INSTALL.html


AUTHOR


Benct Philip Jonsson (bpjonsson@gmail.com, https://github.com/bpj)

COPYRIGHT


Copyright 2017- Benct Philip Jonsson

LICENSE


This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. See http://dev.perl.org/licenses/.


## pandoc-quote-styles.yaml
english:
  66: '&ldquo;'  # HTML entities work!
  99: '&rdquo;'
  6:  '&lsquo;'
  9:  '&rsquo;'
  1:  '&rsquo;'
  11: '&rdquo;'
english-reversed:
  66: ‘
  99: ’
  6:  “
  9:  ”
  1:  ’
  11: ’
german:
  66: „
  99: ”
  6:  ‚
  9:  ’
  1:  ’
  11: ”
french:
  66: '«&#x202f;'
  99: '&#x202f;»'
  6:  '“&#x202f;'
  9:  '&#x202f;”'
  1:  '’'
  11: '»&#x202f;'
  ';': '&#x202f;;'
  ':': '&#x202f;:'
  '?': '&#x202f;?'
  '€': '€&#x202f;'
  '%': '&#x202f;%'
swedish:
  66: ”
  99: ”
  6:  ’
  9:  ’
  1:  ’
  11: ”
swedish-alt:
  66: »
  99: »
  6:  ’
  9:  ’
  1:  ’
  11: ”
swedish-alt-2:
  66: »
  99: »
  6:  ”
  9:  ”
  1:  ’
  11: ”
swedish-old:
  66: »
  99: «
  6:  ”
  9:  ”
  1:  ’
  11: ”
	#!/usr/bin/env perl

	# version 0.4

	use utf8;
	use autodie 2.29;
	use 5.010001;
	use strict;
	use warnings;
	use warnings qw(FATAL utf8);

	sub _msg {
	my $msg = shift;
	$msg = sprintf $msg, @_ if @_;
	$msg =~ s/\n\z//;
	return $msg;
	}

	sub _error { die _msg( @_ ), "\n"; }

	use Pandoc::Elements 0.33;
	use Pandoc::Walker 0.27 qw[ action transform ];
	use Path::Tiny 0.104 qw[ path cwd ];
	use Try::Tiny 0.28;
	use HTML::HTML5::Entities 0.004 qw[ decode_entities ];

	# which quotes should numeric style keys default to?
	my %default = qw(
	6 ‘
	9 ’
	66 “
	99 ”
	1 ’
	11 ”
	);

	# which numeric style keys should dumb quotes default to?
	my %num4quote = qw( 11 " 1 ' );

	my $configfile = 'pandoc-quote-styles.yaml';

	unless ( @ARGV ) {
	my $prog = path( $0 )->basename;
	say "$prog would look for $configfile in:";
	my @paths = cwd->child($configfile);
	if ( try { require File::HomeDir; 1; } ) {
	my $path = try {path( File::HomeDir->my_documents )->realpath->child($configfile)};
	push @paths, $path if $path;
	}
	push @paths, path( '~' )->realpath->child($configfile);
	my %seen;
	for my $path ( @paths ) {
	next if $seen{$path}++;
	say qq[ $path];
	}
	exit 0;
	}

	our $quote_style;

	my $out_format = shift @ARGV;
	my $json = <>;
	my $doc = pandoc_json( $json );
	my $meta = $doc->meta;

	my $use_style = $meta->value( 'quote_style' ) // $ENV{PANDOC_QUOTE_STYLE} // do {
	print $json;
	exit 0;
	};

	my $subst = $meta->value( 'quote_styles_string_subst' )
	// $ENV{PANDOC_QUOTE_STYLES_STRING_SUBST} // 0;

	my $quote_styles = $meta->value( 'quote_styles' ) // $ENV{PANDOC_QUOTE_STYLES};

	my $map_in_meta = 'HASH' eq uc ref $quote_styles;

	my $styles_name = 'metadata quote_styles';

	unless ( 'HASH' eq uc ref $quote_styles ) {
	my $file;
	try { require YAML::Any }
	catch {
	_error "The YAML::Any module couldn't be loaded\n$_";
	};
	unless ( defined $quote_styles ) {
	my @dirs = cwd;
	if ( try { require File::HomeDir; 1; } ) {
	push @dirs, path File::HomeDir->my_documents;
	}
	push @dirs, path '~';
	my @files = map { ; $_->child( $configfile ) } @dirs;
	( $file ) = grep { $_->is_file } @files;
	defined $file or do {
	local $" = q{ and };
	_error "Couldn't find any pandoc-quote-styles.yaml (tried @files)";
	};
	$styles_name = $file;
	}
	else {
	$file = path $styles_name = $quote_styles;
	}
	$file->is_file or _error "Not a file: $file";
	$quote_styles = try {
	YAML::Any->implementation->can( 'LoadFile' )->( "$file" )
	}
	catch { _error "Error loading $file:\n$_" };
	}

	if ( 'HASH' eq uc ref $quote_styles ) {
	my $temp = $quote_styles;
	for my $style ( values %$temp ) {
	next if 'HASH' eq uc ref $style;
	$quote_styles = undef;
	last;
	}
	if ( defined $quote_styles ) {
	for my $style ( values %$quote_styles ) {
	$style = +{ map => $style };
	}
	}
	}

	'HASH' eq uc ref $quote_styles
	or _error "Expected $styles_name to be mapping of mappings";

	$quote_style = get_style($use_style);

	my %style_seen;

	sub get_style {
	no warnings qw[ uninitialized numeric ];
	my ( $name ) = @_;
	my $style = $quote_styles->{$name} // _error "No such quote style: $name";
	$style_seen{$name}++ and return $style;
	for my $map ( $style->{map} ) { # get alias
	while ( my ( $n, $q ) = each %default ) {
	$map->{$n} //= $q;
	}
	unless ( $map_in_meta ) {
	%$map = map { ; decode_entities( $_ ) } %$map;
	}
	else {
	KEY:
	for my $k ( keys %$map ) {
	# decode key, because pandoc doesn't
	my $dk = decode_entities( $k );
	next KEY if $dk eq $k;
	$map->{$dk} = delete $map->{$k};
	}
	}
	if ( $subst and not defined $style->{regex} ) {
	while ( my ( $n, $q ) = each %num4quote ) {
	$map->{$q} //= $map->{$n} // $default{$n};
	}
	for my $re ( $style->{regex} ) { # get alias
	$re = join '\|',
	map { quotemeta $_ }
	sort { length( $b ) <=> length( $a ) }
	grep { length( $_ ) and $_ =~ /[^0-9]/ } keys %{$map};
	$re = qr/($re)/ if length $re;
	}
	}
	}
	return $style;
	}

	my %type2nums = ( SingleQuote => [qw( 6 9 )], DoubleQuote => [qw( 66 99 )], );

	my %actions = (
	Str => sub {
	no warnings qw[ uninitialized numeric ];
	return unless $quote_style->{regex};
	my ( $elem ) = @_;
	( my $str = $elem->content )
	=~ s/$quote_style->{regex}/$quote_style->{map}{$1}/g
	or return;
	return unless defined $1; # unless the regex captured anything;
	return Str $str;
	},
	'Div\|Span' => sub {
	my ( $elem, $action ) = @_;
	my $name = $elem->keyvals->{quotes};
	# localize $quote_style if needed before transforming content
	# this causes the chosen local style to be applied to content
	local $quote_style = get_style( $name ) if defined $name;
	transform $elem->content, $action, $action;
	return $elem;
	},
	Quoted => sub {
	no warnings qw[ uninitialized numeric ];
	my ( $elem, $action ) = @_;
	my $content = transform $elem->content, $action, $action;
	my $type = $type2nums{ $elem->type->name };
	my ( $open, $close )
	= map { ; Str $_ } grep { defined $_ } @{ $quote_style->{map} }{@$type};
	return $elem unless defined $open and defined $close;
	return [ grep { defined $_ } $open, @$content, $close ];
	},
	);

	delete $actions{Str} unless $subst;

	my $action = action \%actions;

	# Allow applying the action recursively
	$doc->transform($action, $action);

	print $doc->to_json;


	__END__

	pandoc-quote-styles.pl
	2017-11-12

	=encoding UTF-8

	=head1 NAME

	pandoc-quote-styles.pl - Use custom smart quotes in Pandoc

	=head1 VERSION

	0.003

	=head1 SYNOPSIS

	pandoc -F pandoc-quote-styles.pl [OPTIONS] [FILENAME]

	=head1 DESCRIPTION

	Out of the box L<< Pandoc\|http://pandoc.org/ >> (as of version 2.0.2) only provides
	English-style L<< smart quotes\|http://www.pensee.com/dunham/smartQuotes.html >>, but different languages use different
	quote styles — some languages even allow several alternative quote
	styles or have changed their preferred quote style over time –, and
	hence requests for configurable smart quotes are rather frequent.

	This program is a Pandoc filter aiming at filling this niche. It allows you
	to define one or more alternate smart quotes styles either in the metadata
	of a Markdown document, or in a per-project or per-user configuration file
	in YAML format. You choose the quote style to use by setting a metadata
	value or an environment variable, and you can even use different quote
	styles in different parts of a document by setting a custom attribute on
	span and div elements. Optionally you can also substitute another string
	for any substrings of printable characters in the text of your document (of
	course excluding code and code blocks!) so that you for example can wrap
	certain punctuation marks in narrow no-break spaces as required by French
	orthography, or implement custom smart punctuation by substituting special
	punctuation characters for sequences of more easily typed punctuation
	characters.

	=head1 USAGE

	When you use this filter you I<< must >> enable Pandoc’s C<< +smart >> extension
	(before Pandoc 2 you use the C<< --smart >> option instead), since the filter
	relies on Pandoc’s marking of quoted passages as such in its AST.

	To activate the filter you set the metadata field C<< quote_style >> to a
	Perl true value — anything other than null, an empty string or a digit
	zero —, which should be the name of the quote style you want to use in
	your document. If this metadata field is missing or has a false value
	the filter will check the environment variable C<< PANDOC_QUOTE_STYLE >>. If
	that is also unset or a (Perl) false value the filter will simply print
	out the JSON AST it received from Pandoc and exit without an error.

	Once the C<< quote_style >> metadata field is set to a true value the filter
	expects that one of the following is true:

	=over

	=item 1.

	The metadata field C<< quote_styles >> (note the -s!) is a mapping, or

	=item 2.

	The metadata field C<< quote_styles >> is a relative or absolute file
	pathE<0x2f>name, or

	=item 3.

	The environment variable C<< PANDOC_QUOTE_STYLES >> (again note the -S!)
	is a relative or absolute file pathE<0x2f>name, or

	=item 4.

	A file C<< pandoc-quote-styles.yaml >> exists in one of the following
	places:

	=over

	=item *

	The current directory,

	=item *

	The current user’s documents folder, if any

	=over

	=item *

	the so-called C<< My Documents >> on Windows,

	=item *

	C<< E<0x2f>homeE<0x2f>«username»E<0x2f>Documents >> on many Linux systems,

	=item *

	C<< E<0x2f>UsersE<0x2f>«username»E<0x2f>Documents >> on Mac, or their localized
	equivalent.

	=back

	This lookup is skipped if the L<< File::HomeDir\|File::HomeDir >> module is not
	installed, or if there is no separate documents folder.

	=item *

	The current user’s home directory or its equivalent.

	=back

	To learn which directories the filter would look in you can run the
	filter script directly I<< without any arguments >> and it will print out
	a message showing the paths to the directories it would look in. On
	my current system:

	$ perl pandoc-quote-styles.pl
	pandoc-quote-styles.pl would look for pandoc-quote-styles.yaml in:
	/home/benct/Dropbox/new-pdc/quote-styles/pandoc-quote-styles.yaml
	/home/benct/Dokument/pandoc-quote-styles.yaml
	/home/benct/pandoc-quote-styles.yaml

	=back

	In the case of (2) or (3) the file must exist and be a YAML file, and
	the L<< YAML::Any\|YAML::Any >> module and a suitable backend module must be installed
	and able to load the file. The file must contain a mapping of mappings
	as described below.

	=head1 THE QUOTE STYLES DEFINITIONS

	The quote styles definitions, whether included in the metadata or loaded
	from a file, should be a mapping of mappings something like this:

	english:
	66: '“' # HTML entities work!
	99: '”'
	6: '‘'
	9: '’'
	1: '’'
	11: '”'
	english-reversed:
	66: ‘
	99: ’
	6: “
	9: ”
	1: ’
	11: ’
	german:
	66: „
	99: ”
	6: ‚
	9: ’
	1: ’
	11: ”
	french:
	66: '« '
	99: ' »'
	6: '“ '
	9: ' ”'
	1: '’'
	11: '» '
	';': ' ;'
	':': ' :'
	'?': ' ?'
	'€': '€ '
	'%': ' %'

	The rules are as follows:

	=over

	=item *

	The quote styles definitions is a mapping of mappings.

	=item *

	The keys in the outer mapping are the names of the quote styles.
	These can be any string which works as a key in YAML, but you may
	want to stick to strings which consist of ASCII alphanumerics,
	underscores and hyphens and start with a letter, so that you can use
	them as unquoted attribute values when using the L<< DIV- AND
	SPAN-LOCAL QUOTE STYLES\|/"4DIV- AND SPAN-LOCAL QUOTE STYLES4" >> feature.

	=item *

	The values corresponding to the style names are mappings, each being
	the definition of a quote style.

	=item *

	In each style definition mapping there are three kinds of keys:

	=over

	=item 1.

	The keys C<< 66 >>, C<< 99 >>, C<< 6 >> and C<< 9 >> correspond to the values which
	shall replace the opening and closing double and single quotes
	respectively in the C<< Quoted >> elements which are included in
	Pandoc’s AST if you run with the C<< +smart >> extension (before
	Pandoc 2 you use the C<< --smart >> option instead). Think of how the
	English typographic quotes resemble these digits! Each of these
	defaults to the respective English typographic quote, so the key
	for each quote which you want to replace must be defined!

	=item 2.

	Keys which contain any character other than the digits 0-9
	represent substrings which you want to replace with some other
	substring in Pandoc’s text elements — that is virtually
	everywhere except in code and code blocks. The replacements are
	the values of the respective keys. This feature exists mainly so
	that certain punctuation characters can be padded with the
	L<< narrow no-break space\|https://en.wikipedia.org/w/index.php?title=Non-breaking_space&oldid=808337900#Width_variation >> characters required for them in French
	orthography, but you could for example use them to replace the
	sequences C<< -+ >> and C<< +-+ >> with dagger characters († and ‡).
	However this feature slows Pandoc down, so you must set the
	metadata field C<< quote_styles_string_subst >> to C<< true >>
	or the evironment variable C<< PANDOC_QUOTE_STYLES_STRING_SUBST >>
	to a Perl true value for this to work!

	=item 3.

	The keys C<< 1 >> and C<< 11 >> represent a kind of middle ground between
	the two previous kinds.

	If the metadata field C<< quote_styles_string_subst >> is set to C<< true >>
	or the evironment variable C<< PANDOC_QUOTE_STYLES_STRING_SUBST >> to a
	Perl true value the keys for the ‘dumb’ quotes C<< ' >> and C<< " >>
	will be set to the values of these fields, or default to the typographic
	apostrophe — identical to the typographic 9 quote — and the
	typographic 99 quote, unless the actual C<< ' >> and C<< " >> mapping fields are
	defined. This will do so that wherever you type C<< \' >> and C<< \" >>
	in your Markdown you will get the values of these keys. This is
	useful because when running in I<< smart >> mode Pandoc will assume all
	C<< ' >> characters in positions where an opening single quote would
	be normal in English to be opening single quotes, but with this
	feature you can type C<< \' >> to force a typographic apostrophe. The
	C<< 11 >> or C<< " >> key can be used to implement the feature found in
	the orthographies of some languages — sometimes in English too
	— where a closing punctuation mark is put at the I<< beginning >> of
	each new paragraph in a quote. This is shown in the C<< french >> style
	in the example above.

	=back

	=item *

	Since you probably use this filter because you have trouble typing
	the various quote and other special characters the filter does some
	fudging so that you can use HTML entities anywhere in both keys and
	values in the definitions. Note however that this is done before
	everything else, so that you can’t for example use C<< 6 >> to force
	substitution of the C<< 6 >> character!

	=item *

	You can’t use Markdown formatting in definition values in metadata,
	since that will be stripped. On the other hand you should use the
	HTML entity C<< * >> to ensure a literal C<< * >> and so on for other
	Markdown special characters.

	=back

	If you are unsure which typographic quotes to use for a particular
	language L<< https:E<0x2f>E<0x2f>en.wikipedia.orgE<0x2f>wikiE<0x2f>Quotation_mark\|https://en.wikipedia.org/wiki/Quotation_mark >> has a
	L<< summary table\|https://en.wikipedia.org/w/index.php?title=Quotation_mark&oldid=809551203#Summary_table >> with information for many languages, which is handy not
	least because you can copy-paste the correct Unicode characters there!

	=head1 DIV- AND SPAN-LOCAL QUOTE STYLES

	You can use another quote style locally inside a specific Pandoc native
	span or div element by specifying a C<< quotes=STYLE-NAME >> attribute on the
	element. Note that this does I<< not >> work for link elements; wrap the link
	in a span if you really need that!

	=head1 PREREQUISITES

	In addition to L<< Pandoc\|http://pandoc.org/ >> itself this filter requires L<< perl\|https://www.perl.org/about.html >> 5.10.1 or
	greater and the following L<< CPAN\|https://www.cpan.org/ >> modules (and their
	prerequisites):

	=over

	=item *

	File::HomeDir

	=item *

	HTML::HTML5::Entities 0.004

	=item *

	Pandoc::Elements 0.33

	=item *

	Pandoc::Walker 0.27

	=item *

	Path::Tiny 0.104

	=item *

	Try::Tiny 0.28

	=item *

	YAML::Any

	=item *

	autodie 2.29

	=back

	=head2 New to Perl?

	=over

	=item B<< TL;DR: >>

	If you already have perl (on Windows: Strawberry Perl) installed run
	these commands on the command line to install all CPAN dependencies
	of this program:

	cpan App::cpanminus
	cpanm Perl::PrereqScanner
	scan-perl-prereqs pandoc-quote-styles.pl \| cpanm

	In the last line you may need to replace C<< pandoc-quote-styles.pl >>
	with the path to the program, either relative to the directory
	(folder) you are in, or an absolute path.

	=back

	This program requires L<< perl\|https://www.perl.org/about.html >> (minimum version as given above) and the
	Perl modules listed above to function. If you haven’t used Perl before
	information on how to getE<0x2f>install perl andE<0x2f>or Perl modules can be found
	at the URLS below, which lead to the official information on these
	topics.

	Don’t worry! If your operating system is Linux or Mac you probably
	already have a new enough version of perl installed. If you don’t or if
	your operating system is Windows it is easy to install a recent version,
	and once you have perl installed installing modules is very easy. Just
	follow the instructions linked to below.

	=over

	=item Getting perl

	L<< https:E<0x2f>E<0x2f>www.perl.orgE<0x2f>get.html\|https://www.perl.org/get.html >>

	(For Windows I recommend Strawberry Perl as module installation is
	easier there.)

	=item Installing Perl modules

	L<< http:E<0x2f>E<0x2f>www.cpan.orgE<0x2f>modulesE<0x2f>INSTALL.html\|http://www.cpan.org/modules/INSTALL.html >>

	=back

	=head1 AUTHOR

	Benct Philip Jonsson (bpjonsson@gmail.com, L<< https:E<0x2f>E<0x2f>github.comE<0x2f>bpj\|https://github.com/bpj >>)

	=head1 COPYRIGHT

	Copyright 2017- Benct Philip Jonsson

	=head1 LICENSE

	This is free software; you can redistribute it andE<0x2f>or modify it under
	the same terms as the Perl 5 programming language system itself. See
	L<< http:E<0x2f>E<0x2f>dev.perl.orgE<0x2f>licensesE<0x2f>\|http://dev.perl.org/licenses/ >>.

	=cut