Bug#976182: javatools: jh_build man page not formatting correctly

[gregor herrmann]

On Tue, 01 Dec 2020 03:15:23 +0000, Wookey wrote:

> man jh_build shows extra capital Is in the FILES section:
> so it comes out like this:
> 
>            A file consisting of each build to perform.  One build per line where each line consists of:
> 
>              I<jarfile> I<source> [... I<source>]
> 
> Looking at the code I think that I<string> is supposed to display
> "string" in an italic font, but for some reason it's not being processed
> as desired, even though this seems to be working elsewhere in the
> file.

It's not processed because the line is indented which means "verbatim".

From perldoc perlpod:

  Verbatim Paragraph
    
    Verbatim paragraphs are usually used for presenting a codeblock
    or other text which does not require any special parsing or
    formatting, and which shouldn't be wrapped.

    A verbatim paragraph is distinguished by having its first
    character be a space or a tab. (And commonly, all its lines begin
    with spaces and/or tabs.) It should be reproduced exactly, with
    tabs assumed to be on 8-column boundaries. There are no special
    formatting codes, so you can't italicize or anything like that. A
    \ means \, and nothing else.

Like in those new-fangeld things as markdown :)
 
> I had a go at fixing it but I've never understood nroff/groff/troff and
> how that interacts with pod2man so I failed. But something is wrong
> here, and it produces quite a confusing man page.

Luckily you don't need *roff or even pod2man here, a plain
perldoc jh_build
in the source package shows the same issue and lets you check any
fixes. Which in this case can probably only be to remove the
formatting code or to unindent the line.

(And for checking the generated manpage, taken from debian/rules:
pod2man --stderr --utf8 -c Javahelper -r 0.77 jh_build | man -l -
)
 

Cheers,
gregor, happy to help with perl knowledge in a java bug :)

-- 
 .''`.  https://info.comodo.priv.at -- Debian Developer https://www.debian.org
 : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D  85FA BB3A 6801 8649 AA06
 `. `'  Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe
   `-   NP: David Bowie: Let's Dance
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: Digital Signature
URL: <http://alioth-lists.debian.net/pipermail/pkg-java-maintainers/attachments/20201201/7660a019/attachment.sig>