Util-Linux Archive on lore.kernel.org
 help / color / Atom feed
From: J William Piggott <elseifthen@gmx.com>
To: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Cc: util-linux@vger.kernel.org
Subject: Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes
Date: Thu, 2 Jan 2020 11:52:06 -0500 (EST)
Message-ID: <nycvar.YAK.7.76.2001021131520.1385@zhn.tzk.pbz> (raw)
In-Reply-To: <20200102001715.GA30885@rhi.hi.is>

On Thu, 2 Jan 2020, Bjarni Ingi Gislason wrote:

> On Tue, Dec 17, 2019 at 03:43:15PM -0500, J William Piggott wrote:
>> On Mon, 16 Dec 2019, Bjarni Ingi Gislason wrote:
>>> Use font macros instead of font escapes (\f[BIPR]).
> [...]
>> I wish you luck. I tried to convince this project that inline escapes should be
>> avoided, but everyone here seems to be in love with them. I had them all
>> stripped out of hwclock(8), but another contributor kept insisting on putting
>> them back. I finally gave up and started using them too.
>  No reason to give up.

  Well, yes there was, but there's no point in going into it.

> Comment the font-escape line and
> add the font-macro line after it.

  If I had submitted a patch like that it would have been rejected
  (although I would not do that to a production man page anyway).

> People need to see the difference easily.

  Many people believe inline escapes are okay, or even better.

>>> ###
>>> Changes based on:
>>> Use a macro to change to the italic font,
>>> instead of \fI [1], if possible.
>>> The macros have the italic corrections,
>>> but "\c" removes the "\/" part.
>>> Or
>>> add the italic corrections.
>>> [1] man-pages(7) [Debian package "manpages"]
>> That must be Debian hack, but Michael should adopt a no inline-escape policy
>> for the man page project, IMO. Although it shouldn't limited to italic.
>  My pointing to reference [1] is wrong,
> as there is no instruction about using a macro
> instead of a font escape request.

Well, I still agree with you on not using them. Maybe you can convince
Michael to add it to man-pages(7)?

> [...]
>>> .TP
>>> -\fB\-n\fR, \fB\-\-no\-argument\fR
>>> +.BR \-n ,\  \-\-no\-argument
>>> +.\" \fB\-n\fR, \fB\-\-no\-argument\fR
>> Remove the old, don't comment it.
>> Same for below.
>  Showing the commented out font-escape line is better,
> so that the reader sees the difference and
> how the transformation is made.
>  The commented old line should come first
> to prepare the user for the changed (maybe strange) line.

I can understand one example of 'what not to do' (that should be visible
when viewing the page with man(1)). But, IMO, filling the page with
unwanted comments just adds clutter.

>  I find now the use of escaped space (,\ ) worse
> than using a quotation (", ").

I haven't formed a strong opinion on this. I use both depending on which
appears the most readable to me (in the source code) and whether having
a line break in the formatted output is unwanted.

> [...]
> --
> Bjarni I. Gislason

  reply index

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-12-16 22:20 Bjarni Ingi Gislason
2019-12-17 20:43 ` J William Piggott
2020-01-02  0:17   ` Bjarni Ingi Gislason
2020-01-02 16:52     ` J William Piggott [this message]
2020-01-03 11:48       ` Karel Zak

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=nycvar.YAK.7.76.2001021131520.1385@zhn.tzk.pbz \
    --to=elseifthen@gmx.com \
    --cc=bjarniig@rhi.hi.is \
    --cc=util-linux@vger.kernel.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Util-Linux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/util-linux/0 util-linux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 util-linux util-linux/ https://lore.kernel.org/util-linux \
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git