[PATCH] NTB: doc: remove underscore escaping

[PATCH] NTB: doc: remove underscore escaping

[Baruch Siach]

This escaping sequence makes the plain text file hard to read, and obscures the
name of identifies like module parameters. This is probably a left over from a
markup version of the text.

Signed-off-by: Baruch Siach <baruch@tkos.co.il>
---
 Documentation/ntb.txt | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index 1d9bbabb6c79..1a7f5731a130 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -26,7 +26,7 @@ as ntb hardware, or hardware drivers, are inserted and removed.  The
 registration uses the Linux Device framework, so it should feel familiar to
 anyone who has written a pci driver.
 
-### NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev)
+### NTB Transport Client (ntb_transport) and NTB Netdev (ntb_netdev)
 
 The primary client for NTB is the Transport client, used in tandem with NTB
 Netdev.  These drivers function together to create a logical link to the peer,
@@ -37,7 +37,7 @@ Transport queue pair.  Network data is copied between socket buffers and the
 Transport queue pair buffer.  The Transport client may be used for other things
 besides Netdev, however no other applications have yet been written.
 
-### NTB Ping Pong Test Client (ntb\_pingpong)
+### NTB Ping Pong Test Client (ntb_pingpong)
 
 The Ping Pong test client serves as a demonstration to exercise the doorbell
 and scratchpad registers of NTB hardware, and as an example simple NTB client.
@@ -55,16 +55,16 @@ Module Parameters:
 	registers.  By default, Ping Pong will not attempt to exercise such
 	hardware.  You may override this behavior at your own risk by setting
 	unsafe=1.
-* delay\_ms - Specify the delay between receiving a doorbell
+* delay_ms - Specify the delay between receiving a doorbell
 	interrupt event and setting the peer doorbell register for the next
 	round.
-* init\_db - Specify the doorbell bits to start new series of rounds.  A new
+* init_db - Specify the doorbell bits to start new series of rounds.  A new
 	series begins once all the doorbell bits have been shifted out of
 	range.
 * dyndbg - It is suggested to specify dyndbg=+p when loading this module, and
 	then to observe debugging output on the console.
 
-### NTB Tool Test Client (ntb\_tool)
+### NTB Tool Test Client (ntb_tool)
 
 The Tool test client serves for debugging, primarily, ntb hardware and drivers.
 The Tool provides access through debugfs for reading, setting, and clearing the
@@ -74,7 +74,7 @@ The Tool does not currently have any module parameters.
 
 Debugfs Files:
 
-* *debugfs*/ntb\_tool/*hw*/ - A directory in debugfs will be created for each
+* *debugfs*/ntb_tool/*hw*/ - A directory in debugfs will be created for each
 	NTB device probed by the tool.  This directory is shortened to *hw*
 	below.
 * *hw*/db - This file is used to read, set, and clear the local doorbell.  Not
@@ -84,16 +84,16 @@ Debugfs Files:
 	followed by the bits to clear.
 * *hw*/mask - This file is used to read, set, and clear the local doorbell mask.
 	See *db* for details.
-* *hw*/peer\_db - This file is used to read, set, and clear the peer doorbell.
+* *hw*/peer_db - This file is used to read, set, and clear the peer doorbell.
 	See *db* for details.
-* *hw*/peer\_mask - This file is used to read, set, and clear the peer doorbell
+* *hw*/peer_mask - This file is used to read, set, and clear the peer doorbell
 	mask.  See *db* for details.
 * *hw*/spad - This file is used to read and write local scratchpads.  To read
 	the values of all scratchpads, read the file.  To write values, write a
 	series of pairs of scratchpad number and value
 	(eg: `echo '4 0x123 7 0xabc' > spad`
 	# to set scratchpads `4` and `7` to `0x123` and `0xabc`, respectively).
-* *hw*/peer\_spad - This file is used to read and write peer scratchpads.  See
+* *hw*/peer_spad - This file is used to read and write peer scratchpads.  See
 	*spad* for details.
 
 ## NTB Hardware Drivers
@@ -101,27 +101,27 @@ Debugfs Files:
 NTB hardware drivers should register devices with the NTB core driver.  After
 registering, clients probe and remove functions will be called.
 
-### NTB Intel Hardware Driver (ntb\_hw\_intel)
+### NTB Intel Hardware Driver (ntb_hw_intel)
 
 The Intel hardware driver supports NTB on Xeon and Atom CPUs.
 
 Module Parameters:
 
-* b2b\_mw\_idx - If the peer ntb is to be accessed via a memory window, then use
+* b2b_mw_idx - If the peer ntb is to be accessed via a memory window, then use
 	this memory window to access the peer ntb.  A value of zero or positive
 	starts from the first mw idx, and a negative value starts from the last
 	mw idx.  Both sides MUST set the same value here!  The default value is
 	`-1`.
-* b2b\_mw\_share - If the peer ntb is to be accessed via a memory window, and if
+* b2b_mw_share - If the peer ntb is to be accessed via a memory window, and if
 	the memory window is large enough, still allow the client to use the
 	second half of the memory window for address translation to the peer.
-* xeon\_b2b\_usd\_bar2\_addr64 - If using B2B topology on Xeon hardware, use
+* xeon_b2b_usd_bar2_addr64 - If using B2B topology on Xeon hardware, use
 	this 64 bit address on the bus between the NTB devices for the window
 	at BAR2, on the upstream side of the link.
-* xeon\_b2b\_usd\_bar4\_addr64 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_usd\_bar4\_addr32 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_usd\_bar5\_addr32 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_dsd\_bar2\_addr64 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_dsd\_bar4\_addr64 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_dsd\_bar4\_addr32 - See *xeon\_b2b\_bar2\_addr64*.
-* xeon\_b2b\_dsd\_bar5\_addr32 - See *xeon\_b2b\_bar2\_addr64*.
+* xeon_b2b_usd_bar4_addr64 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_usd_bar4_addr32 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_usd_bar5_addr32 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_dsd_bar2_addr64 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_dsd_bar4_addr64 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_dsd_bar4_addr32 - See *xeon_b2b_bar2_addr64*.
+* xeon_b2b_dsd_bar5_addr32 - See *xeon_b2b_bar2_addr64*.
-- 
2.7.0

RE: [PATCH] NTB: doc: remove underscore escaping

[Allen Hubbe]

> From: Baruch Siach
> This escaping sequence makes the plain text file hard to read, and
> obscures the
> name of identifies like module parameters. This is probably a left over
> from a
> markup version of the text.

s/identifies/identifiers/

Rather than guessing the original intent, you can say, "This is an artifact left over from formatting the document as markdown."

> 
> Signed-off-by: Baruch Siach <baruch@tkos.co.il>

> -### NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev)
> +### NTB Transport Client (ntb_transport) and NTB Netdev (ntb_netdev)

You are correct.  The escaping of underscore is to avoid italicizing the text between underscores when the document is processed with markdown.  The escaping is intentional.

There is not much by way of official guidance around the use or non-use of markup/markdown/asciidoc in Linux/Documentation (or, I have not found it - please direct me).  There are a few other files under Documentation with similar markup; most seem to be related to acpi.  It seems to me that subsystems like acpi have autonomy in deciding how to markup their own documentation.  There is also value in being consistent, and documents with markup are distinctly in the minority.  I also recognize your point about the markup making the plain text marginally harder to read.

On the other hand, anyone familiar with markdown will recognize the section headings, fixed width annotations, and preformatted blocks.  Someone might take this document, recognize the format, and process it with markdown.  If the escaping is taken away, the result of processing will look strange.  Therefore, if the underscore escaping is to be removed, I would rather see the whole document changed in such a way that makes it obvious that the document is not markdown.

I would leave it in, but I will not stand in the way if Jon and Dave would rather take it out.

Allen