Learned about the label() and link() commands and how to use url()

to do cross ref links.
Jeremy.
(This used to be commit 783c32d08a4857f2e4f209473c30f9073a07b503)

5 files changed, 153 insertions, 89 deletions

diff --git a/docs/yodldocs/make_smbcodepage.1.yo b/docs/yodldocs/make_smbcodepage.1.yo
index 9b8df60d08..b69515585b 100644
--- a/docs/yodldocs/make_smbcodepage.1.yo
+++ b/docs/yodldocs/make_smbcodepage.1.yo
@@ -2,12 +2,15 @@ mailto(samba-bugs@samba.anu.edu.au)
 
 manpage(make_smbcodepage)(1)(23 Oct 1998)(Samba)(SAMBA)
 
+label(NAME)
 manpagename(make_codepage)(Construct a codepage file for Samba)
 
+label(SYNOPSIS)
 manpagesynopsis() 
 
 bf(make_smbcodepage) [c|d] codepage inputfile outputfile
 
+label(DESCRIPTION)
 manpagedescription()
 
 This program is part of the bf(Samba) suite.
@@ -15,6 +18,7 @@ This program is part of the bf(Samba) suite.
 bf(make_smbcodepage) compiles or de-compiles codepage files for use
 with the internationalization features of Samba 2.0
 
+label(OPTIONS)
 manpageoptions()
 
 startdit()
@@ -35,6 +39,7 @@ dit(outputfile) This is the output file to produce.
 
 endit()
 
+label(Samba Codepage files)
 manpagesection(Samba Codepage files)
 
 A text Samba codepage definition file is a description that tells
@@ -64,6 +69,7 @@ them to email(samba-bugs@samba.anu.edu.au). All codepage files in the
 Samba em(source/codepages) directory are compiled and installed when a
 em('make install') command is issued there.
 
+label(FILES)
 manpagefiles()
 
 bf(codepage_def.<codepage>)
@@ -98,6 +104,7 @@ bf(codepage.<codepage>) These are the output (binary) codepage files
 produced and placed in the Samba destination em(lib/codepage)
 directory.
 
+label(INSTALLATION)
 manpagesection(INSTALLATION)
 
 The location of the server and its support files is a matter for
@@ -109,6 +116,7 @@ under the em(/usr/local/samba) hierarchy, in a directory readable by
 all, writeable only by root. The program itself should be executable
 by all.  The program should NOT be setuid or setgid!
 
+label(VERSION)
 manpagesection(VERSION)
 
 This man page is correct for version 2.0 of the Samba
@@ -118,10 +126,12 @@ that your version of the program has extensions or parameter semantics
 that differ from or are not covered by this man page. Please notify
 these to the address below for rectification.
 
+label(SEEALSO)
 manpageseealso()
 
-bf(smb.conf(5)), bf(smbd (8))
+url(bf(smb.conf(5)))(smb.conf.5.html), url(bf(smbd (8)))(smbd.8.html)
 
+label(AUTHOR)
 manpageauthor() 
 
 The bf(make_smbcodepage) program was written by Jeremy Allison (email
diff --git a/docs/yodldocs/nmbd.8.yo b/docs/yodldocs/nmbd.8.yo
index 2bf3de2c01..970089a5d1 100644
--- a/docs/yodldocs/nmbd.8.yo
+++ b/docs/yodldocs/nmbd.8.yo
@@ -2,13 +2,16 @@ mailto(samba-bugs@samba.anu.edu.au)
 
 manpage(nmbd)(8)(23 Oct 1998)(Samba)(SAMBA)
 
+label(NAME)
 manpagename(nmbd)(NetBIOS name server to provide NetBIOS over IP
 naming services to clients)
 
+label(SYNOPSIS)
 manpagesynopsis()
 
 bf(nmbd) [-D] [-o] [-a] [-H lmhosts file] [-d debuglevel] [-l log file basename] [-n primary NetBIOS name] [-p port number] [-s configuration file] [-i NetBIOS scope] [-h]
 
+label(DESCRIPTION)
 manpagedescription()
 
 This program is part of the bf(Samba) suite.
@@ -41,6 +44,7 @@ In addition, nmbd can act as a WINS proxy, relaying broadcast queries
 from clients that do not understand how to talk the WINS protocol to a
 WIN server.
 
+label(OPTIONS)
 manpageoptions()
 
 startdit()
@@ -128,6 +132,7 @@ dit(bf(-h)) Prints the help information (usage) for nmbd.
 
 endit()
 
+label(FILES)
 manpagefiles()
 
 bf(/etc/inetd.conf)
@@ -148,6 +153,7 @@ This is the default location of the em(smb.conf) server configuration
 file. Other common places that systems install this file are
 em(/usr/samba/lib/smb.conf) and em(/etc/smb.conf).
 
+label(SIGNALS)
 manpagesection(SIGNALS)
 
 nmbd will accept SIGHUP, which will cause it to dump out it's
@@ -162,6 +168,7 @@ SIGUSR2 (tt(kill -USR2 <nmbd-pid>)). This is to allow transient
 problems to be diagnosed, whilst still running at a normally low log
 level.
 
+label(VERSION)
 manpagesection(VERSION)
 
 This man page is (mostly) correct for version 2.0 of the Samba suite,
@@ -171,14 +178,18 @@ version of the server has extensions or parameter semantics that
 differ from or are not covered by this man page. Please notify these
 to the address below for rectification.
 
+label(SEEALSO)
 manpageseealso()
 
-bf(inetd (8)), bf(smbd (8)), bf(smb.conf (5)), bf(smbclient (1)),
-bf(testparm (1)), bf(testprns (1)), and the Internet RFC's
-bf(rfc1001.txt), bf(rfc1002.txt). In addition the CIFS (formerly SMB)
-specification is available as a link from the Web page :
+bf(inetd (8)), url(bf(smbd (8)))(smbd.8.html), url(bf(smb.conf
+(5)))(smb.conf.5.html), url(bf(smbclient (1)))(smbclient.1.html),
+url(bf(testparm (1)))(testparm.1.html), url(bf(testprns
+(1)))(testprns.1.html), and the Internet RFC's bf(rfc1001.txt),
+bf(rfc1002.txt). In addition the CIFS (formerly SMB) specification is
+available as a link from the Web page :
 url(http://samba.anu.edu.au/cifs/)(http://samba.anu.edu.au/cifs/).
 
+label(AUTHOR)
 manpageauthor()
 
 The original Samba software and related utilities were created by
diff --git a/docs/yodldocs/samba.7.yo b/docs/yodldocs/samba.7.yo
index f82872c5a2..b9034edd44 100644
--- a/docs/yodldocs/samba.7.yo
+++ b/docs/yodldocs/samba.7.yo
@@ -1,6 +1,10 @@
 mailto(samba-bugs@samba.anu.edu.au)
 manpage(samba)(7)(23 Oct 1998)(Samba)()
+
+label(NAME)
 manpagename(Samba)(A Windows fileserver for UNIX)
+
+label(SYNOPSIS)
 manpagesynopsis()
 bf(Samba)
 
diff --git a/docs/yodldocs/smbclient.1.yo b/docs/yodldocs/smbclient.1.yo
index 41dbfc01fa..fc826db0ef 100644
--- a/docs/yodldocs/smbclient.1.yo
+++ b/docs/yodldocs/smbclient.1.yo
@@ -2,12 +2,15 @@ mailto(samba-bugs@samba.anu.edu.au)
 
 manpage(smbclient)(1)(23 Oct 1998)(Samba)(SAMBA)
 
+label(NAME)
 manpagename(smbclient)(ftp-like client to access SMB/CIFS resources on servers)
 
+label(SYNOPSIS)
 manpagesynopsis()
 
 bf(smbclient) service [password] [-s smb.conf] [-B IP addr] [-O socket_options][-R name resolve order] [-M NetBIOS name] [-i scope] [-N] [-n NetBIOS name] [-d debuglevel] [-P] [-p port] [-l log basename] [-h] [-I dest IP] [-E] [-U username] [-L NetBIOS name] [-t terminal code] [-m max protocol] [-W workgroup] [-T<c|x>IXFqgbNan] [-D directory] [-c command string]
 
+label(DESCRIPTION)
 manpagedescription()
 
 This program is part of the bf(Samba) suite.
@@ -18,6 +21,7 @@ offers an interface similar to that of the ftp program (see bf(ftp
 to the local machine, putting files from the local machine to the
 server, retrieving directory information from the server and so on.
 
+label(OPTIONS)
 manpageoptions()
 
 startdit()
@@ -66,11 +70,103 @@ dit(bf(-B IP addr)) The IP address to use when sending a broadcast packet.
 
 dit(bf(-O socket_options)) TCP socket options to set on the client socket.
 
-  DEBUG(0,("\t-R name resolve order use these name resolution services only\n"));
-  DEBUG(0,("\t-M host               send a winpopup message to the host\n"));
-  DEBUG(0,("\t-i scope              use this NetBIOS scope\n"));
-  DEBUG(0,("\t-N                    don't ask for a password\n"));
-  DEBUG(0,("\t-n netbios name.      Use this name as my netbios name\n"));
+dit(bf(-R name resolve order)) This option allows the user of
+smbclient to determine what name resolution services to use when
+looking up the NetBIOS name of the host being connected to.
+
+The options are :"lmhosts", "host", "wins" and "bcast". They cause
+names to be resolved as follows :
+
+startit()
+
+it() bf(lmhosts) : Lookup an IP address in the Samba lmhosts file.
+
+it() bf(host) : Do a standard host name to IP address resolution,
+using the system /etc/hosts, NIS, or DNS lookups. This method of name
+resolution is operating system depended for instance on IRIX or
+Solaris this may be controlled by the em(/etc/nsswitch.conf) file).  
+
+it() bf(wins) : Query a name with the IP address listed in the bf(wins
+server) parameter in the smb.conf file. If no WINS server has been
+specified this method will be ignored.
+
+it() bf(bcast) : Do a broadcast on each of the known local interfaces
+listed in the bf(interfaces) parameter in the smb.conf file. This is
+the least reliable of the name resolution methods as it depends on the
+target host being on a locally connected subnet. To specify a
+particular broadcast address the bf(-B) option may be used.
+
+endit()
+
+The default order is lmhosts, host, wins, bcast and without this
+parameter the name resolution methods will be attempted in this order.
+
+dit(bf(-M NetBIOS name)) This options allows you to send messages,
+using the "WinPopup" protocol, to another computer. Once a connection
+is established you then type your message, pressing ^D (control-D) to
+end.
+
+If the receiving computer is running WinPopup the user will receive
+the message and probably a beep. If they are not running WinPopup the
+message will be lost, and no error message will occur.
+
+The message is also automatically truncated if the message is over
+1600 bytes, as this is the limit of the protocol.
+
+One useful trick is to cat the message through bf(smbclient).
+For example:
+
+tt(cat mymessage.txt | smbclient -M FRED)
+
+will send the message in the file em(mymessage.txt) to the machine FRED.
+
+You may also find the bf(-U) and bf(-I) options useful, as they allow
+you to control the FROM and TO parts of the message.
+
+See the message command section of bf(smb.conf (5)) for a description
+of how to handle incoming WinPopup messages in Samba.
+
+Note: Copy WinPopup into the startup group on your WfWg PCs if you
+want them to always be able to receive messages.
+
+dit(bf(-i scope)) This specifies a NetBIOS scope that smbclient will use
+to communicate with when generating NetBIOS names. For details on the
+use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes
+are em(very) rarely used, only set this parameter if you are the
+system administrator in charge of all the NetBIOS systems you
+communicate with.
+
+dit(bf(-N)) If specified, this parameter suppresses the normal
+password prompt from the client to the user. This is useful when
+accessing a service that does not require a password.
+
+Unless a password is specified on the command line or this parameter
+is specified, the client will request a password.
+
+dit(bf(-n NetBIOS name)) By default, the client will use the local
+machine's hostname (in uppercase) as its NetBIOS name. This parameter
+allows you to override the host name and use whatever NetBIOS name you
+wish.
+
+dit(bf(-d debuglevel)) debuglevel is an integer from 0 to 10, or the
+letter 'A'.
+
+The default value if this parameter is not specified is zero.
+
+The higher this value, the more detail will be logged to the log files
+about the activities of the client. At level 0, only critical errors
+and serious warnings will be logged. Level 1 is a reasonable level for
+day to day running - it generates a small amount of information about
+operations carried out.
+
+Levels above 1 will generate considerable amounts of log data, and should 
+only be used when investigating a problem. Levels above 3 are designed for 
+use only by developers and generate HUGE amounts of log data, most of which 
+is extremely cryptic.
+.RE
+
+
+
   DEBUG(0,("\t-d debuglevel         set the debuglevel\n"));
   DEBUG(0,("\t-P                    connect to service as a printer\n"));
   DEBUG(0,("\t-p port               connect to the specified port\n"));
@@ -121,41 +217,7 @@ smbclient -L ftp -I ftp.microsoft.com
 will list the shares available on Microsoft's public server.
 .RE
 
-.B \-M
-
 .RS 3
-This options allows you to send messages, using the "WinPopup"
-protocol, to another computer. Once a connection is established you
-then type your message, pressing ^D (control-D) to end.
-
-If the receiving computer is running WinPopup the user will receive
-the message and probably a beep. If they are not running WinPopup the
-message will be lost, and no error message will occur.
-
-The message is also automatically truncated if the message is over
-1600 bytes, as this is the limit of the protocol.
-
-One useful trick is to cat the message through
-.BR smbclient .
-For example:
-
-cat mymessage.txt | smbclient -M FRED
-
-will send the message in the file "mymessage.txt" to the machine FRED.
-
-You may also find the
-.B \-U
-and
-.B \-I
-options useful, as they allow you to
-control the FROM and TO parts of the message. 
-
-See the message command section of
-.BR smb.conf (5)
-for a description of how to handle incoming WinPopup messages in Samba.
-
-Note: Copy WinPopup into the startup group on your WfWg PCs if you
-want them to always be able to receive messages.
 .RE
 
 .B \-E
@@ -185,17 +247,6 @@ There is no default for this parameter. If not supplied, it will be determined
 automatically by the client as described above.
 .RE
 
-.B \-N
-
-.RS 3
-If specified, this parameter suppresses the normal password prompt from the
-client to the user. This is useful when accessing a service that does not
-require a password.
-
-Unless a password is specified on the command line or this parameter is
-specified, the client will request a password.
-.RE
-
 .B \-O
 .I socket options
 
@@ -278,25 +329,6 @@ rejected by these servers.
 Be cautious about including passwords in scripts.
 .RE
 
-.B \-d
-.I debuglevel
-
-.RS 3
-debuglevel is an integer from 0 to 5.
-
-The default value if this parameter is not specified is zero.
-
-The higher this value, the more detail will be logged to the log files about
-the activities of the client. At level 0, only critical errors and serious 
-warnings will be logged. Level 1 is a reasonable level for day to day running
-- it generates a small amount of information about operations carried out.
-
-Levels above 1 will generate considerable amounts of log data, and should 
-only be used when investigating a problem. Levels above 3 are designed for 
-use only by developers and generate HUGE amounts of log data, most of which 
-is extremely cryptic.
-.RE
-
 .B \-l
 .I log basename
 
@@ -322,15 +354,6 @@ log.client.out (containing outbound transaction data)
 The log files generated are never removed by the client.
 .RE
 
-.B \-n
-.I NetBIOS name
-
-.RS 3
-By default, the client will use the local machine's hostname (in
-uppercase) as its NetBIOS name. This parameter allows you to override
-the host name and use whatever NetBIOS name you wish.
-.RE
-
 .B \-W
 .I workgroup
 
diff --git a/docs/yodldocs/smbd.8.yo b/docs/yodldocs/smbd.8.yo
index aefdf8ee03..d8abee3aec 100644
--- a/docs/yodldocs/smbd.8.yo
+++ b/docs/yodldocs/smbd.8.yo
@@ -2,13 +2,16 @@ mailto(samba-bugs@samba.anu.edu.au)
 
 manpage(smbd)(8)(23 Oct 1998)(Samba)(SAMBA)
 
+label(NAME)
 manpagename(smbd)(server to provide SMB/CIFS services to clients)
 
+label(SYNOPSIS)
 manpagesynopsis()
 
 bf(smbd) [-D] [-a] [-o] [-d debuglevel] [-l log file] [-p port number]
 [-O socket options] [-s configuration file] [-i scope] [-P] [-h]
 
+label(DESCRIPTION)
 manpagedescription()
 
 This program is part of the bf(Samba) suite.
@@ -43,6 +46,7 @@ file will not affect connections to any service that is already
 established.  Either the user will have to disconnect from the
 service, or smbd killed and restarted.
 
+label(OPTIONS)
 manpageoptions()
 
 startdit()
@@ -128,6 +132,7 @@ out. Used for debugging by the developers only.
 
 endit()
 
+label(FILES)
 manpagefiles()
 
 bf(/etc/inetd.conf)
@@ -160,6 +165,7 @@ em(/usr/samba/lib/smb.conf) and em(/etc/smb.conf).
 This file describes all the services the server is to make available
 to clients. See bf(smb.conf (5)) for more information.
 
+label(LIMITATIONS)
 manpagesection(LIMITATIONS)
 
 On some systems bf(smbd) cannot change uid back to root after a
@@ -168,6 +174,7 @@ have such a system, you will be unable to connect from a client (such
 as a PC) as two different users at once. Attempts to connect the
 second user will result in "access denied" or similar.
 
+label(ENVIRONMENTVARIABLES)
 manpagesection(ENVIRONMENT VARIABLES)
 
 bf(PRINTER)
@@ -177,7 +184,7 @@ will use the value of this variable (or "lp" if this variable is not
 defined) as the name of the printer to use. This is not specific to
 the server, however.
 
-
+label(INSTALLATION)
 manpagesection(INSTALLATION)
 
  The location of the server and its support files is a matter for
@@ -234,6 +241,7 @@ as a daemon.
 When you've decided, continue with either em(RUNNING THE SERVER AS A
 DAEMON) or em(RUNNING THE SERVER ON REQUEST).
 
+label(RUNNINGTHESERVERASADAEMON)
 manpagesection(RUNNING THE SERVER AS A DAEMON)
 
 To run the server as a daemon from the command line, simply put the
@@ -265,6 +273,7 @@ If the options used at compile time are appropriate for your system,
 all parameters except the desired debug level and bf(-D) may be
 omitted. See the section em(OPTIONS) above.
 
+label(RUNNINGTHESERVERONREQUEST)
 manpagesection(RUNNING THE SERVER ON REQUEST)
 
  If your system uses a meta-daemon such as inetd, you can arrange to
@@ -323,6 +332,7 @@ tt(
 This will allow you to connect to your home directory and print to any
 printer supported by the host (user privileges permitting).
 
+label(TESTINGTHEINSTALLATION)
 manpagesection(TESTING THE INSTALLATION)
 
 If running the server as a daemon, execute it before proceeding. If
@@ -338,6 +348,7 @@ the smbclient program (see bf(smbclient (1))) and also going through
 the steps outlined in the file em(DIAGNOSIS.txt) in the em(docs/)
 directory of your Samba installation.
 
+label(VERSION)
 manpagesection(VERSION)
 
 This man page is (mostly) correct for version 2.0 of the Samba suite,
@@ -347,6 +358,7 @@ version of the server has extensions or parameter semantics that
 differ from or are not covered by this man page. Please notify these
 to the address below for rectification.
 
+label(DIAGNOSTICS)
 manpagesection(DIAGNOSTICS)
 
 Most diagnostics issued by the server are logged in a specified log
@@ -363,6 +375,7 @@ in the source code to warrant describing each and every diagnostic. At
 this stage your best bet is still to grep the source code and inspect
 the conditions that gave rise to the diagnostics you are seeing.
 
+label(SIGNALS)
 manpagesection(SIGNALS)
 
 Sending the smbd a SIGHUP will cause it to re-load its smb.conf
@@ -387,15 +400,18 @@ make the signal handlers safe by un-blocking the signals before the
 select call and re-blocking them after, however this would affect
 performance.
 
+label(SEEALSO)
 manpageseealso()
 
-bf(hosts_access (5)), bf(inetd (8)), bf(nmbd (8)), bf(smb.conf (5)),
-bf(smbclient (1)), bf(testparm (1)), bf(testprns (1)), and the
-Internet RFC's bf(rfc1001.txt), bf(rfc1002.txt). In addition the
-CIFS (formerly SMB) specification is available as a link from the
-Web page :
+bf(hosts_access (5)), bf(inetd (8)), url(bf(nmbd (8)))(nmbd.8.html),
+url(bf(smb.conf (5)))(smb.conf.html), url(bf(smbclient
+(1)))(smbclient.1.html), url(bf(testparm (1)))(testparm.1.html),
+url(bf(testprns (1)))(testprns.1.html), and the Internet RFC's
+bf(rfc1001.txt), bf(rfc1002.txt). In addition the CIFS (formerly SMB)
+specification is available as a link from the Web page :
 url(http://samba.anu.edu.au/cifs/)(http://samba.anu.edu.au/cifs/).
 
+label(AUTHOR)
 manpageauthor()
 
 The original Samba software and related utilities were created by