Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix syntax errors in man pages #42

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
3 participants
@darkxst
Copy link
Contributor

darkxst commented Apr 5, 2018

As picked up by lintian and quotes were not rendered in man pages

W: libzip-dev: manpage-has-errors-from-man usr/share/man/man3/zip_libzip_version.3.gz 21: warning: can't find special character `Lq'
W: ziptool: manpage-has-errors-from-man usr/share/man/man1/ziptool.1.gz 328: warning: can't find special character `Lq'
@ischwarze

This comment has been minimized.

Copy link

ischwarze commented Apr 5, 2018

Hi Tim,

thanks to Thomas Klausner (wiz at NetBSD) for forwarding this bug report to me.

Of course, the patch is invalid and should not be merged: You are patching an auto-generated file.

But as usual, bad patches trigger good ones. I just fixed the root cause upstream at the mandoc project:

http://mandoc.bsd.lv/cgi-bin/cvsweb/mdoc_man.c#rev1.124

Thanks again for the report,
Ingo

P.S.
Unrelated to this bug report, but the Debian package really ought to install the high-quality *.mdoc versions of the manual pages instead of the stunted *.man versions. The man(7) versions are merely provided for prehistoric systems like Oracle Solaris 11 and the like. Modern systems like Debian support mdoc(7) natively and perfectly, no matter whether the user installs groff (which is the Debian default) or mandoc as the manual page formatter.

0-wiz-0 added a commit that referenced this pull request Apr 5, 2018

regen man pages with fixed mandoc
Addresses man page syntax problem reported in
#42
@0-wiz-0

This comment has been minimized.

Copy link
Collaborator

0-wiz-0 commented Apr 5, 2018

Fixed, thanks for the bug report!

@0-wiz-0 0-wiz-0 closed this Apr 5, 2018

@darkxst

This comment has been minimized.

Copy link
Contributor Author

darkxst commented Apr 5, 2018

Hey guys,
Thanks for the quick fix, I clearly didn't realise they were autogenerated ;)

I am working on hopefully sneaking the libzip 1.5.0 update into Ubuntu 18.04 (LP Bug. And will forward my packaging work to the Debian Maintainer at some point.

I can look into making sure the packaging uses the mdoc files, but my understanding is that it is the upstream buildsystem that installs the man pages into a virtual tree as "mdoc.7" etc, then the debhelper tools split them out into other packages if required. Not sure the Debian tools ever see the mdoc files?

@ischwarze: Does that sound right you?

Essentially is it libzip CMake system needs to installs the mdoc ? or does it actually need overrides in the acutal Debian packaging

@0-wiz-0

This comment has been minimized.

Copy link
Collaborator

0-wiz-0 commented Apr 5, 2018

I was assuming in the build system that Linux systems prefer man pages, so only man pages are installed.
I'll change it to mdoc and add a switch for those systems that really do not support mdoc.

@darkxst darkxst deleted the darkxst:man_fix branch Apr 5, 2018

@darkxst

This comment has been minimized.

Copy link
Contributor Author

darkxst commented Apr 5, 2018

@0-wiz-0 thanks! Please also look at my RPATH patch, that is a major blocker in Ubuntu/Debian, although I have just distro patched it for now ;)

bob-beck pushed a commit to openbsd/src that referenced this pull request Apr 5, 2018

For .Do/.Dq, use the documented and portable \(lq and \(rq
character escape sequences rather than the undocumented and
non-portable \(Lq and \(Rq.

Bug reported by Tim L <darkxst at github>
via Thomas Klausner <wiz at NetBSD>;
see nih-at/libzip#42
@ischwarze

This comment has been minimized.

Copy link

ischwarze commented Apr 5, 2018

@0-wiz-0 If you want to do automatic configuration tests, the standard checking goes as follows:
STEP 1: If the system provides a program "groff" or a program called "mandoc", use mdoc (that covers at least Linux, FreeBSD, NetBSD, OpenBSD, DragonFly, illumos, and Minix 3 in practice, but there should be no need to test for system names, better test for features).
STEP 2: If the system provides neither groff nor mandoc nor nroff, install preformatted (cat pages). That should be extremely rare, some maintainers may possibly skip this step if they never encountered such a system.
STEP 3: Otherwise, that is, you find neither groff nor mandoc but you do find nroff, it gets a bit complicated. To be strict, you would test whether "nroff -mdoc" works. If that seems too complicated, assuming mdoc is not available in this case and telling porters to enable it by hand if it is might be acceptable.

An example of a full test suite including a basic mdoc functionality test is available here:

https://www.sudo.ws/repos/sudo/file/tip/configure.ac

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.