[ovs-dev] [PATCH] doc: Add more cross references between docs
Lori Jakab
lojakab at cisco.com
Thu Oct 30 10:55:37 UTC 2014
Thomas,
I really find this work of moving the documentation to Markdown very
useful, thanks for spending time on it!
I have two suggestions about the way files are linked.
First, I would use the new file name in the link, for example
[CONTRIBUTING.md](CONTRIBUTING.md) instead of
[CONTRIBUTING](CONTRIBUTING.md) because the text sometimes says "The
[OPENFLOW-1.1+](OPENFLOW-1.1+.md) file", the word *file* showing up
explicitly. However, in the Markdown's HTML rendering you would see
"OPENFLOW-1.1+ file" which now doesn't exist anymore.
Second, to improve readability, I would only put "[CONTRIBUTING.md]" in
the text without the second part "(CONTRIBUTING.md)" the to avoid
duplication, and add the reference at the end of the file as
"[CONTRIBUTING.md]: CONTRIBUTING.md" once. The last part is necessary
because otherwise the file name is not rendered as a link. It won't
show up in the rendered HTML.
Best regards,
-Lori
On 10/30/14 12:26 PM, Thomas Graf wrote:
> Signed-off-by: Thomas Graf <tgraf at noironetworks.com>
> ---
> FAQ.md | 10 +++++-----
> INSTALL.Libvirt.md | 6 +++---
> INSTALL.NetBSD.md | 3 ++-
> INSTALL.SSL.md | 4 ++--
> INSTALL.md | 16 ++++++++--------
> INSTALL.userspace.md | 6 +++---
> OPENFLOW-1.1+.md | 4 ++--
> README.md | 8 ++++----
> TODO.md | 14 ++++++++------
> tutorial/ovs-sandbox | 2 +-
> 10 files changed, 38 insertions(+), 35 deletions(-)
>
> diff --git a/FAQ.md b/FAQ.md
> index 01228eb..464b01d 100644
> --- a/FAQ.md
> +++ b/FAQ.md
> @@ -1237,11 +1237,11 @@ A: The following table lists the versions of OpenFlow supported by
> (Open vSwitch 2.2 had an experimental implementation of OpenFlow
> 1.4 that could cause crashes. We don't recommend enabling it.)
>
> - OPENFLOW-1.1+ in the Open vSwitch source tree tracks support for
> - OpenFlow 1.1 and later features. When support for OpenFlow 1.4 and
> - 1.5 is solidly implemented, Open vSwitch will enable those version
> - by default. Also, the OpenFlow 1.5 specification is still under
> - development and thus subject to change.
> + [OPENFLOW-1.1+](OPENFLOW-1.1+.md) in the Open vSwitch source tree
> + tracks support for OpenFlow 1.1 and later features. When support
> + for OpenFlow 1.4 and 1.5 is solidly implemented, Open vSwitch will
> + enable those version by default. Also, the OpenFlow 1.5 specification
> + is still under development and thus subject to change.
>
> ### Q: Does Open vSwitch support MPLS?
>
> diff --git a/INSTALL.Libvirt.md b/INSTALL.Libvirt.md
> index 0ee676c..1e0db0f 100644
> --- a/INSTALL.Libvirt.md
> +++ b/INSTALL.Libvirt.md
> @@ -2,9 +2,9 @@ How to Use Open vSwitch with Libvirt
> ====================================
>
> This document describes how to use Open vSwitch with Libvirt 0.9.11 or
> -later. This document assumes that you followed INSTALL or installed
> -Open vSwitch from distribution packaging such as a .deb or .rpm. The Open
> -vSwitch support is included by default in Libvirt 0.9.11. Consult
> +later. This document assumes that you followed [INSTALL](INSTALL.md) or
> +installed Open vSwitch from distribution packaging such as a .deb or .rpm.
> +The Open vSwitch support is included by default in Libvirt 0.9.11. Consult
> www.libvirt.org for instructions on how to build the latest Libvirt, if your
> Linux distribution by default comes with an older Libvirt release.
>
> diff --git a/INSTALL.NetBSD.md b/INSTALL.NetBSD.md
> index 4732250..4718deb 100644
> --- a/INSTALL.NetBSD.md
> +++ b/INSTALL.NetBSD.md
> @@ -30,4 +30,5 @@ As all executables installed with pkgsrc are placed in `/usr/pkg/bin/`
> directory, it might be a good idea to add it to your PATH.
>
> Open vSwitch on NetBSD is currently "userspace switch" implementation
> -in the sense described in INSTALL.userspace and PORTING.
> +in the sense described in [INSTALL.userspace](INSTALL.userspace.md) and
> +[PORTING](PORTING.md).
> diff --git a/INSTALL.SSL.md b/INSTALL.SSL.md
> index aecb2b5..87a334f 100644
> --- a/INSTALL.SSL.md
> +++ b/INSTALL.SSL.md
> @@ -7,8 +7,8 @@ with OpenSSL. SSL support ensures integrity and confidentiality of
> the OpenFlow connections, increasing network security.
>
> This file explains how to configure an Open vSwitch to connect to an
> -OpenFlow controller over SSL. Refer to INSTALL for instructions on
> -building Open vSwitch with SSL support.
> +OpenFlow controller over SSL. Refer to [INSTALL](INSTALL.md) for
> +instructions on building Open vSwitch with SSL support.
>
> Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by
> RFC 2246, which is very similar to SSL version 3.0. TLSv1 was
> diff --git a/INSTALL.md b/INSTALL.md
> index 536cbfb..44a9d34 100644
> --- a/INSTALL.md
> +++ b/INSTALL.md
> @@ -43,16 +43,16 @@ you will need the following software:
>
> On Linux, you may choose to compile the kernel module that comes with
> the Open vSwitch distribution or to use the kernel module built into
> -the Linux kernel (version 3.3 or later). See the FAQ question "What
> -features are not available in the Open vSwitch kernel datapath that
> +the Linux kernel (version 3.3 or later). See the [FAQ](FAQ.md) question
> +"What features are not available in the Open vSwitch kernel datapath that
> ships as part of the upstream Linux kernel?" for more information on
> this trade-off. You may also use the userspace-only implementation,
> -at some cost in features and performance (see INSTALL.userspace for
> -details). To compile the kernel module on Linux, you must also
> -install the following:
> +at some cost in features and performance (see
> +[INSTALL.userspace](INSTALL.userspace.md) for details). To compile the
> +kernel module on Linux, you must also install the following:
>
> - - A supported Linux kernel version. Please refer to README.md for a
> - list of supported versions.
> + - A supported Linux kernel version. Please refer to
> + [README](README.md) for a list of supported versions.
>
> The Open vSwitch datapath requires bridging support
> (CONFIG_BRIDGE) to be built as a kernel module. (This is common
> @@ -184,7 +184,7 @@ Prerequisites section, follow the procedure below to build.
>
> If --with-linux requests building for an unsupported version of
> Linux, then "configure" will fail with an error message. Please
> - refer to the FAQ for advice in that case.
> + refer to the [FAQ](FAQ.md) for advice in that case.
>
> If you wish to build the kernel module for an architecture other
> than the architecture of the machine used for the build, you may
> diff --git a/INSTALL.userspace.md b/INSTALL.userspace.md
> index a9f881c..1e75ae7 100644
> --- a/INSTALL.userspace.md
> +++ b/INSTALL.userspace.md
> @@ -17,9 +17,9 @@ Building and Installing
> -----------------------
>
> The requirements and procedure for building, installing, and
> -configuring Open vSwitch are the same as those given in INSTALL.
> -You may omit configuring, building, and installing the kernel module,
> -and the related requirements.
> +configuring Open vSwitch are the same as those given in
> +[INSTALL](INSTALL.md). You may omit configuring, building, and
> +installing the kernel module, and the related requirements.
>
> On Linux, the userspace switch additionally requires the kernel
> TUN/TAP driver to be available, either built into the kernel or loaded
> diff --git a/OPENFLOW-1.1+.md b/OPENFLOW-1.1+.md
> index 36fd168..844b811 100644
> --- a/OPENFLOW-1.1+.md
> +++ b/OPENFLOW-1.1+.md
> @@ -221,8 +221,8 @@ Please consider the following:
> * Coding style (see the [CodingStyle](CodingStyle.md) file at the
> top of the source tree).
>
> - * The patch submission guidelines (see CONTRIBUTING). I
> - recommend using "git send-email", which automatically follows a
> + * The patch submission guidelines (see [CONTRIBUTING](CONTRIBUTING.md)).
> + I recommend using "git send-email", which automatically follows a
> lot of those guidelines.
>
> Bug Reporting
> diff --git a/README.md b/README.md
> index 5084c31..e7f2b6b 100644
> --- a/README.md
> +++ b/README.md
> @@ -78,8 +78,8 @@ What other documentation is available?
> --------------------------------------
>
> To install Open vSwitch on a regular Linux or FreeBSD host, please
> -read INSTALL. For specifics around installation on a specific
> -platform, please see one of these files:
> +read [INSTALL](INSTALL.md). For specifics around installation on a
> +specific platform, please see one of these files:
>
> - [INSTALL.Debian](INSTALL.Debian.md)
> - [INSTALL.Fedora](INSTALL.Fedora.md)
> @@ -98,13 +98,13 @@ To use Open vSwitch...
> - ...without using a kernel module, read
> [INSTALL.userspace](INSTALL.userspace.md).
>
> -For answers to common questions, read FAQ.
> +For answers to common questions, read [FAQ](FAQ.md).
>
> To learn how to set up SSL support for Open vSwitch, read
> [INSTALL.SSL](INSTALL.SSL.md).
>
> To learn about some advanced features of the Open vSwitch software
> -switch, read the tutorial in tutorial/Tutorial.
> +switch, read the [Tutorial](tutorial/Tutorial.md).
>
> Each Open vSwitch userspace program is accompanied by a manpage. Many
> of the manpages are customized to your configuration as part of the
> diff --git a/TODO.md b/TODO.md
> index 581e213..d1c85ae 100644
> --- a/TODO.md
> +++ b/TODO.md
> @@ -2,7 +2,8 @@ Open vSwitch Project Ideas
> ==========================
>
> This file lists a number of project ideas for Open vSwitch. The ideas
> -here overlap somewhat with those in the OPENFLOW-1.1+ file.
> +here overlap somewhat with those in the [OPENFLOW-1.1+](OPENFLOW-1.1+.md)
> +file.
>
>
> Programming Project Ideas
> @@ -12,11 +13,12 @@ Each of these projects would ideally result in a patch or a short
> series of them posted to ovs-dev.
>
> Please read [CONTRIBUTING](CONTRIBUTING.md) and [CodingStyle](CodingStyle.md)
> -in the top of the source tree before you begin work. The OPENFLOW-1.1+
> -file also has an introduction to how OpenFlow is implemented in Open vSwitch.
> -It is also a good idea to look around the source tree for related code, and
> -back through the Git history for commits on related subjects, to allow
> -you to follow existing patterns and conventions.
> +in the top of the source tree before you begin work. The
> +[OPENFLOW-1.1+](OPENFLOW-1.1+.md) file also has an introduction to how
> +OpenFlow is implemented in Open vSwitch. It is also a good idea to look
> +around the source tree for related code, and back through the Git history
> +for commits on related subjects, to allow you to follow existing patterns
> +and conventions.
>
> Meters
> ------
> diff --git a/tutorial/ovs-sandbox b/tutorial/ovs-sandbox
> index 21066d1..45bb234 100755
> --- a/tutorial/ovs-sandbox
> +++ b/tutorial/ovs-sandbox
> @@ -136,7 +136,7 @@ if $built; then
> case $srcdir in
> '')
> srcdir=$builddir
> - if test ! -e "$srcdir"/WHY-OVS; then
> + if test ! -e "$srcdir"/WHY-OVS.md; then
> srcdir=`cd $builddir/.. && pwd`
> fi
> ;;
More information about the dev
mailing list