Gtkdoc comments are used, among other things, to generate the various
nm-setting-* manual pages. When a constant is referenced in a gtkdoc
comment (i.e. `%NM_IP_TUNNEL_MODE_IPIP`) it is expanded to show the C name
and the value (i.e. `NM_IP_TUNNEL_MODE_IPIP (1)`). To generate the
nm-setting-* manual pages, we don't use gtkdoc, but we process this data
with the custom script tools/generate-docs-nm-settings-docs-gir.py.
This script was expanding the constants in the same way than gtkdoc.
Showing the constants in that way in nm-setting-* manual pages makes
little sense, because users are not going to use the C identifiers.
Let's show them with a more appropriate format.
Additionally, the different nm-setting-* pages might require different
formats than the other. For example, for nm-setting-nmcli a format like
`"ipip" (1)` is prefered, but for nm-setting-dbus it's better
`1 (ipip)`. Let's generate different nm-settings-docs-gir-*.xml files for
nmcli, dbus, keyfile and ifcfg-rh, using the right format for each one.
When we generate the manual page for nm-settings-nmcli, we run:
"/usr/bin/python" \
./tools/generate-docs-nm-settings-docs-merge.py \
--only-from-first \
man/nm-settings-docs-nmcli.xml \
src/nmcli/gen-metadata-nm-settings-nmcli.xml \
src/libnm-client-impl/nm-property-infos-nmcli.xml \
src/libnm-client-impl/nm-settings-docs-gir.xml
If "gen-metadata-nm-settings-nmcli.xml" contains either a <description>
or a <description-docbook>, then we must not continue searching the
other XML documents. The user provided an explicit override, and
fallback (search further) is wrong. Previously, we might take
<description> from the first file, and <description-docbook> from the
second file. As "man/nm-settings-nmcli.xsl" prefers
<description-docbook>, it takes the wrong text. Instead, as we search
the files during merge, we must prefer the first one.
Note that the change doesn't really matter anymore, because each XML
now must also contain both <description> and <description-docbook>.
There is an assertion for that.
Also, stop generating <deprecated-docbook>. First, it lacked the
important "since=" attribute and was necessary. Also, it's redundant and
does not contain anything interesting. So far, we don't need special
formatting for the deprecated message, and we likely never will.
Also, stop accepting or generating the "description=" attribute. This
should always be an XML element now.
From nm-settings-dbus(5):
Before (ugly, offensive, possibly in violation of geneva protocol):
...
| set, the authentication retries for 3
| times before failing the connection.
|
| Currently, this only applies to 802-1x
| authentication.
After (beautiful, smells good, in harmony with nature):
...
| set, the authentication retries for 3
| times before failing the connection.
|
| Currently, this only applies to 802-1x
| authentication.
Previously, the deprecation data was included in <description*>, in form
of an integer. E.g.:
/**
* NMSettingLala:hello:
*
* Does this and that.
*
* Deprecated: 1.12: Be sad instead.
**/
Results in:
<property name="hello">
<description>Does this and that. Deprecated: 1</description>
</property>
Let's make it do this instead:
<property name="hello">
<description>Does this and that.</description>
<deprecated since="1.12">Be sad instead.</description>
</property>
Improve documentation by preserving paragraphs in the
nm-settings-nmcli man pages.
To do that structure of src/libnm-client-impl/nm-settings-docs-gir.xml
was changed to have "description" as subnode to property node instead
of attribute of property node. Another subnode "description-docbook"
was added - this node is then used when generating man pages.
tools/generate-docs-nm-settings-docs-gir.py and man/nm-settings-dbus.xsl
were also changed to accomodate for changes mentioned above.
Replace xsltproc tool with python script when generating
./src/libnmc-setting/settings-docs.h.
Deleted settings-docs.xsl since it was replaced by python script.
Change src/libnmc-setting/settings-docs.h.in accodring to newly
generated src/libnmc-setting/settings-docs.h
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/661https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1260
On python2 the following error is raised:
`LookupError: unknown encoding: unicode`
Seems like `unicode` is a correct encoding in Python 3 but not 2.
Fix:
1. Change encoding to `utf-8`
2. Pass output path string instead of opening file and passing
opened file object. Python2 and 3 might need different file
modes, passing just path lets ElementTree select appropriate
file mode.
Fixes: f00e90923c ('tools: Use ElementTree to write XML in generate-docs-nm-settings-docs-gir.py')
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1249
Instead of manually writting XML line by line.
Quoting is automatic.
Makes it much easier to modify. (just add new elements)
Generated XML not indented at the moment.
* Create main() function and put its execution under
__name__ == '__main__' guard.
* Only one module import per line
* Use required=True to check if necessary arguments have
been passed.
* Remove usage() as ArgumentParser handles that already
The gtk-doc text that the tool receives is not XML, it's a plain text.
When setting the plain text as XML attribute, we need to properly escape
it. The previous XML escape code was naive, and didn't cover for a
plain ampersand.
(cherry picked from commit 1641cc1d03)
