[PATCH 00/11] Documentation/scsi: organize SCSI docs & make more readable

[PATCH 00/11] Documentation/scsi: organize SCSI docs & make more readable

[Randy Dunlap]

Organize the SCSI documentation into categories instead of
alphabetically by filename.

Modify several of the document chapter headings so that they are
shorter and easier to find.

Make several updates to the scsi-generic driver documentation.

 [PATCH 01/11] Docs/scsi: organize the SCSI documentation
 [PATCH 02/11] Docs/scsi: introduction: multiple cleanups
 [PATCH 03/11] Docs/scsi: arcmsr: use a chapter heading for clarity
 [PATCH 04/11] Docs/scsi: scsi-changer: shorten the chapter heading
 [PATCH 05/11] Docs/scsi: dc395x: shorten the chapter heading
 [PATCH 06/11] Docs/scsi: scsi_fc_transport: fix typo in heading
 [PATCH 07/11] Docs/scsi: scsi-generic: multiple cleanups
 [PATCH 08/11] Docs/scsi: g_NCR5380: shorten chapter heading
 [PATCH 09/11] Docs/scsi: megaraid: clarify chapter heading
 [PATCH 10/11] Docs/scsi: ncr53c8xx: shorten chapter heading
 [PATCH 11/11] Docs/scsi: sym53c8xx_2: shorten chapter heading


 Documentation/scsi/arcmsr_spec.rst       |    1 
 Documentation/scsi/dc395x.rst            |    6 +-
 Documentation/scsi/g_NCR5380.rst         |    6 +-
 Documentation/scsi/index.rst             |   37 ++++++++++++--
 Documentation/scsi/megaraid.rst          |    6 +-
 Documentation/scsi/ncr53c8xx.rst         |    6 +-
 Documentation/scsi/scsi-changer.rst      |    6 +-
 Documentation/scsi/scsi-generic.rst      |   53 ++++++++-------------
 Documentation/scsi/scsi.rst              |   23 +++------
 Documentation/scsi/scsi_fc_transport.rst |    8 +--
 Documentation/scsi/sym53c8xx_2.rst       |    6 +-
 11 files changed, 86 insertions(+), 72 deletions(-)


Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Gerd Knorr <kraxel@bytesex.org>
Cc: Oliver Neukum <oliver@neukum.org>
Cc: Ali Akcaagac <aliakc@web.de>
Cc: Jamie Lenehan <lenehan@twibble.org>
Cc: dc395x@twibble.org
Cc: James Smart <james.smart@broadcom.com>
Cc: Doug Gilbert <dgilbert@interlog.com>
Cc: Finn Thain <fthain@linux-m68k.org>
Cc: Michael Schmitz <schmitzmic@gmail.com>
Cc: Kashyap Desai <kashyap.desai@broadcom.com>
Cc: Sumit Saxena <sumit.saxena@broadcom.com>
Cc: Shivasharan S <shivasharan.srikanteshwara@broadcom.com>
Cc: megaraidlinux.pdl@broadcom.com
Cc: Matthew Wilcox <willy@infradead.org>

[PATCH 01/11] Docs/scsi: organize the SCSI documentation

[Randy Dunlap]

Break the SCSI documentation up into categories:
  Introduction, APIs, driver parameters, and host adapter drivers
instead of alphabetical by document file name (i.e., no organization).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/scsi/index.rst |   37 ++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

diff -- a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst
--- a/Documentation/scsi/index.rst
+++ b/Documentation/scsi/index.rst
@@ -7,6 +7,38 @@ SCSI Subsystem
 .. toctree::
    :maxdepth: 1
 
+Introduction
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   scsi
+
+SCSI driver APIs
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   scsi_mid_low_api
+   scsi_eh
+
+SCSI driver parameters
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   scsi-parameters
+   link_power_management_policy
+
+SCSI host adapter drivers
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
    53c700
    aacraid
    advansys
@@ -25,7 +57,6 @@ SCSI Subsystem
    hpsa
    hptiop
    libsas
-   link_power_management_policy
    lpfc
    megaraid
    ncr53c8xx
@@ -33,12 +64,8 @@ SCSI Subsystem
    ppa
    qlogicfas
    scsi-changer
-   scsi_eh
    scsi_fc_transport
    scsi-generic
-   scsi_mid_low_api
-   scsi-parameters
-   scsi
    sd-parameters
    smartpqi
    st

[PATCH 02/11] Docs/scsi: introduction: multiple cleanups

[Randy Dunlap]

Modify URLs to use https instead of http.
Remove ancient URLs that don't work.
Change "scsi" in text to "SCSI".
Change "cdrom" in text to "CD-ROM".
Drop the reference to "autoclean" for modules since I can't
  find it in any current documentation.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/scsi/scsi.rst |   23 ++++++++++-------------
 1 file changed, 10 insertions(+), 13 deletions(-)

diff -- a/Documentation/scsi/scsi.rst b/Documentation/scsi/scsi.rst
--- a/Documentation/scsi/scsi.rst
+++ b/Documentation/scsi/scsi.rst
@@ -6,30 +6,28 @@ SCSI subsystem documentation
 
 The Linux Documentation Project (LDP) maintains a document describing
 the SCSI subsystem in the Linux kernel (lk) 2.4 series. See:
-http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
+https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
 and multiple page HTML renderings as well as postscript and pdf.
-It can also be found at:
-http://web.archive.org/web/%2E/http://www.torque.net/scsi/SCSI-2.4-HOWTO
 
 Notes on using modules in the SCSI subsystem
 ============================================
-The scsi support in the linux kernel can be modularized in a number of
+The SCSI support in the Linux kernel can be modularized in a number of
 different ways depending upon the needs of the end user.  To understand
 your options, we should first define a few terms.
 
-The scsi-core (also known as the "mid level") contains the core of scsi
-support.  Without it you can do nothing with any of the other scsi drivers.
-The scsi core support can be a module (scsi_mod.o), or it can be built into
-the kernel. If the core is a module, it must be the first scsi module
+The scsi-core (also known as the "mid level") contains the core of SCSI
+support.  Without it you can do nothing with any of the other SCSI drivers.
+The SCSI core support can be a module (scsi_mod.o), or it can be built into
+the kernel. If the core is a module, it must be the first SCSI module
 loaded, and if you unload the modules, it will have to be the last one
-unloaded.  In practice the modprobe and rmmod commands (and "autoclean")
+unloaded.  In practice the modprobe and rmmod commands
 will enforce the correct ordering of loading and unloading modules in
 the SCSI subsystem.
 
 The individual upper and lower level drivers can be loaded in any order
-once the scsi core is present in the kernel (either compiled in or loaded
-as a module).  The disk driver (sd_mod.o), cdrom driver (sr_mod.o),
-tape driver [1]_ (st.o) and scsi generics driver (sg.o) represent the upper
+once the SCSI core is present in the kernel (either compiled in or loaded
+as a module).  The disk driver (sd_mod.o), CD-ROM driver (sr_mod.o),
+tape driver [1]_ (st.o) and SCSI generics driver (sg.o) represent the upper
 level drivers to support the various assorted devices which can be
 controlled.  You can for example load the tape driver to use the tape drive,
 and then unload it once you have no further need for the driver (and release
@@ -44,4 +42,3 @@ built into the kernel.
 
 .. [1] There is a variant of the st driver for controlling OnStream tape
        devices. Its module name is osst.o .
-

[PATCH 03/11] Docs/scsi: arcmsr: use a chapter heading for clarity

[Randy Dunlap]

Add a chapter heading so that the document sections are not all
at the same level, mucking up the SCSI subsystem contents.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/scsi/arcmsr_spec.rst |    1 +
 1 file changed, 1 insertion(+)

diff -- a/Documentation/scsi/arcmsr_spec.rst b/Documentation/scsi/arcmsr_spec.rst
--- a/Documentation/scsi/arcmsr_spec.rst
+++ b/Documentation/scsi/arcmsr_spec.rst
@@ -1,3 +1,4 @@
+===================
 ARECA FIRMWARE SPEC
 ===================
 

[PATCH 04/11] Docs/scsi: scsi-changer: shorten the chapter heading

[Randy Dunlap]

Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Gerd Knorr <kraxel@bytesex.org>
---
 Documentation/scsi/scsi-changer.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/scsi-changer.rst b/Documentation/scsi/scsi-changer.rst
--- a/Documentation/scsi/scsi-changer.rst
+++ b/Documentation/scsi/scsi-changer.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-========================================
-README for the SCSI media changer driver
-========================================
+=========================
+SCSI media changer driver
+=========================
 
 This is a driver for SCSI Medium Changer devices, which are listed
 with "Type: Medium Changer" in /proc/scsi/scsi.

[PATCH 05/11] Docs/scsi: dc395x: shorten the chapter heading

[Randy Dunlap]

Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Oliver Neukum <oliver@neukum.org>
Cc: Ali Akcaagac <aliakc@web.de>
Cc: Jamie Lenehan <lenehan@twibble.org>
Cc: dc395x@twibble.org
---
 Documentation/scsi/dc395x.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/dc395x.rst b/Documentation/scsi/dc395x.rst
--- a/Documentation/scsi/dc395x.rst
+++ b/Documentation/scsi/dc395x.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-======================================
-README file for the dc395x SCSI driver
-======================================
+==================
+dc395x SCSI driver
+==================
 
 Status
 ------

[PATCH 06/11] Docs/scsi: scsi_fc_transport: fix typo in heading

[Randy Dunlap]

Fix the typo "Tansport" to be "Transport".
Update email address for James Smart.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: James Smart <james.smart@broadcom.com>
---
 Documentation/scsi/scsi_fc_transport.rst |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff -- a/Documentation/scsi/scsi_fc_transport.rst b/Documentation/scsi/scsi_fc_transport.rst
--- a/Documentation/scsi/scsi_fc_transport.rst
+++ b/Documentation/scsi/scsi_fc_transport.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-================
-SCSI FC Tansport
-================
+=================
+SCSI FC Transport
+=================
 
 Date:  11/18/2008
 
@@ -556,5 +556,5 @@ The following people have contributed to
 
 
 James Smart
-james.smart@emulex.com
+james.smart@broadcom.com
 

[PATCH 07/11] Docs/scsi: scsi-generic: multiple cleanups

[Randy Dunlap]

Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Spell "CDROM" as "CD-ROM".
Capitalize "Linux".

Use https instead of http for URLs.

Drop the Linux Documenation Project URL for the SCSI generic HOWTO
since it hasn't been updated since 2002. Use Doug Gilbert's URL
for it instead.

Drop some outdated documentation & references.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Doug Gilbert <dgilbert@interlog.com>
---
Doug, if you have any specific changes that you would like to see
in this file, please let me know.

 Documentation/scsi/scsi-generic.rst |   53 ++++++++++----------------
 1 file changed, 21 insertions(+), 32 deletions(-)

diff -- a/Documentation/scsi/scsi-generic.rst b/Documentation/scsi/scsi-generic.rst
--- a/Documentation/scsi/scsi-generic.rst
+++ b/Documentation/scsi/scsi-generic.rst
@@ -1,15 +1,15 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=======================================
-Notes on Linux SCSI Generic (sg) driver
-=======================================
+========================
+SCSI Generic (sg) driver
+========================
 
                                                         20020126
 
 Introduction
 ============
 The SCSI Generic driver (sg) is one of the four "high level" SCSI device
-drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg
+drivers along with sd, st and sr (disk, tape and CD-ROM respectively). Sg
 is more generalized (but lower level) than its siblings and tends to be
 used on SCSI devices that don't fit into the already serviced categories.
 Thus sg is used for scanners, CD writers and reading audio CDs digitally
@@ -22,7 +22,7 @@ and examples.
 
 Major versions of the sg driver
 ===============================
-There are three major versions of sg found in the linux kernel (lk):
+There are three major versions of sg found in the Linux kernel (lk):
       - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) .
 	It is based in the sg_header interface structure.
       - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on
@@ -33,34 +33,24 @@ There are three major versions of sg fou
 
 Sg driver documentation
 =======================
-The most recent documentation of the sg driver is kept at the Linux
-Documentation Project's (LDP) site:
+The most recent documentation of the sg driver is kept at
 
-- http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO
+- https://sg.danny.cz/sg/
 
 This describes the sg version 3 driver found in the lk 2.4 series.
 
-The LDP renders documents in single and multiple page HTML, postscript
-and pdf. This document can also be found at:
+Documentation (large version) for the version 2 sg driver found in the
+lk 2.2 series can be found at
 
-- http://sg.danny.cz/sg/p/sg_v3_ho.html
-
-Documentation for the version 2 sg driver found in the lk 2.2 series can
-be found at http://sg.danny.cz/sg/. A larger version
-is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt.
+- https://sg.danny.cz/sg/p/scsi-generic_long.txt.
 
 The original documentation for the sg driver (prior to lk 2.2.6) can be
-found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt
-and in the LDP archives.
+found in the LDP archives at
 
-A changelog with brief notes can be found in the
-/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy
-and edit this file (removing its changelog for example) before placing it
-in /usr/include/scsi/sg.h . Driver debugging information and other notes
-can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file.
+- https://tldp.org/HOWTO/archived/SCSI-Programming-HOWTO/index.html
 
 A more general description of the Linux SCSI subsystem of which sg is a
-part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
+part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
 
 
 Example code and utilities
@@ -73,8 +63,8 @@ There are two packages of sg utilities:
                 and earlier
     =========   ==========================================================
 
-Both packages will work in the lk 2.4 series however sg3_utils offers more
-capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and
+Both packages will work in the lk 2.4 series. However, sg3_utils offers more
+capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and
 freecode.com
 
 Another approach is to look at the applications that use the sg driver.
@@ -83,7 +73,7 @@ These include cdrecord, cdparanoia, SANE
 
 Mapping of Linux kernel versions to sg driver versions
 ======================================================
-Here is a list of linux kernels in the 2.4 series that had new version
+Here is a list of Linux kernels in the 2.4 series that had the new version
 of the sg driver:
 
      - lk 2.4.0 : sg version 3.1.17
@@ -92,10 +82,10 @@ of the sg driver:
      - lk 2.4.17 : sg version 3.1.22
 
 .. [#] There were 3 changes to sg version 3.1.20 by third parties in the
-       next six linux kernel versions.
+       next six Linux kernel versions.
 
-For reference here is a list of linux kernels in the 2.2 series that had
-new version of the sg driver:
+For reference here is a list of Linux kernels in the 2.2 series that had
+the new version of the sg driver:
 
      - lk 2.2.0 : original sg version [with no version number]
      - lk 2.2.6 : sg version 2.1.31
@@ -106,9 +96,8 @@ new version of the sg driver:
      - lk 2.2.17 : sg version 2.1.39
      - lk 2.2.20 : sg version 2.1.40
 
-The lk 2.5 development series has recently commenced and it currently
-contains sg version 3.5.23 which is functionally equivalent to sg
-version 3.1.22 found in lk 2.4.17.
+The lk 2.5 development series currently contains sg version 3.5.23
+which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17.
 
 
 Douglas Gilbert

[PATCH 08/11] Docs/scsi: g_NCR5380: shorten chapter heading

[Randy Dunlap]

Make the chapter heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Finn Thain <fthain@linux-m68k.org>
Cc: Michael Schmitz <schmitzmic@gmail.com>
---
 Documentation/scsi/g_NCR5380.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/g_NCR5380.rst b/Documentation/scsi/g_NCR5380.rst
--- a/Documentation/scsi/g_NCR5380.rst
+++ b/Documentation/scsi/g_NCR5380.rst
@@ -1,9 +1,9 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>
 
-==========================================
-README file for the Linux g_NCR5380 driver
-==========================================
+================
+g_NCR5380 driver
+================
 
 Copyright |copy| 1993 Drew Eckhard
 

[PATCH 09/11] Docs/scsi: megaraid: clarify chapter heading

[Randy Dunlap]

Include "Megaraid" in the chapter heading so that it is clear
what subject the document is about. This improves viewing in the TOC.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Kashyap Desai <kashyap.desai@broadcom.com>
Cc: Sumit Saxena <sumit.saxena@broadcom.com>
Cc: Shivasharan S <shivasharan.srikanteshwara@broadcom.com>
Cc: megaraidlinux.pdl@broadcom.com
---
 Documentation/scsi/megaraid.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/megaraid.rst b/Documentation/scsi/megaraid.rst
--- a/Documentation/scsi/megaraid.rst
+++ b/Documentation/scsi/megaraid.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==========================
-Notes on Management Module
-==========================
+=================================
+Megaraid Common Management Module
+=================================
 
 Overview
 --------

[PATCH 10/11] Docs/scsi: ncr53c8xx: shorten chapter heading

[Randy Dunlap]

Make the chapter heading concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/scsi/ncr53c8xx.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/ncr53c8xx.rst b/Documentation/scsi/ncr53c8xx.rst
--- a/Documentation/scsi/ncr53c8xx.rst
+++ b/Documentation/scsi/ncr53c8xx.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=================================================
-The Linux NCR53C8XX/SYM53C8XX drivers README file
-=================================================
+===========================
+NCR53C8XX/SYM53C8XX drivers
+===========================
 
 Written by Gerard Roudier <groudier@free.fr>
 

[PATCH 11/11] Docs/scsi: sym53c8xx_2: shorten chapter heading

[Randy Dunlap]

Make the chapter heading concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Matthew Wilcox <willy@infradead.org>
---
 Documentation/scsi/sym53c8xx_2.rst |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff -- a/Documentation/scsi/sym53c8xx_2.rst b/Documentation/scsi/sym53c8xx_2.rst
--- a/Documentation/scsi/sym53c8xx_2.rst
+++ b/Documentation/scsi/sym53c8xx_2.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=========================================
-The Linux SYM-2 driver documentation file
-=========================================
+============
+SYM-2 driver
+============
 
 Written by Gerard Roudier <groudier@free.fr>
 

Re: [PATCH 08/11] Docs/scsi: g_NCR5380: shorten chapter heading

[Finn Thain]

On Thu, 18 May 2023, Randy Dunlap wrote:

> Make the chapter heading be concise yet still descriptive.
> This makes the subsystem table of contents more readable (IMO).
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
> Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
> Cc: linux-scsi@vger.kernel.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Finn Thain <fthain@linux-m68k.org>
> Cc: Michael Schmitz <schmitzmic@gmail.com>

Acked-by: Finn Thain <fthain@linux-m68k.org>

> ---
>  Documentation/scsi/g_NCR5380.rst |    6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff -- a/Documentation/scsi/g_NCR5380.rst b/Documentation/scsi/g_NCR5380.rst
> --- a/Documentation/scsi/g_NCR5380.rst
> +++ b/Documentation/scsi/g_NCR5380.rst
> @@ -1,9 +1,9 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  .. include:: <isonum.txt>
>  
> -==========================================
> -README file for the Linux g_NCR5380 driver
> -==========================================
> +================
> +g_NCR5380 driver
> +================
>  
>  Copyright |copy| 1993 Drew Eckhard
>  
> 

Re: [PATCH 02/11] Docs/scsi: introduction: multiple cleanups

[Finn Thain]

On Thu, 18 May 2023, Randy Dunlap wrote:

> Modify URLs to use https instead of http.
> Remove ancient URLs that don't work.
> Change "scsi" in text to "SCSI".
> Change "cdrom" in text to "CD-ROM".
> Drop the reference to "autoclean" for modules since I can't
>   find it in any current documentation.
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
> Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
> Cc: linux-scsi@vger.kernel.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> ---
>  Documentation/scsi/scsi.rst |   23 ++++++++++-------------
>  1 file changed, 10 insertions(+), 13 deletions(-)
> 
> diff -- a/Documentation/scsi/scsi.rst b/Documentation/scsi/scsi.rst
> --- a/Documentation/scsi/scsi.rst
> +++ b/Documentation/scsi/scsi.rst
> @@ -6,30 +6,28 @@ SCSI subsystem documentation
>  
>  The Linux Documentation Project (LDP) maintains a document describing
>  the SCSI subsystem in the Linux kernel (lk) 2.4 series. See:
> -http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
> +https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
>  and multiple page HTML renderings as well as postscript and pdf.
> -It can also be found at:
> -http://web.archive.org/web/%2E/http://www.torque.net/scsi/SCSI-2.4-HOWTO
>  

That link got corrupted by commit b7223d9bdec. It used to be
http://web.archive.org/web/*/http://www.torque.net/scsi/SCSI-2.4-HOWTO
which does actually work.

FWIW, I'm not in favour of replacing any links with archive.org links 
unless no better source can be found. I am in favour of citations in the 
form of a link with retrieval date. In this context the date can often be 
inferred from commit or release dates.

Therefore, a second commit, 0ea6e611221, could also be reverted with 
regards to this link (if you're planning to edit it). Just my $0.02.

Re: [PATCH 00/11] Documentation/scsi: organize SCSI docs & make more readable

[Martin K. Petersen]

Randy,

> Organize the SCSI documentation into categories instead of
> alphabetically by filename.
>
> Modify several of the document chapter headings so that they are
> shorter and easier to find.
>
> Make several updates to the scsi-generic driver documentation.

Applied to 6.5/scsi-staging, thanks!

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 00/11] Documentation/scsi: organize SCSI docs & make more readable

[Martin K. Petersen]

On Thu, 18 May 2023 14:27:38 -0700, Randy Dunlap wrote:

> Organize the SCSI documentation into categories instead of
> alphabetically by filename.
> 
> Modify several of the document chapter headings so that they are
> shorter and easier to find.
> 
> Make several updates to the scsi-generic driver documentation.
> 
> [...]

Applied to 6.5/scsi-queue, thanks!

[01/11] Docs/scsi: organize the SCSI documentation
        https://git.kernel.org/mkp/scsi/c/682b07d2ff54
[02/11] Docs/scsi: introduction: multiple cleanups
        https://git.kernel.org/mkp/scsi/c/c4e672ac8c49
[03/11] Docs/scsi: arcmsr: use a chapter heading for clarity
        https://git.kernel.org/mkp/scsi/c/1d3e21238f50
[04/11] Docs/scsi: scsi-changer: shorten the chapter heading
        https://git.kernel.org/mkp/scsi/c/a292835f69c6
[05/11] Docs/scsi: dc395x: shorten the chapter heading
        https://git.kernel.org/mkp/scsi/c/573a43f26d80
[06/11] Docs/scsi: scsi_fc_transport: fix typo in heading
        https://git.kernel.org/mkp/scsi/c/66fcd6026c71
[07/11] Docs/scsi: scsi-generic: multiple cleanups
        https://git.kernel.org/mkp/scsi/c/8ebddfeef518
[08/11] Docs/scsi: g_NCR5380: shorten chapter heading
        https://git.kernel.org/mkp/scsi/c/b636a0297e4f
[09/11] Docs/scsi: megaraid: clarify chapter heading
        https://git.kernel.org/mkp/scsi/c/0176d3395a3a
[10/11] Docs/scsi: ncr53c8xx: shorten chapter heading
        https://git.kernel.org/mkp/scsi/c/7c891fe3db3a
[11/11] Docs/scsi: sym53c8xx_2: shorten chapter heading
        https://git.kernel.org/mkp/scsi/c/f047d1e38bdf

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 05/11] Docs/scsi: dc395x: shorten the chapter heading

[Bagas Sanjaya]

On 5/19/23 04:27, Randy Dunlap wrote:
> -======================================
> -README file for the dc395x SCSI driver
> -======================================
> +==================
> +dc395x SCSI driver
> +==================
>  

Acked-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara