Add PDF features to improve usability

[marcows]

PDF metadata and PDF outline (navigation in the side bar) have been added.

Tasks:

• [x] Correct position of PDF outline entry srec_wilson(5) It is at the beginning, but should be at the end. Caused by psselect command in page_select.sh (which moves the TOC pages from the end to page 3).
• [x] Fix the destination position of the PDF outline links They are correct for my MSYS2 build, but too far down for my Linux build. They point to around e.g. DESCRIPTION instead of to NAME. Can you reproduce it? Maybe it's just an oddity with my Linux system.
• [x] Avoid influence of .pdfbookmark for HTML+man generation Maybe just enclose it with ".if require_index" as it is done for the .XX macro. Strangely when changing ".nr equire_index 1" (yes, looks like a typo, but seems to be intention) in doc/etc/reference.man to ".nr require_index 1" then the affected TOC entries are missing. I would have expected opposite behaviour.
• [x] PDF outline only for reference.pdf At least in the first step. Currently also README.pdf gets an outline (with only one entry, better to say without the last entry, because of missing .pdfsync command).
• [x] PDF metadata also for BUILDING.pdf, README.pdf and change_log.pdf

(Partially) implements the second task of #1.

[marcows]

With MSYS2 the PDF is in letter format whereas with Linux it is in A4. This also applies to the PDFs found in the official releases srecord-1.65.0-win64.zip and srecord-1.65.0-Linux.tar.gz. The PDF from direct website link is the same as from Linux release.

And indeed the paper size has something to do with the wrong destination position.

I changed the paper size via two groff command line options described here: https://www.gnu.org/software/groff/manual/html_node/Paper-Size.html

Here are my test results, both with MSYS2 and Linux: groff options	outline link destination
-dpaper=a4 -P-pa4	correct, at NAME
-dpaper=letter -P-pletter	correct, at NAME
-dpaper=a4 -P-pletter	too high up, near start of page
-dpaper=letter -P-pa4	too far down, near DESCRIPTION

Should I set A4 explicitly? Then the problem with link destination would be fixed and the PDFs in Win64 and Linux release files would also be in the same paper size.

[marcows]

Rebased on master to modify the new doc/man5/srec_os65a.5

[marcows]

Three tasks done with these new five commits. Rebase and cleanup will happen later.

Have to investigate about the wrong placement of srec_wilson(5) PDF outline entry.

[sierrafoxtrot]

Should I set A4 explicitly? Then the problem with link destination would be fixed and the PDFs in Win64 and Linux release files would also be in the same paper size.

If this is still an open question, then yes set to A4. This was an oversight on my part when getting the MSYS2 build up and running.

[marcows]

If this is still an open question, then yes set to A4.

The latest commit "Explicitly set a consistent paper size" addressed this and set it to A4. But thanks for the reply and agreement.

This was an oversight on my part when getting the MSYS2 build up and running.

The A4/letter inconsistency was already present in the 1.64 release from 2014, I have checked right now.

[sierrafoxtrot]

This is looking great Marcus! I'll wait until you hit "ready for review" before I start looking properly (but please don't feel rushed).

Given the number commits, I'm happy to squash but if you'd prefer to rebase into a few select/logical commits, that works too.

[marcows]

I'll definitely rebase into a few commits, I'm a clean-history-fanatic.

It's Markus with k, the c just comes from the "cow" part of my username which I'm not a big fan of anymore :-/

[sierrafoxtrot]

Sounds good and thank you Markus for correcting me on the spelling. I did take my spelling cue from 'cow" so I'm guessing I'm not the first to make that mistake at least.

[marcows]

Finally ready for review, two notes from my side:

• The consistent setting of the page size changes the layout (see commit log). If this is undesired, we'd have to investigate how to adjust the page layout with troff. But I'm not really eager to do this ;-)
• Should "pdfmark" be moved to dictionaries/cmake.txt? I didn't do this because it looked as if only official cmake keywords were included there, but now I don't think that's true anymore. However, I think names.txt is a good place.

[jtxa]

* Should "pdfmark" be moved to dictionaries/cmake.txt? I didn't do this because it looked as if only official cmake keywords were included there, but now I don't think that's true anymore. However, I think names.txt is a good place.

I created those dictionaries for "non-fixable" words: cmake.txt for CMake stuff (they're all from CMake itself), troff.txt for those I and P prefixed words, and names.txt for any kind of names of people, tools, formats, ... "pdfmark" would fit best into names.txt.

All other words, which I had not analyzed in detail, are excluded in the top-level cspell.config.yaml. Some words will vanish, when the old release description is reworked. I'm open for improvements/simplifcations, e.g. perhaps I should rename cmake.txt to code.txt and also add the C, troff, ... keywords.