doctools man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

doctools(n)		      Documentation tools		   doctools(n)

______________________________________________________________________________

NAME
       doctools - doctools - Processing documents

SYNOPSIS
       package require Tcl  8.2

       package require doctools	 ?1.4.10?

       ::doctools::new objectName ?option value...?

       ::doctools::help

       ::doctools::search path

       objectName method ?arg arg ...?

       objectName configure

       objectName configure option

       objectName configure -option value...

       objectName cget -option

       objectName destroy

       objectName format text

       objectName map symbolic actual

       objectName parameters

       objectName search path

       objectName setparam name value

       objectName warnings

_________________________________________________________________

DESCRIPTION
       This  package  provides	a  class  for  the creation of objects able to
       process and convert text written in the doctools markup	language  into
       any output format X for which a formatting engine is available.

       A reader interested in the markup language itself should start with the
       doctools language introduction and proceed from	there  to  the	formal
       specifications, i.e. the doctools language syntax and the doctools lan‐
       guage command reference.

       If on the other hand the reader wishes  to  write  her  own  formatting
       engine for some format, i.e. is a plugin writer then reading and under‐
       standing the doctools plugin API reference is an absolute necessity, as
       that  document  specifies  the interaction between this package and its
       plugins, i.e. the formatting engines, in detail.

PUBLIC API
   PACKAGE COMMANDS
       ::doctools::new objectName ?option value...?
	      This command creates a new doctools object  with	an  associated
	      Tcl  command  whose  name	 is objectName. This object command is
	      explained in full detail in  the	sections  OBJECT  COMMAND  and
	      OBJECT  METHODS.	The  object  command will be created under the
	      current namespace if the objectName is not fully qualified,  and
	      in the specified namespace otherwise.

	      The options and their values coming after the name of the object
	      are used to set the initial configuration of the object.

       ::doctools::help
	      This is a convenience command for applications wishing  to  pro‐
	      vide  their  user with a short description of the available for‐
	      matting commands and their meanings. It returns  a  string  con‐
	      taining a standard help text.

       ::doctools::search path
	      Whenever	an  object  created by this the package has to map the
	      name of a format to the file containing the code for its format‐
	      ting  engine it will search for the file in a number of directo‐
	      ries stored in a list.  See  section  FORMAT  MAPPING  for  more
	      explanations.

	      This  list not only contains three default directories which are
	      declared by the package itself, but is also extensible  user  of
	      the  package.   This command is the means to do so. When given a
	      path to an existing and readable directory it will prepend  that
	      directory	 to the list of directories to search. This means that
	      the path added last is later searched through first.

	      An error will be thrown if the path either does  not  exist,  is
	      not a directory, or is not readable.

   OBJECT COMMAND
       All commands created by ::doctools::new have the following general form
       and may be used to invoke various operations  on	 their	doctools  con‐
       verter object.

       objectName method ?arg arg ...?
	      The  method method and its arg'uments determine the exact behav‐
	      ior of the command. See section OBJECT METHODS for the  detailed
	      specifications.

   OBJECT METHODS
       objectName configure
	      The method returns a list of all known options and their current
	      values when called without any arguments.

       objectName configure option
	      The method behaves like the method cget when called with a  sin‐
	      gle  argument  and  returns the value of the option specified by
	      said argument.

       objectName configure -option value...
	      The method reconfigures the specified  options  of  the  object,
	      setting  them to the associated values, when called with an even
	      number of arguments, at least two.

	      The legal options are described in the section OBJECT CONFIGURA‐
	      TION.

       objectName cget -option
	      This method expects a legal configuration option as argument and
	      will return the current value of that option for the object  the
	      method was invoked for.

	      The  legal configuration options are described in section OBJECT
	      CONFIGURATION.

       objectName destroy
	      This method destroys the object it is invoked for.

       objectName format text
	      This method runs the  text  through  the	configured  formatting
	      engine  and returns the generated string as its result. An error
	      will be thrown if no -format was configured for the object.

	      The method assumes that the text is in doctools format as speci‐
	      fied  in	the  companion	document  doctools_fmt. Errors will be
	      thrown otherwise.

       objectName map symbolic actual
	      This methods add one entry to the per-object mapping  from  sym‐
	      bolic filenames to the actual uris.  The object just stores this
	      mapping and makes it  available  to  the	configured  formatting
	      engine  through  the command dt_fmap.  This command is described
	      in more detail in the doctools plugin API reference which speci‐
	      fies the interaction between the objects created by this package
	      and doctools formatting engines.

       objectName parameters
	      This method returns a list containing the names  of  all	engine
	      parameters provided by the configured formatting engine. It will
	      return an empty list if the object is not yet configured	for  a
	      specific format.

       objectName search path
	      This  method  extends  the per-object list of paths searched for
	      doctools	formatting  engines.  See  also	 the  command	::doc‐
	      tools::search  on	 how  to extend the per-package list of paths.
	      Note that the path entered last will  be	searched  first.   For
	      more details see section FORMAT MAPPING.

       objectName setparam name value
	      This  method  sets  the  named engine parameter to the specified
	      value.  It will throw an error if the object is either  not  yet
	      configured  for  a  specific format, or if the formatting engine
	      for the configured format does not provide a parameter with  the
	      given  name.   The list of parameters provided by the configured
	      formatting engine can be retrieved through  the  method  parame‐
	      ters.

       objectName warnings
	      This  method  returns  a	list containing all the warnings which
	      were generated by the configured formatting  engine  during  the
	      last invocation of the method format.

   OBJECT CONFIGURATION
       All doctools objects understand the following configuration options:

       -file file
	      The  argument  of	 this  option is stored in the object and made
	      available to the configured formatting engine through  the  com‐
	      mands  dt_file and dt_mainfile.  These commands are described in
	      more detail in the companion document doctools_api which	speci‐
	      fies the API between the object and formatting engines.

	      The default value of this option is the empty string.

	      The  configured  formatting engine should interpret the value as
	      the name of the file containing the document which is  currently
	      processed.

       -module text
	      The  argument  of	 this  option is stored in the object and made
	      available to the configured formatting engine through  the  com‐
	      mand dt_module.  This command is described in more detail in the
	      companion document doctools_api which specifies the API  between
	      the object and formatting engines.

	      The default value of this option is the empty string.

	      The  configured  formatting engine should interpret the value as
	      the name of the module the file containing the document which is
	      currently processed belongs to.

       -format text
	      The argument of this option specifies the format to generate and
	      by implication the formatting engine to use when converting text
	      via  the	method	format. Its default value is the empty string.
	      The method format cannot be used if this option is not set to  a
	      valid value at least once.

	      The package will immediately try to map the given name to a file
	      containing the code for a formatting engine generating that for‐
	      mat. An error will be thrown if this mapping fails. In that case
	      a previously configured format is left untouched.

	      The section FORMAT MAPPING explains in detail  how  the  package
	      and object will look for engine implementations.

       -deprecated boolean
	      This option is a boolean flag. The object will generate warnings
	      if this flag is set and the text given to method format contains
	      the  deprecated  markup  command	strong.	  Its default value is
	      FALSE. In other words, no warnings will be generated.

       -copyright text
	      The argument of this option is stored in	the  object  and  made
	      available	 to  the configured formatting engine through the com‐
	      mand dt_copyright.  This command is described in more detail  in
	      the  companion  document	doctools_api  which  specifies the API
	      between the object and formatting engines.

	      The default value of this option is the empty string.

	      The configured formatting engine should interpret the value as a
	      copyright	 assignment  for  the document which is currently pro‐
	      cessed, or the package described by it.

	      This information must be used if	and  only  if  the  engine  is
	      unable  to  find	any  copyright assignments within the document
	      itself. Such are specified by the formatting command  copyright.
	      This  command is described in more detail in the companion docu‐
	      ment doctools_fmt which specifies the doctools format itself.

   FORMAT MAPPING
       The package and object will perform the following algorithm when trying
       to  map	a  format name foo to a file containing an implementation of a
       formatting engine for foo:

       [1]    If foo is the name  of  an  existing  file  then	this  file  is
	      directly taken as the implementation.

       [2]    If  not,	the  list  of per-object search paths is searched. For
	      each directory in the list the package checks if that  directory
	      contains	a  file	 "fmt.foo". If yes, then that file is taken as
	      the implementation.

	      Note that this list of paths  is	initially  empty  and  can  be
	      extended through the object method search.

       [3]    If  not, the list of package paths is searched.  For each direc‐
	      tory in the list the package checks if that directory contains a
	      file "fmt.foo". If yes, then that file is taken as the implemen‐
	      tation.

	      This list of paths can be extended through  the  command	::doc‐
	      tools::search.  It contains initially one path, the subdirectory
	      "mpformats" of the directory the package itself is  located  in.
	      In  other words, if the package implementation "doctools.tcl" is
	      installed in the directory "/usr/local/lib/tcllib/doctools" then
	      it      will     by     default	  search     the     directory
	      "/usr/local/lib/tcllib/doctools/mpformats" for format  implemen‐
	      tations.

       [4]    The mapping fails.

PREDEFINED ENGINES
       The package provides predefined engines for the following formats. Some
       of the engines support parameters. These will  be  explained  below  as
       well.

       html   This  engine  generates  HTML  markup,  for  processing  by  web
	      browsers and the like. This engine supports four parameters:

	      footer The value for this parameter has  to  be  valid  selfcon‐
		     tained  HTML  markup for the body section of a HTML docu‐
		     ment. The default value is the empty string. The value is
		     inserted  into  the  generated  output  just  before  the
		     </body> tag, closing the body of the generated HTML.

		     This can be used to insert boilerplate footer markup into
		     the generated document.

	      header The  value	 for  this  parameter has to be valid selfcon‐
		     tained HTML markup for the body section of a  HTML	 docu‐
		     ment. The default value is the empty string. The value is
		     inserted into the generated output just after the	<body>
		     tag, starting the body of the generated HTML.

		     This can be used to insert boilerplate header markup into
		     the generated document.

	      meta   The value for this parameter has  to  be  valid  selfcon‐
		     tained HTML markup for the header section of a HTML docu‐
		     ment. The default value is the empty string. The value is
		     inserted  into the generated output just after the <head>
		     tag, starting the header section of the generated HTML.

		     This can be used to insert boilerplate meta  data	markup
		     into   the	 generated  document,  like  references	 to  a
		     stylesheet, standard meta keywords, etc.

	      xref   The value for this parameter has to be a list of  triples
		     specifying	 cross-reference information. This information
		     is used by the engine to  create  more  hyperlinks.  Each
		     triple  is a list containing a pattern, symbolic filename
		     and fragment reference, in this order. If	a  pattern  is
		     specified	multiple  times the last occurence of the pat‐
		     tern will be used.

		     The engine will consult the xref database when encounter‐
		     ing specific commands and will create a link if the rele‐
		     vant text matches one of the patterns. No	link  will  be
		     created  if  no  match was found. The link will go to the
		     uri file#fragment listed in the  relevant	triple,	 after
		     conversion	 of  the  symbolic file name to the actual uri
		     via dt_fmap (see  the  doctools  plugin  API  reference).
		     This file-to-uri mapping was build by calls to the method
		     map of the doctools object (See section OBJECT METHODS).

		     The following formatting commands will consult  the  xref
		     database:

		     cmd word
			    The	 command  will	look for the patterns sa,word,
			    and word, in this order. If this fails if it  will
			    convert word to all lowercase and try again.

		     syscmd word
			    The	 command  will	look for the patterns sa,word,
			    and word, in this order. If this fails if it  will
			    convert word to all lowercase and try again.

		     term word
			    The	 command  will	look for the patterns kw,word,
			    sa,word, and word, in this order. If this fails if
			    it	will  convert  word  to	 all lowercase and try
			    again.

		     package word
			    The command will look for  the  patterns  sa,word,
			    kw,word, and word, in this order. If this fails if
			    it will convert word  to  all  lowercase  and  try
			    again.

		     see_also word...
			    The	 command  will	look for the patterns sa,word,
			    and word, in this order, for each  word  given  to
			    the command. If this fails if it will convert word
			    to all lowercase and try again.

		     keywords word...
			    The command will look for  the  patterns  kw,word,
			    and	 word,	in  this order, for each word given to
			    the command. If this fails if it will convert word
			    to all lowercase and try again.

       latex  This engine generates output suitable for the latex text proces‐
	      sor coming out of the TeX world.

       list   This engine retrieves version, section and title of the  manpage
	      from  the	 document. As such it can be used to generate a direc‐
	      tory listing for a set of manpages.

       nroff  This engine generates nroff output, for processing by nroff,  or
	      groff.  The  result will be standard man pages as they are known
	      in the unix world.

       null   This engine generates no outout at all. This can be used if  one
	      just wants to validate some input.

       tmml   This  engine  generates TMML markup as specified by Joe English.
	      The Tcl Manpage Markup Language is a derivate of XML.

       wiki   This engine generates Wiki markup as understood by  Jean	Claude
	      Wippler's wikit application.

BUGS, IDEAS, FEEDBACK
       This  document,	and the package it describes, will undoubtedly contain
       bugs and other problems.	 Please report such in the  category  doctools
       of	the	  Tcllib       SF	Trackers       [http://source‐
       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
       enhancements you may have for either package and/or documentation.

SEE ALSO
       doctools_intro,	  doctools_lang_cmdref,	   doctools_lang_intro,	  doc‐
       tools_lang_syntax, doctools_plugin_apiref

KEYWORDS
       HTML, TMML, conversion, documentation, manpage, markup, nroff

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2003-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>

doctools			    1.4.10			   doctools(n)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net