[doc] Issues in libnetcfg.1perl

[hmartink]

Man page: libnetcfg.1perl
Issue:    libnetcfg → B<libnetcfg>
 
"The libnetcfg utility can be used to configure the libnet.  Starting from "
"perl 5.8 libnet is part of the standard Perl distribution, but the libnetcfg "
"can be used for any libnet installation."
 
"Without arguments libnetcfg displays the current configuration."
 
"Jarkko Hietaniemi, conversion into libnetcfg for inclusion into Perl 5.8."
--
Man page: libnetcfg.1perl
Issue:    CW<\\*(C`-h\\*(C'> → B<-h>
 
"The CW<\\*(C`-h\\*(C'> option will show a usage message."
--
Man page: libnetcfg.1perl
Issue 1:  CW<\\*(C`-c\\*(C'> → B<-c>
Issue 2:  CW<\\*(C`-d\\*(C'> → B<-d>
 
"To change the configuration you will need to use either the CW<\\*(C`-"
"c\\*(C'> or the CW<\\*(C`-d\\*(C'> options."
--
Man page: libnetcfg.1perl
Issue 1:  is by default → is
Issue 2:  \"libnet.cfg\" → I<libnet.cfg>
--
Man page: libnetcfg.1perl
Issue 1:  -i option → B<-i> option
Issue 2:  \\&CW<\\*(C`-i oldfile\\*(C'> → B<-i> I<oldfile>
 
"The default name of the old configuration file is by default \"libnet.cfg\", "
"unless otherwise specified using the -i option, \\&CW<\\*(C`-i "
"oldfile\\*(C'>, and it is searched first from the current directory, and "
"then from your module path."
--
Man page: libnetcfg.1perl
Issue 1:  \"libnet.cfg\" → I<libnet.cfg>
Issue 2:  -o option → B<-o> option
Issue 3: CW<\\*(C`-o newfile\\*(C'> → B<-o> I<newfile>
 
"The default name of the new configuration file is \"libnet.cfg\", and by "
"default it is written to the current directory, unless otherwise specified "
"using the -o option, CW<\\*(C`-o newfile\\*(C'>."
--
Man page: libnetcfg.1perl
Issue:    Net::Config, libnetFAQ → B<Net::Config>(3perl), B<Net::libnetFAQ>(3perl)
 
"Net::Config, libnetFAQ"

[Grinnz]

First I will note that these pages are maintained in POD format, which are later translated to manpages. It seems you are already aware of this, since you are suggesting pod formatting. The document in question is generated by the file https://github.com/Perl/perl5/blob/blead/utils/libnetcfg.PL .

Second, I'm not sure what most of these suggestions intend to mean. Several of them contain mangled C<> formatting codes and suggest a different formatting code but with no reasoning. The last one I assume suggests linking to the Net::Config and Net::libnetFAQ manpages, which the POD formatting already does but perhaps doesn't translate to the manpages; there isn't much the documentation can do about that.

[karenetheridge]

These reports would be a lot easier to read if backticks or four columns of indenting were used.

[Leont]

These reports would be a lot easier to read if backticks or four columns of indenting were used.

Yeah, that might actually make it readable. Note in particular that right now B<foo> gets turned into Bfoo, which is extremely confusing and plain wrong.

For example currently you use:

Issue:    Net::Config, libnetFAQ → B<Net::Config>(3perl), B<Net::libnetFAQ>(3perl)

Which renders as: Issue: Net::Config, libnetFAQ → BNet::Config(3perl), BNet::libnetFAQ(3perl)

It would render a lot better if you had done something like

Issue:    `Net::Config`, `libnetFAQ` → `B<Net::Config>(3perl)`, `B<Net::libnetFAQ>(3perl)`

Which will actually render as: Issue: Net::Config, libnetFAQ → B<Net::Config>(3perl), B<Net::libnetFAQ>(3perl)

[karenetheridge]

I don't see any string or markup matching CW in utils/libnetcfg.PL or utils/libnetcfg.

However I do see:

The C<-h> option will show a usage message.

What is wrong with this markup? I do not understand what CW<\\*(C\-h\*(C'> → B<-h>` is supposed to mean.

[guest20]

They want the switch in bold and the file name in italics ... A semantic that maybe some people used in pod. Maybe. Sometimes?

[hmartink]

Sorry for my late reply.

Yes, I will use backticks again in the future. I misunderstood from the reply in my initial report last year, that I should not.

Man pages should follow man-pages(7) style. Of course, this might be (partially) different for perl, then please tell me so, so I will filter invalid reports out. Regarding the specific formatting, search for "Any reference to another man page" in the man-pages(7). Regarding option names, search for "The name of the command, and its options, .."

Finally, I only see the markup as created from the man page as shipped by the distribution(s) and then converted by po4a. Also the tools sometimes add additional (non visible) characters. I apologizes for that, simply search for the text in question and use your conventions for markup.