New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

Hi Alec,

Quoted 21 lines · Alec Leamas

Quoted 19 lines · Alec Leamas

Quoted 5 lines · Michael Kerrisk (man-pages)

Quoted 4 lines · Alec Leamas

They are basically blocked on
https://bugzilla.kernel.org/show_bug.cgi?id=75751

Quoted 7 lines

Quoted 1 line

No idea how to make this rolling, there's no feedback whatsoever. Ideas?

I think the best approach might be to send the page source inline as a patch for man-pages. When doing so, please CC

me
[email protected]

The problem is just that before that I need to have that patch accepted
- you can't use this interface without the information available in public header files. That's what the bug is about, it's not the manpages as such. But a pre-requisite.

Quoted 5 lines

Hi again!

After too long time (mostly my bad, doing other things) it seems that the interface is becoming public since my patch is accepted [1] It's still not merged in the kernel tree, though.

I'm confused. What does accepted mean here?

Quoted 4 lines

Enclosing current manpage, which is a merge of lirc and lirc_ioctl as you proposed. I have also made a fist round with updates according to your suggestions. Hopefully, it is reviewable.

Quoted 1 line

Now, what's the next step?

You need a license for the page. See
https://www.kernel.org/doc/man-pages/licenses.html

For the next round, please:

CC [email protected]

From 97fbcb12b7c0871fad324e622f144c93d57b26ab Mon Sep 17 00:00:00 2001

Subject: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

+.\" Copyright (c) <year>, <copyright holder>

Quoted 6 lines · Michael Kerrisk (man-pages)

Hi Alec,

Quoted 3 lines · Alec Leamas

On 04/05/15 21:50, Alec Leamas wrote:

Quoted 7 lines

Quoted 5 lines

Hi again!

After too long time (mostly my bad, doing other things) it seems that the interface is becoming public since my patch is accepted [1] It's still not merged in the kernel tree, though.

I'm confused. What does accepted mean here?

+#include " (\fIuapi/lirc.h\fP)"

Quoted 1 line · Alec Leamas

+#include " (\fIuapi/lirc.h\fP)"

Where is that header supposed to come from?

Quoted 5 lines · Christoph Hellwig

Quoted 1 line · Alec Leamas

+#include " (\fIuapi/lirc.h\fP)"

Where is that header supposed to come from?

kernel-headers, once the media subsystem patch is merged.

Quoted 6 lines · Alec Leamas

Quoted 4 lines · Christoph Hellwig

Quoted 1 line · Alec Leamas

+#include " (\fIuapi/lirc.h\fP)"

Where is that header supposed to come from?

kernel-headers, once the media subsystem patch is merged.

Can you show me the piece of code that mangles the hierachy generated in the kernel into a flat namespace? The include path just doesn't seem to fit our normal patterns.

Quoted 2 lines

+.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual" +.\" Copyright (c) <year>, <copyright holder>

As you noted, this needs fixing.

Your mailer is wrapping text in your patches, Please fix.

Quoted 1 line

+.B LIRC_MODE_LIRCCODE.

.BR LIRC_MODE_LIRCCODE .

Similarly, other cases below need fixing.

Review

Quoted 2 lines

(quoted diff) +2 -0

+In the \fBLIRC_MODE_MODE2 mode\fR, the driver read() provides 32-bit values
+representing a space or a pulse duration, by convention typed as lirc_t.

.IR lirc_t .

Quoted 1 line

+Value reflects a pulse duration (us).

s/us/microseconds/
(Many other instances in the page need fixing also)

Quoted 1 line

+button presses. The length of each packet can be retrieved using

Please start new sentences on new source lines. (See man-pages(7).)

In all cases where you talk about a negative error code, change this to "returns an error". (By the time error numbers reach user space they are positive values in 'errno'.)

Quoted 2 lines

+.B LIRC_GET_REC_MODE

.BR LIRC_GET_REC_MODE ,

Quoted 1 line

+these returns \fI-ENOIOCTLCMD\fR or \fI-ENOSYS\fR if the operation

fail with the error \fIENOIOCTLCMD\fR or \fIENOSYS\fR

Quoted 1 line

+isn't supported and \fI-EINVAL\fR if operation failed.

s/-EINVAL/EINQAL/

Likewise for various cases below.

reserved for future use == it is an error to specify 0 or 100?

If so, make that explicit. If it isn't an error, why not? If you want to reserve these value for future use, then the driver should error on them now.

Quoted 1 line

+Some devices have a fixed timeout, in that case both ioctls will

"both ioctls"? It's not clear which ioctls are being referred to. List them explicitly.

Quoted 1 line

+Returns the driver resolution (us).

s/us/microseconds/

Quoted 1 line

+Note: wide band receiver might be implictly enabled if you enable

implicitly

Quoted 1 line

+is a bitmask combining the following bits.

s/\./:/

Review

Quoted 2 lines

(quoted diff) +2 -0

+device does not have so many transmitters, returns the number of available
+transitters and does nothing otherwise.

transmitters

From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001

On Fri, 11 Dec 2015 20:16:00 +0100
"Michael Kerrisk (man-pages)" <[email protected]> wrote:

Revised patch:

From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001
From: Alec Leamas <[email protected]>
Date: Sun, 6 Dec 2015 22:20:07 +0100
Subject: [PATCH] doc: lirc.4 upstream review remarks fixes.

---
 doc/man-source/lirc.4 | 319 ++++++++++++++++++++++++++++----------------------
 1 file changed, 182 insertions(+), 137 deletions(-)

doc/man-source/lirc.4 +25 -3

index 56d7f08..68685df 100644
@@ -1,54 +1,80 @@
 .TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual"
+
+
+.\" Copyright (c) 2015, Alec Leamas
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
 .SH NAME
 lirc \- lirc devices
 .SH DESCRIPTION
 .P
 \fB/dev/lirc*\fR are character devices providing a low-level
-bi-directional interface to IR remotes.
-When receiving data the driver works in two different modes depending on the
-underlying hardware.
+bi-directional interface to infra-red (IR) remotes.

doc/man-source/lirc.4 +1 -1

 Sometimes, this kind of hardware also supports
 sending IR data.
-It can be used with (almost) any kind of remote.
+Such hardware can be used with (almost) any kind of remote.

doc/man-source/lirc.4 +2 -1

 .P
 In the \fBLIRC_MODE_LIRCCODE\fR
 mode, the data returned by read() reflects decoded
-button presses. The length of each packet could be retrieved using
+button presses.
+The length of each packet can be retrieved using
 the  \fBLIRC_GET_LENGTH\fR ioctl.
 read() on the device must be done in blocks matching
 the bit count, rounded up so it matches full bytes.

@@ -57,15 +83,15 @@ the bit count, rounded up so it matches full bytes.
 .P
 When sending data, only the \fBLIRC_MODE_PULSE\fR

doc/man-source/lirc.4 +3 -3

 .P
-In general each driver should have a default set of settings.
+In general, each driver should have a default set of settings.
 The driver implementation is expected to re-apply the default settings
 when the device is closed by userspace, so that every application opening
 the device can rely on working with the default settings initially.

@@ -88,111 +114,117 @@ the device can rely on working with the default settings initially.
 .P
 \fI/dev/lirc*\fR devices always supports the following commands:
 .TP 4
-.B LIRC_GET_FEATURES void
+.BR LIRC_GET_FEATURES void
 Returns a bitmask of combined features bits, see FEATURES.
 Some drivers have dynamic features which are not updated until after
 an init() command.
 .TP 4
-.B LIRC_GET_REC_MODE void
+.BR LIRC_GET_REC_MODE void

doc/man-source/lirc.4 +20 -16

-.B -ENOIOCTLCMD.
+.BR ENOIOCTLCMD.
 .TP
-.B  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
+.BR  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
 Returns the send mode; currently only
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_MODE " (\fIint\fP)"
-Set the send mode.  Obsolete since only
-.B LIRC_MODE_PULSE
+.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
+Set the send mode.
+Obsolete since only
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_CARRIER " (\fIint\fP)"
+.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
 Set the modulation frequency. The argument is the frequency (Hz).
 .TP
-.B SET_SEND_DUTY_CYCLE " (\fIint\fP)"
-Set the carrier duty cycle. The argument is an int (0 <= value <= 100) which
-describes the pulse width in percent of the total cycle.  Currently, no
-special meaning is defined for 0 or 100, but the values are reserved for
-future use.
+.BR SET_SEND_DUTY_CYCLE " (\fIint\fP)"
+Set the carrier duty cycle.
+The argument is an int (0 < value < 100) which
+describes the pulse width in percent of the total cycle.
+Currently, no special meaning is defined for 0 or 100, but the values
+are reserved for future use.
 .TP
-.B LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
+.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
 Some devices have internal timers that can be used to detect when
 there's no IR activity for a long time.
 This can help lircd in detecting that a IR signal is finished and
 can speed up the decoding process.
 Returns an integer value with the minimum/maximum timeout that can be
 set.
-Some devices have a fixed timeout, in that case both ioctls will
-return the same value even though the timeout cannot be changed.
+Some devices have a fixed timeout, in that case
+.BR LIRC_GET_MIN_TIMEOUT
+and
+.BR LIRC_GET_MAX_TIMEOUT
+will return the same value even though the timeout cannot be changed.
 .TP
-.B LIRC_SET_REC_TIMEOUT " (\fIint\fP)"

doc/man-source/lirc.4 +31 -30

 A value of 0 (if supported by the hardware) disables all hardware timeouts
 and data should be reported as soon as possible.
 If the exact value cannot be set, then the next possible value
 .I greater
 than the given value should be set.
 .TP
-.B LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
+.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
 Enables/disables (1/0) timeout packages in
-.B LIRC_MODE_MODE2.
+.BR LIRC_MODE_MODE2.
 By default, timeout reports should be turned off.
 .TP
-.B LIRC_SET_REC_CARRIER " (\fIint\fP)"
+.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
 Set the receive carrier frequency (Hz).
 .TP
-.B LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
+.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
 First time called sets the lower bound of the carrier range, second time
 the upper bound (Hz).
 .TP
-.B LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
-Enable/disable (1/0) the measure mode. If enabled, from the next key
-press on, the driver will send
-.B LIRC_MODE2_FREQUENCY
+.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
+Enable/disable (1/0) the measure mode.
+If enabled, from the next key press on, the driver will send
+.BR LIRC_MODE2_FREQUENCY
 packets. By default this should be turned off.
 .TP
-.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
-Returns the driver resolution (us).
+.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
+Returns the driver resolution (microseconds).
 .TP
-.B LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
+.BR LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
 Some devices are able to filter out spikes in the incoming signal
 using given filter rules.
 These ioctls return the hardware capabilities that describe the bounds

@@ -201,21 +233,21 @@ Filter settings depend on the IR protocols that are expected.
 lircd derives the settings from all protocols definitions found in its
 config file.
 .TP
-.B LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
+.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
 See
-.B LIRC_GET_MIN_FILTER_PULSE
+.BR LIRC_GET_MIN_FILTER_PULSE
 .TP
-.B LIRC_SET_REC_FILTER " (\fIint\fP)"
-Pulses/spaces shorter than this (us) are filtered out by hardware.
+.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
+Pulses/spaces shorter than this (microseconds) are filtered out by hardware.
 .TP
-.B LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
-Pulses/spaces shorter than this (us) are filtered out by hardware. If
-filters cannot be set independently for pulse/space, the corresponding
+.BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
+Pulses/spaces shorter than this (microseconds) are filtered out by hardware.
+If filters cannot be set independently for pulse/space, the corresponding
 ioctls must return an error and
-.B LIRC_SET_REC_FILTER
+.BR LIRC_SET_REC_FILTER
 shall be used instead.
 .TP
-.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
+.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
 Some receivers are equipped with special wide band receiver which is
 intended to be used to learn output of existing remote.
 Calling that ioctl with (1) will enable it, and with (0) disable it.

@@ -223,123 +255,136 @@ This might be useful of receivers that have otherwise narrow band receiver
 that prevents them to be used with some remotes.
 Wide band receiver might also be more precise.
 On the other hand its disadvantage usually is reduced range of reception.
-Note: wide band receiver might be implictly enabled if you enable
+Note: wide band receiver might be implicitly enabled if you enable
 carrier reports.
 In that case it will be disabled as soon as you disable carrier reports.
 Trying to disable wide band receiver while carrier reports are active will
 do nothing
 
 .TP
-.B LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
+.BR LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
 Setting of several driver parameters can be optimized by encapsulating
 the according ioctl calls with
-.B LIRC_SETUP_START/LIRC_SETUP_END.
+.BR LIRC_SETUP_START/LIRC_SETUP_END.
 When a driver receives a
-.B LIRC_SETUP_START
+.BR LIRC_SETUP_START
 ioctl it can choose to not commit further setting changes to the hardware
 until a
-.B LIRC_SETUP_END
+.BR LIRC_SETUP_END
 is received.  But this is open to the driver implementation and every driver
 must also handle parameter changes which are not encapsulated by
-.B LIRC_SETUP_START
+.BR LIRC_SETUP_START
 and
-.B LIRC_SETUP_END.
+.BR LIRC_SETUP_END.
 Drivers can also choose to ignore these ioctls.
 
 .TP
-.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
+.BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
 This ioctl is called by lircd whenever a successful decoding of an
-incoming IR signal could be done. This can be used by supporting hardware
-to give visual user feedback e.g.,  by flashing a LED.
+incoming IR signal could be done.
+This can be used by supporting hardware to give visual user feedback,
+for example by flashing a LED.
 
 .SH FEATURES
 .P
 The features returned by

doc/man-source/lirc.4 +50 -41

 .TP 8
 .B LIRC_CAN_REC_PULSE
-The driver is capable of receiving using LIRC_MODE_PULSE
+The driver is capable of receiving using
+.BR LIRC_MODE_PULSE
 .TP 8
-.B LIRC_CAN_REC_MODE2
-The driver is capable of receiving using LIRC_MODE_MODE2
+.BR LIRC_CAN_REC_MODE2
+The driver is capable of receiving using
+.BR LIRC_MODE_MODE2
 .TP 8
 .B LIRC_CAN_REC_LIRCCODE
-The driver is capable of receiving using LIRC_MODE_LIRCCODE
+The driver is capable of receiving using
+.BR LIRC_MODE_LIRCCODE
 .TP 8
-.B LIRC_CAN_SET_SEND_CARRIER
+.BR LIRC_CAN_SET_SEND_CARRIER
 Driver supports  changing the modulation frequency using
-.B LIRC_SET_SEND_CARRIER.
+.BR LIRC_SET_SEND_CARRIER.
 .TP 8
-.B LIRC_CAN_SET_SEND_DUTY_CYCLE
-Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
+.BR LIRC_CAN_SET_SEND_DUTY_CYCLE
+Driver supports changing the duty cycle using
+.BR LIRC_SET_SEND_DUTY_CYCLE.
 .TP 8
-.B LIRC_CAN_SET_TRANSMITTER_MASK
+.BR LIRC_CAN_SET_TRANSMITTER_MASK
 Enables the given set of transmitters.
 The first transmitter is encoded by the least significant bit, etc.
-When an invalid bit mask is given e. g.,  a bit is set even though the
+When an invalid bit mask is given, for example a bit is set even though the
 device does not have so many transmitters, returns the number of available
-transitters and does nothing otherwise.
+transmitters and does nothing otherwise.
 .TP 8
-.B LIRC_CAN_SET_REC_CARRIER
-Drvier supports setting the receive carrier frequency using
-.B LIRC_SET_REC_CARRIER.
+.BR LIRC_CAN_SET_REC_CARRIER
+Driver supports setting the receive carrier frequency using
+.BR LIRC_SET_REC_CARRIER.
 .TP 8
-.B LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
-Driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE
+.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
+Driver supports
+.BR LIRC_SET_REC_DUTY_CYCLE_RANGE
 .TP 8
-.B LIRC_CAN_SET_REC_CARRIER_RANGE
-Driver supports LIRC_SET_REC_CARRIER_RANGE
+.BR LIRC_CAN_SET_REC_CARRIER_RANGE
+Driver supports
+.BR LIRC_SET_REC_CARRIER_RANGE
 .TP 8
-.B LIRC_CAN_GET_REC_RESOLUTION
-Driver supports LIRC_GET_REC_RESOLUTION
+.BR LIRC_CAN_GET_REC_RESOLUTION
+Driver supports
+.BR LIRC_GET_REC_RESOLUTION
 .TP 8
-.B LIRC_CAN_SET_REC_TIMEOUT
-Driver supports LIRC_SET_REC_TIMEOUT
+.BR LIRC_CAN_SET_REC_TIMEOUT
+Driver supports
+.BR LIRC_SET_REC_TIMEOUT
 .TP 8
-.B LIRC_CAN_SET_REC_FILTER
-Driver supports LIRC_SET_REC_FILTER
+.BR LIRC_CAN_SET_REC_FILTER
+Driver supports
+.BR LIRC_SET_REC_FILTER
 .TP 8
-.B LIRC_CAN_MEASURE_CARRIER
+.BR LIRC_CAN_MEASURE_CARRIER
 Driver supports measuring of the modulation frequency using
-.B LIRC_MEASURE_CARRIER
+.BR LIRC_MEASURE_CARRIER
 .TP 8
-.B LIRC_CAN_USE_WIDEBAND_RECEIVER
+.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
 Driver supports learning mode using
-.B LIRC_SET_WIDEBAND_RECEIVER
+.BR LIRC_SET_WIDEBAND_RECEIVER
 .TP 8
-.B LIRC_CAN_NOTIFY_DECODE
-Driver supports LIRC_NOTIFY_DECODE.
+.BR LIRC_CAN_NOTIFY_DECODE
+Driver supports
+.BR LIRC_NOTIFY_DECODE.
 .TP 8
-.B LIRC_CAN_SEND_RAW
+.BR LIRC_CAN_SEND_RAW
 Driver supports sending using
-.B LIRC_SEND_RAW
+.BR LIRC_SEND_RAW
 .TP 8
-.B LIRC_CAN_SEND_PULSE
+.BR LIRC_CAN_SEND_PULSE
 Driver supports sending using
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 .TP 8
-.B LIRC_CAN_SEND_MODE2
+.BR LIRC_CAN_SEND_MODE2
 Driver supports sending using
-.B LIRC_SEND_MODE2
+.BR LIRC_SEND_MODE2
 .TP 8
-.B LIRC_CAN_SEND_LIRCCODE
+.BR LIRC_CAN_SEND_LIRCCODE
 Driver supports sending
-.B LIRC_SEND_LIRCCODE
+.BR LIRC_SEND_LIRCCODE
 (this is uncommon, since
-.B LIRCCODE
-drivers reflects hardware like TV-cards which usually does not support
+.BR LIRCCODE
+drivers reflect hardware like TV-cards which usually does not support
 sending.)
 
 .SH BUGS
 .P
-Using these devices requires the kernel source header file lirc.h. That this

Hello Alec,

Quoted 2 lines · Alec Leamas

On Fri, 11 Dec 2015 20:16:00 +0100
"Michael Kerrisk (man-pages)" <[email protected]> wrote:

[Excellent walk though of fixes snipped]

Quoted 1 line

Revised patch:

Patches on top of patches is confusing. For the next round, just send a fresh complete patch. A few more comments below.

Quoted 48 lines

From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001
From: Alec Leamas <[email protected]>
Date: Sun, 6 Dec 2015 22:20:07 +0100
Subject: [PATCH] doc: lirc.4 upstream review remarks fixes.

---
 doc/man-source/lirc.4 | 319 ++++++++++++++++++++++++++++----------------------
 1 file changed, 182 insertions(+), 137 deletions(-)

doc/man-source/lirc.4 +25 -3

index 56d7f08..68685df 100644
@@ -1,54 +1,80 @@
 .TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual"
+
+
+.\" Copyright (c) 2015, Alec Leamas
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
 .SH NAME
 lirc \- lirc devices
 .SH DESCRIPTION
 .P
 \fB/dev/lirc*\fR are character devices providing a low-level
-bi-directional interface to IR remotes.
-When receiving data the driver works in two different modes depending on the
-underlying hardware.
+bi-directional interface to infra-red (IR) remotes.

doc/man-source/lirc.4 line 38

Quoted 10 lines

doc/man-source/lirc.4 +5 -3

+When receiving data, the driver works in two different modes depending
+on the underlying hardware.
 .P
-Some hardware (typically TV-cards) decodes the IR signal internally and just
-provides decoded button presses as integer values.
-Drivers for this kind of hardware works in
+Some hardware (typically TV-cards) decodes the IR signal internally
+and just provides decoded button presses as integer values.
+Drivers for this kind of hardware work in
 .B LIRC_MODE_LIRCCODE.

.BR LIRC_MODE_LIRCCODE .

(There are several other instances to fix also.

doc/man-source/lirc.4 line 45

Quoted 11 lines

doc/man-source/lirc.4 +4 -4

 Such hardware usually does not support sending IR signals.
-Furthermore, it usually only works with a specific remote which is bundled
-with e. g., a TV-card.
+Furthermore, it usually only works with a specific remote which is
+bundled with, for example, a TV-card.
 .P
 Other hardware provides a stream of pulse/space durations.
-Such drivers works in
-.B LIRC_MODE_MODE2.
+Such drivers work in
+.BR LIRC_MODE_MODE2.

.BR LIRC_MODE_MODE2 .

(i.e., add space before '.') Probably there are other instances to fix as well.

doc/man-source/lirc.4 line 52

Quoted 8 lines

doc/man-source/lirc.4 +1 -1

 Sometimes, this kind of hardware also supports
 sending IR data.
-It can be used with (almost) any kind of remote.
+Such hardware can be used with (almost) any kind of remote.
 .P
 The \fBLIRC_GET_REC_MODE\fR ioctl allows probing for the mode.
 
 .SH Reading using LIRC_MODE_MODE2 drivers

doc/man-source/lirc.4 line 56

Quoted 6 lines

doc/man-source/lirc.4 +2 -2

 .P
 In the \fBLIRC_MODE_MODE2 mode\fR, the driver read() provides 32-bit values
-representing a space or a pulse duration, by convention typed as lirc_t.
-The time of the duration (us) is encoded in the lower 24 bits.
+representing a space or a pulse duration, by convention typed as
+.IR lirc_t.

.IR lirc_t .

doc/man-source/lirc.4 line 63

Quoted 11 lines

doc/man-source/lirc.4 +4 -4

+The time of the duration (microseonds) is encoded in the lower 24 bits.
 The upper 8 bit reflects the type of package:
 .TP 4
-.B LIRC_MODE2_SPACE
-Value reflects a space duration (us).
+.BR LIRC_MODE2_SPACE
+Value reflects a space duration (microseconds).
 .TP 4
-.B LIRC_MODE2_PULSE
-Value reflects a pulse duration (us).
+.BR LIRC_MODE2_PULSE

s/$/ ./
(And at various other places below.)

Quoted 11 lines

doc/man-source/lirc.4 +3 -2

+Value reflects a pulse duration (microseconds).
 .TP 4
-.B LIRC_MODE2_FREQUENCY
+.BR LIRC_MODE2_FREQUENCY
 Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl.
 .TP 4
-.B LIRC_MODE2_TIMEOUT
+.BR LIRC_MODE2_TIMEOUT
 The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.
 

doc/man-source/lirc.4 line 72

Quoted 1 line

doc/man-source/lirc.4 +0 -0

 .SH Reading using LIRC_MODE_LIRCCODE drivers.

s/.$//

doc/man-source/lirc.4 line 80

Quoted 9 lines

doc/man-source/lirc.4 +2 -1

 .P
 In the \fBLIRC_MODE_LIRCCODE\fR
 mode, the data returned by read() reflects decoded
-button presses. The length of each packet could be retrieved using
+button presses.
+The length of each packet can be retrieved using
 the  \fBLIRC_GET_LENGTH\fR ioctl.
 read() on the device must be done in blocks matching
 the bit count, rounded up so it matches full bytes.

doc/man-source/lirc.4 the bit count, rounded up so it matches full bytes. · line 92

Quoted 13 lines

doc/man-source/lirc.4 +2 -2

@@ -57,15 +83,15 @@ the bit count, rounded up so it matches full bytes.
 .P
 When sending data, only the \fBLIRC_MODE_PULSE\fR
 mode is supported.
-The data written to the chardev using write() is a pulse/space sequence
-of integer values.
+The data written to the character device using write() is a pulse/space
+sequence of integer values.
 Pulses and spaces are only marked implicitly by their position.
 The data must start and end with a pulse, thus it must always include an odd
 number of samples.
 The write() function  blocks until the data has been transmitted by the
 hardware. If more data is provided than the hardware can send, the driver

s/the driver/the write() call/

Start new sentence on new line.

doc/man-source/lirc.4 the bit count, rounded up so it matches full bytes. · line 93

Quoted 1 line

doc/man-source/lirc.4 +0 -0

 returns

s/returns/fails with the error/

doc/man-source/lirc.4 the bit count, rounded up so it matches full bytes. · line 94

Quoted 2 lines

doc/man-source/lirc.4 +1 -1

-.B EINVAL
+.BR EINVAL

.BR EINVAL .

doc/man-source/lirc.4 returns · line 105

Quoted 11 lines

doc/man-source/lirc.4 +1 -1

 .SH SUPPORTED IOCTL COMMANDS
 .P

@@ -74,11 +100,11 @@ returns
 int ioctl(int fd, int cmd, ...);
 .fi
 .P
-The following ioctls can be used to to probe or change specific lirc
+The following ioctls can be used to probe or change specific lirc
 hardware settings.
 Many require a third argument, usually an int.

Put the"int" on a separate line as

.IR int .

doc/man-source/lirc.4 returns · line 110

Quoted 6 lines

doc/man-source/lirc.4 +1 -1

 .P
-In general each driver should have a default set of settings.
+In general, each driver should have a default set of settings.
 The driver implementation is expected to re-apply the default settings
 when the device is closed by userspace, so that every application opening
 the device can rely on working with the default settings initially.

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 117

Quoted 6 lines

doc/man-source/lirc.4 +1 -1

@@ -88,111 +114,117 @@ the device can rely on working with the default settings initially.
 .P
 \fI/dev/lirc*\fR devices always supports the following commands:
 .TP 4
-.B LIRC_GET_FEATURES void
+.BR LIRC_GET_FEATURES void

Quoted 6 lines

doc/man-source/lirc.4 +1 -1

 Returns a bitmask of combined features bits, see FEATURES.
 Some drivers have dynamic features which are not updated until after
 an init() command.
 .TP 4
-.B LIRC_GET_REC_MODE void
+.BR LIRC_GET_REC_MODE void

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 130

Quoted 10 lines

doc/man-source/lirc.4 +2 -2

 Returns the receive mode, one of
 .RS 4
 .TP
-.B LIRC_MODE_MODE2
+.BR LIRC_MODE_MODE2
 Driver return a sequence of pulse/space durations.
 .TP
-.B LIRC_MODE_LIRCCODE
+.BR LIRC_MODE_LIRCCODE
 Driver returns integer values, each of which representing a decoded button

s/representing/represents/

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 134

Quoted 6 lines

doc/man-source/lirc.4 +1 -2

 press.
 .RE
 .P
-If a device returns a negative error code  for
-.B LIRC_GET_REC_MODE
+If a device returns an error code  for

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 135

Quoted 1 line

doc/man-source/lirc.4 +1 -0

+.BR LIRC_GET_REC_MODE

s/$/ ,/

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 138

Quoted 3 lines

doc/man-source/lirc.4 +0 -0

 it is safe to assume it is not a lirc device.
 
 .BR

Remove that last line.

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 141

Quoted 6 lines

doc/man-source/lirc.4 +1 -3

 .SH Optional Commands
 .P
-Some lirc devices supports the following commands. Unless otherwise stated
-these  returns \fI-ENOIOCTLCMD\fR or \fI-ENOSYS\fR if the operation
-isn't supported and \fI-EINVAL\fR if operation failed.
+Some lirc devices supports the following commands.

s/supports/supports/

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 142

Quoted 2 lines

doc/man-source/lirc.4 +1 -0

+Unless otherwise stated these returns \fIENOIOCTLCMD\fR

s/returns/fail with the error/

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 144

Quoted 2 lines

doc/man-source/lirc.4 +2 -0

+or \fIENOSYS\fR if the operation
+isn't supported and \fIEINVAL\fR if operation failed.

s/and/or with the error/

s/operation/the operation/

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 150

Quoted 9 lines

doc/man-source/lirc.4 +3 -3

 .TP
-.B LIRC_SET_REC_MODE  " (\fIint\fP)"
+.BR LIRC_SET_REC_MODE  " (\fIint\fP)"
 Set the receive mode, either
-.B LIRC_MODE_LIRCCODE
+.BR LIRC_MODE_LIRCCODE
 or
-.B LIRC_MODE_MODE2.
+.BR LIRC_MODE_MODE2.

.BR LIRC_MODE_MODE2 .
(Fix other instances too please.)

Quoted 5 lines

doc/man-source/lirc.4 +1 -1

 .TP
-.B LIRC_GET_LENGTH " (\fIvoid\fP)"
+.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
 Return the positive  length of the returned codes for

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 157

Quoted 4 lines

doc/man-source/lirc.4 +1 -1

-.B LIRC_LIRCCODE
+.BR LIRC_LIRCCODE
 type
 drivers, otherwise

s/$/ fail with the error/

Quoted 52 lines

doc/man-source/lirc.4 +20 -16

-.B -ENOIOCTLCMD.
+.BR ENOIOCTLCMD.
 .TP
-.B  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
+.BR  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
 Returns the send mode; currently only
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_MODE " (\fIint\fP)"
-Set the send mode.  Obsolete since only
-.B LIRC_MODE_PULSE
+.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
+Set the send mode.
+Obsolete since only
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_CARRIER " (\fIint\fP)"
+.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
 Set the modulation frequency. The argument is the frequency (Hz).
 .TP
-.B SET_SEND_DUTY_CYCLE " (\fIint\fP)"
-Set the carrier duty cycle. The argument is an int (0 <= value <= 100) which
-describes the pulse width in percent of the total cycle.  Currently, no
-special meaning is defined for 0 or 100, but the values are reserved for
-future use.
+.BR SET_SEND_DUTY_CYCLE " (\fIint\fP)"
+Set the carrier duty cycle.
+The argument is an int (0 < value < 100) which
+describes the pulse width in percent of the total cycle.
+Currently, no special meaning is defined for 0 or 100, but the values
+are reserved for future use.
 .TP
-.B LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
+.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
 Some devices have internal timers that can be used to detect when
 there's no IR activity for a long time.
 This can help lircd in detecting that a IR signal is finished and
 can speed up the decoding process.
 Returns an integer value with the minimum/maximum timeout that can be
 set.
-Some devices have a fixed timeout, in that case both ioctls will
-return the same value even though the timeout cannot be changed.
+Some devices have a fixed timeout, in that case
+.BR LIRC_GET_MIN_TIMEOUT
+and
+.BR LIRC_GET_MAX_TIMEOUT
+will return the same value even though the timeout cannot be changed.
 .TP
-.B LIRC_SET_REC_TIMEOUT " (\fIint\fP)"

doc/man-source/lirc.4 the device can rely on working with the default settings initially. · line 199

Quoted 10 lines

doc/man-source/lirc.4 +5 -4

-Sets the integer value for IR inactivity timeout. To be accepted, the
-value must be within the limits defined by
-.B LIRC_GET_MIN_TIMEOUT
+.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
+Sets the integer value for IR inactivity timeout.
+To be accepted, the value must be within the limits defined by
+.BR LIRC_GET_MIN_TIMEOUT
 and
-.B LIRC_GET_MAX_TIMEOUT.
+.BR LIRC_GET_MAX_TIMEOUT.

s/.$/ .$/

Quoted 64 lines

doc/man-source/lirc.4 +18 -18

 A value of 0 (if supported by the hardware) disables all hardware timeouts
 and data should be reported as soon as possible.
 If the exact value cannot be set, then the next possible value
 .I greater
 than the given value should be set.
 .TP
-.B LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
+.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
 Enables/disables (1/0) timeout packages in
-.B LIRC_MODE_MODE2.
+.BR LIRC_MODE_MODE2.
 By default, timeout reports should be turned off.
 .TP
-.B LIRC_SET_REC_CARRIER " (\fIint\fP)"
+.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
 Set the receive carrier frequency (Hz).
 .TP
-.B LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
+.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
 First time called sets the lower bound of the carrier range, second time
 the upper bound (Hz).
 .TP
-.B LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
-Enable/disable (1/0) the measure mode. If enabled, from the next key
-press on, the driver will send
-.B LIRC_MODE2_FREQUENCY
+.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
+Enable/disable (1/0) the measure mode.
+If enabled, from the next key press on, the driver will send
+.BR LIRC_MODE2_FREQUENCY
 packets. By default this should be turned off.
 .TP
-.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
-Returns the driver resolution (us).
+.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
+Returns the driver resolution (microseconds).
 .TP
-.B LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
+.BR LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
 Some devices are able to filter out spikes in the incoming signal
 using given filter rules.
 These ioctls return the hardware capabilities that describe the bounds

@@ -201,21 +233,21 @@ Filter settings depend on the IR protocols that are expected.
 lircd derives the settings from all protocols definitions found in its
 config file.
 .TP
-.B LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
+.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
 See
-.B LIRC_GET_MIN_FILTER_PULSE
+.BR LIRC_GET_MIN_FILTER_PULSE
 .TP
-.B LIRC_SET_REC_FILTER " (\fIint\fP)"
-Pulses/spaces shorter than this (us) are filtered out by hardware.
+.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
+Pulses/spaces shorter than this (microseconds) are filtered out by hardware.
 .TP
-.B LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
-Pulses/spaces shorter than this (us) are filtered out by hardware. If
-filters cannot be set independently for pulse/space, the corresponding
+.BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
+Pulses/spaces shorter than this (microseconds) are filtered out by hardware.
+If filters cannot be set independently for pulse/space, the corresponding
 ioctls must return an error and

doc/man-source/lirc.4 Filter settings depend on the IR protocols that are expected. · line 252

Quoted 8 lines

doc/man-source/lirc.4 +2 -2

-.B LIRC_SET_REC_FILTER
+.BR LIRC_SET_REC_FILTER
 shall be used instead.
 .TP
-.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
+.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
 Some receivers are equipped with special wide band receiver which is
 intended to be used to learn output of existing remote.

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver

Quoted 2 lines

doc/man-source/lirc.4 +0 -0

 Calling that ioctl with (1) will enable it, and with (0) disable it.

@@ -223,123 +255,136 @@ This might be useful of receivers that have otherwise narrow band receiver

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 255

Quoted 1 line

doc/man-source/lirc.4 +0 -0

 that prevents them to be used with some remotes.

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 256

Quoted 1 line

doc/man-source/lirc.4 +0 -0

 Wide band receiver might also be more precise.

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 262

Quoted 7 lines

doc/man-source/lirc.4 +1 -1

 On the other hand its disadvantage usually is reduced range of reception.
-Note: wide band receiver might be implictly enabled if you enable
+Note: wide band receiver might be implicitly enabled if you enable
 carrier reports.
 In that case it will be disabled as soon as you disable carrier reports.
 Trying to disable wide band receiver while carrier reports are active will
 do nothing

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 267

Quoted 6 lines

doc/man-source/lirc.4 +1 -1

 .TP
-.B LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
+.BR LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
 Setting of several driver parameters can be optimized by encapsulating
 the according ioctl calls with

Quoted 18 lines

doc/man-source/lirc.4 +5 -5

-.B LIRC_SETUP_START/LIRC_SETUP_END.
+.BR LIRC_SETUP_START/LIRC_SETUP_END.
 When a driver receives a
-.B LIRC_SETUP_START
+.BR LIRC_SETUP_START
 ioctl it can choose to not commit further setting changes to the hardware
 until a
-.B LIRC_SETUP_END
+.BR LIRC_SETUP_END
 is received.  But this is open to the driver implementation and every driver
 must also handle parameter changes which are not encapsulated by
-.B LIRC_SETUP_START
+.BR LIRC_SETUP_START
 and
-.B LIRC_SETUP_END.
+.BR LIRC_SETUP_END.
 Drivers can also choose to ignore these ioctls.
 

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 284

Quoted 7 lines

doc/man-source/lirc.4 +2 -3

 .TP
-.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
+.BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
 This ioctl is called by lircd whenever a successful decoding of an
-incoming IR signal could be done. This can be used by supporting hardware
-to give visual user feedback e.g.,  by flashing a LED.
+incoming IR signal could be done.

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 286

Quoted 2 lines

doc/man-source/lirc.4 +2 -0

+This can be used by supporting hardware to give visual user feedback,
+for example by flashing a LED.

Quoted 4 lines

doc/man-source/lirc.4 +0 -0

 .SH FEATURES
 .P
 The features returned by

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 296

Quoted 10 lines

doc/man-source/lirc.4 +5 -4

-.B LIRC_GET_FEATURES
-is a bitmask combining the following bits.
+.BR LIRC_GET_FEATURES
+is a bitmask combining the following bits:
 .TP 8
-.B LIRC_CAN_REC_RAW
-The driver is capable of receiving using LIRC_MODE_RAW
+.BR LIRC_CAN_REC_RAW
+The driver is capable of receiving using
+.BR LIRC_MODE_RAW

s/$/ ./
(And other instances below)

Quoted 124 lines

doc/man-source/lirc.4 +50 -40

 .TP 8
 .B LIRC_CAN_REC_PULSE
-The driver is capable of receiving using LIRC_MODE_PULSE
+The driver is capable of receiving using
+.BR LIRC_MODE_PULSE
 .TP 8
-.B LIRC_CAN_REC_MODE2
-The driver is capable of receiving using LIRC_MODE_MODE2
+.BR LIRC_CAN_REC_MODE2
+The driver is capable of receiving using
+.BR LIRC_MODE_MODE2
 .TP 8
 .B LIRC_CAN_REC_LIRCCODE
-The driver is capable of receiving using LIRC_MODE_LIRCCODE
+The driver is capable of receiving using
+.BR LIRC_MODE_LIRCCODE
 .TP 8
-.B LIRC_CAN_SET_SEND_CARRIER
+.BR LIRC_CAN_SET_SEND_CARRIER
 Driver supports  changing the modulation frequency using
-.B LIRC_SET_SEND_CARRIER.
+.BR LIRC_SET_SEND_CARRIER.
 .TP 8
-.B LIRC_CAN_SET_SEND_DUTY_CYCLE
-Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
+.BR LIRC_CAN_SET_SEND_DUTY_CYCLE
+Driver supports changing the duty cycle using
+.BR LIRC_SET_SEND_DUTY_CYCLE.
 .TP 8
-.B LIRC_CAN_SET_TRANSMITTER_MASK
+.BR LIRC_CAN_SET_TRANSMITTER_MASK
 Enables the given set of transmitters.
 The first transmitter is encoded by the least significant bit, etc.
-When an invalid bit mask is given e. g.,  a bit is set even though the
+When an invalid bit mask is given, for example a bit is set even though the
 device does not have so many transmitters, returns the number of available
-transitters and does nothing otherwise.
+transmitters and does nothing otherwise.
 .TP 8
-.B LIRC_CAN_SET_REC_CARRIER
-Drvier supports setting the receive carrier frequency using
-.B LIRC_SET_REC_CARRIER.
+.BR LIRC_CAN_SET_REC_CARRIER
+Driver supports setting the receive carrier frequency using
+.BR LIRC_SET_REC_CARRIER.
 .TP 8
-.B LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
-Driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE
+.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
+Driver supports
+.BR LIRC_SET_REC_DUTY_CYCLE_RANGE
 .TP 8
-.B LIRC_CAN_SET_REC_CARRIER_RANGE
-Driver supports LIRC_SET_REC_CARRIER_RANGE
+.BR LIRC_CAN_SET_REC_CARRIER_RANGE
+Driver supports
+.BR LIRC_SET_REC_CARRIER_RANGE
 .TP 8
-.B LIRC_CAN_GET_REC_RESOLUTION
-Driver supports LIRC_GET_REC_RESOLUTION
+.BR LIRC_CAN_GET_REC_RESOLUTION
+Driver supports
+.BR LIRC_GET_REC_RESOLUTION
 .TP 8
-.B LIRC_CAN_SET_REC_TIMEOUT
-Driver supports LIRC_SET_REC_TIMEOUT
+.BR LIRC_CAN_SET_REC_TIMEOUT
+Driver supports
+.BR LIRC_SET_REC_TIMEOUT
 .TP 8
-.B LIRC_CAN_SET_REC_FILTER
-Driver supports LIRC_SET_REC_FILTER
+.BR LIRC_CAN_SET_REC_FILTER
+Driver supports
+.BR LIRC_SET_REC_FILTER
 .TP 8
-.B LIRC_CAN_MEASURE_CARRIER
+.BR LIRC_CAN_MEASURE_CARRIER
 Driver supports measuring of the modulation frequency using
-.B LIRC_MEASURE_CARRIER
+.BR LIRC_MEASURE_CARRIER
 .TP 8
-.B LIRC_CAN_USE_WIDEBAND_RECEIVER
+.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
 Driver supports learning mode using
-.B LIRC_SET_WIDEBAND_RECEIVER
+.BR LIRC_SET_WIDEBAND_RECEIVER
 .TP 8
-.B LIRC_CAN_NOTIFY_DECODE
-Driver supports LIRC_NOTIFY_DECODE.
+.BR LIRC_CAN_NOTIFY_DECODE
+Driver supports
+.BR LIRC_NOTIFY_DECODE.
 .TP 8
-.B LIRC_CAN_SEND_RAW
+.BR LIRC_CAN_SEND_RAW
 Driver supports sending using
-.B LIRC_SEND_RAW
+.BR LIRC_SEND_RAW
 .TP 8
-.B LIRC_CAN_SEND_PULSE
+.BR LIRC_CAN_SEND_PULSE
 Driver supports sending using
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 .TP 8
-.B LIRC_CAN_SEND_MODE2
+.BR LIRC_CAN_SEND_MODE2
 Driver supports sending using
-.B LIRC_SEND_MODE2
+.BR LIRC_SEND_MODE2
 .TP 8
-.B LIRC_CAN_SEND_LIRCCODE
+.BR LIRC_CAN_SEND_LIRCCODE
 Driver supports sending
-.B LIRC_SEND_LIRCCODE
+.BR LIRC_SEND_LIRCCODE
 (this is uncommon, since
-.B LIRCCODE
-drivers reflects hardware like TV-cards which usually does not support
+.BR LIRCCODE
+drivers reflect hardware like TV-cards which usually does not support
 sending.)
 

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 384

Quoted 8 lines

doc/man-source/lirc.4 +2 -4

 .SH BUGS
 .P
-Using these devices requires the kernel source header file lirc.h. That this
-file is not public is a bug, see
-https://bugzilla.kernel.org/show_bug.cgi?id=75751. For the time being the
-file is bundled in the lirc package, see http://www.lirc.org.
+Using these devices requires the kernel source header file lirc.h.
+That this file is not public is a bug, see

doc/man-source/lirc.4 This might be useful of receivers that have otherwise narrow band receiver · line 389

Quoted 5 lines

doc/man-source/lirc.4 +3 -0

+https://bugzilla.kernel.org/show_bug.cgi?id=75751.
+For the time being the file is bundled in the lirc package,
+see http://www.lirc.org.
 .P
 This manual page should really be part of the upstream man-pages project.

Thanks,

Michael.

Quoted 7 lines · Michael Kerrisk (man-pages)

Hello Alec,

Quoted 2 lines · Alec Leamas

On Fri, 11 Dec 2015 20:16:00 +0100
"Michael Kerrisk (man-pages)" <[email protected]> wrote:

[Excellent walk though of fixes snipped]

Quoted 5 lines

Quoted 2 lines

Revised patch:

Patches on top of patches is confusing. For the next round, just send a fresh complete patch. A few more comments below.

Quoted 4 lines

Quoted 2 lines

+Drivers for this kind of hardware work in
.B LIRC_MODE_LIRCCODE.

.BR LIRC_MODE_LIRCCODE .

Quoted 3 lines

.BR LIRC_MODE_MODE2 .

(i.e., add space before '.') Probably there are other instances to fix as well.

Quoted 1 line

Quoted 1 line

.SH Reading using LIRC_MODE_MODE2 drivers

s/using/input with the/

Quoted 3 lines

Quoted 1 line

+.IR lirc_t.

.IR lirc_t .

Quoted 5 lines

Quoted 2 lines

-Value reflects a pulse duration (us).
+.BR LIRC_MODE2_PULSE

s/$/ ./
(And at various other places below.)

s/below/above and below/

Quoted 11 lines

Quoted 11 lines

+Value reflects a pulse duration (microseconds).
.TP 4
-.B LIRC_MODE2_FREQUENCY
+.BR LIRC_MODE2_FREQUENCY
Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl. .TP 4
-.B LIRC_MODE2_TIMEOUT
+.BR LIRC_MODE2_TIMEOUT
The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

Quoted 4 lines

Quoted 1 line

.SH Reading using LIRC_MODE_LIRCCODE drivers.

s/.$//

s/using/input with the/

s/read() on the device must be done/Device input must be read/

Quoted 3 lines

s/the driver/the write() call/

Start new sentence on new line.

Quoted 10 lines

Quoted 2 lines

returns

s/returns/fails with the error/

Quoted 2 lines

-.B EINVAL
+.BR EINVAL

.BR EINVAL .

Quoted 5 lines

Quoted 1 line

Many require a third argument, usually an int.

Put the"int" on a separate line as

.IR int .

Quoted 7 lines

Review the device can rely on working with the default settings initially. · line 117

Quoted 7 lines

(quoted diff) +1 -1

@@ -88,111 +114,117 @@ the device can rely on working with the default settings initially.
 .P
 \fI/dev/lirc*\fR devices always supports the following commands:
 .TP 4
-.B LIRC_GET_FEATURES void
+.BR LIRC_GET_FEATURES void

Why? (and others below)

Quoted 3 lines

Review the device can rely on working with the default settings initially. · line 118

Quoted 1 line

(quoted diff) +0 -0

 Driver returns integer values, each of which representing a decoded button

s/representing/represents/

Quoted 1 line

Review the device can rely on working with the default settings initially. · line 119

Quoted 1 line

(quoted diff) +1 -0

+If a device returns an error code  for

s/ for/ for/

Quoted 10 lines

Review the device can rely on working with the default settings initially. · line 120

Quoted 1 line

(quoted diff) +1 -0

+.BR LIRC_GET_REC_MODE

s/$/ ,/

Review the device can rely on working with the default settings initially. · line 123

Quoted 3 lines

(quoted diff) +0 -0

 it is safe to assume it is not a lirc device.
 
 .BR

Remove that last line.

Quoted 6 lines

Review the device can rely on working with the default settings initially. · line 126

Quoted 4 lines

(quoted diff) +1 -0

 .SH Optional Commands
 .Ped.
+Some lirc devices supports the following commands.

s/supports/supports/

s/supports/support/

Quoted 9 lines

Review the device can rely on working with the default settings initially. · line 127

Quoted 2 lines

(quoted diff) +1 -0

+Unless otherwise stated these returns \fIENOIOCTLCMD\fR

s/returns/fail with the error/

Review the device can rely on working with the default settings initially. · line 129

Quoted 2 lines

(quoted diff) +2 -0

+or \fIENOSYS\fR if the operation
+isn't supported and \fIEINVAL\fR if operation failed.

s/and/or with the error/

s/ and/, or with the error/

Quoted 1 line

s/operation/the operation/

Quoted 4 lines

Review the device can rely on working with the default settings initially. · line 132

Quoted 4 lines

(quoted diff) +1 -1

 .TP
-.B LIRC_GET_LENGTH " (\fIvoid\fP)"
+.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
 Return the positive  length of the returned codes for

s/ length/ length/

Quoted 2 lines

Quoted 2 lines

(quoted diff) +1 -1

-.B LIRC_LIRCCODE
+.BR LIRC_LIRCCODE

Quoted 4 lines

Review the device can rely on working with the default settings initially. · line 135

Quoted 2 lines

(quoted diff) +0 -0

 type
 drivers, otherwise

s/$/ fail with the error/

Quoted 4 lines

Review the device can rely on working with the default settings initially. · line 136

Quoted 2 lines

(quoted diff) +1 -1

-.B LIRC_GET_MAX_TIMEOUT.
+.BR LIRC_GET_MAX_TIMEOUT.

s/.$/ .$/

Quoted 2 lines

Review the device can rely on working with the default settings initially. · line 138

Quoted 2 lines

(quoted diff) +0 -0

 Some receivers are equipped with special wide band receiver which is
 intended to be used to learn output of existing remote.

s/receivers/devices/
s/receiver which is/receivers which are/
s/output/the output/
s/existing/an existing/

Quoted 2 lines

Review This might be useful of receivers that have otherwise narrow band receiver

Quoted 2 lines

(quoted diff) +0 -0

 Calling that ioctl with (1) will enable it, and with (0) disable it.

@@ -223,123 +255,136 @@ This might be useful of receivers that have otherwise narrow band receiver

s/useful of receivers/useful for devices/
s/have otherwise/otherwise have/
s/receiver/receivers/

Quoted 2 lines

Review This might be useful of receivers that have otherwise narrow band receiver · line 255

Quoted 2 lines

(quoted diff) +0 -0

 that prevents them to be used with some remotes.

which prevent them from being used with certain remotes.

Quoted 1 line

Review This might be useful of receivers that have otherwise narrow band receiver · line 256

Quoted 1 line

(quoted diff) +0 -0

 Wide band receiver might also be more precise.

s/receiver/receivers/
s/might/may/

Quoted 8 lines

Review This might be useful of receivers that have otherwise narrow band receiver · line 262

Quoted 8 lines

(quoted diff) +1 -1

 On the other hand its disadvantage usually is reduced range of reception.
-Note: wide band receiver might be implictly enabled if you enable
+Note: wide band receiver might be implicitly enabled if you enable
 carrier reports.
 In that case it will be disabled as soon as you disable carrier reports.
 Trying to disable wide band receiver while carrier reports are active will
 do nothing

s/wide/a wide/
s/$/.$/

Quoted 6 lines

Review This might be useful of receivers that have otherwise narrow band receiver · line 266

Quoted 6 lines

(quoted diff) +1 -1

 .TP
-.B LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
+.BR LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
 Setting of several driver parameters can be optimized by encapsulating
 the according ioctl calls with

does 'according' make sense here? accompanying?

Quoted 3 lines

Review This might be useful of receivers that have otherwise narrow band receiver · line 267

Quoted 3 lines

(quoted diff) +1 -0

+for example by flashing a LED.

s/a/an/

Quoted 4 lines

Review This might be useful of receivers that have otherwise narrow band receiver · line 268

Quoted 1 line

(quoted diff) +1 -0

+.BR LIRC_MODE_RAW

s/$/ ./
(And other instances below)

Quoted 1 line

Review This might be useful of receivers that have otherwise narrow band receiver · line 269

Quoted 1 line

(quoted diff) +1 -0

+That this file is not public is a bug, see

This file not being public is a bug, see

Quoted 3 lines

.SH Reading using LIRC_MODE_MODE2 drivers

s/using/input with the/

Quoted 2 lines

read() on the device must be done in blocks matching
the bit count, rounded up so it matches full bytes.

s/read() on the device must be done/Device input must be read/

Driver returns integer values, each of which representing a decoded

s/representing/represents/

Quoted 1 line

+If a device returns an error code for

s/ for/ for/

Quoted 1 line

+Some lirc devices supports the following commands.

s/supports/support/

Unless otherwise stated these returns \fIENOIOCTLCMD\fR>

s/returns/fail with the error/

Quoted 1 line

Return the positive length of the returned codes for

s/ length/ length/

Quoted 2 lines

Some receivers are equipped with special wide band receiver which is intended to be used to learn output of existing remote.

s/receivers/devices/
s/receiver which is/receivers which are/
s/output/the output/
s/existing/an existing/

Review This might be useful of receivers that have

Quoted 2 lines

Calling that ioctl with (1) will enable it, and with (0) disable it.

(quoted diff) +0 -0

@@ -223,123 +255,136 @@ This might be useful of receivers that have

s/useful of receivers/useful for devices/
s/have otherwise/otherwise have/
s/receiver/receivers/

Review This might be useful of receivers that have · line 255

Quoted 1 line

(quoted diff) +0 -0

 that prevents them to be used with some remotes.

which prevent them from being used with certain remotes.

Quoted 1 line

Wide band receiver might also be more precise.

s/receiver/receivers/
s/might/may/

Quoted 1 line

Trying to disable wide band receiver while carrier reports are active

Quoted 1 line

do nothing

s/wide/a wide/
s/$/.$/

Quoted 2 lines

etting of several driver parameters can be optimized by encapsulating
the according ioctl calls with

does 'according' make sense here? accompanying?

Review

Quoted 2 lines

(quoted diff) +1 -1

-to give visual user feedback e.g.,  by flashing a LED.
+incoming IR signal could be done.

s/could be done/is possible/

Quoted 1 line

or example by flashing a LED.

s/a/an/

Quoted 1 line

+That this file is not public is a bug, see

This file not being public is a bug, see

From 0864603b5f912be5e9b43dc690b313e1ba83b0f5 Mon Sep 17 00:00:00 2001

Quoted 4 lines

Quoted 4 lines

Quoted 1 line

Revised patch:

Patches on top of patches is confusing. For the next round, just send a fresh complete patch. A few more comments below.

Indeed, and that's what I thought I did...

Quoted 4 lines

Quoted 4 lines

Quoted 2 lines

+Drivers for this kind of hardware work in
.B LIRC_MODE_LIRCCODE.

.BR LIRC_MODE_LIRCCODE .

All '^\.B ' fixed

Quoted 3 lines

Quoted 3 lines

.BR LIRC_MODE_MODE2 .

(i.e., add space before '.') Probably there are other instances to fix as well.

Hopefully found and fixed them all.

New patch (hopefully in better shape...)

Quoted 1 line

From 0864603b5f912be5e9b43dc690b313e1ba83b0f5 Mon Sep 17 00:00:00 2001

From: Alec Leamas <[email protected]>
Date: Mon, 14 Dec 2015 10:47:08 +0100
Subject: [PATCH] Adding new lirc.4 manpage

---
 doc/man-source/lirc.4 | 396
++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 396 insertions(+)
 create mode 100644 doc/man-source/lirc.4

doc/man-source/lirc.4 new file +40 -0

new file mode 100644
index 0000000..f468364
@@ -0,0 +1,396 @@
+.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual"
+
+
+.\" Copyright (c) 2015, Alec Leamas
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.SH NAME
+lirc \- lirc devices
+.SH DESCRIPTION
+.P
+\fB/dev/lirc*\fR are character devices providing a low-level
+bi-directional interface to infra-red (IR) remotes.
+When receiving data, the driver works in two different modes depending
+on the underlying hardware.
+.P
+Some hardware (typically TV-cards) decodes the IR signal internally
+and just provides decoded button presses as integer values.
+Drivers for this kind of hardware work in
+.BR LIRC_MODE_LIRCCODE .
+Such hardware usually does not support sending IR signals.
+Furthermore, it usually only works with a specific remote which is

doc/man-source/lirc.4 new file +5 -0

+describes the pulse width in percent of the total cycle.
+Currently, no special meaning is defined for 0 or 100, but the values
+are reserved for future use.
+.TP
+.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", LIRC_GET_MAX_TIMEOUT "

(\fIvoid\fP)"

+Some devices have a fixed timeout, in that case

+.TP
+.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Sets the integer value for IR inactivity timeout.

doc/man-source/lirc.4 new file +4 -0

+If enabled, from the next key press on, the driver will send
+.BR LIRC_MODE2_FREQUENCY
+packets. By default this should be turned off.
+.TP

+config file.
+.TP
+.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)",
LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
+See
+.BR LIRC_GET_MIN_FILTER_PULSE

+.TP
+.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
+Some devices are equipped with special wide band receiver which are

doc/man-source/lirc.4 new file +4 -0

+Note: wide band receiver may be implicitly enabled if you enable
+carrier reports.
+In that case it will be disabled as soon as you disable carrier reports.
+Trying to disable a wide band receiver while carrier reports are active

will

doc/man-source/lirc.4 new file +13 -0

+do nothing.
+
+.TP
+.BR LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)"
+Setting of several driver parameters can be optimized by encapsulating
+the actual ioctl calls with
+.BR LIRC_SETUP_START/LIRC_SETUP_END .
+When a driver receives a
+.BR LIRC_SETUP_START
+ioctl it can choose to not commit further setting changes to the hardware
+until a
+.BR LIRC_SETUP_END
+is received.

+incoming IR signal is possible..

doc/man-source/lirc.4 new file +25 -0

+This can be used by supporting hardware to give visual user feedback,
+for example by flashing an LED.
+
+.SH FEATURES
+.P
+The features returned by
+.BR LIRC_GET_FEATURES
+is a bitmask combining the following bits:
+.TP 8
+.BR LIRC_CAN_REC_RAW
+The driver is capable of receiving using
+.BR LIRC_MODE_RAW .
+.TP 8
+.BR LIRC_CAN_REC_PULSE
+The driver is capable of receiving using
+.BR LIRC_MODE_PULSE .
+.TP 8
+.BR LIRC_CAN_REC_MODE2
+The driver is capable of receiving using
+.BR LIRC_MODE_MODE2 .
+.TP 8
+.BR LIRC_CAN_REC_LIRCCODE
+The driver is capable of receiving using
+.BR LIRC_MODE_LIRCCODE .
+.TP 8

+.TP 8
+.BR LIRC_CAN_SET_REC_CARRIER_RANGE

doc/man-source/lirc.4 new file +46 -0

+Driver supports
+.BR LIRC_SET_REC_CARRIER_RANGE
+.TP 8
+.BR LIRC_CAN_GET_REC_RESOLUTION
+Driver supports
+.BR LIRC_GET_REC_RESOLUTION
+.TP 8
+.BR LIRC_CAN_SET_REC_TIMEOUT
+Driver supports
+.BR LIRC_SET_REC_TIMEOUT
+.TP 8
+.BR LIRC_CAN_SET_REC_FILTER
+Driver supports
+.BR LIRC_SET_REC_FILTER
+.TP 8
+.BR LIRC_CAN_MEASURE_CARRIER
+Driver supports measuring of the modulation frequency using
+.BR LIRC_MEASURE_CARRIER
+.TP 8
+.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
+Driver supports learning mode using
+.BR LIRC_SET_WIDEBAND_RECEIVER
+.TP 8
+.BR LIRC_CAN_NOTIFY_DECODE
+Driver supports
+.BR LIRC_NOTIFY_DECODE .
+.TP 8
+.BR LIRC_CAN_SEND_RAW
+Driver supports sending using
+.BR LIRC_SEND_RAW
+.TP 8
+.BR LIRC_CAN_SEND_PULSE
+Driver supports sending using
+.BR LIRC_MODE_PULSE
+.TP 8
+.BR LIRC_CAN_SEND_MODE2
+Driver supports sending using
+.BR LIRC_SEND_MODE2
+.TP 8
+.BR LIRC_CAN_SEND_LIRCCODE
+Driver supports sending
+.BR LIRC_SEND_LIRCCODE
+(this is uncommon, since
+.BR LIRCCODE
+drivers reflect hardware like TV-cards which usually does not support
+sending.)

Hello Alec,

Thanks, better, but your mailer is still wrapping patches...

Quoted 1 line

+The \fBLIRC_GET_REC_MODE\fR ioctl allows probing for the mode.

s/ioctl/ioctl (described below)/

Quoted 1 line

+In the \fBLIRC_MODE_MODE2 mode\fR, the driver read() provides 32-bit values

s/ mode\fR/\fR mode/

Change "the driver read() provides" to

[[
the data returned by
.BR read (2)
consists of
]]

Quoted 2 lines

+.BR LIRC_MODE2_FREQUENCY .
+Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl.

Constants should generally always be bolded, so:

.B LIRC_SET_MEASURE_CARRIER

Various other places need fixing below.

Quoted 1 line

+.SH Reading input with the LIRC_MODE_LIRCCODE drivers

For all of the ".SH" lines that use lower-case titles, change ".SH" to ".SS".

(Many instances to change below.)

Review

Quoted 3 lines

+.P

(quoted diff) +2 -0

+In the \fBLIRC_MODE_LIRCCODE\fR
+mode, the data returned by read() reflects decoded

.BR read (2)

Review

Quoted 2 lines

(quoted diff) +2 -0

+the \fBLIRC_GET_LENGTH\fR ioctl.
+Device must be read in blocks matching

s/Device must be read/Reads must be/

Quoted 1 line

+the bit count, rounded up so it matches full bytes.

What bit count is this? This needs clarifying.

Quoted 1 line

+.SH Sending data.

s/.$//

Review

Quoted 4 lines

+.P

(quoted diff) +3 -0

+When sending data, only the \fBLIRC_MODE_PULSE\fR
+mode is supported.
+The data written to the character device using write() is a pulse/space

.BR write (2)

Review

Quoted 3 lines

(quoted diff) +3 -0

+The data must start and end with a pulse, thus it must always include an
+odd number of samples.
+The write() function blocks until the data has been transmitted by the

Change "The write() function" to

[[
A
.BR write (2)
]]

Review

Quoted 2 lines

(quoted diff) +2 -0

+hardware.
+If more data is provided than the hardware can send, the write() call

.BR write (2)

Quoted 2 lines

+.nf
+#include " (\fIuapi/lirc.h\fP)"

So, presumably this is not the correct path, as noted in BUGS. Where does the "lirc" package put it? Use that path here, and write:

#include <path.h> /* But see BUGS */

Review

Quoted 4 lines

(quoted diff) +4 -0

+The following ioctls can be used to probe or change specific lirc
+hardware settings.
+Many require a third argument, usually an
+.IR int .

Replace last line with

[[
.IR int ,
referred to below as
.I val .
]]

Quoted 2 lines

+.P
+\fI/dev/lirc*\fR devices always supports the following commands:

s/supports/support/

Quoted 3 lines

+.TP 4
+.BR LIRC_GET_FEATURES void

s/void/" (\fIvoid\fP)"

Review

Quoted 5 lines

(quoted diff) +5 -0

+Returns a bitmask of combined features bits, see FEATURES.
+Some drivers have dynamic features which are not updated until after
+an init() command.
+.TP 4
+.BR LIRC_GET_REC_MODE void

s/void/" (\fIvoid\fP)"

Quoted 1 line

+Returns the receive mode, one of

a/one of/which will be one of:/

Quoted 1 line

+Driver return a sequence of pulse/space durations.

s/return/returns

Quoted 3 lines

+.P
+If a device returns an error code for
+.BR LIRC_GET_REC_MODE

s/$/ ,/

Review

Quoted 5 lines

(quoted diff) +5 -0

+it is safe to assume it is not a lirc device.
+
+.SH Optional Commands
+.P
+Some lirc devices support the following commands.

s/following commands/commands listed below/

Quoted 2 lines

+Unless otherwise stated these fails with the error \fIENOIOCTLCMD\fR

s/stated/stated,/
s/fails/fail/

Formatting of ENOIOCTLCMD should be \fB, not \fI

Quoted 1 line

+or with the error\fIENOSYS\fR if the operation

s/error/error /

\fI ==> \fB

Quoted 1 line

+isn't supported, or with the error \fIEINVAL\fR if the operation failed.

\fI ==> \fB

Quoted 3 lines

+.TP
+.BR LIRC_SET_REC_MODE " (\fIint\fP)"
+Set the receive mode, either

Change ", either" to

[[
;
.IR val
is either
]]

Quoted 3 lines

+.TP
+.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
+Return the positive length of the returned codes for

s/positive //

Review

Quoted 3 lines

+.BR LIRC_SET_SEND_MODE " (\fIint\fP)"

(quoted diff) +2 -0

+Set the send mode.
+Obsolete since only

I think the word "Obsolete" isn't right here. Change to "Currently serves no purpose"?

Quoted 3 lines

+.TP
+.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"

Formatting problems here.

Make these last two (wrapped) lines:

+.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP), " LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"

The same kind of change is required at various points below where you put two constants on one line after .TP

Review

Quoted 3 lines

(quoted diff) +3 -0

+Some devices have internal timers that can be used to detect when
+there's no IR activity for a long time.
+This can help lircd in detecting that a IR signal is finished and

.BR lircd >
s/a IR/an IR/(8)

Review

Quoted 3 lines

(quoted diff) +3 -0

+can speed up the decoding process.
+Returns an integer value with the minimum/maximum timeout that can be
+set.

Note the unit that is used here for measuring the timeout. Microseconds?

Quoted 1 line

+Some devices have a fixed timeout, in that case

s/, in that case/. For such drivers,/

Quoted 2 lines

+.BR LIRC_GET_MAX_TIMEOUT
+will return the same value even though the timeout cannot be changed.

s/ even though the timeout cannot be changed//

Quoted 3 lines

+.TP
+.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Sets the integer value for IR inactivity timeout.

It seems to me that the unit of measurement for this timeout should be specified. Is it microseconds? Make it explicit.

Quoted 2 lines

+.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
+Enables/disables (1/0) timeout packages in

Change that last line to

[[
Enables
.RI ( val
is 1) or disables
.RI (val is
0) timeout packages in
]]

Review

Quoted 10 lines

+.BR LIRC_MODE_MODE2 .

(quoted diff) +8 -0

+By default, timeout reports should be turned off.
+.TP
+.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
+Set the receive carrier frequency (Hz).
+.TP
+.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
+First time called sets the lower bound of the carrier range, second time
+the upper bound (Hz).

Really? What an odd API!

But this sentence could be clearer. "First time called"... since when? System boot? Open of the device? Make it explicit. Also, I'd word something like

After [some explicit point in time], the first use of
.BR LIRC_SET_REC_CARRIER_RANGE
sets the lower bound of the carrier range, and the second use sets the upper bound (hz).

Quoted 1 line

+the upper bound (Hz).

Quoted 3 lines

+.TP
+.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
+Enable/disable (1/0) the measure mode.

[[
Enables
.RI ( val
is 1) or disables
.RI (val is
0) the measure mode
]]

Quoted 3 lines

+lircd derives the settings from all protocols definitions found in its

.BR lircd (8)

Quoted 2 lines

+See
+.BR LIRC_GET_MIN_FILTER_PULSE

s/$/ ./

Review

Quoted 3 lines

(quoted diff) +3 -0

+ioctls must return an error and
+.BR LIRC_SET_REC_FILTER
+shall be used instead.

s/shall/should/ (I think).

Quoted 1 line

+Some devices are equipped with special wide band receiver which are

s/special/a special/

Review

Quoted 3 lines

(quoted diff) +2 -0

+intended to be used to learn the output of an existing remote.
+Calling that ioctl with (1) will enable it, and with (0) disable it.

Better for the last sentence would I think be:

[[
This ioctl can be used to enable
.RI ( val
equals 1) or disable
.RI ( val
equals 0) this functionality.

Review

Quoted 5 lines

(quoted diff) +4 -0

+This might be useful for devices that otherwise have narrow band receivers
+that prevent them to be used with certain remotes.
+Wide band receivers may also be more precise.
+On the other hand its disadvantage usually is reduced range of reception.

Insert a ".IP" line here

Quoted 1 line

+This ioctl is called by lircd whenever a successful decoding of an

.BR lircd (8)

Quoted 1 line

+incoming IR signal is possible..

s/..$/./

Quoted 2 lines

+.BR LIRC_CAN_SET_TRANSMITTER_MASK
+Enables the given set of transmitters.

I don't understand that last sentence. this bit mask is being used to return some information to us. How can it be enabling something. Should this be something like:

Quoted 4 lines

+.TP 8
+.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
+Driver supports
+.BR LIRC_SET_REC_DUTY_CYCLE_RANGE

s/$/ ./
(And various cases below)

Quoted 1 line

+This manual page should really be part of the upstream man-pages project.

You can remove that last line. It will soon cease to be true ;-).

From 46308403b9cbd2286078934c697a38937fbe4b1f Mon Sep 17 00:00:00 2001

Revised patch below. In case of troubles, a fresh copy is available at
http://paste.fedoraproject.org/300732/45011842

Hi Alec,

Quoted 2 lines

Revised patch below. In case of troubles, a fresh copy is available at
http://paste.fedoraproject.org/300732/45011842

The version inline, and at that URL seems to be an old version of the page where the fixes just discussed have not been made....

From 5c3191b29a81e202ecc59e967cb2c508ece3e855 Mon Sep 17 00:00:00 2001