From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 60A68C2D0CE for ; Mon, 30 Dec 2019 19:12:30 +0000 (UTC) Received: from silver.osuosl.org (smtp3.osuosl.org [140.211.166.136]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 34A1A2053B for ; Mon, 30 Dec 2019 19:12:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 34A1A2053B Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=lwn.net Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=linux-kernel-mentees-bounces@lists.linuxfoundation.org Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 0B7CC204FF; Mon, 30 Dec 2019 19:12:30 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 0zQ72PEy4Bgb; Mon, 30 Dec 2019 19:12:29 +0000 (UTC) Received: from lists.linuxfoundation.org (lf-lists.osuosl.org [140.211.9.56]) by silver.osuosl.org (Postfix) with ESMTP id 03CC120488; Mon, 30 Dec 2019 19:12:28 +0000 (UTC) Received: from lf-lists.osuosl.org (localhost [127.0.0.1]) by lists.linuxfoundation.org (Postfix) with ESMTP id E4BB6C1796; Mon, 30 Dec 2019 19:12:28 +0000 (UTC) Received: from hemlock.osuosl.org (smtp2.osuosl.org [140.211.166.133]) by lists.linuxfoundation.org (Postfix) with ESMTP id 5E392C077D for ; Mon, 30 Dec 2019 19:12:27 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 486FD87582 for ; Mon, 30 Dec 2019 19:12:27 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from hemlock.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id w56X39wBogVc for ; Mon, 30 Dec 2019 19:12:26 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by hemlock.osuosl.org (Postfix) with ESMTPS id 9AA0B87554 for ; Mon, 30 Dec 2019 19:12:26 +0000 (UTC) Received: from lwn.net (localhost [127.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 80B74536; Mon, 30 Dec 2019 19:12:25 +0000 (UTC) Date: Mon, 30 Dec 2019 12:12:24 -0700 From: Jonathan Corbet To: "Daniel W. S. Almeida" Message-ID: <20191230121224.1d9e795a@lwn.net> In-Reply-To: References: Organization: LWN.net MIME-Version: 1.0 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 X-BeenThere: linux-kernel-mentees@lists.linuxfoundation.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: linux-kernel-mentees-bounces@lists.linuxfoundation.org Sender: "Linux-kernel-mentees" On Mon, 30 Dec 2019 01:55:55 -0300 "Daniel W. S. Almeida" wrote: > From: "Daniel W. S. Almeida" > > 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 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