From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>, Andrew Lunn <andrew@lunn.ch>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
"David S. Miller" <davem@davemloft.net>,
Jakub Kicinski <kuba@kernel.org>,
Jesse Brandeburg <jesse.brandeburg@intel.com>,
Tony Nguyen <anthony.l.nguyen@intel.com>,
intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org,
netdev@vger.kernel.org
Subject: Re: [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
Date: Tue, 11 May 2021 21:10:28 +0200 [thread overview]
Message-ID: <20210511211028.557de948@coco.lan> (raw)
In-Reply-To: <YJrRcgmrqJLSOjR5@casper.infradead.org>
Em Tue, 11 May 2021 19:48:18 +0100
Matthew Wilcox <willy@infradead.org> escreveu:
> On Tue, May 11, 2021 at 12:24:52PM -0600, Jonathan Corbet wrote:
> > Andrew Lunn <andrew@lunn.ch> writes:
> >
> > >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> > >> +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`
> > >
> > > ...
> > >
> > >> For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
> > >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> > >> +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``
> > >
> > > Is there a difference between ` and `` ? Does it make sense to be
> > > consistent?
> >
> > This is `just weird quotes`
Gah, sorry for that! I sent a wrong version of this patch...
i40e.rst should also be using:
monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``
I'll fix it on the next spin.
>
> umm ... `this` is supposed to be "interpreted text"
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup
>
> Maybe we don't actually interpret it.
Well, if we use it as something like :ref:`foo`, it is then interpreted ;-)
using `foo` on Sphinx produces, in practice, the same effect as
``foo`` (at least on the initial versions): it also sets the font to
monospace and stops parsing other markups inside the `interpreted text`
string.
I remember that, at the very beginning, I did some ReST conversions
using `foo`. Then, I realized that this actually wrong, from the
definition PoV, and started using ``foo``.
>
> > This is ``literal text`` set in monospace in processed output.
> >
> > There is a certain tension between those who want to see liberal use of
> > literal-text markup, and those who would rather have less markup in the
> > text overall; certainly, it's better not to go totally nuts with it.
>
> I really appreciate the work you did to reduce the amount of
> markup that's needed!
In the specific case of using things like: ``command -n``, I would
put it on a literal block, either like the proposed path, or as:
monitoring tools such as::
ifstat
or::
sar -n DEV [interval] [number of samples]
ifstat is there using the same monospaced font just for
consistency purposes.
See, if you use just: sar -n
The Sphinx output could convert the hyphen to a dash.
Btw, if there was two hyphens, like: "ifstat --help"
This would be converted into "ifstat –help", using the EN DASH UTF-8
character.
So, I strongly recommend that programs (specially when followed
by arguments) to always use a literal block markup.
Thanks,
Mauro
next prev parent reply other threads:[~2021-05-11 19:10 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
2021-05-11 15:21 ` Jens Axboe
2021-05-11 15:01 ` [PATCH 2/5] docs: ABI: remove a meaningless UTF-8 character Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 3/5] docs: ABI: remove some spurious characters Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars Mauro Carvalho Chehab
2021-05-11 18:55 ` Guenter Roeck
2021-05-12 5:33 ` Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 5/5] docs: networking: device_drivers: " Mauro Carvalho Chehab
2021-05-11 17:22 ` Andrew Lunn
2021-05-11 18:24 ` Jonathan Corbet
2021-05-11 18:48 ` Matthew Wilcox
2021-05-11 19:10 ` Mauro Carvalho Chehab [this message]
2021-05-11 17:01 ` [PATCH 0/5] Fix some UTF-8 bad usages Jonathan Corbet
Reply instructions:
You may reply publicly 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=20210511211028.557de948@coco.lan \
--to=mchehab+huawei@kernel.org \
--cc=andrew@lunn.ch \
--cc=anthony.l.nguyen@intel.com \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=intel-wired-lan@lists.osuosl.org \
--cc=jesse.brandeburg@intel.com \
--cc=kuba@kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=netdev@vger.kernel.org \
--cc=willy@infradead.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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).