doc: dts: revisit documentation

This is joint work with Kumar Gala (see signed-off-by).

Document the changes to the generated node macros in macros.bnf,
moving the old file to legacy-macros.bnf and putting it in its own
section.

The actual generated macros are now a low-level detail, so rewrite the
foregoing sections as examples in terms of the new <devicetree.h> APIs.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>