Bug#1100029: gdbus-codegen.1: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Mon Mar 10 12:45:36 GMT 2025
Package: libglib2.0-bin
Version: 2.83.4-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:31: warning: start (0) and end (0) index of substring out of range
an.tmac:<stdin>:31: warning: TH: second argument is not a numeric expression:
an.tmac:<stdin>:31: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:31: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
troff:<stdin>:31: warning: name 'an-extra3' not defined
an.tmac:<stdin>:31: style: .TH missing fifth argument and second argument '' not a recognized manual section; specify its title
an.tmac:<stdin>:145: style: 1 leading space(s) on input line
an.tmac:<stdin>:230: style: 1 leading space(s) on input line
an.tmac:<stdin>:240: style: 1 leading space(s) on input line
an.tmac:<stdin>:547: style: 1 leading space(s) on input line
an.tmac:<stdin>:628: style: 1 leading space(s) on input line
an.tmac:<stdin>:630: style: 1 leading space(s) on input line
troff:<stdin>:1: warning [page 9, line 41, diversion '3tbd2,2', line 6]: cannot break line
<stdin>:1: warning: table wider than line length minus indentation
an.tmac:<stdin>:840: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 1848u = 77n = 77m
an.tmac:<stdin>:996: style: 1 leading space(s) on input line
an.tmac:<stdin>:998: style: 1 leading space(s) on input line
an.tmac:<stdin>:1015: style: 1 leading space(s) on input line
troff:<stdin>:1015: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages libglib2.0-bin depends on:
ii libc6 2.40-7
ii libelf1t64 0.192-4
ii libglib2.0-0t64 2.83.4-1
ii libglib2.0-data 2.83.4-1
libglib2.0-bin recommends no packages.
libglib2.0-bin suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is gdbus-codegen.1
Output from "mandoc -T lint gdbus-codegen.1": (shortened list)
2 input text line longer than 80 bytes: (documentation <http...
[...]
1 missing date, using "": TH
12 skipping paragraph macro: sp after SH
2 skipping paragraph macro: sp after SS
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z gdbus-codegen.1": (shortened list)
1 .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 1848u = 77n = 77m
1 cannot break line
1 name 'an-extra3' not defined
1 start (0) and end (0) index of substring out of range
1 table wider than line length minus indentation
1 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Show if docman-to-man created this.
Who is actually creating this man page? Debian or upstream?
Is the generating software out of date?
55:[\-\-generate\-docbook \fIOUTFILES\fP]
78:header (via \fB\-\-header\fP) and DocBook XML (via \fB\-\-generate\-docbook\fP).
130:.SH GENERATING DOCBOOK DOCUMENTATION
132:Each generated DocBook XML file (see the \fB\-\-generate\-docbook\fP option for
134:DocBook documentation <https://tdg.docbook.org/tdg/4.5/refentry.html>
170:calculating the type name for the C binding and the DocBook \fBsortas\fP
171:attribute <https://tdg.docbook.org/tdg/4.5/primary.html>
176:\fB\-\-generate\-docbook\fP \fIOUTFILES\fP
179:Generate DocBook Documentation for each D\-Bus interface and put it in
285:Using \fB\-\-generate\-c\-code\fP, \fB\-\-generate\-docbook\fP or \fB\-\-output\-directory\fP
297:Using \fB\-\-generate\-c\-code\fP, \fB\-\-generate\-docbook\fP or \fB\-\-output\-directory\fP
310:Using \fB\-\-generate\-c\-code\fP, \fB\-\-generate\-docbook\fP or \fB\-\-output\-directory\fP
324:Using \fB\-\-generate\-c\-code\fP, \fB\-\-generate\-docbook\fP or \fB\-\-output\-directory\fP
380:Using \fB\-\-generate\-c\-code\fP, \fB\-\-generate\-docbook\fP or \fB\-\-output\-directory\fP
503:When generating DocBook XML, a deprecation warning will appear along the
518:When generating DocBook XML, the value of this tag appears in the
526:A string with DocBook content for documentation. This annotation can
535:A string with DocBook content for short/brief documentation. This annotation
627:parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>
629:constant <https://tdg.docbook.org/tdg/4.5/constant.html>
1002:While the generated DocBook for D\-Bus interfaces isn???t expected to change, no
-.-.
Show if generated from reStructuredText or rd2
Who is actually generating this man page? Debian or upstream?
Is the generating software out of date?
2:.\" Man page generated from reStructuredText.
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Reduce space between words.
[List of affected lines removed.]
-.-
Remove space in the first column, if not indented.
Use ".in +<number>n" and ".in" to end it; ".nf" and ".fi" to end
it, for an extra indention.
gdbus-codegen.1:145: document
gdbus-codegen.1:230: or \fIUgly_Case\fP (see
gdbus-codegen.1:240: preprocessor
gdbus-codegen.1:547: or \fIUgly_Case\fP (see
gdbus-codegen.1:628: and
gdbus-codegen.1:630: respectively.
gdbus-codegen.1:996: and
gdbus-codegen.1:998: comments and
gdbus-codegen.1:1015: <gdbus(1)>
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URL (web address)
74 D\-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>
493 D\-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>
878 (documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
959 (documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
-.-.
Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
181:name, e.g. \fBnet.Corp.FooBar\fP and so on.
193:name, e.g. \fBnet.Corp.FooBar\fP and so on.
205:name, e.g. \fBnet.Corp.FooBar\fP and so on.
619:Note that \fB at since\fP can be used in any inline documentation bit (e.g. for
890:\fBGObject\fP property from the subclass. To emit a signal, use e.g.
970:natural types, e.g. \fBgboolean\fP, \fBgdouble\fP, \fBgint\fP, \fBgchar*\fP, \fBgchar**\fP
1000:about e.g. \fBSECTION\fP usage etc. are given.
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Do not use more than two space characters between sentences or (better)
only a new line character.
668: \-\-interface\-prefix net.corp.MyApp. \e
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
1015: <gdbus(1)>
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).
878:(documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
959:(documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
-.-.
Use a character "\(->" instead of plain "->" or "\->".
585:\-\->
593: \-\->
606: \-\->
-.-.
No need for '\&' to be in front of a period (.),
if there is a character in front of it.
Remove with "sed -e 's/\\&\././g'".
81:using \fB\-\-interface\-info\-body\fP and \fB\-\-interface\-info\-header\fP\&.
108:interface \fBcom.acme.Coyote\fP the name used is \fBComAcmeCoyote\fP\&. For the D\-Bus
110:\fBorg.project.\fP, the name used is \fBBarFrobnicator\fP\&.
128:is \fBiscsi_target\fP\&. If the annotation is used on the method \fBEjectTheiPod\fP
129:with the value \fBEject_The_iPod\fP, the lower\-case form is \fBeject_the_ipod\fP\&.
218:including sub\-directories will be referenced from \fBOUTFILES.c\fP\&.
221:\fB$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}\fP\&.
262:but you should likely switch your project to use \fBall\fP\&.
283:disk by using the path and file name provided by \fB\-\-output\fP\&.
295:disk by using the path and file name provided by \fB\-\-output\fP\&.
308:the path and file name provided by \fB\-\-output\fP\&.
322:the path and file name provided by \fB\-\-output\fP\&.
335:prototypes in the generated header will be marked with \fBDECORATOR\fP\&. This can
337:\fBgdbus\-codegen\fP\&.
377:the path and filename provided by \fB\-\-output\fP\&. The full path could be
378:something like \fB$($OUTFILE).{c,h}\fP\&.
391:filename like \fBfoo\-impl.h\fP and \fB#include\fP it into a wrapper \fB\&.c\fP file.
398:it should be prefixed with \fB\&./\fP\&.
430:Any UTF\-8 string can be used for \fIKEY\fP and \fIVALUE\fP\&.
441:\fB\-\-glib\-min\-required\fP\&. If this option is not passed, the output from
452:be smaller than \fB2.30\fP\&.
464:using \fBg_dbus_proxy_call()\fP\&.
479:greater than or equal to that passed to \fB\-\-glib\-min\-required\fP\&.
480:It defaults to the version of GLib which provides this \fBgdbus\-codegen\fP\&.
492:is \fBtrue\fP\&. Note that this annotation is defined in the
495:and can only assume the values \fBtrue\fP and \fBfalse\fP\&. In particular, you
677:\fBSkeleton\fP\&. The generated file, roughly, contains the following facilities:
804:Use \fBMyAppFrobberProxy\fP\&.
814:Receive via the \fBhandle_hello_world()\fP signal handler. Complete the call with \fBm_a_f_complete_hello_world()\fP\&.
830:Implement the \fBget_property()\fP vfunc of \fBGObject\fP\&.
838:Implement the \fBset_property()\fP vfunc of \fBGObject\fP\&.
891:\fBmy_app_emit_signal()\fP or \fBg_signal_emit_by_name()\fP\&.
-.-.
One space only after a possible end of sentence
(after a punctuation, that
can end a sentence).
[List of affected lines removed.]
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
gdbus-codegen.1:31:.TH "GDBUS-CODEGEN" "" "" ""
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:31: warning: start (0) and end (0) index of substring out of range
an.tmac:<stdin>:31: warning: TH: second argument is not a numeric expression:
an.tmac:<stdin>:31: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:31: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
troff:<stdin>:31: warning: name 'an-extra3' not defined
an.tmac:<stdin>:31: style: .TH missing fifth argument and second argument '' not a recognized manual section; specify its title
an.tmac:<stdin>:145: style: 1 leading space(s) on input line
an.tmac:<stdin>:230: style: 1 leading space(s) on input line
an.tmac:<stdin>:240: style: 1 leading space(s) on input line
an.tmac:<stdin>:547: style: 1 leading space(s) on input line
an.tmac:<stdin>:628: style: 1 leading space(s) on input line
an.tmac:<stdin>:630: style: 1 leading space(s) on input line
troff:<stdin>:1: warning [page 9, line 41, diversion '3tbd2,2', line 6]: cannot break line
<stdin>:1: warning: table wider than line length minus indentation
an.tmac:<stdin>:840: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 1848u = 77n = 77m
an.tmac:<stdin>:996: style: 1 leading space(s) on input line
an.tmac:<stdin>:998: style: 1 leading space(s) on input line
an.tmac:<stdin>:1015: style: 1 leading space(s) on input line
troff:<stdin>:1015: warning: trailing space in the line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-------------- next part --------------
--- gdbus-codegen.1 2025-03-10 01:09:35.939026583 +0000
+++ gdbus-codegen.1.new 2025-03-10 12:39:50.530049112 +0000
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
-.TH "GDBUS-CODEGEN" "" "" ""
+.TH GDBUS-CODEGEN 1 "" ""
.SH NAME
gdbus-codegen \- D-Bus code and documentation generator
.\" This has to be duplicated from above to make it machine-readable by `reuse`:
@@ -47,7 +47,8 @@ gdbus-codegen \- D-Bus code and document
.in +2
[\-\-help]
[\-\-interface\-prefix \fIorg.project.Prefix\fP]
-[\-\-header | \-\-body | \-\-interface\-info\-header | \-\-interface\-info\-body | \-\-generate\-c\-code \fIOUTFILES\fP]
+[\-\-header | \-\-body | \-\-interface\-info\-header |
+\-\-interface\-info\-body | \-\-generate\-c\-code \fIOUTFILES\fP]
[\-\-c\-namespace \fIYourProject\fP]
[\-\-c\-generate\-object\-manager]
[\-\-c\-generate\-autocleanup none|objects|all]
@@ -57,7 +58,9 @@ gdbus-codegen \- D-Bus code and document
[\-\-generate\-rst \fIOUTFILES\fP]
[\-\-pragma\-once]
[\-\-xml\-files \fIFILE\fP]
-[\-\-symbol\-decorator \fIDECORATOR\fP [\-\-symbol\-decorator\-header \fIHEADER\fP] [\-\-symbol\-decorator\-define \fIDEFINE\fP]]
+[\-\-symbol\-decorator \fIDECORATOR\fP [\-\-symbol\-decorator\-header
+\fIHEADER\fP]
+[\-\-symbol\-decorator\-define \fIDEFINE\fP]]
[\-\-annotate \fIELEMENT\fP \fIKEY\fP \fIVALUE\fP]???
[\-\-glib\-min\-required \fIVERSION\fP]
[\-\-glib\-max\-allowed \fIVERSION\fP]
@@ -71,7 +74,8 @@ gdbus-codegen \- D-Bus code and document
D\-Bus interfaces.
.sp
\fBgdbus\-codegen\fP reads
-D\-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>
+D\-Bus Introspection XML
+<https://dbus.freedesktop.org/\:doc/\:dbus\-specification.html#\:introspection\-format>
from files passed as additional arguments on the command line and generates
output files. It currently supports generating C source code (via \fB\-\-body\fP) or
@@ -142,7 +146,7 @@ details) is a plain text Markdown docume
Each generated reStructuredText file (see the \fB\-\-generate\-rst\fP option for
details) is a plain text
reStructuredText <https://docutils.sourceforge.io/rst.html>
- document
+document
describing the D\-Bus interface.
.SH OPTIONS
.sp
@@ -227,7 +231,7 @@ The full paths would then be
.INDENT 3.5
The namespace to use for generated C code. This is expected to be in
CamelCase <https://en.wikipedia.org/wiki/Camel_case>
- or \fIUgly_Case\fP (see
+or \fIUgly_Case\fP (see
above).
.UNINDENT
.UNINDENT
@@ -237,7 +241,7 @@ above).
.INDENT 3.5
If this option is passed, the
#pragma once <https://en.wikipedia.org/wiki/Pragma_once>
- preprocessor
+preprocessor
directive is used instead of include guards.
.UNINDENT
.UNINDENT
@@ -490,7 +494,9 @@ The following D\-Bus annotations are sup
Can be used on any \fB<interface>\fP, \fB<method>\fP, \fB<signal>\fP and
\fB<property>\fP element to specify that the element is deprecated if its value
is \fBtrue\fP\&. Note that this annotation is defined in the
-D\-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>
+D\-Bus specification
+.br
+<https://dbus.freedesktop.org/\:doc/\:dbus-specification.html#\:introspection\-format>
and can only assume the values \fBtrue\fP and \fBfalse\fP\&. In particular, you
cannot specify the version that the element was deprecated in nor any helpful
@@ -544,7 +550,7 @@ Can be used on any \fB<interface>\fP, \f
\fB<property>\fP element to specify the name to use when generating C code. The
value is expected to be in
CamelCase <https://en.wikipedia.org/wiki/Camel_case>
- or \fIUgly_Case\fP (see
+or \fIUgly_Case\fP (see
above).
.UNINDENT
.UNINDENT
@@ -569,7 +575,7 @@ be used on \fB<method>\fP elements.
.sp
As an easier alternative to using the \fBorg.gtk.GDBus.DocString\fP annotation,
note that parser used by \fBgdbus\-codegen\fP parses XML comments in a way similar
-to gtk\-doc <https://gitlab.gnome.org/GNOME/gtk-doc/>
+to gtk\-doc <https://gitlab.gnome.org/GNOME/gtk\-doc/>
:
.INDENT 0.0
.INDENT 3.5
@@ -625,9 +631,9 @@ comments), note that substrings of the f
interface, method, signal and property. Additionally, substrings starting with
\fB@\fP and \fB%\fP characters are rendered as
parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>
- and
+and
constant <https://tdg.docbook.org/tdg/4.5/constant.html>
- respectively.
+respectively.
.sp
If both XML comments and \fBorg.gtk.GDBus.DocString\fP or
\fBorg.gtk.GDBus.DocString.Short\fP annotations are present, the latter wins.
@@ -788,8 +794,8 @@ functions are generated (one setter, one
The following table summarizes the generated facilities and where they are
applicable:
.TS
-box center;
-l|l|l.
+box ;
+L | L | L.
T{
Symbol type
T} T{
@@ -801,7 +807,7 @@ _
T{
Types
T} T{
-Use \fBMyAppFrobberProxy\fP\&.
+Use \fBMyAppFrobberProxy\fP.
T} T{
Any type implementing the \fBMyAppFrobber\fP interface.
T}
@@ -811,7 +817,8 @@ Methods
T} T{
Use \fBm_a_f_hello_world()\fP to call.
T} T{
-Receive via the \fBhandle_hello_world()\fP signal handler. Complete the call with \fBm_a_f_complete_hello_world()\fP\&.
+Receive via the \fBhandle_hello_\%world()\fP signal handler.
+Complete the call with \%\fBm_a_f_complete_\%hello_world()\fP.
T}
_
T{
@@ -819,23 +826,27 @@ Signals
T} T{
Connect to the \fB::notification\fP signal.
T} T{
-Use \fBm_a_f_emit_notification()\fP to emit signal.
+Use \fBm_a_f_emit_\%notification()\fP to emit signal.
T}
_
T{
-Properties (Reading)
+Properties
+.br
+(Reading)
T} T{
Use \fBm_a_f_get_verbose()\fP or the \fB:verbose\fP property.
T} T{
-Implement the \fBget_property()\fP vfunc of \fBGObject\fP\&.
+Implement the \fBget_property()\fP vfunc of \fBGObject\fP.
T}
_
T{
-Properties (writing)
+Properties
+.br
+(writing)
T} T{
Use \fBm_a_f_set_verbose()\fP or the \fB:verbose\fP property.
T} T{
-Implement the \fBset_property()\fP vfunc of \fBGObject\fP\&.
+Implement the \fBset_property()\fP vfunc of \fBGObject\fP.
T}
.TE
.SS Client\-side usage
@@ -875,7 +886,9 @@ listen to property changes.
Note that all property access is via the \fBGDBusProxy\fP property cache so no I/O
is ever done when reading properties. Also note that setting a property will
cause the \fBorg.freedesktop.DBus.Properties.Set\fP method
-(documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
+(documentation
+.br
+<https://dbus.freedesktop.org/\:doc/\:dbus\-specification.html#standard\-interfaces\-properties>
)
to be called on the remote object. This call, however, is asynchronous so
setting a property won???t block. Further, the change is delayed and no error
@@ -940,10 +953,11 @@ on_handle_hello_world (MyAppFrobber
[???]
error = NULL;
- if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
- connection,
- \(dq/path/of/dbus_object\(dq,
- &error))
+ if (!g_dbus_interface_skeleton_export
+ (G_DBUS_INTERFACE_SKELETON (interface),
+ connection,
+ \(dq/path/of/dbus_object\(dq,
+ &error))
{
/* handle error */
}
@@ -956,7 +970,9 @@ To facilitate atomic changesets (multipl
an idle handler (which is called from the thread\-default main loop of the thread
where the skeleton object was constructed) and will cause emissions of the
\fBorg.freedesktop.DBus.Properties::PropertiesChanged\fP
-(documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
+(documentation
+.br
+<https://dbus.freedesktop.org/\:doc/\:dbus\-specification.html#standard\-interfaces\-properties>
)
signal with all the properties that have changed. Use
\fBg_dbus_interface_skeleton_flush()\fP or \fBg_dbus_object_skeleton_flush()\fP to
@@ -992,10 +1008,10 @@ only if, each added method, property sig
versions.
.sp
The generated C code currently happens to be annotated with
-gtk\-doc <https://gitlab.gnome.org/GNOME/gtk-doc/>
- and
+gtk\-doc <https://gitlab.gnome.org/GNOME/gtk\-doc/>
+and
GObject Introspection <https://gi.readthedocs.io/en/latest/>
- comments and
+comments and
annotations. The layout and contents might change in the future so no guarantees
about e.g. \fBSECTION\fP usage etc. are given.
.sp
@@ -1011,7 +1027,6 @@ Please send bug reports to either the di
upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>
\&.
.SH SEE ALSO
-.sp
- <gdbus(1)>
+.BR gdbus (1)
.\" Generated by docutils manpage writer.
.
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
More information about the pkg-gnome-maintainers
mailing list