Linux Kernel Mentees Archive on lore.kernel.org
 help / color / Atom feed
From: Jonathan Corbet <corbet@lwn.net>
To: "Daniel W. S. Almeida" <dwlsalmeida@gmail.com>
Cc: mchehab+samsung@kernel.org,
	linux-kernel-mentees@lists.linuxfoundation.org,
	linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org
Subject: Re: [Linux-kernel-mentees] [PATCH v2 1/8] Documentation: convert nfs.txt to ReST
Date: Mon, 30 Dec 2019 12:12:24 -0700
Message-ID: <20191230121224.1d9e795a@lwn.net> (raw)
In-Reply-To: <ddeb8a98f4c5c24df2f36e1ce1cc5ab4da6442a1.1577681164.git.dwlsalmeida@gmail.com>

On Mon, 30 Dec 2019 01:55:55 -0300
"Daniel W. S. Almeida" <dwlsalmeida@gmail.com> wrote:

> From: "Daniel W. S. Almeida" <dwlsalmeida@gmail.com>
> 
> This patch converts nfs.txt to RST. It also moves it to admin-guide.
> The reason for moving it is because this document contains information
> useful for system administrators, as noted on the following paragraph:
> 
> 'The purpose of this document is to provide information on some of the
> special features of the NFS client that can be configured by system
> administrators'.
> 
> Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>

This generally looks good, I just have one request...

>  Documentation/admin-guide/index.rst           |  1 +
>  Documentation/admin-guide/nfs/index.rst       |  9 ++
>  .../nfs/nfs-client.rst}                       | 91 ++++++++++---------
>  3 files changed, 58 insertions(+), 43 deletions(-)
>  create mode 100644 Documentation/admin-guide/nfs/index.rst
>  rename Documentation/{filesystems/nfs/nfs.txt => admin-guide/nfs/nfs-client.rst} (72%)
> 
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 4405b7485312..4433f3929481 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
>     device-mapper/index
>     efi-stub
>     ext4
> +   nfs/index
>     gpio/index
>     highuid
>     hw_random
> diff --git a/Documentation/admin-guide/nfs/index.rst b/Documentation/admin-guide/nfs/index.rst
> new file mode 100644
> index 000000000000..f5c0180f4e5e
> --- /dev/null
> +++ b/Documentation/admin-guide/nfs/index.rst
> @@ -0,0 +1,9 @@
> +=============
> +NFS
> +=============
> +
> +.. toctree::
> +    :maxdepth: 1
> +
> +    nfs-client
> +
> diff --git a/Documentation/filesystems/nfs/nfs.txt b/Documentation/admin-guide/nfs/nfs-client.rst
> similarity index 72%
> rename from Documentation/filesystems/nfs/nfs.txt
> rename to Documentation/admin-guide/nfs/nfs-client.rst
> index f2571c8bef74..f01bf6a6c207 100644
> --- a/Documentation/filesystems/nfs/nfs.txt
> +++ b/Documentation/admin-guide/nfs/nfs-client.rst
> @@ -1,3 +1,6 @@
> +==========
> +NFS Client
> +==========
>  
>  The NFS client
>  ==============
> @@ -59,10 +62,11 @@ The DNS resolver
>  
>  NFSv4 allows for one server to refer the NFS client to data that has been
>  migrated onto another server by means of the special "fs_locations"
> -attribute. See
> -	http://tools.ietf.org/html/rfc3530#section-6
> -and
> -	http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
> +attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and
> +`Implementation Guide for Referrals in NFSv4`_.
> +
> +.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6
> +.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
>  
>  The fs_locations information can take the form of either an ip address and
>  a path, or a DNS hostname and a path. The latter requires the NFS client to
> @@ -72,16 +76,16 @@ upcall to allow userland to provide this service.
>  Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual
>  /var/lib/nfs/rpc_pipefs, the upcall consists of the following steps:
>  
> -   (1) The process checks the dns_resolve cache to see if it contains a
> +   #.  The process checks the dns_resolve cache to see if it contains a

It really only occurs to me now that we probaby shouldn't use the "#"
notation.  If we truly need an *enumerated* list, meaning that the numbers
are an important part of reading the list, then we should retain the
numbers in the plain-text version, even if that means we occasionally have
to change them if the list changes.  If, instead, the numbers aren't
important, we should just use bullets instead.

In this case, we have an explicit sequence of events, so the numbers should
probably remain.

Thanks,

jon
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

  reply index

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-12-30  4:55 [Linux-kernel-mentees] [PATCH v2 0/8] Documentation: nfs: Convert a few documents to RST and move them to admin-guide Daniel W. S. Almeida
2019-12-30  4:55 ` [Linux-kernel-mentees] [PATCH v2 1/8] Documentation: convert nfs.txt to ReST Daniel W. S. Almeida
2019-12-30 19:12   ` Jonathan Corbet [this message]
2019-12-30  4:55 ` [Linux-kernel-mentees] [PATCH v2 2/8] Documentation: nfsroot.txt: convert " Daniel W. S. Almeida
2019-12-30 19:18   ` Jonathan Corbet
2019-12-31  4:08     ` Daniel W. S. Almeida
2019-12-31 15:32       ` Jonathan Corbet
2019-12-31 19:15         ` Daniel W. S. Almeida
2019-12-30  4:55 ` [Linux-kernel-mentees] [PATCH v2 3/8] Documentation: nfs-rdma: " Daniel W. S. Almeida
2019-12-30 19:28   ` Jonathan Corbet
2019-12-30  4:55 ` [Linux-kernel-mentees] [PATCH v2 4/8] Documentation: convert nfsd-admin-interfaces " Daniel W. S. Almeida
2019-12-30 19:30   ` Jonathan Corbet
2019-12-30  4:55 ` [Linux-kernel-mentees] [PATCH v2 5/8] Documentation: nfs: idmapper: convert " Daniel W. S. Almeida
2019-12-30  4:56 ` [Linux-kernel-mentees] [PATCH v2 6/8] Documentation: nfs: convert pnfs-block-server " Daniel W. S. Almeida
2019-12-30  4:56 ` [Linux-kernel-mentees] [PATCH v2 7/8] Documentation: nfs: pnfs-scsi-server: convert " Daniel W. S. Almeida
2019-12-30  4:56 ` [Linux-kernel-mentees] [PATCH v2 8/8] Documentation: nfs: fault_injection: " Daniel W. S. Almeida

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191230121224.1d9e795a@lwn.net \
    --to=corbet@lwn.net \
    --cc=dwlsalmeida@gmail.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel-mentees@lists.linuxfoundation.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab+samsung@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux Kernel Mentees Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-kernel-mentees/0 linux-kernel-mentees/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-kernel-mentees linux-kernel-mentees/ https://lore.kernel.org/linux-kernel-mentees \
		linux-kernel-mentees@lists.linuxfoundation.org
	public-inbox-index linux-kernel-mentees

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.linuxfoundation.lists.linux-kernel-mentees


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git