scsi: convert to rst for documenation
Subsystems (3)
PATCH 1/1 scsi: convert to rst for documenation
- Update to the link in documenation
- Remove trailing white space
- Adaptation the sphinx doc syntax
---
Documentation/index.rst | 1 +
Documentation/scsi/index.rst | 29 +
.../scsi/link_power_management_policy.rst | 22 +
.../scsi/link_power_management_policy.txt | 19 -
.../scsi/{scsi-changer.txt => scsi-changer.rst} | 108 +-
.../scsi/{scsi-generic.txt => scsi-generic.rst} | 74 +-
.../{scsi-parameters.txt => scsi-parameters.rst} | 30 +-
Documentation/scsi/{scsi.txt => scsi.rst} | 4 +-
Documentation/scsi/scsi_eh.rst | 533 ++++++++
Documentation/scsi/scsi_eh.txt | 475 -------
...scsi_fc_transport.txt => scsi_fc_transport.rst} | 94 +-
Documentation/scsi/scsi_mid_low_api.rst | 1357 ++++++++++++++++++++
Documentation/scsi/scsi_mid_low_api.txt | 1279 ------------------
13 files changed, 2120 insertions(+), 1905 deletions(-)
create mode 100644 Documentation/scsi/index.rst
create mode 100644 Documentation/scsi/link_power_management_policy.rst
delete mode 100644 Documentation/scsi/link_power_management_policy.txt
rename Documentation/scsi/{scsi-changer.txt => scsi-changer.rst} (71%)
rename Documentation/scsi/{scsi-generic.txt => scsi-generic.rst} (70%)
rename Documentation/scsi/{scsi-parameters.txt => scsi-parameters.rst} (82%)
rename Documentation/scsi/{scsi.txt => scsi.rst} (93%)
create mode 100644 Documentation/scsi/scsi_eh.rst
delete mode 100644 Documentation/scsi/scsi_eh.txt
rename Documentation/scsi/{scsi_fc_transport.txt => scsi_fc_transport.rst} (93%)
create mode 100644 Documentation/scsi/scsi_mid_low_api.rst
delete mode 100644 Documentation/scsi/scsi_mid_low_api.txtDocumentation/index.rst +1 -0
@@ -95,6 +95,7 @@ needed). input/index hwmon/index gpu/index + scsi/index security/index sound/index crypto/index
Documentation/scsi/index.rst new file +29 -0
@@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux Kernel SCSI Subsystem Documentation +========================================= + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 3 + + scsi + scsi-generic + scsi-parameters + scsi_mid_low_api + scsi_eh + scsi-changer + scsi_fc_transport + link_power_management_policy + +.. only:: html and subproject + + Indices + ======= + + * :ref:`genindex`
Documentation/scsi/link_power_management_policy.rst new file +22 -0
@@ -0,0 +1,22 @@ +SCSI Power Management Policy +============================ + +This parameter allows the user to set the link (interface) power management. +There are 3 possible options: + ++-------------------+------------------------------------------------------+ +| Value | Effect | ++===================+======================================================+ +| min_power | Tell the controller to try to make the link use the | +| | least possible power when possible. This may | +| | sacrifice some performance due to increased latency | +| | when coming out of lower power states. | ++-------------------+------------------------------------------------------+ +| max_performance | Generally, this means no power management. Tell | +| | the controller to have performance be a priority | +| | over power management. | ++-------------------+------------------------------------------------------+ +| medium_power | Tell the controller to enter a lower power state | +| | when possible, but do not enter the lowest power | +| | state, thus improving latency over min_power setting.| ++-------------------+------------------------------------------------------+
Documentation/scsi/link_power_management_policy.txt deleted +0 -19
@@ -1,19 +0,0 @@ -This parameter allows the user to set the link (interface) power management. -There are 3 possible options: - -Value Effect ----------------------------------------------------------------------------- -min_power Tell the controller to try to make the link use the - least possible power when possible. This may - sacrifice some performance due to increased latency - when coming out of lower power states. - -max_performance Generally, this means no power management. Tell - the controller to have performance be a priority - over power management. - -medium_power Tell the controller to enter a lower power state - when possible, but do not enter the lowest power - state, thus improving latency over min_power setting. - -
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +57 -51
148 lines not on this page · raw message
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +42 -32
124 lines not on this page · raw message
Documentation/scsi/scsi-parameters.rst renamed from Documentation/scsi/scsi-parameters.txt +22 -8
@@ -1,16 +1,30 @@ - SCSI Kernel Parameters - ~~~~~~~~~~~~~~~~~~~~~~ +SCSI Kernel Parameters +====================== -See Documentation/admin-guide/kernel-parameters.rst for general information on -specifying module parameters. +See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command -"modinfo -p ${modulename}" shows a current list of all parameters of a loadable + +.. code-block:: bash + + modinfo -p ${modulename} + +shows a current list of all parameters of a loadable module. Loadable modules, after being loaded into the running kernel, also -reveal their parameters in /sys/module/${modulename}/parameters/. Some of these -parameters may be changed at runtime by the command -"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". +reveal their parameters in + +.. code-block:: bash + + /sys/module/${modulename}/parameters/ + +Some of these parameters may be changed at runtime by the command + +.. code-block:: bash + + echo -n ${value} > /sys/module/${modulename}/parameters/${parm} +.. code-block:: text advansys= [HW,SCSI] See header of drivers/scsi/advansys.c.
Documentation/scsi/scsi.rst renamed from Documentation/scsi/scsi.txt +1 -3
@@ -4,11 +4,9 @@ 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 and multiple page HTML renderings as well as postscript and pdf. -It can also be found at: -http://web.archive.org/web/*/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 different ways depending upon the needs of the end user. To understand your options, we should first define a few terms.
Documentation/scsi/scsi_eh.rst new file +533 -0
533 lines not on this page · raw message
Documentation/scsi/scsi_eh.txt deleted +0 -475
475 lines not on this page · raw message
Documentation/scsi/scsi_fc_transport.rst renamed from Documentation/scsi/scsi_fc_transport.txt +56 -38
204 lines not on this page · raw message
Documentation/scsi/scsi_mid_low_api.rst new file +1357 -0
1,357 lines not on this page · raw message
Documentation/scsi/scsi_mid_low_api.txt deleted +0 -1279
32 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.11.0
Part of the diff is not shown here. View the raw message.
Jonathan Corbet
maintainerQuoted 5 lines · On Sat, 22 Jun 2019 22:19:47 +0700 Phong Tran <tranmanphong at gmail.com> wrote:
- Update to the link in documenation
- Remove trailing white space
- Adaptation the sphinx doc syntaxSigned-off-by Phong Tran <tranmanphong at gmail.com>
Thanks for working to improve the documentation! That said, I think this patch needs a fair amount of work before we are ready to accept it. I'll only get partway in, but it should be enough to start with.
The first overall thing I would like to point out (and hopefully the SCSI folks won't fight me too much on this) is that Documentation/scsi is the wrong place for much of this stuff. We are doing our best to organize the documentation with the audience in mind. So, for example, documents that are of interest to system administrators should go into Documentation/admin-guide. Information for driver developers should go in Documentation/driver-api. And so on.
[...]
Documentation/scsi/link_power_management_policy.rst line 5
Quoted 11 lines
Documentation/scsi/link_power_management_policy.rst new file +5
-0@@ -0,0 +1,22 @@ +SCSI Power Management Policy +============================ + +This parameter allows the user to set the link (interface) power management. +There are 3 possible options:
This isn't your fault, but...*which* parameter allows this? The document describes the values, but not where they can be set. That makes it less than fully useful.
Quoted 16 lines
Documentation/scsi/link_power_management_policy.rst new file +16
-0++-------------------+------------------------------------------------------+ +| Value | Effect | ++===================+======================================================+ +| min_power | Tell the controller to try to make the link use the | +| | least possible power when possible. This may | +| | sacrifice some performance due to increased latency | +| | when coming out of lower power states. | ++-------------------+------------------------------------------------------+ +| max_performance | Generally, this means no power management. Tell | +| | the controller to have performance be a priority | +| | over power management. | ++-------------------+------------------------------------------------------+ +| medium_power | Tell the controller to enter a lower power state | +| | when possible, but do not enter the lowest power | +| | state, thus improving latency over min_power setting.| ++-------------------+------------------------------------------------------+
[...]
Quoted 22 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-2@@ -1,4 +1,3 @@ - README for the SCSI media changer driver ========================================@@ -10,7 +9,7 @@ common small CD-ROM changers, neither one-lun-per-slot SCSI changers nor IDE drives. Userland tools available from here: - http://linux.bytesex.org/misc/changer.html + http://linux.bytesex.org/misc/changer.html General Information
Documentation/scsi/scsi-changer.rst The SCSI changer model is complex, compared to - for example - IDE-CD · line 30
Quoted 4 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-0@@ -28,15 +27,17 @@ The SCSI changer model is complex, compared to - for example - IDE-CD changers. But it allows to handle nearly all possible cases. It knows 4 different types of changer elements: +::
Two notes:
- You can put the double colon on the line above ("...elements::") and don't need to make a separate line for it.
- But, more to the point, please avoid the temptation to use a literal block for something that doesn't actually require that treatment. This should be reworked as an RST definition list.
Quoted 11 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +2
-2media transport - this one shuffles around the media, i.e. the transport arm. Also known as "picker". storage - a slot which can hold a media. import/export - the same as above, but is accessible from outside, i.e. there the operator (you !) can use this to fill in and remove media from the changer. - Sometimes named "mailslot". + Sometimes named "mailslot". data transfer - this is the device which reads/writes, i.e. the - CD-ROM / Tape / whatever drive. + CD-ROM / Tape / whatever drive.
[...]
Quoted 29 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +7
-5@@ -1,8 +1,10 @@ - Notes on Linux SCSI Generic (sg) driver - --------------------------------------- - 20020126 +======================================= +Notes on Linux 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 is more generalized (but lower level) than its siblings and tends to be@@ -16,20 +18,20 @@ and examples. Major versions of the sg driver -=============================== +------------------------------- There are three major versions of sg found in the linux kernel (lk):
Documentation/scsi/scsi-generic.rst and examples. · line 28
Quoted 10 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +4
-4- - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . - It is based in the sg_header interface structure. + - 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 - an extended version of the sg_header interface structure. + an extended version of the sg_header interface structure. - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). - It adds the sg_io_hdr interface structure. + It adds the sg_io_hdr interface structure.
Perhaps we don't *really* need to preserve information about what versions were around in the 1990's?
Documentation/scsi/scsi-generic.rst and examples. · line 35
Quoted 7 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +2
-2Sg driver documentation -======================= +----------------------- The most recent documentation of the sg driver is kept at the Linux -Documentation Project's (LDP) site: +Documentation Project's (LDP) site: http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO
That document claims to have been last updated in 2002. Is there really nothing more recent than that?
Documentation/scsi/scsi-generic.rst and examples. · line 36
Quoted 1 line
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +0
-0This describes the sg version 3 driver found in the lk 2.4 series.
...and it's unclear to me that users of the 5.x kernel are much concerned with what was found in 2.4.
That is the problem with this document in general. I suspect that about the only useful information left in it is the location of the sg3_utils source. I honestly don't think that it helps the documentation that much to carry forward ancient information to the RST format.
Of course, doing this right by deleting obsolete information and updating the documents to reflect current reality is a *lot* more work. Probably far more than you were thinking of signing up for. If you were willing to work on this, there may be somebody from the SCSI community who would be in a position to help you with it.
Unfortunately, the SCSI community probably did not see this patch because you didn't copy the linux-scsi list. I'll fix that now, but they will not have seen your original patch. You should be sure to include them on future postings.
I would like to make a suggestion, in addition to all of the above: rather than trying to do a mass conversion in a single 4000-line patch, start with a single file and post a patch doing just that one, being sure to include the linux-scsi list. That will give everybody something more workable to start with.
Thanks,
jon
Douglas Gilbert
maintainerPlease see below.
Quoted 151 lines · Jonathan Corbet
Quoted 5 lines · On Sat, 22 Jun 2019 22:19:47 +0700 Phong Tran <tranmanphong at gmail.com> wrote:
- Update to the link in documenation
- Remove trailing white space
- Adaptation the sphinx doc syntaxSigned-off-by Phong Tran <tranmanphong at gmail.com>Thanks for working to improve the documentation! That said, I think this patch needs a fair amount of work before we are ready to accept it. I'll only get partway in, but it should be enough to start with.
The first overall thing I would like to point out (and hopefully the SCSI folks won't fight me too much on this) is that
Documentation/scsiis the wrong place for much of this stuff. We are doing our best to organize the documentation with the audience in mind. So, for example, documents that are of interest to system administrators should go intoDocumentation/admin-guide. Information for driver developers should go inDocumentation/driver-api. And so on.[...]
Documentation/scsi/link_power_management_policy.rst line 5
Quoted 11 lines
Documentation/scsi/link_power_management_policy.rst new file +5
-0@@ -0,0 +1,22 @@ +SCSI Power Management Policy +============================ +Its +This parameter allows the user to set the link (interface) power management. +There are 3 possible options:This isn't your fault, but...*which* parameter allows this? The document describes the values, but not where they can be set. That makes it less than fully useful.
Quoted 16 lines
Documentation/scsi/link_power_management_policy.rst new file +16
-0++-------------------+------------------------------------------------------+ +| Value | Effect | ++===================+======================================================+ +| min_power | Tell the controller to try to make the link use the | +| | least possible power when possible. This may | +| | sacrifice some performance due to increased latency | +| | when coming out of lower power states. | ++-------------------+------------------------------------------------------+ +| max_performance | Generally, this means no power management. Tell | +| | the controller to have performance be a priority | +| | over power management. | ++-------------------+------------------------------------------------------+ +| medium_power | Tell the controller to enter a lower power state | +| | when possible, but do not enter the lowest power | +| | state, thus improving latency over min_power setting.| ++-------------------+------------------------------------------------------+[...]
Quoted 22 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-2@@ -1,4 +1,3 @@ - README for the SCSI media changer driver ========================================@@ -10,7 +9,7 @@ common small CD-ROM changers, neither one-lun-per-slot SCSI changers nor IDE drives. Userland tools available from here: - http://linux.bytesex.org/misc/changer.html + http://linux.bytesex.org/misc/changer.html General InformationDocumentation/scsi/scsi-changer.rst The SCSI changer model is complex, compared to - for example - IDE-CD · line 30
Quoted 4 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-0@@ -28,15 +27,17 @@ The SCSI changer model is complex, compared to - for example - IDE-CD changers. But it allows to handle nearly all possible cases. It knows 4 different types of changer elements: +::Two notes:
- You can put the double colon on the line above ("...elements::") and don't need to make a separate line for it.
- But, more to the point, please avoid the temptation to use a literal block for something that doesn't actually require that treatment. This should be reworked as an RST definition list.
Quoted 11 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +2
-2media transport - this one shuffles around the media, i.e. the transport arm. Also known as "picker". storage - a slot which can hold a media. import/export - the same as above, but is accessible from outside, i.e. there the operator (you !) can use this to fill in and remove media from the changer. - Sometimes named "mailslot". + Sometimes named "mailslot". data transfer - this is the device which reads/writes, i.e. the - CD-ROM / Tape / whatever drive. + CD-ROM / Tape / whatever drive.[...]
Quoted 29 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +7
-5@@ -1,8 +1,10 @@ - Notes on Linux SCSI Generic (sg) driver - --------------------------------------- - 20020126 +======================================= +Notes on Linux 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 is more generalized (but lower level) than its siblings and tends to be@@ -16,20 +18,20 @@ and examples. Major versions of the sg driver -=============================== +------------------------------- There are three major versions of sg found in the linux kernel (lk):Documentation/scsi/scsi-generic.rst and examples. · line 28
Quoted 10 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +4
-4- - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . - It is based in the sg_header interface structure. + - 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 - an extended version of the sg_header interface structure. + an extended version of the sg_header interface structure. - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). - It adds the sg_io_hdr interface structure. + It adds the sg_io_hdr interface structure.Perhaps we don't *really* need to preserve information about what versions were around in the 1990's?
Quoted 10 lines
Documentation/scsi/scsi-generic.rst and examples. · line 35
Quoted 7 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +2
-2Sg driver documentation -======================= +----------------------- The most recent documentation of the sg driver is kept at the Linux -Documentation Project's (LDP) site: +Documentation Project's (LDP) site: http://www.tldp.org/HOWTO/SCSI-Generic-HOWTOThat document claims to have been last updated in 2002. Is there really nothing more recent than that?
http://sg.danny.cz/sg/sg_v40.html
Last updated: yesterday.
Quoted 9 lines
Documentation/scsi/scsi-generic.rst and examples. · line 36
Quoted 1 line
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +0
-0This describes the sg version 3 driver found in the lk 2.4 series....and it's unclear to me that users of the 5.x kernel are much concerned with what was found in 2.4.
That is the problem with this document in general. I suspect that about the only useful information left in it is the location of the
sg3_utilssource. I honestly don't think that it helps the documentation that much to carry forward ancient information to the RST format.
That old document is pretty damn accurate. At least one feature was quietly removed over the years. And some ioctls no longer do anything (see the ioctl table towards the end of the above document). The sg driver's public interface is a lot more stable than the kernel API behind it :-) . There is driver in FreeBSD that implements that interface, it's called scsi_sg .
Quoted 5 lines
Of course, doing this right by deleting obsolete information and updating the documents to reflect current reality is a *lot* more work. Probably far more than you were thinking of signing up for. If you were willing to work on this, there may be somebody from the SCSI community who would be in a position to help you with it.
Hmmm.
Quoted 10 lines
Unfortunately, the SCSI community probably did not see this patch because you didn't copy the linux-scsi list. I'll fix that now, but they will not have seen your original patch. You should be sure to include them on future postings.
I would like to make a suggestion, in addition to all of the above: rather than trying to do a mass conversion in a single 4000-line patch, start with a single file and post a patch doing just that one, being sure to include the linux-scsi list. That will give everybody something more workable to start with.
Editorial comments welcome.
Martin Petersen wants to see that document reworked in order to market the new features that I am proposing. My approach is to document the code that I have in front of me ***, plus add a bit of historical context.
I chose that format so I could add diagrams (using Libreoffice writer). Do those diagrams help?
Doug Gilbert
*** it helps me find bugs in my code and my documentation. I'm also testing
the code at the same time.
Quoted 14 lines · Jonathan Corbet
Quoted 5 lines · On Sat, 22 Jun 2019 22:19:47 +0700 Phong Tran <tranmanphong at gmail.com> wrote:
- Update to the link in documenation
- Remove trailing white space
- Adaptation the sphinx doc syntaxSigned-off-by Phong Tran <tranmanphong at gmail.com>Thanks for working to improve the documentation! That said, I think this patch needs a fair amount of work before we are ready to accept it. I'll only get partway in, but it should be enough to start with.
Quoted 8 lines
The first overall thing I would like to point out (and hopefully the SCSI folks won't fight me too much on this) is that
Documentation/scsiis the wrong place for much of this stuff. We are doing our best to organize the documentation with the audience in mind. So, for example, documents that are of interest to system administrators should go intoDocumentation/admin-guide. Information for driver developers should go inDocumentation/driver-api. And so on.
in my understanding,
link_power_management_policy.txt and scsi-parameters.txt should be in Documentation/admin-guide correct?
scsi_mid_low_api.txt should be moved to Documentation/driver-api?
Quoted 151 lines
[...]
Documentation/scsi/link_power_management_policy.rst line 5
Quoted 11 lines
Documentation/scsi/link_power_management_policy.rst new file +5
-0@@ -0,0 +1,22 @@ +SCSI Power Management Policy +============================ + +This parameter allows the user to set the link (interface) power management. +There are 3 possible options:This isn't your fault, but...*which* parameter allows this? The document describes the values, but not where they can be set. That makes it less than fully useful.
Quoted 16 lines
Documentation/scsi/link_power_management_policy.rst new file +16
-0++-------------------+------------------------------------------------------+ +| Value | Effect | ++===================+======================================================+ +| min_power | Tell the controller to try to make the link use the | +| | least possible power when possible. This may | +| | sacrifice some performance due to increased latency | +| | when coming out of lower power states. | ++-------------------+------------------------------------------------------+ +| max_performance | Generally, this means no power management. Tell | +| | the controller to have performance be a priority | +| | over power management. | ++-------------------+------------------------------------------------------+ +| medium_power | Tell the controller to enter a lower power state | +| | when possible, but do not enter the lowest power | +| | state, thus improving latency over min_power setting.| ++-------------------+------------------------------------------------------+[...]
Quoted 22 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-2@@ -1,4 +1,3 @@ - README for the SCSI media changer driver ========================================@@ -10,7 +9,7 @@ common small CD-ROM changers, neither one-lun-per-slot SCSI changers nor IDE drives. Userland tools available from here: - http://linux.bytesex.org/misc/changer.html + http://linux.bytesex.org/misc/changer.html General InformationDocumentation/scsi/scsi-changer.rst The SCSI changer model is complex, compared to - for example - IDE-CD · line 30
Quoted 4 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +1
-0@@ -28,15 +27,17 @@ The SCSI changer model is complex, compared to - for example - IDE-CD changers. But it allows to handle nearly all possible cases. It knows 4 different types of changer elements: +::Two notes:
- You can put the double colon on the line above ("...elements::") and don't need to make a separate line for it.
- But, more to the point, please avoid the temptation to use a literal block for something that doesn't actually require that treatment. This should be reworked as an RST definition list.
Quoted 11 lines
Documentation/scsi/scsi-changer.rst renamed from Documentation/scsi/scsi-changer.txt +2
-2media transport - this one shuffles around the media, i.e. the transport arm. Also known as "picker". storage - a slot which can hold a media. import/export - the same as above, but is accessible from outside, i.e. there the operator (you !) can use this to fill in and remove media from the changer. - Sometimes named "mailslot". + Sometimes named "mailslot". data transfer - this is the device which reads/writes, i.e. the - CD-ROM / Tape / whatever drive. + CD-ROM / Tape / whatever drive.[...]
Quoted 29 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +7
-5@@ -1,8 +1,10 @@ - Notes on Linux SCSI Generic (sg) driver - --------------------------------------- - 20020126 +======================================= +Notes on Linux 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 is more generalized (but lower level) than its siblings and tends to be@@ -16,20 +18,20 @@ and examples. Major versions of the sg driver -=============================== +------------------------------- There are three major versions of sg found in the linux kernel (lk):Documentation/scsi/scsi-generic.rst and examples. · line 28
Quoted 10 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +4
-4- - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . - It is based in the sg_header interface structure. + - 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 - an extended version of the sg_header interface structure. + an extended version of the sg_header interface structure. - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). - It adds the sg_io_hdr interface structure. + It adds the sg_io_hdr interface structure.Perhaps we don't *really* need to preserve information about what versions were around in the 1990's?
Documentation/scsi/scsi-generic.rst and examples. · line 35
Quoted 7 lines
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +2
-2Sg driver documentation -======================= +----------------------- The most recent documentation of the sg driver is kept at the Linux -Documentation Project's (LDP) site: +Documentation Project's (LDP) site: http://www.tldp.org/HOWTO/SCSI-Generic-HOWTOThat document claims to have been last updated in 2002. Is there really nothing more recent than that?
Documentation/scsi/scsi-generic.rst and examples. · line 36
Quoted 1 line
Documentation/scsi/scsi-generic.rst renamed from Documentation/scsi/scsi-generic.txt +0
-0This describes the sg version 3 driver found in the lk 2.4 series....and it's unclear to me that users of the 5.x kernel are much concerned with what was found in 2.4.
That is the problem with this document in general. I suspect that about the only useful information left in it is the location of the
sg3_utilssource. I honestly don't think that it helps the documentation that much to carry forward ancient information to the RST format.
Quoted 6 lines
Of course, doing this right by deleting obsolete information and updating the documents to reflect current reality is a *lot* more work. Probably far more than you were thinking of signing up for. If you were willing to work on this, there may be somebody from the SCSI community who would be in a position to help you with it.
yes! I would greatly appreciate
Quoted 5 lines
Unfortunately, the SCSI community probably did not see this patch because you didn't copy the linux-scsi list. I'll fix that now, but they will not have seen your original patch. You should be sure to include them on future postings.
Note in next post.
Quoted 3 lines
I would like to make a suggestion, in addition to all of the above: rather than trying to do a mass conversion in a single 4000-line patch, start with a single file and post a patch doing just that one, being sure to include
yes will send a new patch for each file.
Quoted 6 lines
the linux-scsi list. That will give everybody something more workable to start with.
Thanks,
jon