doc/spam.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>OSPAM</TITLE>
   5 </HEAD>
   6 <BODY>
   7 <H1>OSPAM</H1>
   8 <H4>
   9 An SGML System Conforming to International Standard ISO 8879 --
  10 Standard Generalized Markup Language
  11 </H4>
  12 <H4>
  13 An SGML Extended Facilities system conforming to
  14 Annex A of International Standard ISO/IEC 10744 --
  15 Hypermedia/Time-based Structuring Language
  16 </H4>
  17 <H2>
  18 SYNOPSIS
  19 </H2>
  20 <P>
  21 <CODE>ospam</CODE> [ <CODE>option...</CODE> ] <CODE><VAR>sysid...</VAR></CODE>
  22 <H2>DESCRIPTION</H2>
  23 <P>
  24 Ospam (SP Add Markup) is an SGML markup stream editor implemented using the
  25 OpenSP parser. Ospam parses the SGML document contained in
  26 <CODE><VAR>sysid...</VAR></CODE> and copies to the standard output the portion
  27 of the document entity containing the document instance, adding or changing
  28 markup as specified by the <CODE>-m</CODE> options. The <CODE>-p</CODE> option
  29 can be used to include the SGML declaration and prolog in the output. The
  30 <CODE>-o</CODE> option can be used to output other entities. The
  31 <CODE>-x</CODE> option can be used to expand entity references.
  32 <H2>OPTIONS</H2>
  33 <P>
  34 The following options are available:
  35 <DL>
  36 <DT>
  37 <CODE>-c<VAR>sysid</VAR></CODE>,
  38 <CODE>--catalog=<VAR>sysid</VAR></CODE>,
  39 <DD>
  40 Use the catalog entry file <CODE><VAR>sysid</VAR></CODE>.
  41 <DT>
  42 <CODE>-C</CODE>,
  43 <CODE>--catalogs</CODE>
  44 <DD>
  45 This has the same effect as in <A HREF="nsgmls.htm#optC">onsgmls</A>.
  46 <DT>
  47 <CODE>-D<VAR>directory</VAR></CODE>,
  48 <CODE>--directory=<VAR>directory</VAR></CODE>
  49 <DD>
  50 Search <CODE><VAR>directory</VAR></CODE> for files specified in system
  51 identifiers.  This has the same effect as in
  52 <A HREF="nsgmls.htm#optD">onsgmls</A>.
  53 <DT>
  54 <CODE>-e</CODE>,
  55 <CODE>--open-entities</CODE>
  56 <DD>
  57 Describe open entities in error messages.
  58 <DT>
  59 <CODE>-f<VAR>file</VAR></CODE>,
  60 <CODE>--error-file=<VAR>file</VAR></CODE>
  61 <DD>
  62 Redirect errors to <CODE><VAR>file</VAR></CODE>.
  63 This is useful mainly with shells that do not support redirection
  64 of stderr.
  65 <DT>
  66 <CODE>--help</CODE>
  67 <DD>Show a help message and exit.
  68 <DT>
  69 <CODE>-h</CODE>,
  70 <CODE>--hoist-omitted-tags</CODE>
  71 <DD>
  72 Hoist omitted tags out from the start of internal entities.
  73 If the text at the beginning of an internal entity causes
  74 a tag to be implied, the tag will usually be treated as being in that
  75 internal entity; this option will instead cause it to be treated as
  76 being in the entity that referenced the internal entity.
  77 This option makes a difference in conjunction with
  78 <CODE>-momittag</CODE>
  79 or
  80 <CODE>-x -x</CODE>.
  81 <DT>
  82 <CODE>-i<VAR>name</VAR></CODE>,
  83 <CODE>--include=<VAR>name</VAR></CODE>
  84 <DD>
  85 This has the same effect as in <A HREF="nsgmls.htm#opti">onsgmls</A>.
  86 <DT>
  87 <CODE>-l</CODE>,
  88 <CODE>--lowercase</CODE>
  89 <DD>
  90 Prefer lower-case.
  91 Added names that were subject to upper-case substitution
  92 will be converted to lower-case.
  93 <DT>
  94 <CODE>-m<VAR>option</VAR></CODE>,
  95 <CODE>--markup-option=<VAR>option</VAR></CODE>
  96 <DD>
  97 Change the markup in the output according to the value
  98 of <CODE><VAR>option</VAR></CODE> as follows:
  99 <DL>
 100 <DT>
 101 <CODE>omittag</CODE>
 102 <DD>
 103 Add tags that were omitted using omitted tag minimization.
 104 End tags that were omitted because the element has
 105 a declared content of <SAMP>EMPTY</SAMP>
 106 or an explicit content reference
 107 will not be added.
 108 <DT>
 109 <CODE>shortref</CODE>
 110 <DD>
 111 Replace short references by named entity references.
 112 <DT>
 113 <CODE>net</CODE>
 114 <DD>
 115 Change null end-tags
 116 into unminimized end-tags,
 117 and change net-enabling start-tags
 118 into unminimized start-tags.
 119 <DT>
 120 <CODE>emptytag</CODE>
 121 <DD>
 122 Change empty tags into unminimized tags.
 123 <DT>
 124 <CODE>unclosed</CODE>
 125 <DD>
 126 Change unclosed tags into unminimized tags.
 127 <DT>
 128 <CODE>attname</CODE>
 129 <DD>
 130 Add omitted attribute names and
 131 <CODE>vi</CODE>s.
 132 <DT>
 133 <CODE>attvalue</CODE>
 134 <DD>
 135 Add literal delimiters omitted from attribute values.
 136 <DT>
 137 <CODE>attspec</CODE>
 138 <DD>
 139 Add omitted attribute specifications.
 140 <DT>
 141 <CODE>current</CODE>
 142 <DD>
 143 Add omitted attribute specifications for current attributes.
 144 This option is implied by the
 145 <CODE>attspec</CODE>
 146 option.
 147 <DT>
 148 <CODE>shorttag</CODE>
 149 <DD>
 150 Equivalent to combination of
 151 <CODE>net</CODE>,
 152 <CODE>emptytag</CODE>,
 153 <CODE>unclosed</CODE>,
 154 <CODE>attname</CODE>,
 155 <CODE>attvalue</CODE>
 156 and
 157 <CODE>attspec</CODE>
 158 options.
 159 <DT>
 160 <CODE>rank</CODE>
 161 <DD>
 162 Add omitted rank suffixes.
 163 <DT>
 164 <CODE>reserved</CODE>
 165 <DD>
 166 Put reserved names in upper-case.
 167 <DT>
 168 <CODE>ms</CODE>
 169 <DD>
 170 Remove marked section declarations whose effective status
 171 is IGNORE, and replace each marked section declaration
 172 whose effective status is INCLUDE by its marked section.
 173 In the document instance, empty comments will be added
 174 before or after the marked section declaration to ensure
 175 that ignored record ends remain ignored.
 176 </DL>
 177 <P>
 178 Multiple
 179 <CODE>-m</CODE>
 180 options are allowed.
 181 <DT>
 182 <CODE>-o<VAR>name</VAR></CODE>,
 183 <CODE>--output-entity=<VAR>name</VAR></CODE>
 184 <DD>
 185 Output the general entity <CODE><VAR>name</VAR></CODE> instead of
 186 the document entity.  The output will correspond to the first time
 187 that the entity is referenced in content.
 188 <DT>
 189 <CODE>-p</CODE>,
 190 <CODE>-output-prolog</CODE>
 191 <DD>
 192 Output the part of the document entity containing the SGML declaration
 193 (if it was explicitly present in the document entity)
 194 and the prolog before anything else.
 195 If this option is specified two or more times,
 196 then all entity references occurring between declarations
 197 in the prolog will be expanded;
 198 this includes the implicit reference to the entity
 199 containing the external subset of the DTD, if there is one.
 200 Note that the SGML declaration will not be included if it was
 201 specified by an SGMLDECL entry in a catalog.
 202 <DT>
 203 <CODE>-r</CODE>,
 204 <CODE>--raw</CODE>
 205 <DD>
 206 Don't perform any conversion on RSs and REs when outputting the entity.
 207 The entity would typically have the storage manager attribute
 208 <CODE>records=asis</CODE>.
 209 <DT>
 210 <CODE>-R</CODE>,
 211 <CODE>--restricted</CODE>
 212 <DD>
 213 This has the same effect as in <A HREF="nsgmls.htm#optR">onsgmls</A>.
 214 <DT>
 215 <CODE>-v</CODE>,
 216 <CODE>--version</CODE>
 217 <DD>
 218 Print the version number.
 219 <DT>
 220 <CODE>-w<VAR>type</VAR></CODE>,
 221 <CODE>--warning=<VAR>type</VAR></CODE>
 222 <DD>
 223 Control warnings and errors according to
 224 <CODE><VAR>type</VAR></CODE>.
 225 This has the same effect as in <A HREF="nsgmls.htm#optw">onsgmls</A>.
 226 <DT>
 227 <CODE>-x</CODE>,
 228 <CODE>--expand-references</CODE>
 229 <DD>
 230 Expand references to entities that are changed.
 231 If this option is specified two or more times,
 232 then all references to entities that contain tags
 233 will be expanded.
 234 </DL>
 235
 236 <H2>BUGS</H2>
 237 <P>
 238 Omitted tags are added at the point where they are
 239 implied by the SGML parser (except as modified
 240 by the
 241 <CODE>-h</CODE>
 242 option); this is often not quite where they are wanted.
 243 <P>
 244 The case of general delimiters is not preserved.
 245 <P>
 246 Incorrect results may be produced if a variant concrete syntax is used
 247 which is such that there are delimiters in markup to be added that have a
 248 prefix that is a proper suffix of some other delimiter.
 249 <P>
 250 If an entity reference in a default value uses the default entity and
 251 an entity with that name is subsequently defined and that default
 252 value is added to the document instance, then the resulting document
 253 may not be equivalent to the original document.
 254 Ospam will give a warning when the first two conditions are met.
 255 </BODY>
 256 </HTML>