#748 docs: formatting error in man page: missing newline before macro (with fix)

[Erik Auerswald]

Hi,

there is a missing newline in the -on-error option description in the man page before the appease action. This results in the man page showing the following line:

Establish global error handlers, depending on action:.PP appease

The .PP macro needs to be at the start of a line, i.e., a newline needs to be inserted between the colon (:) and the .PP macro. This can be done using the following sed command (this works with GNU sed):

sed -i '434s/:.PP/:\n.PP/' doc/_clisp.1

Thanks,
Erik

P.S. I did not see a fitting milestone, since this documentation problem is neither an ANSI compliance issue, nor a build problem, nor a lisp error, nor a segfault. Thus I left the default selection.

[Erik Auerswald]

While the above sed command works in the current case, the . in the pattern should have been escaped:

sed -i '434s/:\.PP/:\n.PP/' doc/_clisp.1

[Erik Auerswald]

Well, it seems as if the file doc/_clisp.1 might be generated via XSLT transformations, but I have not yet found the source, nor have I found the relevant style sheet.

The root cause for the issue might be found in either of them, or at least a workaround would likely pertain to the man page source or the style sheet. If I were told (e.g., via ticket comment) where to find those and how to generate just the doc/_clisp.1 file, I would be happy to look into finding a solution.

[Erik Auerswald]

I have created the attached patch via sed -i '434s/:\.PP/:\n.PP/' doc/_clisp.1 followed by hg diff.

[Erik Auerswald]

OK, I think I found the problematic file: doc/clisp.xml.in. Comparing the domain encoding and on error sections it seems to me as if a newline should be inserted in front of <variablelist>:

sed -i '316s/:/:\n   /' doc/clisp.xml.in

The attached patch shows the results of above command.

Please note that I did not test this and thus do not know if it really fixes the issue. I have not yet attempted to build the clisp sources….

[Erik Auerswald]

Going deeper down this rabbit hole…:

• doc/man.xsl seems to be the style sheet entry point
• this reference http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
• that file invokes further XSL stuff, somewhere within must be defined how to write man macros, including .PP

One might assume that the docbook transformation to man page format should ensure that formatting directives that need to be preceded by a newline are actually preceded by a newline. Thus one might assume that there may be a bug lurking in those style sheets, i.e., in a different project. I don't know. I have never used docbook, XSL style sheets, or XSL transformations myself.

I would suggest to look for a workaround (e.g., adjusting doc/clisp.xml.in, or even post processing the generated man page with sed). In parallel, you might consider opening an issue with the docbook project, if you should come to the conclusion that the root cause lies there.

Thanks,
Erik

[Erik Auerswald]

Well, I have looked at the wrong repository, i.e., the one at SourceForge instead of the one at GitLab. The problem is still there, but the affected line in doc/_clisp.1 is 438, not 434. Thus the fix would be sed -i '438s/:\.PP/:\n.PP/' doc/_clisp.1 for the generated man page, and possibly sed -i '316s/:/:\n /' doc/clisp.xml.in for the XML source for (among other formats) the man page (same line as in SourceForge Mercurial repository).

Since the generated doc/_clisp.1 man page is checked into the repository, and no XML tools are listed as build requirements, manually fixing the man page seems OK. Of course this would risk introducing a regression the moment it is regenerated, thus adding a post-processing step to the respective Makefile (which might be generated, too…) seems to be a more useful approach. But since the line number can change, the sed script should not use a hard-coded line number. Just using sed -E 's/(.)\.PP/\1\n.PP/' doc/_clisp.1 works as well, and fixes another instance of the problem, too:

$ sed -En 's/(.)\.PP/\1\n.PP/p' doc/_clisp.1
\fIaction\fR:
.PP
\(em\m[blue]\fBJohn Foderaro\fR\m[]\&\s-2\u[47]\d\s+2
.PP

Now that I have looked at the GitLab page, I see a bug tracker there, too.

The https://clisp.org page still only mentions the SourceForge bug tracker, not the GitLab one. It also still points to the SourceForge Mercurial repository, not to the GitLab Git repository, for the Development NEWS file. Might it be helpful if that web page would (1) mention the GitLab Git repository and (2) not link to the obsolete SourceForge Mercurial repository? Perhaps even the GitLab bug tracker could be mentioned there, if only to guide potential bug reporters to the preferred one, whichever that may be?

Is this bug tracker here at SourceForge still in use by the CLISP project?

[Erik Auerswald]

I have also opened a bug report regarding this issue at Ubuntu, because I originally encountered the issue with CLISP packaged in Ubuntu 20.04: https://bugs.launchpad.net/bugs/2022970

[Erik Auerswald]

I have further explored the man page generation rabbit hole, and attached two fresh patches against current HEAD in the GitLab git repository.

The XML source seems not to be used by the normal build scripts. Thus modifying doc/_clisp.1 seems closest to the practical source of the man page. The attached patch clisp-gitlab-manpage-formatting-fix-via-_clisp.1.patch against current GitLab HEAD does this for both current instances of the problem.

But since the doc/_clisp.1 file seems to be generated from an XML source and then checked into the source code repository, adjustments to this file might get lost whenever a newly generated version is checked in. But the doc/_clisp.1 file is but a starting point for further transformations. Said transformations are affected via the (generated) src/Makefile. This Makefile is generated via src/makemake, itself generated from src/makemake.in. The attached patch clisp-gitlab-manpage-formatting-fix-via-makemake.patch against current GitLab HEAD adds another sed invocation to this transformation. (Changes to src/makemake.in do not result in rebuilding everything depending on it, thus this patch needs to be tested from a clean repository.)

I have tested both patches successfully.

[Bruno Haible]

Thanks for the report. Fixed through https://gitlab.com/gnu-clisp/clisp/-/commit/f2bc9977107f39b0d3fb7478c75b67cecd19bcaf .