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

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

Hi Tim,

You wrote:

> I have found that <screen> elements are not indented as they used to
> be.

I think I kknow the particular Screen instances of which you speak,
because your patchutils.xml file is one of the files I test with.

> I have a refentry/refsect1/para/screen, and whereas it used to
> be rendered as this:
> 
> .IP
> interdiff patch /dev/null
> 
> it is now rendered as this:
> 
> .nf
> interdiff patch /dev/null
> .fi
> 
> (which I now see is more correct).  Is there any way to get
> indentation working with .nf?

For "verbatim environment" instances (Screen and also Address,
Literallayout, Programlisting, and Synopsis instances -- they are
all handled pretty much the same way by the manpages stylesheets),
the short answer is: You can achieve the same indenting effect by
marking them up with embedded leading spaces. Like this:

<para>Reversing part of a patch (and ignoring the
  rest):

<screen>    <![CDATA[filterdiff -i file.c patchfile | \
      interdiff /dev/stdin /dev/null]]></screen></para>

Or even like this:

<para>Reversing part of a patch (and ignoring the
  rest):

<screen
>    <![CDATA[filterdiff -i file.c patchfile | \
      interdiff /dev/stdin /dev/null]]></screen></para>

Either one of those will cause the above to be rendered as:

  Reversing part of a patch (and ignoring the rest):

      filterdiff -i file.c patchfile | \
        interdiff /dev/stdin /dev/null

Note that you'd already need to do that to have it be indented in
HTML or PDF output, because the HTML and PDF stylesheets do not
automatically indent verbatim enviroments either.

That said, in the case of HTML, you can add some indenting
globally using CSS. And in the case of FO output, I think you can
use the "shade.verbatim.style" parameter to add indenting.

I suppose that for man output, many people might want to have all
verbatim environments automatically indented by the same amount of
space (I think I would myself, actually), rather than needing to
add that space manually in all their content.

To have verbatim environments indented automatically, I could add
a new boolean parameter -- named "man.verbatim.indent.width",
perhaps -- with the value being a number of characters, and the
default being 0 (for no indent). Or should the default be
something else? 2 characters? Or 4 characters?

I have created a new feature request:

  Add param for indenting verbatims
  https://sourceforge.net/tracker/index.php?func=detail&aid=1242997&group_id=21935&atid=516914

Please add comments there (if you have any).

> Also, I have a section 3 man page where the "AUTHOR" section has
> disappeared, but perhaps this is intentional.  It had been picked up
> from /book/bookinfo/author previously, and I can see why that might
> not be desirable.

That was not entirely intentional. I changed the logic for looking
for Author, such that the stylesheet now does the following:

  1. Check current Refentry for a Info, Refentryinfo, or Docinfo
     child and process any Author descendent(s) of that.

  2. If not found, check any *parent* of the current Refentry for
     an info, refentryinfo, referenceinfo, articleinfo,
     chapterinfo, sectioninfo, sect1info, sect2info, sect3info,
     sect4info, sect5info, partinfo, prefaceinfo, appendixinfo, or
     docinfo child, and process andy Author descendant(s) of that.

So, in the case of your patchutils.xml file, you have Book that
contains a Reference, which contains a set of Refentry children.
So if you created a Referenceinfo section and copied the Author
section from your current Bookinfo section to that Referenceinfo
section, that Author content will get picked up and used for
output of any Refentry that lacks an Author of its own.

I suppose I maybe should also add a step 3 to the logic above, to
look in any _ancestor_ *info section if no usable content is found
in the Refentry *info or its parent's *info. I have opened a new
feature request for that. -

  Check and use ancestor *info content
  https://sourceforge.net/tracker/index.php?func=detail&aid=1243035&group_id=21935&atid=516914

I am also planning to make some significant improvements to
handling for the AUTHOR section for the next release -

  Impove handling of AUTHOR section
  https://sourceforge.net/tracker/index.php?func=detail&aid=1243027&group_id=21935&atid=516914

Please feel free to add comments to any or both of those.

> Overall, looks really good!

Thanks -- if you find anything I've muffed up, or have any other
specific comments about anything, definitely please let me know.

  --Mike

Digital signature