Ian Jackson <[email protected]> wrote:
> Simon, do you know what's wrong here?
Yes – mancfg.but is the culprit. If you just give Halibut the single
input file man-ipbt.but, it generates a correct man page with headings.
With mancfg.but on the command line too, the headings are discarded,
because mancfg.but contains the Halibut directive \cfg{man-mindepth}{2},
and the \U headings are at depth 1.
mancfg.but comes from the parent PuTTY code base, and its purpose is to
arrange that the PuTTY man pages can appear as subsections of an
appendix in the main manual (where each man page's internal headings are
at depth 2) _and_ be built standalone to go in /usr/share/man. For the
latter, mancfg.but provides a dummy depth-1 chapter heading to make the
depth-2 headings in each man page not cause errors, and a directive to
omit it from the output.
This works for the PuTTY man pages because their internal sections are
defined using the \H directive, which means a second-level heading
within a chapter. The Halibut one uses \U, which is a top-level heading,
because it wasn't written with the same requirement to be part of a
chapter.
I don't exactly recall, but it seems likely that when I last merged
updates from PuTTY into IPBT, I must have tried to make the docs build
more like the PuTTY one, to reduce downstream diff and future merge
conflicts. And since the build didn't _fail_, I probably just failed to
notice that its output was subtly wrong.
An interim fix is to remove mancfg.but from the build command:
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index f4117e71..d721950f 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -38,10 +38,9 @@ macro(manpage title section)
if(HALIBUT)
add_custom_command(OUTPUT ${title}.${section}
COMMAND ${HALIBUT} --man=${title}.${section}
- ${CMAKE_CURRENT_SOURCE_DIR}/mancfg.but
${CMAKE_CURRENT_SOURCE_DIR}/man-${title}.but
DEPENDS
- mancfg.but man-${title}.but)
+ man-${title}.but)
register_manpage(${title} ${section})
elseif(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section})
# Our tarballs include prebuilt man pages in the source tree, so
But probably a better permanent fix from a "minimal downstream diff"
perspective is to change the heading level in man-ipbt.but so that the
same build command _will_ work the same way between the two projects.
I'll probably do that fix upstream when I get a chance.
Cheers,
Simon
--
import hashlib; print((lambda p,q,g,y,r,s,m: (lambda w:(pow(g,int(hashlib.sha1(
m.encode('ascii')).hexdigest(),16)*w%q,p)*pow(y,r*w%q,p)%p)%q)(pow(s,q-2,q))==r
and s%q!=0 and m)(12342649995480866419, 2278082317364501, 1670428356600652640,
5398151833726432125, 645223105888478, 1916678356240619, "<[email protected]>"))
