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

