"nm-setting-ip-config.c" is a base class for IPv4 and IPv6 settings. So
far, any tags there were ignored, which was not obvious. It can be
useful to document common properties there. Well, maybe every property
better has a IPv4/IPv6 specific text, but that should not be a technical
limitation of the tool. So also honor the base file for "ipv4" and
"ipv6" settings.
When doing that, the settings are no longer processed in the order as
they are provided on the command line. Because, one file would be parsed
twice, it wouldn't make much sense. Instead, sort the my setting name.
The advantage is that the generated XML is independent from the order
that make/meson passes to the tool.
If the information is missing, the entire attribute should not be there.
Don't set it to the empty word.
Also, don't alias the "variable" attribute to the "name". It's not clear
what the "variable" fields is supposed to mean, but if it's not
explicitly set, don't make up the information. If a user of that
information cares, the can always fallback to the "name".
Our docs can be long. It's important to be able to express paragraphs.
Honor a blank line to include a newline. For XML often whitespace is
ignored, but our tools can choose to honor the newline.
Also, don't strip the whitespace from the beginning and the end.
We keep whitespace for a certain indentation level, but additional
whitespace gets preserved. This is less important, because regular
spaces is indeed irrelevant. But when we write the annotations, we
should be in full control over spaces.
With the given input, this produces *exactly* the same XML as before.
- the parsing is now stricter (and thus the code more verbose). No
funny stuff, get the annotations correct.
- on parsing errors, we log now the affecting lines
- "nm-setting-ip-config.c" is a base class. Previously it was ignored
and for the moment we still do that. Next, we will allow to also
describe properties there.
- prepare the code to better preserve whitespace, indentation and line
wrappings. In particular, to honor a blank line to indicate a line break
and support paragraphs. This is not yet done to compare the output
to before, but will be turned on with a small patch next.
- the code will make it simple to promote the XML attributes to
nodes. Attributes aren't great, let's write XML nodes later.
We will only need to adjust the "keywords" dictionary for that,
but this change will require changes to the entire chain of tools.
I don't understand the code, but it mangles the XML.
There is no difference in the markup we have so far. But if you
have nested XML (like for description-docbook tag) there are cases
where this is wrong.
There is also no need to prettify anything. If you want pretty-formatted
XML, do it yourself, for example with
$ tidy --indent yes --indent-spaces 4 --indent-attributes yes --wrap-attributes yes --input-xml yes --output-xml yes src/libnm-client-impl/nm-property-infos-nmcli.xml
I think this was initially done, because we had the tool in perl, and
when migrating, we wanted to generate the exactly same output. And it
was the same output, and it was fine for the input we have. But with
different input, it's wrong. Drop it now.
(cherry picked from commit 35599b4349)
Coverity warns about this:
2. NetworkManager-1.32.2/tools/generate-docs-nm-property-infos.py:117: identical_branches:
The same code is executed regardless of whether "temp.index(subelement) < len(temp) - 1" is
true, because the then and else branches are identical. Should one of the branches be modified,
or the entire 'if' statement replaced?
Fixes: c3504f7e62 ('Rewrite `./tools/generate-docs-nm-property-infos.py` with XML library')
`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>
In order to make the generated XML file format consistent before and
after using XML library, adjust `property` tag format.
Signed-off-by: Wen Liang <liangwen12year@gmail.com>
When writing XML text with XML library, single quote will not be
escaped. So remove the escaping for single quote in current tool.
Signed-off-by: Wen Liang <liangwen12year@gmail.com>
In order to make the generated XML file format consistent before and
after using XML library, replace self-closing `property` tag with
paired `property` tag.
Signed-off-by: Wen Liang <liangwen12year@gmail.com>
In order to have more structured settings in man page and make it more
manageable to generate the docbook, it is recommended to use python
script to replace `./tools/generate-docs-nm-property-infos.pl` (this
tool is used to parse the comment section starting with `---nmcli---`,
`---dbus---`, `---keyfile---`, `---ifcfg-rh---`).
Signed-off-by: Wen Liang <liangwen12year@gmail.com>
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/824
