RFC: Improving Ref-Settings.html

I have recently been working with setting up NetworkManager with
keyfiles and struggled to understand
To that end, I have some suggestions for a newcomer, although one who
is well-versed in Linux networking.

* Include a "data type" section before "configuration settings."
Basically just explain the data types and how to type them. Strings
are straightforward, but even things that are simple to programmers
like uint32 are likely confusing to users. The case-sensitivity of
booleans should be defined. Arrays are probably the most confusing.
The documentation is not clear about whether brackets should be used
around the array, what the valid separations are, and if strings need
quotes around them.

For example, I initially tried this when I saw the data types:

    address1=[, 24,]

This change should still allow easy use of the current documentation
generation tools since it would just be a static block before the
dynamic content.

* Add a description for each table. Many of the tables are easy to
understand like ipv4 and bluetooth. Some are less clear like
bridge-port. It would be nice if there was a short description for
each table, even if some are painfully obvious. I did a brief look at
how the documentation strings are specified in libnm-util/. For the
most part, it looks like all of nm-setting-*.c files have a decent
SECTION description. They would need to be rewritten a little for user
documentation, but that seems like an easy way to expose more
information to users.

* Clarify complex data types. This likely applies to many different
types, but I encountered it with ipv4->addresses. I call this a
complex data type, because each address is an array of length two.
(Note the documentation says 3-array, which doesn't reflect the recent
changes.) The first element is an address with a subnet mask. The
documentation should more clearly specify to use a slash and subnet.
Again, I only experienced this problem with this key, but I'm sure
that it exists in many other keys.

* Reconcile "method" between ipv4 and ipv6. It used to be that
method=ignore worked for both. Sometime in the past 6 months or so,
ignore has been replaced with "disabled" but only for ipv4. Either
term is fine, but they should be the same.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]