Update manpage and use in related files

[postscript-dev]

Changes:

• Update exiv2.md to use GitHub-flavoured markdown bullet points
• Move man/man1/exiv2.md to ./exiv2.md, for easier use
• Update all markdown files to reflect changes in exiv2.md and exiv2 program
• Update exiv2.1 with reference to exiv2.md in GitHub
• Fix long code block lines in exiv2.md
• Add RETURN VALUES section to exiv2.md
• Fix: minor formatting and text in exiv2.md

[codecov]

Codecov Report

Merging #1914 (5bec024) into main (b27aa0b) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #1914   +/-   ##
=======================================
  Coverage   61.13%   61.13%           
=======================================
  Files          96       96           
  Lines       19059    19059           
  Branches     9734     9734           
=======================================
  Hits        11651    11651           
  Misses       5092     5092           
  Partials     2316     2316           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b27aa0b...5bec024. Read the comment docs.

[clanmills]

This really looks the business. Gosh, I'm impressed. Really nice job.

I have several minor comments and it's OK for you to ignore them:

1. Is man/man1/exiv2.md the correct location?
   Windows users wouldn't know to look there and I don't think man page readers deal with .md files. Maybe simply put exiv2.1 at the top level (beside README.md).
2. Update README.md (and possibly other .md files) to say that exiv2.md exists.
3. Have you thought about deleting most of the content of man/man1/exiv2.1 to say "read exiv2.md". Maybe you should have a link to https://github/exiv2/exiv2/exiv2.md and you have control of the format (courtesy of the GitHub's mark-down renderer).
4. There's an article here about ronn (a do ron ron, a do ron day) which is a mark-down to man format convertor. Might be useful. Might be a read herring. https://spin.atomicobject.com/2015/05/06/man-pages-in-markdown-ronn/

[postscript-dev]

This really looks the business. Gosh, I'm impressed. Really nice job.

Thanks, it's nice when effort is appreciated.

1. Is man/man1/exiv2.md the correct location?
   Windows users wouldn't know to look there and I don't think man page readers deal with .md files. Maybe simply put exiv2.1 at the top level (beside README.md).

I didn't know what to do with this, so left it in the same place as the old manpage. I can easily move it, if it is easier to find.

2. Update README.md (and possibly other .md files) to say that exiv2.md exists.

You are right, I will make any changes.

3. Have you thought about deleting most of the content of man/man1/exiv2.1 to say "read exiv2.md". Maybe you should have a link to https://github/exiv2/exiv2/exiv2.md and you have control of the format (courtesy of the GitHub's mark-down
   renderer).

I deleted the contents of man/man1/exiv2.1 and left a message pointing to the exiv2 website. Maybe it is better to change this to the GitHub location. Users can choose the branch which has the appropriate manpage for their version (if it is important).

3. There's an article here about ronn (a do ron ron, a do ron day) which is a mark-down to man format convertor. Might be useful.

I have no idea if we still need to provide an old fashioned manpage. I will have a look at the link.

I will make any changes to this PR.

[clanmills]

I looked at the utility pandoc on macOS. It does doc<->doc conversions and can generate man pages from markdown. I was unimpressed by the default result when I converted exiv2.md to exiv2.1.

I think what you've done to condense exiv2.1 is fine.

542 rmills@rmillsm1:~/gnu/github/exiv2/fix_markdown_manpage/man/man1 $ cat exiv2.1
The Exiv2 manpage is available online.
.sp 1
See: https://www.exiv2.org/manpage.html543 rmills@rmillsm1:~/gnu/github/exiv2/fix_markdown_manpage/man/man1 $ 

This is a valuable contribution to Exiv2 and I think we're more-or-less done with this now. Having the documentation for the exiv2 command-line program in mark-down will encourage us to maintain/edit/clarify the document with more frequency.

I suspect you're now beginning to realise the size of the Exiv2 project. In Chapter 11 of my book, I discuss Project Management and deal with 24 sub-topics of the Project. One of those is "Documentation" and that includes the man page, the various mark-down documents, the releases notes, the platform specific ReadMe.txt for the bundles and the doxygen generated API documentation. My book took was about 6 months of full-time work. https://clanmills.com/exiv2/book/#11-4

Documentation is only one of 24 topics. Many other topics such as code, build, test, security, and user support are much larger. It has taken a considerable chunk of Andreas' and my life to create and maintain Exiv2. A few folks understand the work involved, most have no idea how much work has been done.

[postscript-dev]

I tried ronn but the markdown-to-manpage didn't like the HTML tags (e.g. <div ...>) and the output didn't work. This would take a lot of work to make it useable.

ronn did a good job of rendering the markdown as a manpage-styled HTML page. I only had a quick look, but I think that with a couple of minor adjustments, this could be made to work. ronn formatted the page 80 chars wide, in an appropriate font and style, with manpage tables and preserved hyperlinks. This looks like an HTML manpage.

For exiv2.org though, I would suggest rendering the markdown as a normal HTML page. I think that this would take advantage of better formatting (e.g. not 80 characters wide, better tables) and be easier to use

Unless there is a real demand for an old fashioned manpage, then I am happy to leave the markdown as it is.

[clanmills]

@postscript-dev I'd like to leave reviewing this at the moment because I'm on vacation this week!

I'm happy with reducing man/man1/exiv2.1 to a pointer to the web. It's reasonable to say goodbye to man pages and adopt markdown for all Exiv2 documents.

You're also doing this for 'main' and therefore Exiv2 v1.00. I hope Exiv2 will recruit a build/release engineer for v1.00 and they can think about the web-site. I'm happy to cooperate/mentor/assist.

[postscript-dev]

I removed several long lines in exiv2.md, which would have caused problems when the file is converted to PDF. The current manpage PDF is approx 115 characters wide and I have tried to work to that standard.

Unless I need to correct something, I don't intend to add anything else.