Manpage cleanups

[marschap]

This pull request

• adds DocBook sources for npa-tool, egk-tool, opensc-notify & opensc-asn1
  (I stick to my promises ;-)
• installs the man pages for them from doc/tools instead from src/tools
• fixes test-manpage.sh to check in a safer manner instead of blocking on some tools
• improves markup of option groups, alternatives, ... from hard-coded to DocBook tags
• adds option descriptions to man pages that test-manpage.sh found missing

Checklist

• Documentation is added or updated

[frankmorgner]

looks good, thanks.

I think the reference to help2man can also be removed from configure.ac and .travis.yml

[marschap]

I am at a loss.
Upon Frank's request I removed help2man references from configure.ac & .travis.yml
In addition I also removed the legacy man pages from src/tools and also removed the reference to them in Makefile.am.
This un-broke the Linux build, but the MacOS build still fails:
It complains about missing help2man, but I do not find any occurrence of help2man in the code any more.
Any help appreciated!

[frankmorgner]

I forgot that help2man is still a dependency when building OpenPACE (as done in MacOSX/build-package.in). So your current change set should be OK.

[marschap]

Phew! It works.

[frankmorgner]

Do you have a link that discusses the correct usage of xslt for man pages or is there some other documentation available?

[marschap]

I am not sure I understand your question correctly. Please bear with me if my answer missed the point.
I assume you're talking about the xml (i.e. not xslt) structure used for man pages, and the markup used for specific purposes.

In my understanding there is a "practical agreement" (by majority of documentation ;-) of using DocBook as the standard format for documentation in OpenSC. I can only speculate on the reasons (well known standard, versatility, ...)

DocBook as a documentation standard is documented on http:https://tdg.docbook.org/, with manual pages explicitly mentioned in https://tdg.docbook.org/tdg/5.2/ch02.html#making-refentry (similar entries in previous versions), mentioning <refentry> as the top-level tag for manual pages.

The tag reference then mentions explicitly what a tag is for, what attributes it can take, with what values (e.g. <filename class="directory"> to denote a directory) and what subordinate tag are allowed inside the tag.
By browsing through that reference you then end up at tags like e.g. <group> where the reference https://tdg.docbook.org/tdg/5.2/group.html explicitly stated how the tag is expected to be formatted.

Does this answer the question?

[frankmorgner]

Yes, that was my question. I am a bit overwhelmed by the pure size of the DocBook standard, so that I have difficulties to figure out what tags/attributes are relevant when writing a manpage...

[marschap]

Yeah, its a trove of information, isn't it.
I spent quite a few hours over the weekend on going through the Docbook reference to find what tags match best and and trying out whether the results match the intended meaning.

Is there a reason not to pull this request into main?

• It has no conflicts with main
• it improves documentation
• it consolidates documentation
• it fixed test-manpage.sh to find more undocumented command line options
  and not to block on opensc-notify
• I answered hopefully all your questions
• ...

[frankmorgner]

thanks