Skip to contentSkip to conversation

Documentation: Converted .txt file to .rst Changed the file

PATCH Superseded sushmaunnibhavi425 at gmail.com (Sushma Unnibhavi) 1 participant 2 messages Jun 29, 2019 Documentation

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

sushmaunnibhavi425 at gmail.com (Sushma Unnibhavi)

#0 lore raw

PATCH v2 1/1 Documentation: Converted .txt file to .rst Changed the file

aha152x.txt into a .rst form and renamed aha152x.txt to aha152x.rst

Signed-off-by Sushma Unnibhavi <sushmaunnibhavi425 at gmail.com>
---
 Documentation/scsi/aha152x.rst | 121 +++++++++++++++++++--------------
 1 file changed, 70 insertions(+), 51 deletions(-)
Documentation/scsi/aha152x.rst +70 -51
index b3646a5948d9..207994d94b91 100644
@@ -1,5 +1,7 @@
-$Id: README.aha152x,v 1.2 1999/12/25 15:32:30 fischer Exp fischer $
+
+=====================================================
 Adaptec AHA-1520/1522 SCSI driver for Linux (aha152x)
+=====================================================
 
 Copyright 1993-1999 J?rgen Fischer <fischer at norbit.de>
 TC1550 patches by Luuk van Dijk (ldz at xs4all.nl)
@@ -14,61 +16,78 @@ less polling loops), has slightly higher throughput  (at
 least on my ancient test box; a i486/33Mhz/20MB).
 
 
+########################
 CONFIGURATION ARGUMENTS:
---------------------------------------------------------------------------------
-|IOPORT     |   base io address                        | (0x340/0x140)         |
---------------------------------------------------------------------------------
-|IRQ        |  interrupt level                         | (9-12; default 11)    |
---------------------------------------------------------------------------------
-|SCSI_ID    |  scsi id of controller                   | (0-7; default 7)      |
---------------------------------------------------------------------------------
-|RECONNECT  |  allow targets to disconnect from the bus| (0/1; default 1 [on]) |
---------------------------------------------------------------------------------
-|PARITY     |  enable parity checking                  | (0/1; default 1 [on]) |
---------------------------------------------------------------------------------
-|SYNCHRONOUS|  enable synchronous transfers            | (0/1; default 1 [on]) |
---------------------------------------------------------------------------------
-|DELAY:     |  bus reset delay                         | (default 100)         |
---------------------------------------------------------------------------------
-|EXT_TRANS: |  enable extended translation             | (0/1: default 0 [off])|
-|           |  (see NOTES)                             |                       |
---------------------------------------------------------------------------------
+########################
+
+IOPORT-base io address-(0x340/0x140) 
+                               
+IRQ-interrupt level-(9-12; default 11)
+
+SCSI_ID-scsi id of controller-(0-7; default 7)
+
+RECONNECT-allow targets to disconnect from the bus-(0/1; default 1 [on])
+
+PARITY-enable parity checking-(0/1; default 1 [on])
+
+SYNCHRONOUS-enable synchronous transfers-(0/1; default 1 [on])
+
+DELAY-bus reset delay-(default 100)         
+
+EXT_TRANS-enable extended translation-(0/1: default 0 [off])(see NOTES)
+
+##########################################################################
 COMPILE TIME CONFIGURATION (go into AHA152X in drivers/scsi/Makefile):
+##########################################################################
+
+
+1. DAUTOCONF :
 
--DAUTOCONF
- use configuration the controller reports (AHA-152x only)
+   use configuration the controller reports (AHA-152x only)
 
--DSKIP_BIOSTEST
- Don't test for BIOS signature (AHA-1510 or disabled BIOS)
+2. DSKIP_BIOSTEST : 
+   
+   Don't test for BIOS signature (AHA-1510 or disabled BIOS)
 
--DSETUP0="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the first controller 
+3. DSETUP0 :
 
--DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the second controller
+   "{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+   override for the first controller
 
--DAHA152X_DEBUG
- enable debugging output
+4. DSETUP1 : 
 
--DAHA152X_STAT
- enable some statistics
+   "{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+   override for the second controller
 
+5. DAHA152X_DEBUG :
 
+   enable debugging output
+
+6. DAHA152X_STAT : 
+
+   enable some statistics
+
+###########################
 LILO COMMAND LINE OPTIONS:
+###########################
 
 aha152x=<IOPORT>[,<IRQ>[,<SCSI-ID>[,<RECONNECT>[,<PARITY>[,<SYNCHRONOUS>[,<DELAY> [,<EXT_TRANS]]]]]]]
 
-The normal configuration can be overridden by specifying a command 
-line.When you do this, the  BIOS  test  is skipped. Entered values 
-have to be valid (known).  Don't use values that  aren't supported 
+
+
+The normal configuration can be overridden by specifying a command
+line.When you do this, the  BIOS  test  is skipped. Entered values
+have to be valid (known).  Don't use values that  aren't supported
 under normal operation.  If  you think that you need other values:
 contact me. For two controllers  use  the aha152x statement twice.
 
-
+#################################
 SYMBOLS FOR MODULE CONFIGURATION:
+#################################
 
+****************************
 Choose from 2 alternatives:
-
+****************************
 1. specify everything (old)
 
    aha152x=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
@@ -107,22 +126,22 @@ Choose from 2 alternatives:
 
 If you use both alternatives the first will be taken.
 
-
-NOTES ON EXT_TRANS: 
-
+####################
+NOTES ON EXT_TRANS:
+####################
 SCSI uses block numbers to address blocks/sectors on a device.
 The BIOS uses a cylinder/head/sector addressing scheme (C/H/S)
-scheme instead.  DOS expects a BIOS or driver that understands 
+scheme instead.  DOS expects a BIOS or driver that understands
 this C/H/S addressing.
 
-The number of cylinders/heads/sectors is called geometry and is 
-required as base for requests in  C/H/S  addressing.  SCSI only 
+The number of cylinders/heads/sectors is called geometry and is
+required as base for requests in  C/H/S  addressing.  SCSI only
 knows about the total capacity  of  disks  in blocks (sectors).
 
 Therefore the SCSI BIOS/DOS driver has to calculate a logical/virtual
-geometry just  to  be  able  to  support  that addressing scheme. The 
-geometry returned by the SCSI BIOS is  a  pure  calculation  and  has 
-nothing to do with the  real/physical  geometry  of  the  disk (which 
+geometry just  to  be  able  to  support  that addressing scheme. The
+geometry returned by the SCSI BIOS is  a  pure  calculation  and  has
+nothing to do with the  real/physical  geometry  of  the  disk (which
 is usually irrelevant anyway).
 
 Basically this has no impact at all on Linux, because it also  uses block
@@ -145,7 +164,7 @@ BIOSes of some  newer controllers based on the AIC-6260/6360 support
 extended  translation.  This means that the BIOS uses 255 for heads,
 63 for  sectors  and then divides the capacity of the disk by 255*63
 (about 8 MB), as soon it sees a disk greater than 1 GB. That results
-in a maximum of about 8 GB addressable  diskspace  in the  partition 
+in a maximum of about 8 GB addressable  diskspace  in the  partition
 table (but there are already bigger disks out there today).
 
 To make it even more complicated the translation mode might/might
@@ -154,12 +173,12 @@ not be configurable in certain BIOS setups.
 This driver does some more or less failsafe guessing to get the
 geometry right in most cases:
 
-- for disks<1GB: 
+- for disks<1GB:
   -use default translation (C/32/64)
 
 - for disks>1GB:
   - take current geometry from the partition table (using scsicam_bios_param
-    and accept only `valid' geometries, ie. either (C/32/64) or (C/63/255)). 
+    and accept only `valid' geometries, ie. either (C/32/64) or (C/63/255)).
 	This can be extended translation even if it's not enabled in the driver.
 
   - if that fails, take extended translation if  enabled  by override,
@@ -167,9 +186,9 @@ geometry right in most cases:
     ask the user for verification.  This might on  not yet partitioned
     disks.
 
-
+#################
 REFERENCES USED:
-
+#################
  "AIC-6260 SCSI Chip Specification", Adaptec Corporation.
 
  "SCSI COMPUTER SYSTEM INTERFACE - 2 (SCSI-2)", X3T9.2/86-109 rev. 10h
@@ -184,7 +203,7 @@ REFERENCES USED:
 
  Drew Eckhardt (drew at cs.colorado.edu)
 
- Eric Youngdale (eric at andante.org) 
+ Eric Youngdale (eric at andante.org)
 
  special thanks to Eric Youngdale for the free(!) supplying the
  documentation on the chip.
Signature · 1 line
2.17.1
#1 lore raw

PATCH v2 1/1 Documentation: Converted .txt file to .rst Changed the file

Em Sat, 29 Jun 2019 15:23:10 +0530
Sushma Unnibhavi <sushmaunnibhavi425 at gmail.com> escreveu:

Quoted 3 lines

aha152x.txt into a .rst form and renamed aha152x.txt to aha152x.rst

Signed-off-by Sushma Unnibhavi <sushmaunnibhavi425 at gmail.com>

Please improve the description. There are lots of such examples of a good description on my conversion tree:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_next_v1

Quoted 32 lines
---
 Documentation/scsi/aha152x.rst | 121 +++++++++++++++++++--------------
 1 file changed, 70 insertions(+), 51 deletions(-)
Documentation/scsi/aha152x.rst +4 -10
index b3646a5948d9..207994d94b91 100644
@@ -1,5 +1,7 @@
-$Id: README.aha152x,v 1.2 1999/12/25 15:32:30 fischer Exp fischer $
+
+=====================================================
 Adaptec AHA-1520/1522 SCSI driver for Linux (aha152x)
+=====================================================
 
 Copyright 1993-1999 J?rgen Fischer <fischer at norbit.de>
 TC1550 patches by Luuk van Dijk (ldz at xs4all.nl)
@@ -14,61 +16,78 @@ less polling loops), has slightly higher throughput  (at
 least on my ancient test box; a i486/33Mhz/20MB).
 
 
+########################
 CONFIGURATION ARGUMENTS:
---------------------------------------------------------------------------------
-|IOPORT     |   base io address                        | (0x340/0x140)         |
---------------------------------------------------------------------------------
-|IRQ        |  interrupt level                         | (9-12; default 11)    |
---------------------------------------------------------------------------------
-|SCSI_ID    |  scsi id of controller                   | (0-7; default 7)      |
---------------------------------------------------------------------------------
-|RECONNECT  |  allow targets to disconnect from the bus| (0/1; default 1 [on]) |
---------------------------------------------------------------------------------

Documentation/scsi/aha152x.rst less polling loops), has slightly higher throughput (at · line 21

Quoted 10 lines
Documentation/scsi/aha152x.rst +1 -9
-|PARITY     |  enable parity checking                  | (0/1; default 1 [on]) |
---------------------------------------------------------------------------------
-|SYNCHRONOUS|  enable synchronous transfers            | (0/1; default 1 [on]) |
---------------------------------------------------------------------------------
-|DELAY:     |  bus reset delay                         | (default 100)         |
---------------------------------------------------------------------------------
-|EXT_TRANS: |  enable extended translation             | (0/1: default 0 [off])|
-|           |  (see NOTES)                             |                       |
---------------------------------------------------------------------------------
+########################

We only use two bars like:

###
Foo
###

for the document title.

There's a suggestion about what markups we use for each level of the docs:

https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

I actually do it a little different myself, but the idea is that we use symbols in a order where the top level gets bolder and the lower levels get lighter.

Also, it would be better to place the titles on lowercase, and without any punctuation after the title.

So, the best here would be to use:

Configuration Arguments
=======================

Quoted 6 lines
Documentation/scsi/aha152x.rst +6 -0
+
+IOPORT-base io address-(0x340/0x140) 
+                               
+IRQ-interrupt level-(9-12; default 11)
+
+SCSI_ID-scsi id of controller-(0-7; default 7)

Documentation/scsi/aha152x.rst less polling loops), has slightly higher throughput (at · line 37

Quoted 10 lines
Documentation/scsi/aha152x.rst +10 -0
+
+RECONNECT-allow targets to disconnect from the bus-(0/1; default 1 [on])
+
+PARITY-enable parity checking-(0/1; default 1 [on])
+
+SYNCHRONOUS-enable synchronous transfers-(0/1; default 1 [on])
+
+DELAY-bus reset delay-(default 100)         
+
+EXT_TRANS-enable extended translation-(0/1: default 0 [off])(see NOTES)

Please preserve the document original style as much as possible. In this specific case, you should keep it as a table. A simple replacement of "-" to "+" at the crossing lines is enough for this table to be recognized as such, e. g.:

  +-----------+------------------------------------------+-----------------------+
  |IOPORT     |   base io address                        | (0x340/0x140)         |
  +-----------+------------------------------------------+-----------------------+
  |IRQ        |  interrupt level                         | (9-12; default 11)    |
  +-----------+------------------------------------------+-----------------------+

Documentation/scsi/aha152x.rst less polling loops), has slightly higher throughput (at · line 46

Quoted 11 lines
Documentation/scsi/aha152x.rst +7 -2
+
+##########################################################################
 COMPILE TIME CONFIGURATION (go into AHA152X in drivers/scsi/Makefile):
+##########################################################################
+
+
+1. DAUTOCONF :
 
--DAUTOCONF
- use configuration the controller reports (AHA-152x only)
+   use configuration the controller reports (AHA-152x only)

No need to change much here. This would be enough:

DAUTOCONF
use configuration the controller reports (AHA-152x only)

This produces a nice output: on older Sphinx version, the "DAUTOCONF" becomes bold. With Sphinx 2.0, the output is even nicer.

Quoted 5 lines
Documentation/scsi/aha152x.rst +2 -2
--DSKIP_BIOSTEST
- Don't test for BIOS signature (AHA-1510 or disabled BIOS)
+2. DSKIP_BIOSTEST : 
+   

Documentation/scsi/aha152x.rst less polling loops), has slightly higher throughput (at · line 55

Quoted 10 lines
Documentation/scsi/aha152x.rst +4 -4
+   Don't test for BIOS signature (AHA-1510 or disabled BIOS)
 
--DSETUP0="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the first controller 
+3. DSETUP0 :
 
--DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the second controller
+   "{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+   override for the first controller

Same applies here:

DSETUP0="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
override for the first controller

And to all parameters.

Quoted 34 lines
Documentation/scsi/aha152x.rst +17 -7
--DAHA152X_DEBUG
- enable debugging output
+4. DSETUP1 : 
 
--DAHA152X_STAT
- enable some statistics
+   "{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+   override for the second controller
 
+5. DAHA152X_DEBUG :
 
+   enable debugging output
+
+6. DAHA152X_STAT : 
+
+   enable some statistics
+
+###########################
 LILO COMMAND LINE OPTIONS:
+###########################
 
 aha152x=<IOPORT>[,<IRQ>[,<SCSI-ID>[,<RECONNECT>[,<PARITY>[,<SYNCHRONOUS>[,<DELAY> [,<EXT_TRANS]]]]]]]
 
-The normal configuration can be overridden by specifying a command 
-line.When you do this, the  BIOS  test  is skipped. Entered values 
-have to be valid (known).  Don't use values that  aren't supported 
+
+
+The normal configuration can be overridden by specifying a command
+line.When you do this, the  BIOS  test  is skipped. Entered values
+have to be valid (known).  Don't use values that  aren't supported
 under normal operation.  If  you think that you need other values:
 contact me. For two controllers  use  the aha152x statement twice.

Documentation/scsi/aha152x.rst less polling loops), has slightly higher throughput (at · line 90

Quoted 10 lines
Documentation/scsi/aha152x.rst +4 -2
 
-
+#################################
 SYMBOLS FOR MODULE CONFIGURATION:
+#################################
 
+****************************
 Choose from 2 alternatives:
-
+****************************

Did you try to compile it with
make htmldocs?

This will produce a warning, as the markup doesn't have the same number of chars that the title has.

Documentation/scsi/aha152x.rst Choose from 2 alternatives: · line 131

Quoted 13 lines
Documentation/scsi/aha152x.rst +3 -3
 1. specify everything (old)
 
    aha152x=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
@@ -107,22 +126,22 @@ Choose from 2 alternatives:
 
 If you use both alternatives the first will be taken.
 
-
-NOTES ON EXT_TRANS: 
-
+####################
+NOTES ON EXT_TRANS:
+####################

Please try to preserve what the author did. In this case, it has one blank line after the title. So, this one should be:

Notes on EXT_TRANS
==================

SCSI uses...

Quoted 59 lines
Documentation/scsi/aha152x.rst +11 -11
 SCSI uses block numbers to address blocks/sectors on a device.
 The BIOS uses a cylinder/head/sector addressing scheme (C/H/S)
-scheme instead.  DOS expects a BIOS or driver that understands 
+scheme instead.  DOS expects a BIOS or driver that understands
 this C/H/S addressing.
 
-The number of cylinders/heads/sectors is called geometry and is 
-required as base for requests in  C/H/S  addressing.  SCSI only 
+The number of cylinders/heads/sectors is called geometry and is
+required as base for requests in  C/H/S  addressing.  SCSI only
 knows about the total capacity  of  disks  in blocks (sectors).
 
 Therefore the SCSI BIOS/DOS driver has to calculate a logical/virtual
-geometry just  to  be  able  to  support  that addressing scheme. The 
-geometry returned by the SCSI BIOS is  a  pure  calculation  and  has 
-nothing to do with the  real/physical  geometry  of  the  disk (which 
+geometry just  to  be  able  to  support  that addressing scheme. The
+geometry returned by the SCSI BIOS is  a  pure  calculation  and  has
+nothing to do with the  real/physical  geometry  of  the  disk (which
 is usually irrelevant anyway).
 
 Basically this has no impact at all on Linux, because it also  uses block
@@ -145,7 +164,7 @@ BIOSes of some  newer controllers based on the AIC-6260/6360 support
 extended  translation.  This means that the BIOS uses 255 for heads,
 63 for  sectors  and then divides the capacity of the disk by 255*63
 (about 8 MB), as soon it sees a disk greater than 1 GB. That results
-in a maximum of about 8 GB addressable  diskspace  in the  partition 
+in a maximum of about 8 GB addressable  diskspace  in the  partition
 table (but there are already bigger disks out there today).
 
 To make it even more complicated the translation mode might/might
@@ -154,12 +173,12 @@ not be configurable in certain BIOS setups.
 This driver does some more or less failsafe guessing to get the
 geometry right in most cases:
 
-- for disks<1GB: 
+- for disks<1GB:
   -use default translation (C/32/64)
 
 - for disks>1GB:
   - take current geometry from the partition table (using scsicam_bios_param
-    and accept only `valid' geometries, ie. either (C/32/64) or (C/63/255)). 
+    and accept only `valid' geometries, ie. either (C/32/64) or (C/63/255)).
 	This can be extended translation even if it's not enabled in the driver.
 
   - if that fails, take extended translation if  enabled  by override,
@@ -167,9 +186,9 @@ geometry right in most cases:
     ask the user for verification.  This might on  not yet partitioned
     disks.
 
-
+#################
 REFERENCES USED:
-
+#################
  "AIC-6260 SCSI Chip Specification", Adaptec Corporation.
 
  "SCSI COMPUTER SYSTEM INTERFACE - 2 (SCSI-2)", X3T9.2/86-109 rev. 10h

Documentation/scsi/aha152x.rst REFERENCES USED: · line 209

Quoted 8 lines
Documentation/scsi/aha152x.rst +1 -1
@@ -184,7 +203,7 @@ REFERENCES USED:
 
  Drew Eckhardt (drew at cs.colorado.edu)
 
- Eric Youngdale (eric at andante.org) 
+ Eric Youngdale (eric at andante.org)
 
  special thanks to Eric Youngdale for the free(!) supplying the
  documentation on the chip.

Thanks,
Mauro