Restore man page generation (alternative to #202)

[ssbarnea]

Use argparse-manpage to generate the manpage.

[hartwork]

@ssbarnea

• This produces are partly broken man page. I'm attaching an annotated screenshot of the local build result (from tox -e pkg) with details, below.
• The new man page is not on par with the old one content-wise, no (or broken) usage examples, no links, no authors/attribution, no synopsis advertising --inline and --partial as most important arguments to know about. All of things that made the existing man page human are out the window now. This new page only serves the "has to have a man page" rule of e.g. Debian, nothing more.
• Asciidoc is one of the best options around to produce man pages from markup, it is maintained, the syntax is close to Markdown, it was and is today a fine choice to maintain a man page targetting humans.
• Output location man/ansi2html.1 is not ideal for when the repository does not contain a folder man after this, e.g. because there is no file man/.keepdir. It seems to work, but why put the file in an otherwise empty non-existing folder.
• The addition of allowlist_externals = sh seems either unrelated or a leftover from experiments. My vote for removal or extracting a dedicated pull request.
• You're closing my pull request Restore man page rendering #202 without a true chance for a discussion. I repeat, this is not how I want to collaborate.

[ssbarnea]

@ssbarnea

• This produces are partly broken man page. I'm attaching an annotated screenshot of the local build result (from tox -e pkg) with details, below.
• The new man page is not on par with the old one content-wise, no (or broken) usage examples, no links, no authors/attribution, no synopsis advertising --inline and --partial as most important arguments to know about. All of things that made the existing man page human are out the window now. This new page only serves the "has to have a man page" rule of e.g. Debian, nothing more.
• Asciidoc is one of the best options around to produce man pages from markup, it is maintained, the syntax is close to Markdown, it was and is today a fine choice to maintain a man page targeting humans.
• Output location man/ansi2html.1 is not ideal for when the repository does not contain a folder man after this, e.g. because there is no file man/.keepdir. It seems to work, but why put the file in an otherwise empty non-existing folder.
• The addition of allowlist_externals = sh seems either unrelated or a leftover from experiments. My vote for removal or extracting a dedicated pull request.
• You're closing my pull request Restore man page rendering #202 without a true chance for a discussion. I repeat, this is not how I want to collaborate.

I will work on fixing these tomorrow. BTW, how can I display the man page locally without installing it?

For what platform are you building a system package? I would like to setup a pipeline to do so. I did something like this for rpm building using packit on few projects.

[hartwork]

BTW, how can I display the man page locally without installing it?

@ssbarnea that would be man ./man/ansi2html.1 or man man/ansi2html.1 — I think the slash makes man understand that it's dealing with a file and not a page name.

For what platform are you building a system package? I would like to setup a pipeline to do so. I did something like this for rpm building using packit on few projects.

@ssbarnea could you elaborate, I'm not sure I understand the question. I maintain the packaging of ansi2html in Gentoo Linux at https://gitweb.gentoo.org/repo/gentoo.git/tree/dev-python/ansi2html/ansi2html-1.8.0-r1.ebuild . I would expect that you want zero Gentoo in your pipeline.

[ssbarnea]

@hartwork I can generate the man page at any location but if I do not restore exactly the same location, any consumer will need to update his build scripts. This makes me think that you want me to restore the empty folder with .gitignore on it and keep the location. Am I right?

Re other issues, I am working on them, already fixed several.

[hartwork]

@hartwork I can generate the man page at any location but if I do not restore exactly the same location, any consumer will need to update his build scripts.

@ssbarnea the change would be trivial, so I would not mind personally.

This makes me think that you want me to restore the empty folder with .gitignore on it and keep the location. Am I right?

I was not intending to push for man/.gitignore in particular, but it's maybe the best solution to that very problem.

[hartwork]

Here's an updated screenshort of what I see in the man page rendered by latest commit 248c8d6 in here:

And this is the previous output as #202 would restore:

I guess we're at a point now where the difference is marginal and both versions have pros and cons. I'll disable auto-merge now, then approve the pull request, and leave it to you @ssbarnea to push the merge button. It would allow us to get back to a releasable state.

[hartwork]

Rebasing onto latest main using GitHub's button for it…

[hartwork]

@ssbarnea any thoughts on #206 (comment) above?

[hartwork]

@ssbarnea any thoughts on #206 (comment) above?

[ssbarnea]

@hartwork I do not have bandwidth to work on this, someone else will need to to the work, sorry.

[hartwork]

@ssbarnea while we have an "At least 1 approving review is required to merge this pull request." policy around here plus only regular Collaborator permissions for me, without you I literally cannot do anything: not merge pull requests, not push to master directly, not release to PyPI. Can you do something about that at least? Right now I have both hands tied behind my back.