Tcl Library Source Code

2013-02-08  Andreas Kupries <[email protected]>

	* apps/dtplite: Fixed missing -ibase option in direcotry
	* apps/dtplite.man: processing with -merge. Fixed sorting in
	  generated toc and indices. Plus new feature: -toc for external
	  toc to place in the output. Bumped to 1.0.4. Updated
	  documentation.

2013-02-01  Andreas Kupries  <[email protected]>

	*
	* Released and tagged Tcllib 1.15 ========================
	* 

2013-01-28  Andreas Kupries  <[email protected]>

#! /bin/sh
# -*- tcl -*- \
exec tclsh "$0" ${1+"$@"}

# @@ Meta Begin
# Application dtplite 1.0.3
# Application dtplite 1.0.4
# Meta platform     tcl
# Meta summary      Lightweight DocTools Processor
# Meta description  This application is a simple processor
# Meta description  for documents written in the doctools
# Meta description  markup language. It covers the most
# Meta description  common use cases, but is not as
# Meta description  configurable as its big brother dtp.
# Meta category     Processing doctools documents
# Meta subject      doctools doctoc docidx
# Meta require      {doctools 1}
# Meta require      {doctools::idx 1}
# Meta require      {doctools::toc 1}
# Meta require      fileutil
# Meta require      textutil::repeat
# Meta author       Andreas Kupries
# Meta license      BSD
# @@ Meta End

package provide dtplite 1.0.3
package provide dtplite 1.0.4

# dtp lite - Lightweight DocTools Processor
# ======== = ==============================
#
# Use cases
# ---------
# 
#
# (1)	Validation of a single manpage, i.e. checking that it is valid
#	doctools format.
# 
#
# (1a)	Getting a preliminary version of the formatted output, for
#	display in a browser, nroff, etc., proofreading the
#	formatting.
# 
#
# (2)	Generate documentation for a single package, i.e. all the
#	manpages, plus index and table of contents.
# 
#
# (3)	Generation of unified documentation for several
#	packages. Especially unified keyword index and table of
#	contents. This may additionally generate per-package TOCs
#	as well (Per-package indices don't make sense IMHO).
# 
#
# Command syntax
# --------------
# 
#
# Ad 1)	dtplite -o output format file
# 
#
#	The option -o specifies where to write the output to. Using
#	the string "-" as name of the output file causes the tool to
#	write the generated data to stdout. If $output is a directory
#	then a file named [[file rootname $file].$format] is written
#	to the directory.

# Ad 1a)	dtplite validate file
#
#	The "validate" format does not generate output at all, only
#	syntax checking is performed.
# 
#
# Ad 2)	dtplite -o output format directory
# 
#
#	I.e. we distinguish (2) from (1) by the type of the input,
#	file, or directory. In this situation output has to be a
#	directory. Use the path "." to place the results into the
#	current directory.
# 
#
#	We locate _all_ files under directory, i.e. all subdirectories
#	are scanned as well. We replicate the found directory
#	structure in the output (See example below). The index and
#	table of contents are written to the toplevel directory in the
#	output. The names are hardwired to "toc.$format" and
#	"index.$format".
# 
#
# Ad 3)	dtplite -merge -o output format directory
# 
#
#	This can be treated as special case of (2). The -merge option
#	tells it that the output is nested one level deeper, to keep a
#	global toc and index in the toplevel and to merge the package
#	toc and index into them.
# 
#
#	This way the global documents are built up incrementally. This
#	can help us in a future extended installer as well!, extending
#	a global documentation tree of all installed packages.
# 
#
# Additional features.
# 
#
# *	As described above the format name is used as the extension
#	for the generated files. Does it make sense to introduce an
#	option with which we can overide this, or should we simply
#	extect that a calling script does a proper renaming of all the
#	files ?  ... The option is better. In HTML output we have
#	links between the files, and renaming from the outside just
#	breaks the links. This option is '-ext'. It is ignored if the
#	output is a single file (fully specified via -o), or stdout.
# 
#
#	-ext extension
# 
#
# *	Most of the formats don't need much/none of customizability.
#	I.e. text, nroff, wiki, tmml, ...  For HTML however some
#	degree of customizability is required for good output.  What
#	should we given to the user ?
# 
#
#	- Allow setting of a stylesheet.
#	- Allow integration of custom body header and footer html.
#	- Allow additional links for the navigation bar.
# 
#
#	Note: The tool generates standard navigation bars to link the
#	all tocs, indices, and pages together.
# 
#
#	-style file
#	-header file
#	-footer file
#	-nav label url
# 
#
# *	The application may mis-detect files as doctools input.
#	And we cannot always mark them as non-doctools because
#	they may be such. Test cases, for example. To exclude
#	these we have the option '-exclude' taking a glob pattern.
#	Multiple uses of the option accumulate.
#
#	-exclude glob
#
# *	For tcllib itself we have external tools generating a nicer
#	TOC. Use option -toc to specify the doctoc file to use instead
#	of generating our own.
#
#	-toc path
#
# That should be enough to allow the creation of good looking formatted
# documentation without getting overly complex in both implementation
# and use.

package require doctools      1.4.11 ; # 'image' support, -ibase support
package require doctools::idx 1.0.4 ;
package require doctools::toc 1.1.3 ;

    # Database of image files for use by dt_imap.

    variable  imap
    array set imap {}

    # Database of exclusion patterns. Files matching these are not
    # manpages. For example, test files for doctools itself may full
    # manpages. For example, test files for doctools itself may fall
    # under this.

    variable excl {}

    # Path of a user specified table of contents (doctoc format).

    variable utoc {}
}

# ### ### ### ######### ######### #########
## External data and status
#
## Only the directory merge mode uses external data, saving the
## internal representations of current toc, index. and xref

# dtplite	-o outputpath	\
#		?-merge?	\
#		?-ext ext?	\
#		?-style file?	\
#		?-header file?	\
#		?-footer file?	\
#		?-nav label url?... \
#		?-exclude glob?... \
#		?-toc path? \
#		format inputpath
##

proc ::dtplite::processCmdline {} {
    global argv

    variable output ; variable style  ; variable stdout
    variable format ; variable header ; variable single
    variable input  ; variable footer ; variable mode
    variable ext    ; variable nav    ; variable merge  
    variable module ; variable excl
    variable ext    ; variable nav    ; variable merge
    variable module ; variable excl   ; variable utoc

    # Process the options, perform basic validation.

    while {[llength $argv]} {
	set opt [lindex $argv 0]
	if {![string match "-*" $opt]} break

	if {[string equal $opt "-o"]} {
	    if {[llength $argv] < 2} Usage
	    set output [lindex $argv 1]
	    set argv   [lrange $argv 2 end]
	} elseif {[string equal $opt "-merge"]} {
	    set merge 1
	    set argv [lrange $argv 1 end]
	} elseif {[string equal $opt "-ext"]} {
	    if {[llength $argv] < 2} Usage
	    set ext  [lindex $argv 1]
	    set argv [lrange $argv 2 end]
	} elseif {[string equal $opt "-toc"]} {
	    if {[llength $argv] < 2} Usage
	    set utoc [lindex $argv 1]
	    set argv [lrange $argv 2 end]
	} elseif {[string equal $opt "-exclude"]} {
	    if {[llength $argv] < 2} Usage
	    lappend excl [lindex $argv 1]
	    set argv [lrange $argv 2 end]
	} elseif {[string equal $opt "-style"]} {
	    if {[llength $argv] < 2} Usage

    # and toc. I.e. any existing index and toc files are overwritten.

    variable input
    variable out
    variable module
    variable meta
    variable format
    variable utoc

    # Phase 0. Find the documents to convert.
    # Phase I. Collect meta data, and compute the map from input to
    # ........ output files. This is also the map for the symbolic
    # ........ references. We extend an existing map (required for use
    # ........ in merge op.
    # Phase II. Build index and toc information from the meta data.
    # Phase III. Convert each file, using index, toc and meta
    # .......... information.

    MapImages
    set files [LocateManpages $input]
    if {![llength $files]} {
	ArgError "Module \"$module\" has no files to process."	
	ArgError "Module \"$module\" has no files to process."
    }

    MetadataGet $files
    StyleMakeLocal

    if {$utoc ne {}} {
	if {[file exists $utoc]} {
	    set utoc [Get $utoc]
	}
	TocWrite toc index $utoc
    } else {
    TocWrite toc index [TocGenerate [TocGet $module toc]]
	TocWrite toc index [TocGenerate [TocGet $module toc]]
    }
    IdxWrite index toc [IdxGenerate $module [IdxGet]]

    dt configure -module $module
    XrefGet
    XrefSetup   dt
    FooterSetup dt
    MapSetup    dt

    variable input
    variable out
    variable module
    variable meta
    variable output
    variable format
    variable utoc

    # Phase 0. Find the documents to process.
    # Phase I. Collect meta data, and compute the map from input to
    # ........ output files. This is also the map for the symbolic
    # ........ references. We extend an existing map (required for use
    # ........ in merge op.
    # Phase II. Build module local toc from the meta data, insert it
    # ......... into the main toc as well, and generate a global
    # ......... index.
    # Phase III. Process each file, using cross references, and links
    # .......... to boths tocs and the index.

    MapImages
    set files [LocateManpages $input]
    if {![llength $files]} {
	ArgError "Module \"$module\" has no files to process."	
	ArgError "Module \"$module\" has no files to process."
    }

    MetadataGet $files $module
    StyleMakeLocal     $module

    set localtoc [TocGet $module $module/toc]
    TocWrite $module/toc index [TocGenerate $localtoc] [TocMap $localtoc]
    if {$utoc ne {}} {
	if {[file exists $utoc]} {
	    set utoc [Get $utoc]
	}
	TocWrite toc index $utoc
    } else {
    TocWrite toc         index [TocGenerate [TocMergeSaved $localtoc]]
    IdxWrite index       toc   [IdxGenerate {} [IdxGetSaved index]]
	TocWrite toc index [TocGenerate [TocMergeSaved $localtoc]]
    }
    IdxWrite index toc [IdxGenerate {} [IdxGetSaved index]]

    dt configure -module $module
    XrefGetSaved
    XrefSetup   dt
    FooterSetup dt
    MapSetup    dt

    foreach f [lsort -dict $files] {
	puts stdout \t$f

	set o $out($f)
	dt configure -file [At $o]
	dt configure -file [At $o] -ibase $input/$f

	NavbuttonPush {Keyword Index}          [Output index]       $o
	NavbuttonPush {Table Of Contents}      [Output $module/toc] $o
	NavbuttonPush {Main Table Of Contents} [Output toc]         $o
	HeaderSetup dt
	NavbuttonPop
	NavbuttonPop

}

proc ::dtplite::TocGenerate {data} {
    # Handling single and multiple divisions.
    # single div => div is full toc
    # multi div  => place divs into the toc in alpha order.
    #
    # Sort toc (each division) by label.
    # Sort toc (each division) by label (index 1).
    # Write as doctoc.

    array set toc $data

    TagsBegin
    if {[array size toc] < 2} {
	# Empty, or single division. The division is the TOC, toplevel.

	unset toc
	set desc [lindex $data 0]
	set data [lindex [lindex $data 1] 1]
	TocAlign mxf mxl $data

	Tag+ toc_begin [list {Table Of Contents} $desc]
	foreach item [lsort -dict -index 2 $data] {
	foreach item [lsort -dict -index 1 $data] {
	    foreach {symfile label desc} $item break
	    Tag+ item \
		    [FmtR mxf $symfile] \
		    [FmtR mxl $label] \
		    [list $desc]
	}
    } else {
	Tag+ toc_begin [list {Table Of Contents} Modules]
	foreach desc [lsort -dict [array names toc]] {
	    foreach {ref div} $toc($desc) break
	    TocAlign mxf mxl $div

	    Tag+ division_start [list $desc [Output $ref]]
	    foreach item [lsort -dict -index 2 $div] {
	    foreach item [lsort -dict -index 1 $div] {
		foreach {symfile label desc} $item break
		Tag+ item \
			[FmtR mxf $symfile] \
			[FmtR mxl $label] \
			[list $desc]
	    }
	    Tag+ division_end

    TagsBegin
    Tag+ index_begin [list {Keyword Index} $desc]

    foreach k [lsort -dict [array names keys]] {
	IdxAlign mxf $keys($k)

	Tag+ key [list $k]
	foreach v [lsort -dict -index 0 $keys($k)] {
	foreach v [lsort -dict -index 1 $keys($k)] {
	    foreach {file label} $v break
	    Tag+ manpage [FmtR mxf $file] [list $label]
	}
    }

    Tag+ index_end
    #puts ____________________\n[join $lines \n]\n_________________________

When processing an input directory the stylesheet file is copied into
the output directory and the generated HTML will refer to the copy, to
make the result more self-contained. When processing an input file we
have no location to copy the stylesheet to and so just reference it as
specified.

[para]

When used multiple times only the last definition is relevant.


[opt_def -toc path]

This option specifies a doctoc file to use for the table of contents
instead of generating our own.

[para]

When used multiple times only the last definition is relevant.


[opt_def -nav "label url"]

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/dtplite.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Andreas Kupries <[email protected]>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "dtplite" n 1.0 tcllib "Documentation toolbox"
.BS
.SH NAME
dtplite \- Lightweight DocTools Markup Processor
.SH SYNOPSIS
\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputfile\fR
.sp
\fBdtplite\fR \fBvalidate\fR \fIinputfile\fR
.sp
\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR
.sp
\fBdtplite\fR \fB-merge\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR
.sp
.BE
.SH DESCRIPTION
.PP
The application described by this document, \fBdtplite\fR, is the
successor to the extremely simple \fBmpexpand\fR. Influenced in its
functionality by the \fBdtp\fR doctools processor it is much more
powerful than \fBmpexpand\fR, yet still as easy to use; definitely
easier than \fBdtp\fR with its myriad of subcommands and options.
.PP
\fBdtplite\fR is based upon the package \fBdoctools\fR, like
the other two processors.
.SS "USE CASES"
\fBdtplite\fR was written with the following three use cases in
mind.
.PP
.IP [1]
Validation of a single document, i.e. checking that it was written in
valid doctools format. This mode can also be used to get a preliminary
version of the formatted output for a single document, for display in
a browser, nroff, etc., allowing proofreading of the formatting.
.IP [2]
Generation of the formatted documentation for a single package,
i.e. all the manpages, plus a table of contents and an index of
keywords.
.IP [3]
An extension of the previous mode of operation, a method for the easy
generation of one documentation tree for several packages, and
especially of a unified table of contents and keyword index.
.PP
.PP
Beyond the above we also want to make use of the customization
features provided by the HTML formatter. It is not the only format the
application should be able to generate, but we anticipiate it to be
the most commonly used, and it is one of the few which do provide
customization hooks.
.PP
We allow the caller to specify a header string, footer string, a
stylesheet, and data for a bar of navigation links at the top of the
generated document.
While all can be set as long as the formatting engine provides an
appropriate engine parameter (See section \fBOPTIONS\fR) the last
two have internal processing which make them specific to HTML.
.SS "COMMAND LINE"
.TP
\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputfile\fR
This is the form for use case [1]. The \fIoptions\fR will be
explained later, in section \fBOPTIONS\fR.
.RS
.TP
path \fIoutput\fR (in)
This argument specifies where to write the generated document. It can
be the path to a file or directory, or \fB-\fR.
The last value causes the application to write the generated
documented to \fBstdout\fR.
.sp
If the \fIoutput\fR does not exist then [file dirname $output]
has to exist and must be a writable directory.
The generated document will be written to a file in that directory,
and the name of that file will be derived from the \fIinputfile\fR,
the \fIformat\fR, and the value given to option \fB-ext\fR (if
present).
.TP
(path|handle) \fIformat\fR (in)
This argument specifies the formatting engine to use when processing
the input, and thus the format of the generated document. See section
\fBFORMATS\fR for the possibilities recognized by the application.
.TP
path \fIinputfile\fR (in)
This argument specifies the path to the file to process. It has to
exist, must be readable, and written in \fIdoctools\fR format.
.RE
.sp
.TP
\fBdtplite\fR \fBvalidate\fR \fIinputfile\fR
This is a simpler form for use case [1]. The "validate" format
generates no output at all, only syntax checks are performed. As such
the specification of an output file or other options is not necessary
and left out.
.TP
\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR
This is the form for use case [2]. It differs from the form for
use case [1] by having the input documents specified through a
directory instead of a file. The other arguments are identical, except
for \fIoutput\fR, which now has to be the path to an existing and
writable directory.
.sp
The input documents are all files in \fIinputdirectory\fR or any of
its subdirectories which were recognized by \fBfileutil::fileType\fR
as containing text in \fIdoctools\fR format.
.TP
\fBdtplite\fR \fB-merge\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR
This is the form for use case [3]. The only difference to the
form for use case [2] is the additional option \fB-merge\fR.
.sp
Each such call will merge the generated documents coming from
processing the input documents under \fIinputdirectory\fR or any of
its subdirectories to the files under \fIoutput\fR. In this manner it
is possible to incrementally build the unified documentation for any
number of packages. Note that it is necessary to run through all the
packages twice to get fully correct cross-references (for formats
supporting them).
.PP
.SS OPTIONS
This section describes all the options available to the user of the
application, with
the exception of the options \fB-o\fR and \fB-merge\fR. These
two were described already, in section \fBCOMMAND LINE\fR.
.PP
.TP
\fB-exclude\fR string
This option specifies an exclude (glob) pattern. Any files identified
as manpages to process which match the exclude pattern are
ignored. The option can be provided multiple times, each usage adding
an additional pattern to the list of exclusions.
.TP
\fB-ext\fR string
If the name of an output file has to be derived from the name of an
input file it will use the name of the \fIformat\fR as the extension
by default. This option here will override this however, forcing it to
use \fIstring\fR as the file extension. This option is ignored if the
name of the output file is fully specified through option \fB-o\fR.
.sp
When used multiple times only the last definition is relevant.
.TP
\fB-header\fR file
This option can be used if and only if the selected \fIformat\fR
provides an engine parameter named "header". It takes the contents of
the specified file and assign them to that parameter, for whatever use
by the engine. The HTML engine will insert the text just after the tag
\fB<body>\fR.
If navigation buttons are present (see option \fB-nav\fR below),
then the HTML generated for them is appended to the header data
originating here before the final assignment to the parameter.
.sp
When used multiple times only the last definition is relevant.
.TP
\fB-footer\fR file
Like \fB-header\fR, except that: Any navigation buttons are ignored,
the corresponding required engine parameter is named "footer", and the
data is inserted just before the tag \fB</body>\fR.
.sp
When used multiple times only the last definition is relevant.
.TP
\fB-style\fR file
This option can be used if and only if the selected \fIformat\fR
provides an engine parameter named "meta". When specified it will
generate a piece of HTML code declaring the \fIfile\fR as the
stylesheet for the generated document and assign that to the
parameter. The HTML engine will insert this inot the document, just
after the tag \fB<head>\fR.
.sp
When processing an input directory the stylesheet file is copied into
the output directory and the generated HTML will refer to the copy, to
make the result more self-contained. When processing an input file we
have no location to copy the stylesheet to and so just reference it as
specified.
.sp
When used multiple times only the last definition is relevant.
.TP
\fB-toc\fR path
This option specifies a doctoc file to use for the table of contents
instead of generating our own.
.sp
When used multiple times only the last definition is relevant.
.TP
\fB-nav\fR label url
Use this option to specify a navigation button with \fIlabel\fR to
display and the \fIurl\fR to link to. This option can be used if and
only if the selected \fIformat\fR provides an engine parameter named
"header". The HTML generated for this is appended to whatever data we
got from option \fB-header\fR before it is inserted into the
generated documents.
.sp
When used multiple times all definitions are collected and a
navigation bar is created, with the first definition shown at the left
edge and the last definition to the right.
.PP
.SS FORMATS
At first the \fIformat\fR argument will be treated as a path to a tcl
file containing the code for the requested formatting engine. The
argument will be treated as the name of one of the predefined formats
listed below if and only if the path does not exist.
.PP
\fINote a limitation\fR: If treating the format as path to the tcl
script implementing the engine was sucessful, then this script has to
implement not only the engine API for doctools, i.e.
\fIdoctools_api\fR, but for \fIdoctoc_api\fR and \fIdocidx_api\fR
as well. Otherwise the generation of a table of contents and of a
keyword index will fail.
.PP
List of predefined formats, i.e. as provided by the
package \fBdoctools\fR:
.PP
.TP
\fBnroff\fR
The processor generates *roff output, the standard format for unix
manpages.
.TP
\fBhtml\fR
The processor generates HTML output, for usage in and display by web
browsers. This engine is currently the only one providing the various
engine parameters required for the additional customaization of the
output.
.TP
\fBtmml\fR
The processor generates TMML output, the Tcl Manpage Markup Language,
a derivative of XML.
.TP
\fBlatex\fR
The processor generates LaTeX output.
.TP
\fBwiki\fR
The processor generates Wiki markup as understood by \fBwikit\fR.
.TP
\fBlist\fR
The processor extracts the information provided by \fBmanpage_begin\fR.
This format is used internally to extract the meta data from which
both table of contents and keyword index are derived from.
.TP
\fBnull\fR
The processor does not generate any output. This is equivalent to
\fBvalidate\fR.
.PP
.SS "DIRECTORY STRUCTURES"
In this section we describe the directory structures generated by the
application under \fIoutput\fR when processing all documents in an
\fIinputdirectory\fR. In other words, this is only relevant to the use
cases [2] and [3].
.TP
[2]
The following directory structure is created when processing a single
set of input documents.  The file extension used is for output in
HTML, but that is not relevant to the structure and was just used to
have proper file names.
.CS


    output/
        toc.html
        index.html
        files/
            path/to/FOO.html

.CE
.IP
The last line in the example shows the document
generated for a file FOO located at
.CS


    inputdirectory/path/to/FOO

.CE
.TP
[3]
When merging many packages into a unified set of documents the
generated directory structure is a bit deeper:
.CS


    output
        .toc
        .idx
        .tocdoc
        .idxdoc
        .xrf
        toc.html
        index.html
        FOO1/
            ...
        FOO2/
            toc.html
            files/
                path/to/BAR.html

.CE
.IP
Each of the directories FOO1, ... contains the documents generated for
the package FOO1, ... and follows the structure shown for use case
[2]. The only exception is that there is no per-package index.
.sp
The files "\fI.toc\fR", "\fI.idx\fR", and "\fI.xrf\fR" contain the
internal status of the whole output and will be read and updated by
the next invokation. Their contents will not be documented. Remove
these files when all packages wanted for the output have been
processed, i.e. when the output is complete.
.sp
The files "\fI.tocdoc\fR", and "\fI.idxdoc\fR", are intermediate files
in doctoc and docidx markup, respectively, containing the main table
of contents and keyword index for the set of documents before their
conversion to the chosen output format.
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fIdoctools\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH "SEE ALSO"
docidx introduction, doctoc introduction, doctools introduction
.SH KEYWORDS
HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff
.SH CATEGORY
Documentation tools
.SH COPYRIGHT
.nf
Copyright (c) 2004 Andreas Kupries <[email protected]>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nns.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2007-2008 Andreas Kupries <[email protected]>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "nns" n 1.1 tcllib "Name service facility"
.BS
.SH NAME
nns \- Name service facility, Commandline Client Application
.SH SYNOPSIS
\fBnns\fR \fBbind\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? \fIname\fR \fIdata\fR
.sp
\fBnns\fR \fBsearch\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? ?\fB-continuous\fR? ?\fIpattern\fR?
.sp
\fBnns\fR \fBident\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR?
.sp
\fBnns\fR \fBwho\fR
.sp
.BE
.SH DESCRIPTION
.PP
Please read \fIName service facility, introduction\fR first.
.PP
The application described by this document, \fBnns\fR, is a simple
command line client for the nano name service facility provided by the
Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR.
Beyond that the application's sources also serve as an example of how
to use the client package \fBnameserv\fR. All abilities of a
client are covered, from configuration to registration of names to
searching.
.PP
This name service facility has nothing to do with the Internet's
\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the
reader is looking for a package dealing with that please see either of
the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib
too.
.SS "USE CASES"
\fBnns\fR was written with the following two main use cases in
mind.
.PP
.IP [1]
Registration of a name/data pair in the name service.
.IP [2]
Searching the name service for entries matching a glob pattern.
.PP
.PP
Beyond the above we also want to be able to identify the client, and
get information about the name service.
.SS "COMMAND LINE"
.TP
\fBnns\fR \fBbind\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? \fIname\fR \fIdata\fR
This form registers the \fIname\fR/\fIdata\fR pair in the specified
name service. In this form the command will \fInot\fR exit to keep
the registration alive. The user has to kill it explicitly, either by
sending a signal, or through the job-control facilities of the shell
in use. It will especially survive the loss of the connection to the
name service and reestablish the \fIname\fR/\fIdata\fR pair when the
connection is restored.
.sp
The options to specify the name service will be explained later, in
section \fBOPTIONS\fR.
.TP
\fBnns\fR \fBsearch\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? ?\fB-continuous\fR? ?\fIpattern\fR?
This form searches the specified name service for entries matching the
glob-\fIpattern\fR and prints them to stdout, with each entry on its
own line. If no pattern is specified it defaults to \fB*\fR,
matching everything.
.sp
The options to specify the name service will be explained later, in
section \fBOPTIONS\fR.
.sp
If the option \fB-continuous\fR is specified the client will not
exit after performing the search, but start to continuously monitor
the service for changes to the set of matching entries, appropriately
updating the display as changes arrive. In that form it will
especially also survive the loss of the connection to the name service
and reestablish the search when the connection is restored.
.TP
\fBnns\fR \fBident\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR?
This form asks the specified name service for the version and features
of the name service protocol it supports and prints the results to
stdout.
.sp
The options to specify the name service will be explained later, in
section \fBOPTIONS\fR.
.TP
\fBnns\fR \fBwho\fR
This form prints name, version, and protocol version of the
application to stdout.
.PP
.SS OPTIONS
This section describes all the options available to the user of the
application
.PP
.TP
\fB-host\fR name|ipaddress
If this option is not specified it defaults to \fBlocalhost\fR. It
specifies the name or ip-address of the host the name service to talk
to is running on.
.TP
\fB-port\fR number
If this option is not specified it defaults to \fB38573\fR. It
specifies the TCP port the name service to talk to is listening on for
requests.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fInameserv\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH "SEE ALSO"
nameserv(n), nameserv::common(n)
.SH KEYWORDS
application, client, name service
.SH CATEGORY
Networking
.SH COPYRIGHT
.nf
Copyright (c) 2007-2008 Andreas Kupries <[email protected]>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nnsd.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2007-2008 Andreas Kupries <[email protected]>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "nnsd" n 1.0.1 tcllib "Name service facility"
.BS
.SH NAME
nnsd \- Name service facility, Commandline Server Application
.SH SYNOPSIS
\fBnnsd\fR ?\fB-localonly\fR \fIflag\fR? ?\fB-port\fR \fIport\fR?
.sp
.BE
.SH DESCRIPTION
.PP
Please read \fIName service facility, introduction\fR first.
.PP
The application described by this document, \fBnns\fR, is a simple
command line server for the nano name service facility provided by the
Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR.
Beyond that the application's sources also serve as an example of how
to use the server package \fBnameserv::server\fR.
.PP
This name service facility has nothing to do with the Internet's
\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the
reader is looking for a package dealing with that please see either of
the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib
too.
.SS "USE CASES"
\fBnnsd\fR was written with the following main use case in
mind.
.PP
.IP [1]
Run a nano name service on some host.
.PP
.PP
.SS "COMMAND LINE"
.TP
\fBnnsd\fR ?\fB-localonly\fR \fIflag\fR? ?\fB-port\fR \fIport\fR?
The command configures a server per the specified options and starts
it. The command will not exit on its, as it keeps the name service
database wholly in memory. The user has to kill it explicitly, eithre
by sending a a signal, or through the job-control facilities of the
shell in use.
.sp
The options to configure the name service are explained in section
\fBOPTIONS\fR.
.PP
.SS OPTIONS
This section describes all the options available to the user of the
application
.PP
.TP
\fB-localonly\fR bool
If this option is not specified it defaults to \fBtrue\fR, i.e.
acceptance of only local connections. The server will accept remote
connections, i.e. connections from other hosts, if and only if this
option is configured to \fBfalse\fR.
.TP
\fB-port\fR number
If this option is not specified it defaults to \fB38573\fR. It
specifies the TCP port the server has to listen on for requests.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fInameserv\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH "SEE ALSO"
nameserv::common(n), nameserv::server(n)
.SH KEYWORDS
application, name service, server
.SH CATEGORY
Networking
.SH COPYRIGHT
.nf
Copyright (c) 2007-2008 Andreas Kupries <[email protected]>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nnslog.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2008 Andreas Kupries <[email protected]>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "nnslog" n 1.0 tcllib "Name service facility"
.BS
.SH NAME
nnslog \- Name service facility, Commandline Logging Client Application
.SH SYNOPSIS
\fBnnslog\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR?
.sp
.BE
.SH DESCRIPTION
.PP
Please read \fIName service facility, introduction\fR first.
.PP
The application described by this document, \fBnnslog\fR, is a
simple command line client for the nano name service facility provided
by the Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR.
.PP
It essentially implements "\fBnns\fR search -continuous *", but
uses a different output formatting. Instead of continuously showing
the current contents of the server in the terminal it simply logs all
received add/remove events to \fBstdout\fR.
.PP
This name service facility has nothing to do with the Internet's
\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the
reader is looking for a package dealing with that please see either of
the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib
too.
.SS "USE CASES"
\fBnnslog\fR was written with the following main use case in mind.
.PP
.IP [1]
Monitoring the name service for all changes and logging them in a text
terminal.
.PP
.PP
.SS "COMMAND LINE"
.TP
\fBnnslog\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR?
The command connects to the specified name service, sets up a search
for all changes and then prints all received events to stdout, with
each events on its own line. The command will not exit until it is
explicitly terminated by the user. It will especially survive the loss
of the connection to the name service and reestablish the search and
log when the connection is restored.
.sp
The options to specify the name service will be explained later, in
section \fBOPTIONS\fR.
.PP
.SS OPTIONS
This section describes all the options available to the user of the
application
.TP
\fB-host\fR name|ipaddress
If this option is not specified it defaults to \fBlocalhost\fR. It
specifies the name or ip-address of the host the name service to talk
to is running on.
.TP
\fB-port\fR number
If this option is not specified it defaults to \fB38573\fR. It
specifies the TCP port the name service to talk to is listening on for
requests.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fInameserv\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH "SEE ALSO"
nameserv(n), nameserv::common(n)
.SH KEYWORDS
application, client, name service
.SH CATEGORY
Networking
.SH COPYRIGHT
.nf
Copyright (c) 2008 Andreas Kupries <[email protected]>

.fi