Search code examples
text-formattingperl-podtroff

How can I prevent "adjusting" for pod2man?


I wrote a perl-pod manual page that looked correct under perldoc:

Screen capture of terminal output for part of the SYNOPSIS section of some documentation. The text appears with single spaces between words.

But when I converted it to PostScript via pod2man and groff -Tps -man, the SYNOPSIS was "block-adjusted", adding a lot of space between the options:

PostScript render of the same text. Lines are fully justified using only word spacing; letters within a word have normal kerning, but a large amount of space appears between words.

How can I tell POD not to "adjust" a part of the manual page?

The relevant POD source for the section shown is (obviously) this:

=head1 SYNOPSIS

B<ldap-user-check>
[B<--account-context=>I<context>]
[B<--account-filter=>I<filter>]
[B<--default-notification-email-address=>I<email-addr>]
[B<--ca-certs-path=>I<path>]
[B<--credentials-file-name=>I<filename>]
[B<--ldap-size-limit=>I<number>]

Solution

  • According to a related question (https://unix.stackexchange.com/q/781914/320598) this seems to be the answer:

    Yo can insert spacial commands (either for "roff" or "man") using the =for POD command like this:

    
    =begin roff
    
    .\" your roff commands go here
    
    =end roff
    
    

    Or specific for the question, save the adjust mode, then disable it, and later re-enable it, like this:

    
    =pod
    
    ...
    
    =head1 SYNOPSIS
    
    =begin roff
    
    .\" BEGIN roff
    .\" save adjustment, then left-adjust
    .ds _A \n[.j]
    .ad l
    .\" END roff
    
    =end roff
    
    Here your command and the many options follow...
    
    =begin roff
    
    .\" BEGIN roff
    .\" restore saved adjustment
    .ad \*(_A
    .\" END roff
    
    =end roff
    
    =head1 DESCRIPTION
    
    Blabla...
    
    =cut
    
    

    In pod2man output the contents if the block will be inserted like this:

    .\" ...
    .SH "SYNOPSIS"
    .IX Header "SYNOPSIS"
    .\" BEGIN roff
    .\" save adjustment, then left-adjust
    .ds _A \n[.j]
    .\" END roff
    .\" ...
    .\" BEGIN roff
    .\" restore saved adjustment
    .ad \*(_A
    .\" END roff
    .SH "DESCRIPTION"
    .IX Header "DESCRIPTION"
    .\" ...