Re: RFC: Improving Ref-Settings.html

[Dan Williams <dcbw redhat com>]

On Thu, 2014-03-27 at 13:55 -0500, Justin Brown wrote:
> I have recently been working with setting up NetworkManager with
> keyfiles and struggled to understand
> https://developer.gnome.org/NetworkManager/unstable/ref-settings.html#idp7510624.
> To that end, I have some suggestions for a newcomer, although one who
> is well-versed in Linux networking.

These are great suggestions and they make me think we actually want to
create separate documentation for 'keyfile' instead of using the
settings reference.  It can still be auto-generated from the code
documentation (which is great for us since it reduces duplication) but
we'll want to override certain settings to make better documentation.
Also, we'll probably want to generate manpages too.

Dan

> * 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=[192.168.1.2, 24, 192.168.1.1]
>
> 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.
>
>
> Thanks,
> Justin
> _______________________________________________
> networkmanager-list mailing list
> networkmanager-list gnome org
> https://mail.gnome.org/mailman/listinfo/networkmanager-list