Bug#1039605: perltoc.1: weird formatted text in chapter "Portability"

[Russ Allbery]

Bjarni Ingi Gislason <bjarniig at simnet.is> writes:

>   Part of the text needs correct formatting.

>   The formatted text in chapter

> Portability
> Alphabetical Listening of Perl Functions

>   begins so (with column width of 100):

>            Portability
>            Alphabetical Listing of Perl Functions
>                -X FILEHANDLE

>                , -X EXPR, -X DIRHANDLE, -X, abs VALUE  , abs, accept NEWSOCKET,GENERICSOCKET ,
>                alarm SECONDS , alarm, atan2 Y,X    , bind SOCKET,NAME , binmode FILEHANDLE, LAYER
>                 , binmode FILEHANDLE, bless REF,CLASSNAME , bless REF, break, caller EXPR    ,
>                caller, chdir EXPR   , chdir FILEHANDLE, chdir DIRHANDLE, chdir, chmod LIST   ,
>                chomp VARIABLE     , chomp( LIST ), chomp, chop VARIABLE , chop( LIST ), chop,
>                chown LIST
>                   , chr NUMBER , chr, chroot FILENAME  , chroot, close FILEHANDLE , close,
>                closedir DIRHANDLE , connect SOCKET,NAME , continue BLOCK , continue, cos EXPR
>                   , cos, crypt PLAINTEXT,SALT

>                  , dbmclose HASH , dbmopen HASH,DBNAME,MASK     , defined EXPR
>                  , defined, delete EXPR , die LIST
>                     , do BLOCK , do EXPR , dump LABEL   , dump EXPR, dump, each HASH  , each
>                ARRAY , eof FILEHANDLE   , eof (), eof, eval EXPR

This appears to be an upstream bug.  Upstream is making extensive use of
the X<> escape, which expands to the empty string and is used just to add
an index entry to formatters that support indexing, but they have
surrounded each of those X<> escapes with whitespace.  This is incorrect;
the whitespace is then preserved and results in the weird formatting you
see, with spaces before commas.  There should never be whitespace around
an X<> escape.

I think whoever is maintaining this documentation may not understand what
X<> is for, since its use of X<> doesn't make any sense to me.  This is a
list of available documentation that doesn't contain any documentation
itself, so the index entries for everything mentioned seem spurious.  You
would not want to follow an index reference and have it lead to nothing
but a list of all available topics.

perlpodspec:

    "X<topic name>" -- an index entry
        See the brief discussion in "Formatting Codes" in perlpod.

        This code is unusual in that most formatters completely discard this
        code and its content. Other formatters will render it with invisible
        codes that can be used in building an index of the current document.

perlpod:

    "X<topic name>" -- an index entry
        This is ignored by most formatters, but some may use it for building
        indexes. It always renders as empty-string. Example: "X<absolutizing
        relative URLs>"

-- 
Russ Allbery (rra at debian.org)              <https://www.eyrie.org/~eagle/>