unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



rsml(5)								      rsml(5)



NAME

  rsml,	sml - rsml and sml macro packages that support RSML-coded reference
  pages

SYNOPSIS

  tbl file... |	neqn | nroff -h	 [options] -man	 |  ...

  tbl file... |	neqn | nroff -h	 [options] -man.page  |	 ...

OPTIONS

  The following	descriptions of	options	contain	information about *troff out-
  put.	This is	provided for completeness, only.  Compaq does not supply or
  support any *troff formatters.

  -h  Uses output tabs during horizontal spacing to speed output and reduce
      output character count.  Tab settings are	assumed	to be every eight
      nominal character	widths.

  -nN Numbers the first	generated page as N.  Ignored by the *sml macros for
      nroff output.

      Ignored for *troff output	unless -rpS is also specified.

  -rlN
      Turns on line double-spacing mode	if N is	greater	than 0.

  -rnN
      Numbers the first	generated page as N.  Page numbers always print	on
      the outside end of the page footer.

      Ignored by the *sml macros for nroff output.

  -rpS
      Sets the section number to S.  Section numbers appear in output page
      footers as S-N (chapter-page-number).

      Page numbers always print	on the outside end of the page footer. Start-
      ing page number defaults to ``1''	unless -nN or -rnN is also specified.

      Ignored by the *sml macros for nroff output.

  -rv2
      Prints crop marks.  Only for use with *troff formatters.








DESCRIPTION

  Reference pages that originate from the Open Software	Foundation (OSF) and
  those	created	for Tru64 UNIX are coded using RSML (Reference Semantic
  Markup Language). This markup	is implemented through a combination of	two
  macro	packages, sml and rsml.	In addition, certain macros and	requests sup-
  ported for RSML coding are defined in	the tmac.an (man) macro	package.

  To use RSML coding in	a reference page, include the following	as the first
  two lines of the reference page source file:

       .so /usr/share/lib/tmac/sml
       .so /usr/share/lib/tmac/rsml

  Make sure these lines	are included in	the order shown; some rsml macro
  definitions are intended to overwrite	definitions in the sml and man macro
  sets.	You can	format a reference page	manually using the command line	shown
  in the SYNOPSIS section; specify one of the following	options	on your	com-
  mand line:

  -man	  To process the reference page	for unpaginated	viewing	or for print-
	  ing on ASCII printers

  -man.page
	  To process the reference page	for paginated ASCII output

  Do not specify a .so entry in	a reference page source	file to	include	the
  tmac.an or tmac.an.page macros from the /usr/share/lib/tmac directory. The
  man and catman commands automatically	specify	the -man option	to nroff when
  they process reference page source files; you	should follow the same con-
  vention when formatting reference pages directly with	*roff commands.

  The file argument in the command line	is the name of the reference page
  source file.

  Macros


  This section describes the macros used to mark up reference pages in Refer-
  ence Semantic	Markup Language	(RSML).

  Note that some of the	macro descriptions contain information about *troff
  output.  This	is provided for	completeness, only.  Compaq does not supply
  or support any *troff	formatters.

  Any text, phrase, or title argument in the following macro descriptions can
  consist of more than one word. Use quotation marks ("	") to enclose an
  argument containing more than	a single word.

  Note that the	.ds, .EN, .EQ, .ne, .PE, .PS, .T, .TE, and .TS macros are
  used in RSML markup but are implemented through the tmac.an (man) macro
  package.

  .AL Starts a numbered	list.  Use the .LI macro to identify the list items.
      Use the .LE macro	to end the list.

  .cE Ends a comment section.

  .cS Begins a comment section.	Text between a .cS and a .cE macro does	not
      appear in	the output.

  .dI subdocument
      Includes a subdocument containing	RSML markup.

  .dE Ends a type declaration section.

  .dS [arg-type]
      Starts a type declaration	section.  Use within a function	definition
      section (.fS/.fE). Use the optional arg-type argument to specify the
      argument type.  Place the	parameter name on a line between the .dS and
      .dE macros. Imbed	the .fS/.fE and	.dS/.dE	macro pairs within an .sS/.sE
      region.

  .ds string text
      Defines a	string.	 The argument string is	one or two characters. Use
      the \*string construct to	cause a	single-character string	to be
      replaced by the specified	text in	the output. Use	the \*(string con-
      struct to	cause a	two-character string to	be replaced by the specified
      text in the output.

  .E, phrase text
      Sets phrase in the font selected for emphasis, generally italics.	 The
      phrase is	followed by text set in	the normal font	with no	intervening
      space.

  .,E text phrase
      Sets phrase in the font selected for emphasis, generally italics.	 The
      phrase is	preceded by text set in	the normal font	with no	intervening
      space.

  .EC title
      Sets the title argument as the caption for an equation.

  .eI subdocument
      Includes an example subdocument.	No troff commands in the subdocument
      are processed.  The subdocument can contain backslash (\)	characters
      and lines	beginning with a period.  The subdocument is treated as	a
      display; line breaks in the subdocument cause line breaks	in the output
      document.

  .eM text
      Sets text	in the font selected for emphasis, generally italics.

  .EN Ends a section containing	one or more equations.

  .EQ Starts a section containing one or more equations.

  .EX title
      Sets the title argument as the caption for an example.

  .FG title
      Sets the title argument as the caption for a figure.

  .fE Ends a function definition section.

  .fS Starts a function	definition section. Use	the type declaration macros
      (.dS/.dE)	within the function definition macros (.fS/.fE). Imbed the
      .fS/.fE and .dS/.dE macro	pairs within an	.sS/.sE	region.

  .iE Ends a user command input	region.

  .iS Starts a user command input region.  When	a section is designed to show
      user command input, use the .iS/.iE markup.  This	region is not a
      display.	It continues to	the next page, if needed.  To ensure that a
      user command input region	is not continued over a	page boundary, use
      the .ne command to check for enough space	on the current page. The
      default font for an .iS/.iE region is \*L.

  .iX  ["-flags"] "primary" ["secondary"|"cross-reference"]
      Creates an index entry.  The primary entry is required; the flags	and
      other entries are	optional.  The flags are as follows:

      !	  Highlight an entry as	the main entry for this	topic.

      [	  Start	a page range for this topic.

      ]	  End a	page range for this topic.

      :	  Specify use of See other-entry-name instead of a page	number.

      ;	  Specify use of See also other-entry-name instead of a	page number.

      If used, the flags : or ;	must appear last.  The flag ! may be used
      with [, :, or ; -- no other combination is meaningful.

  .K, key text
      Sets the key argument in the bold	font and encloses it in	angle brack-
      ets.  The	key name is followed by	text set in the	normal font with no
      intervening space.  Use this macro when you have ordinary	text immedi-
      ately following the keyboard key name.

  .,K text key
      Sets the key argument in the bold	font and encloses it in	angle brack-
      ets.  The	key name is preceded by	text set in the	normal font with no
      intervening space.  Use this macro when you have ordinary	text immedi-
      ately preceding the keyboard key name.

  .kY key
      Sets the key argument in the bold	font and encloses it in	angle brack-
      ets.  Use	this macro to display the name of a keyboard key.

  .LE Ends a list started by .AL, .ML, or .VL.

  .LI [phrase]
      Marks an item in a list started by .AL, .ML, or .VL.  For	lists started
      by .AL and .ML, place the	list item on the lines following the .LI
      macro. The .VL macro starts a two-column list; place the left-column
      entry on the same	line as	the .LI	macro, surrounded by double quotes
      (" ").  Because the double quote character delimits the left-column
      entry, you must enter four double	quotes ("""") to print any double
      quote character that is part of the left-column entry. Place the
      right-column entry starting on the line below the	.LI macro.

  .ML Starts a marked list.  Use the .LI macro to identify the list items.
      Use the .LE macro	to end the list.

  .ne x
      Starts a new page	if fewer than x	number of lines	remain on the current
      page.

  .nL Forces a line break.

  .nP Forces a page break.

  .oE Ends a system output example region.

  .oS Starts a system output example region.  When a section is	designed to
      show system output or a file listing, use	the .oS/.oE markup.  This
      region is	not a display.	It continues to	the next page, if needed.  To
      ensure that a system output example region is not	continued over a page
      boundary,	use the	.ne command to check for enough	space on the current
      page. The	default	font for an .oS/.oE region is \*C.

  .PE Ends a pic drawing.

  .PP Starts a block paragraph.	 Sets the prevailing indent to .5i for nroff
      and four picas for *troff	text formatters.

  .PS Starts a pic drawing; for	use with *troff	text formatters	only.

  .rE [	k ]
      Returns to the kth relative right	shift indent level.  (Restores the
      left margin to the position prior	to the kth .rS call).  Specifying k=0
      is equivalent to specifying k=1.	If k is	omitted, .rE restores the
      left margin to the most recent previous position.	When k=1 or 0, the
      default .rS indent increment is restored.

  .rS [	i ]
      Shifts the left margin to	the right (relatively) the amount of i ens.
      The .rS macro calls can be nested	up to nine levels.  If i is not
      specified	for the	first .rS call,	the relative right shift increases .5
      inch for nroff and four picas for	*troff text formatters.	 Nested	.rS
      calls increment the relative indent by i ens, or by .2 inch for nroff,
      or by 2 picas for	*troff text formatters.

  .sE Ends a synopsis definition.

  .SH text
      Creates a	section	header.

  .SS text
      Creates a	subsection header.

  .sS Starts a synopsis	definition. When coding	function prototypes, imbed
      the .fS/.fE and .dS/.dE macro pairs within an .sS/.sE region. If you
      use the .iS/.iE macros to	code a function	prototype, imbed the .iS/.iE
      macros within the	.sS/.sE	region.	To code	a command synopsis, start the
      synopsis with the	.sS macro, code	the command line with \*L, \*V,	and
      \*O text markup, and end the synopsis with the .sE macro.

  .T& Changes the format of columns within a table.  Follow the	table con-
      tinue request (.T&&) with the new format line and then the	column data.

  .TB title
      Sets the title for a table.

  .TE Ends a table.

  .TH n	c[s] [fc] [fl] [hc] [o]	[a]
      Begins a new reference page and sets the page title.  Also sets up
      headers and footers for printed output pages and sets up all defaults
      and traps. The title appears as a	header on all pages of the formatted
      reference	page. The n argument is	the reference page name.  The c	argu-
      ment is the primary section number or letter. The	s argument is the
      subsection, if any.  The fc argument is optional and specifies the text
      for the page foot	center.	The fl argument	is optional and	specifies the
      text for the page	foot left. The hc argument is optional and specifies
      the text for the page head center. The o argument	is optional and	can
      be used for ``origin'' information; for example, ``Free Software Foun-
      dation'' or ``X11R5.'' The a argument is optional	and can	be used	to
      specify the machine architecture,	for example ``Alpha AXP.''

      Fields n,	c, and s appear	together at the	top of each output page	(see
      the top of this page for an example). These fields are displayed at
      both the top left	and right of the screen, or printed page. Fields fc
      and fl are in effect only	with the man.page macro	package, or when
      using a *troff formatter.	 Field hc appears at the top center of each
      output page. Field o, the	``origin'' label, appears under	the reference
      page name	and section number, at the top left and	right sides of the
      screen, or printed page. Field a appears under the ``origin'' label, or
      under the	reference page name and	section	number if there	is no ``ori-
      gin'' label, at the top left and right sides of the screen, or printed
      page.

      The last five fields are optional.  To skip a field, specify a pair of
      quotation	marks ("") in the field	to be skipped.

  .TS Starts a table.

  .VL indent
      Starts a two-column list.	 Specify the indent for	the list in i inches,
      c	centimeters, or	in m ems. Follow the .VL macro with the	list item
      (.LI) macro. Place the left-column entry on the same line	as the .LI
      macro, surrounded	by double quotes (" ").	 If the	left-column entry is
      a	phrase,	code a backslash before	each space to prevent the formatter
      from using the spaces when it calculates the justification for the
      first line. If the left-column entry is longer than the specified
      indent, code the .nL macro on the	line following the .LI macro to	force
      the right-column entry onto a new	line. Place the	right-column entry
      starting on the line below the .LI macro,	or on the line below the .nL
      macro, if	used.

  Meaningful Text Markup


  The following	describes the text markup that can be used in a	source file
  to change the	font for conveying the semantic	meaning	of the text.

  _______________________________________________________________
  Markup   Semantic Meaning    Examples		   Font	Produced
  _______________________________________________________________
  \*L	   Literal text				   Bold

			       User command
			       input, command
			       names, glossary
			       term in text
  \*V	   Variable text			   Italic

			       User-supplied
			       term
  \*O	   Ordinary text			   Roman font

			       Returns the font
			       to normal; use
			       after a font
			       change
  \*C	   Computer output			   Constant width

			       System output,
			       file listing
  \*E	   Emphasized text			   Italic

			       Book title,
			       emphasized term
  \*A			       Error constant	   Constant width

	   Alphabetic con-
	   stant
  \*N	   Numeric constant    Error constant	   Constant width
  _______________________________________________________________

  Macros That Need Text	Lines


  The following	macros affect the following line of text if they are speci-
  fied in the input without arguments:

  .SH	   .SS

  Defaults


  For a	list of	defaults, see the man(5) reference page.








RESTRICTIONS

  Using	man macros not described in this reference page	in the same source
  file with macros that	are described in this reference	page can give
  undesirable results.

  For a	list of	predefined registers, reserved registers, predefined strings,
  and reserved strings and macros for the man and man.page macro packages,
  see the man(5) reference page.

  In addition, the following sections describe the RSML	reserved registers,
  reserved strings, internal macros, and macro names reserved for future use.

  RSML Reserved	Registers


  The following	registers are reserved for internal use	by the macro packages
  for RSML:

  %n   #n   Ll	 $A   $M   $U
  |A   |B   |Q	 !x   !+   !%

  Predefined Strings


  The following	strings	are predefined for RSML	markup and should not be
  changed:

  lq  "if nroff, `` if *troff

  rq  "	if nroff, '' if	*troff

  RSML Reserved	Strings	and Macros


  The following	string and macro names are reserved for	internal use by	the
  macro	packages that implement	RSML:

  %n   #n   .e:	  .e;	.e,   .P#   .SP	  .!~	.)F

  The following	string names are reserved for RSML users:

  A   C	  E   L	  N   O	  U   V

  RSML Macro Names Reserved for	Future Use


  The following	macro names are	reserved for future use	by RSML	users:

  .aE	.aS   .lE   .lS	  .P!	.pI   .pM   .tH	  .wH

  .TH Macro Restrictions


  Section numbers should only be those listed in the man(1) reference page as
  recognized by	the man(1) command.

  Sections 5, 6, and the single-letter sections	listed in the man(1) refer-
  ence page normally do	not have subsections, so none should be	specified.

  Subsections ``.z'' and ``.Z''	are not	valid and should never be used.

  For nroff output, keep the size of the reference page	name, including	its
  section and subsection, to a maximum of 38 characters	to prevent overprint-
  ing in the reference page header.  Similarly,	restrict the size of the o
  and a	fields to a maximum of 38 characters. If the hc	field is used, reduce
  the size of the name,	section, and subsection	fields by the size of the hc
  field	+ 1.

  The maximum sizes for	the reference page name, o and a fields, are much
  shorter if the reference page	is formatted with a *troff formatter.

  The NAME Section


  The catman command assumes the NAME section of a reference page has the
  following format:

       name[, name, name ...] -	explanatory text

  There	should be at least one space after any comma and only one space	fol-
  lowing the ``hyphen''	(-).  A	``backslash hyphen'' (\-) may also be used to
  produce a longer dash. Avoid using Return characters,	macros,	or markup
  other	than \*L and \*O to code information in	the NAME section entry.	The
  explanatory text in this entry should	be brief. The catman command combines
  information in the NAME section with parameters of the .TH macro to create
  an entry in a	database searched by the apropos, man -k, and whatis com-
  mands. Unrecognized markup, use of the wildcard character (*), or unex-
  pected Return	characters in the NAME section cause errors or incorrect
  results when the whatis database is created or searched.

FILES

  /usr/share/lib/tmac/rsml
      RSML macros

  /usr/share/lib/tmac/sml
      SML macros

  /usr/share/lib/tmac/tmac.an
      man macros for unpaginated output

  /usr/share/lib/tmac/tmac.an.page
      man macros for paginated output

SEE ALSO

  Commands: checkeq(1),	man(1),	neqn(1), nroff(1), tbl(1), catman(8)

  Files: man(5)