In nmcli we have renamed dhcp-send-hostname and dhcp-send-hostname-v2 to
dhcp-send-hostname-deprecated and dhcp-send-hostname so users don't need
to worry about the details of the weird workarounds that we sometimes
need to do to expand and/or deprecate some properties.
However, the autogenerated documentation didn't include this names. Add
---nmcli--- specific documentation, adding a new property-infos field
called "rename" with the new name used in nmcli. This field can be used
for more properties if we use the same strategy in the future.
If there are properties that accept special values apart from the
normally accepted values, or any of those values has an special meaning,
it can be shown as "Special value", indicating the nicknames and numbers
that can be used to select it.
Show a new field called "Valid values" in those properties that only
accept a limited set of values, like enums, ints with a valid range of
values, etc.
As there is some complex logic behind getting this information, this
logic has been put in nm-meta-setting-desc and nm-enum-utils so they can
be re-used, avoiding duplicity and errors. Some refactor has been done
in nm-meta-setting-desc in this direction, too.
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.
The input always actually has a <description-docbook> field, so the secret-flags
hint was never shown.
Move it. It's indepenent from <description> and <description-docbook> anyway.
With this we see the expected messages
See the section called “Secret flag types:” for flag values.
The manual page is large. When you search for a properties, then it's
not immediately clear to which setting it belongs. You would have to
scroll up for the setting name.
This also makes sense for the nmcli manual page, because on the command
line you have to specify the full name.
`description-docbook` is the alternative tag to `description`, the
difference is that `description-docbook` expects docbook XML but not
plaintext.
Signed-off-by: Wen Liang <liangwen12year@gmail.com>
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
