Re: [docbook-apps] Refentry, man pages, and DocBook XSL 1.69.0

[Michael Smith <smith@xml-doc.org>]

Paul DuBois <paul@kitebird.com> writes:

> I've tried the new release a bit, and am pleased to note the changes that
> result in much reduced runs of blank lines in the output.

I spent a lot of time trying to get that part right. One of the
things I'd like to get feedback on is whether there are places
where there is still too many blank lines being generating. Or
places where there is now too little.

> I do note one problem, which was also present in earlier
> releases: Sometimes <refsection><title>... does not result in an
> .SH macro in the output.  But this is sporadic and I have not
> found a pattern, so I do not yet have a good test case to
> provide.

When you can provide a test case, I would very much like to see
it. The only cases in which a <refsection><title>...  instance
will currently not produce a .SH macro are described below.

  - if the Refsection is the equivalent of a Refsect2 element
    (that is, a child of a Refsection which is a "top level" child
    of the Refentry), it will produce a .SS macro.

  - if the Refection is the equivalent of a Refsect3 or Refsect4
    element, it will currently produce something that looks like
    the following, where "FOO" is the title of the Refsection.

      .it 1 an-trap
      .nr an-no-space-flag 1
      .nr an-break-flag 1
      .br
      \fBFOO\fR
      .RS 3
      .PP

    Which is arcane. But it is the only way I know how to get groff
    to format it as it should (with a nested indent, and with no line
    space between the Refsection title the first following paragraph).

But that second case is new in the 1.69.0 release. Prior to this,
Refsect3 and Refsect4 and Refsection/Refsection/Refsection...
were not handled at all -- their titles just got tossed.

  --Mike

smime.p7s