Package: python3-json-pointer
Version: 2.4-4
Severity: minor
Tags: patch

Dear Maintainer,

AI disclosure: I prepared this assisted by Claude Opus 5.5.

python3-json-pointer ships /usr/bin/jsonpointer without a
corresponding manpage, which violates Debian Policy 12.1.

I have attached jsonpointer.1 which fixes this, and the source
debdiff. I will follow up with an MR with these changes.

Note that the changelog says #TBD, as this bug was not filed
yet; the MR will use this bug's number.

Note that the manpage differs from the output of `--help` and
the upstream docs: the upstream docs are stale and describe
`jsonpointer` v1.x, while I found some discrepancies between
what `--help` describes and the tool's actual behavior, e.g.
`-f` actually requires a file, it is not optional.

Upstream version 3.x fixes a lot of these issues; the BUGS
section in the manpage describes the issues I found.


-- System Information:
Debian Release: forky/sid
  APT prefers testing
  APT policy: (500, 'testing'), (100, 'unstable')
Architecture: arm64 (aarch64)

Kernel: Linux 7.2.15+deb14-arm64 (SMP w/4 CPU threads; PREEMPT)
Locale: LANG=en_IE.UTF-8, LC_CTYPE=en_IE.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_IE:en
Shell: /bin/sh linked to /usr/bin/dash
Init: unable to detect

Versions of packages python3-json-pointer depends on:
ii  python3  3.14.7-3

python3-json-pointer recommends no packages.

python3-json-pointer suggests no packages.

-- no debconf information
.TH JSONPOINTER 1 2026-11-13
.SH NAME
jsonpointer \- resolve a JSON pointer on JSON files
.SH SYNOPSIS
.SY jsonpointer
.RB [ \-h ]
.RB [ "\-\-indent\~\fIINDENT\fP" ]
.RB [ \-v ]
(\fB\-f\fP\~\fIPOINTER_FILE\fP | \fIPOINTER\fP) \fIFILE\fP [\fIFILE\fP ...]
.YS
.SH DESCRIPTION
\fBjsonpointer\fR resolves a JSON \fIPOINTER\fR, passed as a positional 
argument or as a \fIPOINTER_FILE\fR, on JSON \fIFILE\fRs.
If \fB\-\fR is passed in for \fIFILE\fP,
it is interpreted as stdin.
For each input \fIFILE\fR, the referenced JSON value is printed.
Errors are printed on stderr.
For more on JSON pointers, see
.UR https://www.rfc-editor.org/rfc/rfc6901
RFC 6901
.UE .
.
.SH OPTIONS
.TP
\fB\-h\fR,\~\fB\-\-help\fR
Show usage information.
.TP
\fB\-f\fR,\~\fB\-\-pointer\-file\fR \fIPOINTER_FILE\fR
File containing a JSON pointer expression.
Use \fB\-\fR to read the expression from stdin.
.TP
\fB\-\-indent\fR\~\fIINDENT\fR
If not set, the output is printed compactly on one line.
If set, each nested object or array element is printed on a new line,
indented \fIINDENT\fR spaces more per level.
.TP
\fB\-v\fR,\~\fB\-\-version\fR
Show program's version number.
.
.SH "EXIT STATUS"
.TP
.B 0
No error reported.
See BUGS below for errors that go unreported.
.TP
.B 1
Execution was interrupted, or an error occurred.
.TP
.B 2
Usage error, such as:
.RS
.IP \(bu 2
an unknown option
.IP \(bu 2
a missing \fIFILE\fR
.IP \(bu 2
an unreadable \fIFILE\fR
.IP \(bu 2
\fB\-f\fR combined with two or more \fIFILE\fRs
.RE
.
.SH BUGS
.TP
A pointer does not resolve
This prints "Could not resolve pointer: ..."
but exits with status 0.
.TP
Using \fB\-f\fR with two or more \fIFILE\fRs
This throws an
"argument POINTER: not allowed with argument \-f/\-\-pointer\-file" error,
as the second \fIFILE\fR is taken as the \fIPOINTER\fR.
.IP
As a workaround, either pass the pointer as the \fIPOINTER\fR argument,
or run \fBjsonpointer\fR in a loop against one \fIFILE\fR at a time.
.TP
Pointer files containing trailing whitespace
If the pointer is read from a file, leading and trailing whitespace is stripped.
The pointer has to start with \fB/\fR so stripping leading whitespace
is fine, but stripping trailing whitespace from the last member name
could result in the wrong member being looked up.
.IP
As a workaround, pass such pointers using the \fIPOINTER\fR positional argument.
.
.SH EXAMPLES
Taking the document from stdin, and indexing into an array:
.P
.EX
$ echo \[aq]{"foo": ["a", "b", "c"]}\[aq] | jsonpointer /foo/1 \-
"b"
.EE
.P
Using the same pointer on multiple documents:
.P
.EX
# inspect JSON files
$ cat a.json
{ "a": [1, 2, 3] }
\&
$ cat b.json
{ "a": {"b": [1, 3, 4]}, "b": 1 }
\&
# resolve JSON pointer
$ jsonpointer /a a.json b.json
[1, 2, 3]
{"b": [1, 3, 4]}
\&
# now with indentation, and stdin for the pointer
# because of the bug we can only use one file
$ echo /a | jsonpointer \-\-indent 0 \-f \- a.json
[
1,
2,
3
]
$ jsonpointer \-\-indent 2 /a a.json
[
  1,
  2,
  3
]
.EE
.
.SH "SEE ALSO"
.BR jq (1)
diff -Nru python-json-pointer-2.4/debian/changelog 
python-json-pointer-2.4/debian/changelog
--- python-json-pointer-2.4/debian/changelog    2026-02-10 11:58:54.000000000 
+0000
+++ python-json-pointer-2.4/debian/changelog    2026-11-13 19:58:38.000000000 
+0000
@@ -1,3 +1,9 @@
+python-json-pointer (2.4-5) UNRELEASED; urgency=medium
+
+  * Add manpage for jsonpointer (Closes: #TBD)
+
+ -- Michel Lind <[email protected]>  Fri, 13 Nov 2026 19:58:38 +0000
+
 python-json-pointer (2.4-4) unstable; urgency=medium
 
   * Cleans better (Closes: #1046832).
diff -Nru python-json-pointer-2.4/debian/jsonpointer.1 
python-json-pointer-2.4/debian/jsonpointer.1
--- python-json-pointer-2.4/debian/jsonpointer.1        1970-01-01 
01:00:00.000000000 +0100
+++ python-json-pointer-2.4/debian/jsonpointer.1        2026-11-13 
19:54:19.000000000 +0000
@@ -0,0 +1,123 @@
+.TH JSONPOINTER 1 2026-11-13
+.SH NAME
+jsonpointer \- resolve a JSON pointer on JSON files
+.SH SYNOPSIS
+.SY jsonpointer
+.RB [ \-h ]
+.RB [ "\-\-indent\~\fIINDENT\fP" ]
+.RB [ \-v ]
+(\fB\-f\fP\~\fIPOINTER_FILE\fP | \fIPOINTER\fP) \fIFILE\fP [\fIFILE\fP ...]
+.YS
+.SH DESCRIPTION
+\fBjsonpointer\fR resolves a JSON \fIPOINTER\fR, passed as a positional 
argument or as a \fIPOINTER_FILE\fR, on JSON \fIFILE\fRs.
+If \fB\-\fR is passed in for \fIFILE\fP,
+it is interpreted as stdin.
+For each input \fIFILE\fR, the referenced JSON value is printed.
+Errors are printed on stderr.
+For more on JSON pointers, see
+.UR https://www.rfc-editor.org/rfc/rfc6901
+RFC 6901
+.UE .
+.
+.SH OPTIONS
+.TP
+\fB\-h\fR,\~\fB\-\-help\fR
+Show usage information.
+.TP
+\fB\-f\fR,\~\fB\-\-pointer\-file\fR \fIPOINTER_FILE\fR
+File containing a JSON pointer expression.
+Use \fB\-\fR to read the expression from stdin.
+.TP
+\fB\-\-indent\fR\~\fIINDENT\fR
+If not set, the output is printed compactly on one line.
+If set, each nested object or array element is printed on a new line,
+indented \fIINDENT\fR spaces more per level.
+.TP
+\fB\-v\fR,\~\fB\-\-version\fR
+Show program's version number.
+.
+.SH "EXIT STATUS"
+.TP
+.B 0
+No error reported.
+See BUGS below for errors that go unreported.
+.TP
+.B 1
+Execution was interrupted, or an error occurred.
+.TP
+.B 2
+Usage error, such as:
+.RS
+.IP \(bu 2
+an unknown option
+.IP \(bu 2
+a missing \fIFILE\fR
+.IP \(bu 2
+an unreadable \fIFILE\fR
+.IP \(bu 2
+\fB\-f\fR combined with two or more \fIFILE\fRs
+.RE
+.
+.SH BUGS
+.TP
+A pointer does not resolve
+This prints "Could not resolve pointer: ..."
+but exits with status 0.
+.TP
+Using \fB\-f\fR with two or more \fIFILE\fRs
+This throws an
+"argument POINTER: not allowed with argument \-f/\-\-pointer\-file" error,
+as the second \fIFILE\fR is taken as the \fIPOINTER\fR.
+.IP
+As a workaround, either pass the pointer as the \fIPOINTER\fR argument,
+or run \fBjsonpointer\fR in a loop against one \fIFILE\fR at a time.
+.TP
+Pointer files containing trailing whitespace
+If the pointer is read from a file, leading and trailing whitespace is 
stripped.
+The pointer has to start with \fB/\fR so stripping leading whitespace
+is fine, but stripping trailing whitespace from the last member name
+could result in the wrong member being looked up.
+.IP
+As a workaround, pass such pointers using the \fIPOINTER\fR positional 
argument.
+.
+.SH EXAMPLES
+Taking the document from stdin, and indexing into an array:
+.P
+.EX
+$ echo \[aq]{"foo": ["a", "b", "c"]}\[aq] | jsonpointer /foo/1 \-
+"b"
+.EE
+.P
+Using the same pointer on multiple documents:
+.P
+.EX
+# inspect JSON files
+$ cat a.json
+{ "a": [1, 2, 3] }
+\&
+$ cat b.json
+{ "a": {"b": [1, 3, 4]}, "b": 1 }
+\&
+# resolve JSON pointer
+$ jsonpointer /a a.json b.json
+[1, 2, 3]
+{"b": [1, 3, 4]}
+\&
+# now with indentation, and stdin for the pointer
+# because of the bug we can only use one file
+$ echo /a | jsonpointer \-\-indent 0 \-f \- a.json
+[
+1,
+2,
+3
+]
+$ jsonpointer \-\-indent 2 /a a.json
+[
+  1,
+  2,
+  3
+]
+.EE
+.
+.SH "SEE ALSO"
+.BR jq (1)
diff -Nru python-json-pointer-2.4/debian/python3-json-pointer.manpages 
python-json-pointer-2.4/debian/python3-json-pointer.manpages
--- python-json-pointer-2.4/debian/python3-json-pointer.manpages        
1970-01-01 01:00:00.000000000 +0100
+++ python-json-pointer-2.4/debian/python3-json-pointer.manpages        
2026-11-13 19:56:11.000000000 +0000
@@ -0,0 +1 @@
+debian/jsonpointer.1

Reply via email to