From 10796bdfa6da99ca8f774091c1310d2da3968435 Mon Sep 17 00:00:00 2001
From: Mathias Kende <mathias@kende.fr>
Date: Fri, 17 May 2024 20:34:54 +0200
Subject: [PATCH] Improve the documentation.

---
 README.md        | 35 ++++++++++++++++++++++-------------
 Syntax.md        |  2 +-
 script/pmarkdown |  2 ++
 3 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 88e41aa..4e5814a 100644
--- a/README.md
+++ b/README.md
@@ -11,11 +11,14 @@ This software supports the entire
 some more custom extensions. It also has compatibility with the
 [original Markdown syntax](https://daringfireball.net/projects/markdown/syntax).
 
-It is based on the [Markdown::Perl](https://metacpan.org/pod/Markdown::Perl)
-library that can be used in standalone Perl program.
-
 See the [Syntax page](Syntax.md) for a full description of the default syntax
-supported by `pmarkdown`.
+supported by `pmarkdown`. You can also
+[try it out online](https://dingus.mkdoc.io/) or compare it to other
+implementations by using [Babelmark](https://babelmark.github.io/).
+
+This program is based on the
+[Markdown::Perl](https://metacpan.org/pod/Markdown::Perl) library that can be
+used in standalone Perl programs.
 
 ## Usage
 
@@ -38,35 +41,37 @@ You can download portable versions of `pmarkdown` for Windows and Linux on the
 ### Installation from the Perl package manager
 
 To install `pmarkdown` you need Perl (which is already installed on most Linux
-distributions) and you need the `cpanm` Perl package manager. You can usually
-get both with one of these commands:
+distributions) and you need the `cpanm` Perl package manager. In addition, the
+`perl-doc` program is optional but will improve the display of the program
+documentation. You can usually get them with one of these commands:
 
 ```shell
 # On Debian, Ubuntu, Mint, etc.
-sudo apt-get install perl cpanminus
+sudo apt-get install perl cpanminus perl-doc
 
 # On Red Hat, Fedora, CentOS, etc.
-sudo yum install perl perl-App-cpanminus
+sudo yum install perl perl-App-cpanminus perl-doc
 ```
 
 Then run the following to install `pmarkdown`:
 
 ```shell
-cpanm --notest App::pmarkdown
+sudo cpanm App::pmarkdown -n -L /usr/local --man-pages --install-args 'DESTINSTALLBIN=/usr/local/bin'
 ```
 
 ### Installation from the Git sources
 
 To install `pmarkdown` you need Perl (which is already installed on most Linux
-distributions) and you need the `cpanm` Perl package manager. You can usually
-get both with one of these commands:
+distributions) and you need the `cpanm` Perl package manager. In addition, the
+`perl-doc` program is optional but will improve the display of the program
+documentation. You can usually get them with one of these commands:
 
 ```shell
 # On Debian, Ubuntu, Mint, etc.
-sudo apt-get install perl cpanminus
+sudo apt-get install perl cpanminus perl-doc
 
 # On Red Hat, Fedora, CentOS, etc.
-sudo yum install perl perl-App-cpanminus
+sudo yum install perl perl-App-cpanminus perl-doc
 ```
 
 Then run the following command to install `pmarkdown` (note that you do not need
@@ -80,3 +85,7 @@ perl Makefile.PL
 make
 sudo make install
 ```
+
+Note that, with this installation method, you might need to reinstall the
+program each time your system Perl is updated. So the methods above are
+recommended.
diff --git a/Syntax.md b/Syntax.md
index 725cbc9..8417327 100644
--- a/Syntax.md
+++ b/Syntax.md
@@ -470,7 +470,7 @@ Is rendered as:
 
 The rendering of these delimited spans can be tuned with the `inline_delimiters`
 option, which allows to specify arbitrary tags to generate for a given delimiter
-(and can also be used to generate C<< <span> >> with arbitrary classes).
+(and can also be used to generate `<span>` with arbitrary classes).
 
 ### Links
 
diff --git a/script/pmarkdown b/script/pmarkdown
index 2547290..371c8db 100644
--- a/script/pmarkdown
+++ b/script/pmarkdown
@@ -5,6 +5,8 @@ use strict;
 use warnings;
 use utf8;
 
+use lib '/usr/local/lib/perl5';  # To be used together with the cpanm command given in the README.md file.
+
 use Encode;
 use Encode::Locale 'decode_argv';
 use English;