[Rpm-maint] [rpm-software-management/rpm] Inconsistency in manpage formatting (Issue #2731)

[Frank Dana]

A third format:

https://github.com/rpm-software-management/rpm/blob/bbadc2bb6445e4608251d3b375120a02a8693286/docs/man/rpm2cpio.8.md?plain=1#L28-L31

FTR, when viewed with <code>yelp man:<var>page</var></code>, it turns all three of these formats into inter-manpage links, so from that perspective it doesn't matter.

(Yelp, however, does _not_ like the `@` characters in any of the `AUTHORS` email addresses: `** (yelp:1402081): WARNING **: 23:04:28.570: Couldn't parse troff special character: 'at'`. It shows, instead, as a "�" character.)

Looking at other man pages, it's typically _common_ to list `SEE ALSO` references as a comma-separated list (or multiple comma-separated lists), rather than one-per-line, and nobody seems to agree on whether italics or bold is the way to go for formatting:

```console
$ # Italics...
$ gunzip < $(man -w bash)
.SH "SEE ALSO"
.PD 0
.TP
\fIBash Reference Manual\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE --
http://pubs.opengroup.org/onlinepubs/9699919799/
.TP
http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
.TP
\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
.TP
\fIemacs\fP(1), \fIvi\fP(1)
.TP
\fIreadline\fP(3)
.PD

$ gunzip < $(man -w zsh)
.SH "SEE ALSO"
\fIsh\fP(1),
\fIcsh\fP(1),
\fItcsh\fP(1),
\fIrc\fP(1),
\fIbash\fP(1),
\fIksh\fP(1),
\fIzshall\fP(1),
\fIzshbuiltins\fP(1),
\fIzshcalsys\fP(1),
\fIzshcompwid\fP(1),
\fIzshcompsys\fP(1),
\fIzshcompctl\fP(1),
\fIzshcontrib\fP(1),
\fIzshexpn\fP(1),
\fIzshmisc\fP(1),
\fIzshmodules\fP(1),
\fIzshoptions\fP(1),
\fIzshparam\fP(1),
\fIzshroadmap\fP(1),
\fIzshtcpsys\fP(1),
\fIzshzftpsys\fP(1),
\fIzshzle\fP(1)
.PP
\fBIEEE Standard for information Technology \-

$ # Bold...
$ gunzip < $(man -w cat)
.SH "SEE ALSO"
\fBtac\fP(1)
.PP
.br
Full documentation <https://www.gnu.org/software/coreutils/cat>
.br
or available locally via: info \(aq(coreutils) cat invocation\(aq

$ gunzip < $(man -w git)
.SH "SEE ALSO"
.sp
\fBgittutorial\fR(7), \fBgittutorial-2\fR(7), \fBgiteveryday\fR(7), \fBgitcvs-migration\fR(7), \fBgitglossary\fR(7), \fBgitcore-tutorial\fR(7), \fBgitcli\fR(7), \m[blue]\fBThe Git User\(cqs Manual\fR\m[]\&\s-2\u[1]\d\s+2, \fBgitworkflows\fR(7)
```

(Note that the `zsh` list will wrap itself into a comma-separated list, since there are no separators between each entry.)

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/issues/2731#issuecomment-1776451653
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/issues/2731/1776451653 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20231023/cd2e2c06/attachment.html>