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)?

>
>>>
> [...]
>>> .SH OPTIONS
>>> .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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* 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 \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* 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 \
		util-linux@vger.kernel.org
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.util-linux


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