Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for dtformat (redhat section n)

format(n)			       Documentation tools				format(n)

NAME
       format - Specification of simple tcl markup for manpages

SYNOPSIS
       manpage_begin command section version

       manpage_end

       moddesc desc

       titledesc desc

       description

       require pkg ?version?

       section name

       para

       see_also args

       keywords args

       arg text

       cmd text

       opt text

       emph text

       strong text

       comment text

       sectref text

       syscmd text

       method text

       option text

       widget text

       fun text

       type text

       package text

       class text

       var text

       file text

       uri text

       term text

       const text

       nl

       lb

       rb

       example_begin

       example_end

       example text

       list_begin what

       list_end

       bullet

       enum

       lst_item text

       call args

       arg_def type name ?mode?

       opt_def name ?arg?

       cmd_def command

       tkoption_def name dbname dbclass

       usage args

DESCRIPTION
       This manpage specifies

       [1]    The overall format of manpages using this markup, and

       [2]    the tcl commands used as the markup

       The manpage format described here is simpler than TMML, but convertible into it (and other
       formats, like HTML and nroff).

       The tcl sources of this manpage can serve as an example for all of the markup described by
       it. Every possible construct (with the exception of require) is used here.

OVERVIEW
       o      The  main commands are manpage_begin, manpage_end, moddesc, titledesc, and descrip-
	      tion. Four of these five are required  for  a  manpage.  The  optional  command  is
	      titledesc. The first two are the first and last commands in a manpage. Neither text
	      nor other commands may precede manpage_begin nor follow manpage_end.   The  command
	      description separates header and body of the manpage and may not be omitted.

	      The  remaining  commands	(moddesc  and titledesc) provide one-line descriptions of
	      module and specific title respectively.

       o      The only text allowed between manpage_begin and description is the command require.
	      Other  commands or normal text are not permitted. require is used to list the pack-
	      ages the described command(s) depend(s) on for its  operation.  This  list  can  be
	      empty.

       o      After  description  text	and all other commands are allowed. The text can be sepa-
	      rated into highlevel blocks using  named	sections.   Each  block  can  be  further
	      divided into paragraphs via para.

       o      The  commands  see_also  and keywords define whole sections named SEE ALSO and KEY-
	      WORDS. They can occur everywhere in the manpage but making them the last section is
	      the usual thing to do. They can be omitted.

       o      There  are five commands available to markup words, arg, cmd, opt, emph and strong.
	      The first three are used to mark words as command arguments, as command  names  and
	      as  optional.  The  other two are visual markup to emphasize words in two different
	      ways. The term words is used in a loose sense here, i.e application of the commands
	      to a sequence of words is entierely possible, if they are properly quoted.

       o      Another  set  of	commands is available to construct (possibly nested) lists. These
	      are list_begin, list_end, lst_item, bullet, enum, call, arg_def, opt_def,  cmd_def,
	      and tkoption_def. The first two of these begin and end a list respectively.

	      The  argument to the first command denotes the type of the list. The allowed values
	      and their associated item command are explained later, in the section detailing the
	      Commands.

	      The  other  commands  start  list  items and each can be used only inside a list of
	      their type. In other words, bullet is allowed in bulleted lists but  nowhere  else,
	      enum  in enumerated lists and lst_item and call are for definition lists. These two
	      commands also have some text directly associated with the item although  the  major
	      bulk of the item is the text following the item until the next list command.

	      The last list command, call is special. It is used to describe the syntax of a com-
	      mand and its arguments. It should not only cause the appropriate markup of  a  list
	      item  at	its  place but also add the syntax to the table of contents (synopsis) if
	      supported by the output format in question. nroff and HTML for example do. A format
	      focused on logical markup, like TMML, may not.

       o      The  command  usage  is  similar to call in that it adds the syntax to the table of
	      contents (synopsis) if supported by the output format. Unlike call,   this  command
	      doens't  add any text to the output as a direct result of the command. Thus, it can
	      be used anywhere within the document to add usage information. Typically it is used
	      near the top of the document, in cases where it is not desireable to use call else-
	      here in the document, or where additional usage information is desired (eg: to doc-
	      ument a "package require" command).

Commands
       manpage_begin command section version
	      This  command begins a manpage. Nothing is allowed to precede it. Arguments are the
	      name of the command described by the manpage, the section of the manpages this man-
	      pages  lives  in, the version of the module containing the command, the name of the
	      module itself and two descriptions, one short for the command and one a bit  longer
	      for the module. Both have to fit on one line.

       manpage_end
	      This command closes a manpage. Nothing is allowed to follow it.

       moddesc desc
	      This  command  is required and comes after manpage_begin, but before either require
	      or description.  Its  argument  provides	a  one-line  description  of  the  module
	      described by the manpage.

       titledesc desc
	      This  command  is optional and comes after manpage_begin, but before either require
	      or description. Its argument provides a one-line expansion of  the  title  for  the
	      manpage.	If  this command is not used the manpage processor has to use information
	      from moddesc instead.

       description
	      This command separates the header part of the manpage  from  the	main  body.  Only
	      require, moddesc, or titledesc may precede it.

       require pkg ?version?
	      May  occur only between manpage_begin and description. Is used to list the packages
	      which are required for the described command to be operational.

       section name
	      Used to structure the body of the manpage into named sections. This command is  not
	      allowed inside of a list or example. It implicitly closes the last paragraph before
	      the command and also implicitly opens the first paragraph of the new section.

       para   Used to structure sections into paragraphs. Must not be used inside of  a  list  or
	      example.

       see_also args
	      Creates  a  section SEE ALSO containing the arguments as cross-references. Must not
	      be used inside of a list or example.

       keywords args
	      Creates a section KEYWORDS containing the arguments as words indexing the  manpage.
	      Must not be used inside of a list or example.

       arg text
	      Declares that the marked text is the name of a command argument.

       cmd text
	      Declares that the marked text is the name of a command.

       opt text
	      Declares that the marked text is something optional. Most often used in conjunction
	      with arg to denote optional command arguments.

       emph text
	      One way to emphasize text in a general manner.

       strong text
	      Another way to emphasize text in a general manner.

       comment text
	      Declares that the marked text is a comment.

       sectref text
	      Declares that the marked text is a section reference.

       syscmd text
	      Declares that the marked text is a system command.

       method text
	      Declares that the marked text is a object method.

       option text
	      Declares that the marked text is a option.

       widget text
	      Declares that the marked text is a widget.

       fun text
	      Declares that the marked text is a function.

       type text
	      Declares that the marked text is a data type.

       package text
	      Declares that the marked text is a package.

       class text
	      Declares that the marked text is a class.

       var text
	      Declares that the marked text is a variable.

       file text
	      Declares that the marked text is a file .

       uri text
	      Declares that the marked text is a uri.

       term text
	      Declares that the marked text is a unspecific terminology.

       const text
	      Declares that the marked text is a constant value.

       nl     Vertical space to separate text without breaking it into a new paragraph.

       lb     Introduces a left bracket into the output.

       rb     Introduces a right bracket into the output. The bracket commands are  necessary  as
	      plain brackets are used to denote the beginnings and endings of the formatting com-
	      mands.

       example_begin
	      Formats subsequent text as a code sample: line breaks, spaces, and  tabs	are  pre-
	      served and, where appropriate, text is presented in a fixed-width font.

       example_end
	      End of a code sample block.

       example text
	      Formats  text  as  a  multi-line	block of sample code.  text should be enclosed in
	      braces.

       list_begin what
	      Starts new list of type what. The allowed types (and  their  associated  item  com-
	      mands) are:

	      bullet bullet

	      enum   enum

	      definitions
		     lst_item and call

	      arg    arg_def

	      cmd    cmd_def

	      opt    opt_def

	      tkoption
		     tkoption_def

       list_end
	      Ends the list opened by the last list_begin.

       bullet Starts a new item in a bulleted list.

       enum   Starts a new item in an enumerated list.

       lst_item text
	      Starts a new item in a definition list. The argument is the term to be defined.

       call args
	      Starts a new item in a definition list, but the term defined by it is a command and
	      its arguments.

       arg_def type name ?mode?
	      Starts a new item in an argument list. Specifies the  data-type  of  the	described
	      argument, its name and possibly its i/o-mode.

       opt_def name ?arg?
	      Starts  a new item in an option list. Specifies the name of the option and possible
	      (i.e. optional) arguments.

       cmd_def command
	      Starts a new item in a command list. Specifies the name of the command.

       tkoption_def name dbname dbclass
	      Starts a new item in a widget option list.  Specifies the name of the option,  i.e.
	      the name used in scripts, name used by the option database, and the class (type) of
	      the option.

       usage args
	      Defines a term to be used in the table of contents or synopsis  section,	depending
	      on  the format. This command is silent, as it doesn't add any text to the output as
	      a direct result of the call. It merely defines data to appear in another section.

SEE ALSO
       expander(n), formatter(n), mpexpand(n)

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

doctools				       1.0					format(n)


All times are GMT -4. The time now is 07:00 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password