Issue 331 links for pdf with section url rewrites

[sluicing]

This change updates the uni.pl file to include working in-pdf links for most items.

It works by rewriting anchor tags to other files to be anchor tags to a section in the current file, so a link like this from layout.md:

See also the [libcurl examples](../libcurl/examples.md) section of this book.

becomes

See also the [libcurl examples](#libcurl__examples__md) section of this book.

in the combined uni.md

It also adds explicit section IDs referencing to '#' headings, so a heading like:

## Reply or new mail

becomes

## Reply or new mail {#project__etiquette__md-_-_-reply-or-new-mail}

KNOWN ISSUES:

The perl itself could be cleaned up a bit, but I've decided to err on the side of submitting this and doing some clean up later. If there are specific things that are too messy / to inconsistent with the rest of the code here, let me know and I'll clean them up before submitting

The links within the prose sections can be hard to notice when you're reading the doc. You can add color to the link with pandoc options, like -V colorlinks=true -V linkcolor=blue -V urlcolor=red -V toccolor=gray, but I didn't include that in this PR

There are a couple of things in the combined PDF that don't quite work right yet :

• a couple of the section headings have [] chars in them and aren't handled well by the regexes. As one example, the index links for "--trace" include a broken link to the section starting "<command [option"

• a couple of the section headings have anchor tags IN THE HEADING, which is handled by generates some weirdness in the Table of Contents, the "How to read this book" section has a contents entry labeled "1. The cURL Project", for that entry the "1" links to page 3, but the "The cURL Project" links to page 5, because the original section header that went into the table of contents linked to page 5.

• the section link to '#https' within http.md doesn't work, the script doesn't add section IDs to the unordered list items

[bagder]

when I run make pdf with this patch applied it says:

[WARNING] Duplicate identifier 'bookindex__md-_-_-sect' at uni.md line 17347 column 1
broken link: http__md-_-_-https

[sluicing]

when I run make pdf with this patch applied it says:

[WARNING] Duplicate identifier 'bookindex__md-_-_-sect' at uni.md line 17347 column 1
broken link: http__md-_-_-https

The file 'http.md' in the root directory has a link to #https; I think that might be a bad link? There isn't a matching #https heading in that file. Maybe it should be a link to http/https.md?

[bagder]

The file 'http.md' in the root directory has a link to #https

Fixed now!

[bagder]

"This branch has conflicts that must be resolved"

Can you please fix the conflicts and force-push? You should probably not push bookindex.md as part of the PR as it changes a little too often for it to be comfortable.

[bagder]

. You can add color to the link with pandoc options, like -V colorlinks=true -V linkcolor=blue -V urlcolor=red -V toccolor=gray, but I didn't include that in this PR

Do they then also end up shown like that in PDF and ePUB? The PDF at least I think could really benefit of showing links (better). If so, we could do that in a separate PR.

[sluicing]

Can you please fix the conflicts and force-push?

Done. Also, I updated urlify.pl to handle sections headers that were just "." and "/", introduced by recent upstream changes.

The updated PDF looks ok at a quick glance.

You should probably not push bookindex.md as part of the PR as it changes a little too often for it to be comfortable.

good point.

[bagder]

It still says:

This branch cannot be rebased due to conflicts

You need to rebase and force-push to get rid of that, not just merge master into this branch.

[sluicing]

You need to rebase and force-push to get rid of that, not just merge master into this branch.

Sorry about that; tried to finish this in a hurry and completely forgot about the rebase/force-push piece.

[bagder]

Thanks!