From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: "Mauro Carvalho Chehab" <mchehab+huawei@kernel.org>,
"Jonathan Corbet" <corbet@lwn.net>,
"Nícolas F. R. A. Prado" <nfraprado@protonmail.com>,
"Jaroslav Kysela" <perex@perex.cz>,
"Julia Lawall" <Julia.Lawall@inria.fr>,
"Takashi Iwai" <tiwai@suse.com>,
alsa-devel@alsa-project.org, linux-kernel@vger.kernel.org
Subject: [PATCH 45/53] docs: sound: kernel-api: writing-an-alsa-driver.rst: avoid using UTF-8 chars
Date: Mon, 10 May 2021 12:26:57 +0200 [thread overview]
Message-ID: <8ac9e0ecd6e3b89c4a213f2d33de6344122401a3.1620641727.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1620641727.git.mchehab+huawei@kernel.org>
While UTF-8 characters can be used at the Linux documentation,
the best is to use them only when ASCII doesn't offer a good replacement.
So, replace the occurences of the following UTF-8 characters:
- U+00a0 (' '): NO-BREAK SPACE
- U+201c ('“'): LEFT DOUBLE QUOTATION MARK
- U+201d ('”'): RIGHT DOUBLE QUOTATION MARK
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../kernel-api/writing-an-alsa-driver.rst | 68 +++++++++----------
1 file changed, 34 insertions(+), 34 deletions(-)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index e6365836fa8b..201ced3bba6e 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -533,7 +533,7 @@ Management of Cards and Components
Card Instance
-------------
-For each soundcard, a “card” record must be allocated.
+For each soundcard, a "card" record must be allocated.
A card record is the headquarters of the soundcard. It manages the whole
list of devices (components) on the soundcard, such as PCM, mixers,
@@ -980,7 +980,7 @@ The role of destructor is simple: disable the hardware (if already
activated) and release the resources. So far, we have no hardware part,
so the disabling code is not written here.
-To release the resources, the “check-and-release” method is a safer way.
+To release the resources, the "check-and-release" method is a safer way.
For the interrupt, do like this:
::
@@ -1133,7 +1133,7 @@ record:
The ``probe`` and ``remove`` functions have already been defined in
the previous sections. The ``name`` field is the name string of this
-device. Note that you must not use a slash “/” in this string.
+device. Note that you must not use a slash "/" in this string.
And at last, the module entries:
@@ -1692,8 +1692,8 @@ Typically, you'll have a hardware descriptor as below:
The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
- supports the “pause” operation, while the ``RESUME`` bit means that
- the pcm supports the full “suspend/resume” operation. If the
+ supports the "pause" operation, while the ``RESUME`` bit means that
+ the pcm supports the full "suspend/resume" operation. If the
``PAUSE`` flag is set, the ``trigger`` callback below must handle
the corresponding (pause push/release) commands. The suspend/resume
trigger commands can be defined even without the ``RESUME``
@@ -1731,7 +1731,7 @@ Typically, you'll have a hardware descriptor as below:
``periods_min`` define the maximum and minimum number of periods in
the buffer.
- The “period” is a term that corresponds to a fragment in the OSS
+ The "period" is a term that corresponds to a fragment in the OSS
world. The period defines the size at which a PCM interrupt is
generated. This size strongly depends on the hardware. Generally,
the smaller period size will give you more interrupts, that is,
@@ -1756,7 +1756,7 @@ application. This field contains the enum value
``SNDRV_PCM_FORMAT_XXX``.
One thing to be noted is that the configured buffer and period sizes
-are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
+are stored in "frames" in the runtime. In the ALSA world, ``1 frame =
channels \* samples-size``. For conversion between frames and bytes,
you can use the :c:func:`frames_to_bytes()` and
:c:func:`bytes_to_frames()` helper functions.
@@ -1999,7 +1999,7 @@ prepare callback
static int snd_xxx_prepare(struct snd_pcm_substream *substream);
-This callback is called when the pcm is “prepared”. You can set the
+This callback is called when the pcm is "prepared". You can set the
format type, sample rate, etc. here. The difference from ``hw_params``
is that the ``prepare`` callback will be called each time
:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
@@ -2436,8 +2436,8 @@ size is aligned with the period size.
The hw constraint is a very much powerful mechanism to define the
preferred PCM configuration, and there are relevant helpers.
-I won't give more details here, rather I would like to say, “Luke, use
-the source.”
+I won't give more details here, rather I would like to say, "Luke, use
+the source."
Control Interface
=================
@@ -2518,50 +2518,50 @@ Control Names
-------------
There are some standards to define the control names. A control is
-usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
+usually defined from the three parts as "SOURCE DIRECTION FUNCTION".
The first, ``SOURCE``, specifies the source of the control, and is a
-string such as “Master”, “PCM”, “CD” and “Line”. There are many
+string such as "Master", "PCM", "CD" and "Line". There are many
pre-defined sources.
The second, ``DIRECTION``, is one of the following strings according to
-the direction of the control: “Playback”, “Capture”, “Bypass Playback”
-and “Bypass Capture”. Or, it can be omitted, meaning both playback and
+the direction of the control: "Playback", "Capture", "Bypass Playback"
+and "Bypass Capture". Or, it can be omitted, meaning both playback and
capture directions.
The third, ``FUNCTION``, is one of the following strings according to
-the function of the control: “Switch”, “Volume” and “Route”.
+the function of the control: "Switch", "Volume" and "Route".
-The example of control names are, thus, “Master Capture Switch” or “PCM
-Playback Volume”.
+The example of control names are, thus, "Master Capture Switch" or "PCM
+Playback Volume".
There are some exceptions:
Global capture and playback
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
-global capture (input) source, switch and volume. Similarly, “Playback
-Switch” and “Playback Volume” are used for the global output gain switch
+"Capture Source", "Capture Switch" and "Capture Volume" are used for the
+global capture (input) source, switch and volume. Similarly, "Playback
+Switch" and "Playback Volume" are used for the global output gain switch
and volume.
Tone-controls
~~~~~~~~~~~~~
-tone-control switch and volumes are specified like “Tone Control - XXX”,
-e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
-Center”.
+tone-control switch and volumes are specified like "Tone Control - XXX",
+e.g. "Tone Control - Switch", "Tone Control - Bass", "Tone Control -
+Center".
3D controls
~~~~~~~~~~~
-3D-control switches and volumes are specified like “3D Control - XXX”,
-e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
+3D-control switches and volumes are specified like "3D Control - XXX",
+e.g. "3D Control - Switch", "3D Control - Center", "3D Control - Space".
Mic boost
~~~~~~~~~
-Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
+Mic-boost switch is set as "Mic Boost" or "Mic Boost (6dB)".
More precise information can be found in
``Documentation/sound/designs/control-names.rst``.
@@ -3368,7 +3368,7 @@ This ensures that the device can be closed and the driver unloaded
without losing data.
This callback is optional. If you do not set ``drain`` in the struct
-snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
+snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
instead.
Miscellaneous Devices
@@ -3506,20 +3506,20 @@ fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
callback, you don't specify the value field for this type (the count
field must be set, though).
-“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
-status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
+"IEC958 Playback Con Mask" is used to return the bit-mask for the IEC958
+status bits of consumer mode. Similarly, "IEC958 Playback Pro Mask"
returns the bitmask for professional mode. They are read-only controls,
and are defined as MIXER controls (iface =
``SNDRV_CTL_ELEM_IFACE_MIXER``).
-Meanwhile, “IEC958 Playback Default” control is defined for getting and
+Meanwhile, "IEC958 Playback Default" control is defined for getting and
setting the current default IEC958 bits. Note that this one is usually
defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
although in some places it's defined as a MIXER control.
In addition, you can define the control switches to enable/disable or to
set the raw bit mode. The implementation will depend on the chip, but
-the control should be named as “IEC958 xxx”, preferably using the
+the control should be named as "IEC958 xxx", preferably using the
:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
You can find several cases, for example, ``pci/emu10k1``,
@@ -3547,7 +3547,7 @@ function.
Usually, ALSA drivers try to allocate and reserve a large contiguous
physical space at the time the module is loaded for the later use. This
-is called “pre-allocation”. As already written, you can call the
+is called "pre-allocation". As already written, you can call the
following function at pcm instance construction time (in the case of PCI
bus).
@@ -4163,7 +4163,7 @@ The typical coding would be like below:
Also, don't forget to define the module description and the license.
Especially, the recent modprobe requires to define the
-module license as GPL, etc., otherwise the system is shown as “tainted”.
+module license as GPL, etc., otherwise the system is shown as "tainted".
::
@@ -4181,7 +4181,7 @@ So far, you've learned how to write the driver codes. And you might have
a question now: how to put my own driver into the ALSA driver tree? Here
(finally :) the standard procedure is described briefly.
-Suppose that you create a new PCI driver for the card “xyz”. The card
+Suppose that you create a new PCI driver for the card "xyz". The card
module name would be snd-xyz. The new driver is usually put into the
alsa-driver tree, ``sound/pci`` directory in the case of PCI
cards.
--
2.30.2
next prev parent reply other threads:[~2021-05-10 10:34 UTC|newest]
Thread overview: 92+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-10 10:26 [PATCH 00/53] Get rid of UTF-8 chars that can be mapped as ASCII Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 01/53] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 02/53] docs: ABI: remove a meaningless UTF-8 character Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 03/53] docs: ABI: remove some spurious characters Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 04/53] docs: index.rst: avoid using UTF-8 chars Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 05/53] docs: hwmon: " Mauro Carvalho Chehab
2021-05-10 13:30 ` Guenter Roeck
2021-05-10 10:26 ` [PATCH 06/53] docs: admin-guide: " Mauro Carvalho Chehab
2021-05-10 18:40 ` Gabriel Krisman Bertazi
2021-05-12 8:44 ` Mauro Carvalho Chehab
2021-05-12 9:25 ` David Woodhouse
2021-05-12 10:22 ` Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 07/53] docs: admin-guide: media: ipu3.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 08/53] docs: admin-guide: sysctl: kernel.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 09/53] docs: admin-guide: perf: imx-ddr.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 10/53] docs: admin-guide: pm: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 11/53] docs: trace: coresight: coresight-etm4x-reference.rst: " Mauro Carvalho Chehab
2021-05-10 19:28 ` Mathieu Poirier
2021-05-10 10:26 ` [PATCH 12/53] docs: driver-api: " Mauro Carvalho Chehab
[not found] ` <CAHp75Vegsb-+fVppv3C7Jp0a=mEGAh2pchX=Cr5ZvOMFt+G73Q@mail.gmail.com>
2021-05-12 8:49 ` Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 13/53] docs: driver-api: fpga: " Mauro Carvalho Chehab
2021-05-10 17:48 ` Moritz Fischer
2021-05-10 10:26 ` [PATCH 14/53] docs: driver-api: iio: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 15/53] docs: driver-api: thermal: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 16/53] docs: driver-api: media: drivers: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 17/53] docs: driver-api: firmware: other_interfaces.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 18/53] docs: driver-api: nvdimm: btt.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 19/53] docs: fault-injection: nvme-fault-injection.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 20/53] docs: usb: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 21/53] docs: process: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 22/53] docs: block: data-integrity.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 23/53] docs: userspace-api: media: fdl-appendix.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 24/53] docs: userspace-api: media: v4l: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 25/53] docs: userspace-api: media: dvb: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 26/53] docs: vm: zswap.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 27/53] docs: filesystems: f2fs.rst: " Mauro Carvalho Chehab
2021-05-11 3:16 ` [f2fs-dev] " Chao Yu
2021-05-10 10:26 ` [PATCH 28/53] docs: filesystems: ext4: " Mauro Carvalho Chehab
2021-05-10 19:23 ` Theodore Ts'o
2021-05-10 10:26 ` [PATCH 29/53] docs: kernel-hacking: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 30/53] docs: hid: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 31/53] docs: security: tpm: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 32/53] docs: security: keys: trusted-encrypted.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 33/53] docs: riscv: vm-layout.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 34/53] docs: networking: scaling.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 35/53] docs: networking: devlink: devlink-dpipe.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 36/53] docs: networking: device_drivers: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 37/53] docs: x86: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 38/53] docs: scheduler: sched-deadline.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 39/53] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab
2021-05-10 10:48 ` Marco Elver
2021-05-12 8:52 ` Mauro Carvalho Chehab
2021-05-10 23:35 ` David Gow
2021-05-12 8:14 ` Mauro Carvalho Chehab
2021-05-12 8:29 ` Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 40/53] docs: power: powercap: powercap.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 41/53] docs: ABI: " Mauro Carvalho Chehab
2021-05-10 13:53 ` Guenter Roeck
2021-05-10 10:26 ` [PATCH 42/53] docs: doc-guide: contributing.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 43/53] docs: PCI: acpi-info.rst: " Mauro Carvalho Chehab
2021-05-10 10:37 ` Krzysztof Wilczyński
2021-05-10 10:26 ` [PATCH 44/53] docs: gpu: " Mauro Carvalho Chehab
2021-05-10 11:16 ` Jani Nikula
2021-05-10 12:36 ` Liviu Dudau
2021-05-10 10:26 ` Mauro Carvalho Chehab [this message]
2021-05-10 10:26 ` [PATCH 46/53] docs: arm64: arm-acpi.rst: " Mauro Carvalho Chehab
2021-05-10 10:26 ` [PATCH 47/53] docs: infiniband: tag_matching.rst: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 48/53] docs: timers: no_hz.rst: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 49/53] docs: misc-devices: ibmvmc.rst: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 50/53] docs: firmware-guide: acpi: lpit.rst: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 51/53] docs: firmware-guide: acpi: dsd: graph.rst: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 52/53] docs: virt: kvm: " Mauro Carvalho Chehab
2021-05-10 10:27 ` [PATCH 53/53] docs: RCU: " Mauro Carvalho Chehab
2021-05-11 0:05 ` Paul E. McKenney
2021-05-10 10:52 ` [PATCH 00/53] Get rid of UTF-8 chars that can be mapped as ASCII Thorsten Leemhuis
2021-05-10 11:19 ` Mauro Carvalho Chehab
2021-05-10 12:27 ` Mauro Carvalho Chehab
2021-05-10 10:54 ` David Woodhouse
2021-05-10 11:55 ` Mauro Carvalho Chehab
2021-05-10 13:16 ` Edward Cree
2021-05-10 13:38 ` Mauro Carvalho Chehab
2021-05-10 13:58 ` Edward Cree
2021-05-10 13:59 ` Matthew Wilcox
2021-05-10 14:33 ` Edward Cree
2021-05-11 9:00 ` Mauro Carvalho Chehab
2021-05-11 9:19 ` David Woodhouse
2021-05-10 13:49 ` David Woodhouse
2021-05-10 19:22 ` Theodore Ts'o
2021-05-11 9:37 ` Mauro Carvalho Chehab
2021-05-11 9:25 ` Mauro Carvalho Chehab
2021-05-10 14:00 ` Ben Boeckel
2021-05-10 21:57 ` Adam Borowski
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=8ac9e0ecd6e3b89c4a213f2d33de6344122401a3.1620641727.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=Julia.Lawall@inria.fr \
--cc=alsa-devel@alsa-project.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=nfraprado@protonmail.com \
--cc=perex@perex.cz \
--cc=tiwai@suse.com \
/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).