Manual page style work.

Submitted by:	Alexey Zelkin <phantom@FreeBSD.org>
thanks!

1 files changed, 137 insertions, 63 deletions

diff --git a/share/man/man4/netgraph.4 b/share/man/man4/netgraph.4
index 46cc658..546aeed 100644
--- a/share/man/man4/netgraph.4
+++ b/share/man/man4/netgraph.4
@@ -80,25 +80,37 @@ to interact with other nodes in a well defined manner.
 Each node has a
 .Em type ,
 which is a static property of the node determined at node creation time.
-A node's type is described by a unique ASCII type name.
+A node's type is described by a unique
+.Tn ASCII
+type name.
 The type implies what the node does and how it may be connected
 to other nodes.
 .Pp
 In object-oriented language, types are classes and nodes are instances
 of their respective class. All node types are subclasses of the generic node
 type, and hence inherit certain common functionality and capabilities
-(e.g., the ability to have an ASCII name).
+(e.g., the ability to have an
+.Tn ASCII
+name).
 .Pp
-Nodes may be assigned a globally unique ASCII name which can be
+Nodes may be assigned a globally unique
+.Tn ASCII
+name which can be
 used to refer to the node.
-The name must not contain the characters ``.'' or  ``:'' and is limited to
+The name must not contain the characters
+.Dq \&.
+or
+.Dq \&:
+and is limited to
 .Dv "NG_NODELEN + 1"
 characters (including NUL byte).
 .Pp
 Each node instance has a unique
 .Em ID number
 which is expressed as a 32-bit hex value. This value may be used to
-refer to a node when there is no ASCII name assigned to it.
+refer to a node when there is no
+.Tn ASCII
+name assigned to it.
 .Sh Hooks
 Nodes are connected to other nodes by connecting a pair of
 .Em hooks ,
@@ -110,9 +122,15 @@ Hooks have these properties:
 .Pp
 .Bl -bullet -compact -offset 2n
 .It
-A hook has an ASCII name which is unique among all hooks
+A hook has an
+.Tn ASCII
+name which is unique among all hooks
 on that node (other hooks on other nodes may have the same name).
-The name must not contain a ``.'' or a ``:''  and is
+The name must not contain a
+.Dq \&.
+or a
+.Dq \&:
+and is
 limited to
 .Dv "NG_HOOKLEN + 1"
 characters (including NUL byte).
@@ -123,7 +141,9 @@ removing either hook destroys both hooks.
 .El
 .Pp
 A node may decide to assign special meaning to some hooks. 
-For example, connecting to the hook named ``debug'' might trigger
+For example, connecting to the hook named
+.Dq debug
+might trigger
 the node to start sending debugging information to that hook.
 .Sh Data Flow
 Two types of information flow between nodes: data messages and
@@ -137,7 +157,8 @@ directly to some arbitrary other node.  Control messages have a common
 header format, followed by type-specific data, and are binary structures
 for efficiency.  However, node types also may support conversion of the
 type specific data between binary and
-ASCII for debugging and human interface purposes (see the
+.Tn ASCII
+for debugging and human interface purposes (see the
 .Dv NGM_ASCII2BINARY
 and
 .Dv NGM_BINARY2ASCII
@@ -146,9 +167,13 @@ these conversions.
 .Pp
 There are two ways to address a control message. If
 there is a sequence of edges connecting the two nodes, the message
-may be ``source routed'' by specifying the corresponding sequence
+may be
+.Dq source routed
+by specifying the corresponding sequence
 of hooks as the destination address for the message (relative
-addressing).  Otherwise, the recipient node global ASCII name
+addressing).  Otherwise, the recipient node global
+.Tn ASCII
+name
 (or equivalent ID based name) is used as the destination address
 for the message (absolute addressing).  The two types of addressing
 may be combined, by specifying an absolute start node and a sequence
@@ -156,7 +181,9 @@ of hooks.
 .Pp
 Messages often represent commands that are followed by a reply message
 in the reverse direction. To facilitate this, the recipient of a
-control message is supplied with a ``return address'' that is suitable
+control message is supplied with a
+.Dq return address
+that is suitable
 for addressing a reply.
 .Pp
 Each control message contains a 32 bit value called a
@@ -167,7 +194,7 @@ that it understands.  However, a node may choose to recognize and
 implement more than one type of message.
 .Sh Netgraph is Functional
 In order to minimize latency, most
-.Nm netgraph
+.Nm
 operations are functional.
 That is, data and control messages are delivered by making function
 calls rather than by using queues and mailboxes.  For example, if node
@@ -175,7 +202,9 @@ A wishes to send a data mbuf to neighboring node B, it calls the
 generic
 .Nm
 data delivery function. This function in turn locates
-node B and calls B's ``receive data'' method. While this mode of operation
+node B and calls B's
+.Dq receive data
+method. While this mode of operation
 results in good performance, it has a few implications for node
 developers:
 .Pp
@@ -186,13 +215,13 @@ may need to allow for the possibility of receiving a returning message
 before the original delivery function call returns.
 .It
 Netgraph nodes and support routines generally run at
-.Dv "splnet()" .
+.Fn splnet .
 However, some nodes may want to send data and control messages
 from a different priority level. Netgraph supplies queueing routines which
 utilize the NETISR system to move message delivery to 
-.Dv "splnet()" .
+.Fn splnet .
 Note that messages are always received at
-.Dv "splnet()" .
+.Fn splnet .
 .It
 It's possible for an infinite loop to occur if the graph contains cycles.
 .El
@@ -215,7 +244,7 @@ which is both a netgraph node and a
 BSD socket in the protocol family
 .Dv PF_NETGRAPH .
 Socket nodes allow user processes to participate in
-.Nm netgraph .
+.Nm Ns .
 Other nodes communicate with socket nodes using the usual methods, and the
 node hides the fact that it is also passing information to and from a
 cooperating user process.
@@ -225,7 +254,7 @@ a node interface to the hardware.
 .Sh Node Methods
 Nodes are notified of the following actions via function calls
 to the following node methods (all at
-.Dv "splnet()" )
+.Fn splnet )
 and may accept or reject that action (by returning the appropriate
 error code):
 .Bl -tag -width xxx
@@ -235,7 +264,9 @@ allowed, the constructor must call the generic node creation
 function (in object-oriented terms, the superclass constructor)
 and then allocate any special resources it needs. For nodes that
 correspond to hardware, this is typically done during the device
-attach routine. Often a global ASCII name corresponding to the
+attach routine. Often a global
+.Tn ASCII
+name corresponding to the
 device name is assigned here as well.
 .It Creation of a new hook
 The hook is created and tentatively
@@ -270,7 +301,7 @@ An mbuf chain is passed to the node.
 The node is notified on which hook the data arrived,
 and can use this information in its processing decision.
 The node must must always 
-.Dv m_freem()
+.Fn m_freem
 the mbuf chain on completion or error, or pass it on to another node
 (or kernel module) which will then be responsible for freeing it.
 .Pp
@@ -280,13 +311,13 @@ structure describing meta-data about the message
 .Dv NULL
 if there is no additional information. The format for this information is
 described in 
-.Dv netgraph.h .
+.Pa netgraph.h .
 The memory for meta-data must allocated via
-.Dv malloc()
+.Fn malloc
 with type
 .Dv M_NETGRAPH .
 As with the data itself, it is the receiver's responsibility to
-.Dv free()
+.Fn free
 the meta-data. If the mbuf chain is freed the meta-data must
 be freed at the same time. If the meta-data is freed but the
 real data on is passed on, then a
@@ -324,14 +355,14 @@ to point to the reply.
 Then when the control message delivery function returns,
 the caller can check if this pointer has been made non-NULL,
 and if so then it points to the reply message allocated via
-.Dv malloc()
+.Fn malloc
 and containing the synchronous response. In both directions, 
 (request and response) it is up to the 
 receiver of that message to 
-.Dv free()
+.Fn free
 the control message buffer. All control messages and replies are
 allocated with
-.Dv malloc()
+.Fn malloc
 type
 .Dv M_NETGRAPH .
 .El
@@ -339,7 +370,9 @@ type
 Much use has been made of reference counts, so that nodes being
 free'd of all references are automatically freed, and this behaviour
 has been tested and debugged to present a consistent and trustworthy
-framework for the ``type module'' writer to use.
+framework for the
+.Dq type module
+writer to use.
 .Sh Addressing
 The 
 .Nm
@@ -358,7 +391,11 @@ A relative address includes only the sequence of hook names, implicitly
 starting hook traversal at the local node.
 .Pp
 There are a couple of special possibilities for the node name.
-The name ``.'' (referred to as ``.:'') always refers to the local node.
+The name
+.Dq \&.
+(referred to as
+.Dq \&.: )
+always refers to the local node.
 Also, nodes that have no global name may be addressed by their ID numbers,
 by enclosing the hex representation of the ID number within square brackets.
 Here are some examples of valid netgraph addresses:
@@ -560,19 +597,22 @@ be changed.
 The de facto method for generating unique type cookies is to take the
 seconds from the epoch at the time the header file is written
 (i.e., the output of
-.Dv "date -u +'%s'" ")."
+.Dv "date -u +'%s'" ) .
 .Pp
 There is a predefined typecookie
 .Dv NGM_GENERIC_COOKIE
-for the ``generic'' node type, and
+for the
+.Dq generic
+node type, and
 a corresponding set of generic messages which all nodes understand.
 The handling of these messages is automatic.
 .It Dv command
 The identifier for the message command. This is type specific,
 and is defined in the same header file as the typecookie.
 .It Dv cmdstr
-Room for a short human readable version of ``command'' (for debugging
-purposes only).
+Room for a short human readable version of
+.Dq command
+(for debugging purposes only).
 .El
 .Pp
 Some modules may choose to implement messages from more than one 
@@ -580,25 +620,34 @@ of the header files and thus recognize more than one type cookie.
 .Sh Control Message ASCII Form
 Control messages are in binary format for efficiency.  However, for
 debugging and human interface purposes, and if the node type supports
-it, control messages may be converted to and from an equivalent ASCII
-form.  The ASCII form is similar to the binary form, with two exceptions:
+it, control messages may be converted to and from an equivalent
+.Tn ASCII
+form.  The
+.Tn ASCII
+form is similar to the binary form, with two exceptions:
 .Pp
 .Bl -tag -compact -width xxx
 .It o
 The
 .Dv cmdstr
-header field must contain the ASCII name of the command, corresponding to the
+header field must contain the
+.Tn ASCII
+name of the command, corresponding to the
 .Dv cmd
 header field.
 .It o
 The
 .Dv args
-field contains a NUL-terminated ASCII string version of the message arguments.
+field contains a NUL-terminated
+.Tn ASCII
+string version of the message arguments.
 .El
 .Pp
 In general, the arguments field of a control messgage can be any
 arbitrary C data type.  Netgraph includes parsing routines to support
-some pre-defined datatypes in ASCII with this simple syntax:
+some pre-defined datatypes in
+.Tn ASCII
+with this simple syntax:
 .Pp
 .Bl -tag -compact -width xxx
 .It o
@@ -616,24 +665,28 @@ does not have an explicit index, the index is implicitly the previous
 element's index plus one.
 .It o
 Structures are enclosed in curly braces, and each field is specified
-in the form ``fieldname=value''.
+in the form 
+.Dq fieldname=value .
 .It o
 Any array element or structure field whose value is equal to its
-``default value'' may be omitted. For integer types, the default value
+.Dq default value
+may be omitted. For integer types, the default value
 is usually zero; for string types, the empty string.
 .It o
 Array elements and structure fields may be specified in any order.
 .El
 .Pp
 Each node type may define its own arbitrary types by providing
-the necessary routines to parse and unparse.  ASCII forms defined
+the necessary routines to parse and unparse.
+.Tn ASCII
+forms defined
 for a specific node type are documented in the documentation for
 that node type.
 .Sh Generic Control Messages
 There are a number of standard predefined messages that will work
 for any node, as they are supported directly by the framework itself.
 These are defined in
-.Dv ng_message.h
+.Pa ng_message.h
 along with the basic layout of messages and other similar information.
 .Bl -tag -width xxx
 .It Dv NGM_CONNECT
@@ -655,7 +708,9 @@ is the default for nodes created using the
 method. Such nodes can only be addressed relatively or by their ID number.
 .It Dv NGM_RMHOOK
 Ask the node to break a hook connection to one of its neighbours.
-Both nodes will have their ``disconnect'' method invoked.
+Both nodes will have their
+.Dq disconnect
+method invoked.
 Either node may elect to totally shut down as a result.
 .It Dv NGM_NODEINFO
 Asks the target node to describe itself. The four returned fields
@@ -688,12 +743,16 @@ elect to not support this message. The text response must be less than
 bytes in length (presently 1024). This can be used to return general
 status information in human readable form.
 .It Dv NGM_BINARY2ASCII
-This message converts a binary control message to its ASCII form.
+This message converts a binary control message to its
+.Tn ASCII
+form.
 The entire control message to be converted is contained within the
 arguments field of the
 .Dv Dv NGM_BINARY2ASCII
 message itself.  If successful, the reply will contain the same control
-message in ASCII form.
+message in
+.Tn ASCII
+form.
 A node will typically only know how to translate messages that it
 itself understands, so the target node of the
 .Dv NGM_BINARY2ASCII
@@ -701,7 +760,9 @@ is often the same node that would actually receive that message.
 .It Dv NGM_ASCII2BINARY
 The opposite of
 .Dv NGM_BINARY2ASCII .
-The entire control message to be converted, in ASCII form, is contained
+The entire control message to be converted, in
+.Tn ASCII
+form, is contained
 in the arguments section of the
 .Dv NGM_ASCII2BINARY
 and need only have the
@@ -765,20 +826,20 @@ node of unknown type
 is made,
 .Nm
 will attempt to load the KLD module
-.Dv ng_type.ko .
+.Pa ng_type.ko .
 .Pp
 Types can also be installed at boot time, as certain device drivers
 may want to export each instance of the device as a netgraph node.
 .Pp
 In general, new types can be installed at any time from within the
 kernel by calling
-.Dv ng_newtype() ,
+.Fn ng_newtype ,
 supplying a pointer to the type's
 .Dv struct ng_type
 structure.
 .Pp
 The
-.Dv "NETGRAPH_INIT()"
+.Fn NETGRAPH_INIT
 macro automates this process by using a linker set.
 .Sh EXISTING NODE TYPES
 Several node types currently exist. Each is fully documented
@@ -808,8 +869,9 @@ calls, using a
 socket address.
 .Pp
 .It HOLE
-Responds only to generic messages and is a ``black hole'' for data,
-Useful for testing. Always accepts new hooks.
+Responds only to generic messages and is a
+.Dq black hole
+for data, Useful for testing. Always accepts new hooks.
 .Pp
 .It ECHO
 Responds only to generic messages and always echoes data back through the
@@ -817,7 +879,9 @@ hook from which it arrived. Returns any non generic messages as their
 own response. Useful for testing.  Always accepts new hooks.
 .Pp
 .It TEE
-This node is useful for ``snooping.'' It has 4 hooks:
+This node is useful for
+.Dq snooping .
+It has 4 hooks:
 .Dv left ,
 .Dv right ,
 .Dv left2right ,
@@ -836,24 +900,31 @@ to left.
 .Pp
 .It RFC1490 MUX
 Encapsulates/de-encapsulates frames encoded according to RFC 1490.
-Has a hook for the encapsulated packets (``downstream'') and one hook
+Has a hook for the encapsulated packets
+.Pq Dq downstream
+and one hook
 for each protocol (i.e., IP, PPP, etc.).
 .Pp
 .It FRAME RELAY MUX
 Encapsulates/de-encapsulates Frame Relay frames.
-Has a hook for the encapsulated packets (``downstream'') and one hook
+Has a hook for the encapsulated packets
+.Pq Dq downstream
+and one hook
 for each DLCI.
 .Pp
 .It FRAME RELAY LMI
 Automatically handles frame relay
-``LMI'' (link management interface) operations and packets.
+.Dq LMI
+(link management interface) operations and packets.
 Automatically probes and detects which of several LMI standards
 is in use at the exchange.
 .Pp
 .It TTY
 This node is also a line discipline. It simply converts between mbuf
 frames and sequential serial data, allowing a tty to appear as a netgraph
-node. It has a programmable ``hotkey'' character.
+node. It has a programmable
+.Dq hotkey
+character.
 .Pp
 .It ASYNC
 This node encapsulates and de-encapsulates asynchronous frames
@@ -891,14 +962,14 @@ It might be freed by any node the data passes through, and a
 .Dv NULL
 passed onwards, but the caller will never free it.
 Two macros
-.Dv "NG_FREE_META(meta)"
+.Fn NG_FREE_META "meta"
 and
-.Dv "NG_FREE_DATA(m, meta)"
+.Fn NG_FREE_DATA "m" "meta"
 should be used if possible to free data and meta data (see
-.Dv netgraph.h ")."
+.Pa netgraph.h ) .
 .It 3
 Messages sent using
-.Dv ng_send_message()
+.Fn ng_send_message
 are freed by the callee. As in the case above, the addresses
 associated with the message are freed by whatever allocated them so the 
 recipient should copy them if it wants to keep that information.
@@ -974,7 +1045,10 @@ and
 The
 .Nm
 system was designed and first implemented at Whistle Communications, Inc.
-in a version FreeBSD 2.2 customized for the Whistle InterJet.
+in a version
+.Fx 2.2
+customized for the Whistle InterJet.
 .Sh AUTHORS
-Julian Elischer <julian@whistle.com>, with contributions by
-Archie Cobbs <archie@whistle.com>.
+.An Julian Elischer Aq julian@whistle.com ,
+with contributions by
+.An Archie Cobbs Aq archie@whistle.com .