Re: More man page improvements
Hi!
On Tue, 2020-05-05 at 21:09:05 +0200, Helge Kreutzmann wrote:
> During the recent proofreading we discovered some possible
> improvements to the original pages as well, which I list for you to
> consider and implement (where you agree):
Perfect thanks!
> # bug report numbers → bug report numbers of bugs
> #. type: Plain text
> #: deb-changes.man
> msgid ""
> "A space-separated list of bug report numbers that have been resolved with "
> "this upload. The distribution archive software might use this field to "
> "automatically close the referred bug numbers in the distribution bug "
> "tracking system."
I think the original is correct here. This is a list of bug-report
numbers. Maybe hyphenating here would make this more clear? Otherwise
could you say what seems wrong?
> # libgcc → B<libgcc> or quotes?
> #. type: Plain text
> #: deb-src-symbols.man
Done.
> # markup of "eval"?
> #. type: Plain text
> #: dpkg-architecture.man
> msgid ""
> "Print an export command. This can be used to set the environment variables "
> "using eval."
Done, and clarified that eval is a POSIX shell command.
> # apt → B<apt>
> #. type: Plain text
> #: dselect.man
Done. I've corrected all apt and aptitude instances, updated them to
apt instead of apt-get when appropriate and fixed the section numbers.
> # Why is this bold but not the others?
> #. type: TP
> #: dpkg-buildflags.man
> #, no-wrap
> msgid "B<lfs>"
Hmm the other feature names are in bold too. Or are you referring to
something else here?
> # debian/changelog → I<debian/changelog>
> #. type: Plain text
> #: deb-src-control.man
>
> # debian/chagelog → I<debian/changelog>
> #. type: Plain text
> #: dpkg-gensymbols.man
>
> # debian/changelog → B<debian/changelog>
> #. type: Plain text
> #: dpkg-mergechangelogs.man
>
> And in general, sometimes file names are marked up, sometimes not.
Right, I've got an unfinished patch laying around fixing pathnames to
be in italic, but I think I'll postpone this one for now until the
switch to POD, so that I can use F<> instead of I<>. There's also the
problem with pathnames that contain variable parts, which up to now
were represented as B</some/pathname/>I<variable-part>B</rest>, and
with all pathnames in italics gets rather cumbersome.
The «man groff_man» convention appears to be to use mathematical
typography (use italics for the static parts in pathnames and roman
for the variable parts), but of course this does not even seem
consistent with other conventions such as «man man-pages». :/
I'll push later today.
Thanks,
Guillem
Reply to: