src/devices/grohtml/grohtml.man

   1 .TH GROHTML @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .SH NAME
   3 grohtml \- html driver for groff
   4 .
   5 .
   6 .\" license
   7 .de co
   8 Copyright \[co] 1999-2014 Free Software Foundation, Inc.
   9
  10 Permission is granted to make and distribute verbatim copies of this
  11 manual provided the copyright notice and this permission notice are
  12 preserved on all copies.
  13
  14 Permission is granted to copy and distribute modified versions of this
  15 manual under the conditions for verbatim copying, provided that the
  16 entire resulting derived work is distributed under the terms of a
  17 permission notice identical to this one.
  18
  19 Permission is granted to copy and distribute translations of this
  20 manual into another language, under the above conditions for modified
  21 versions, except that this permission notice may be included in
  22 translations approved by the Free Software Foundation instead of in
  23 the original English.
  24 ..
  25 .
  26 .\" Like TP, but if specified indent is more than half
  27 .\" the current line-length - indent, use the default indent.
  28 .de Tp
  29 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  30 .  el .TP "\\$1"
  31 ..
  32 .
  33 .\" --------------------------------------------------------------------
  34 .SH SYNOPSIS
  35 .\" --------------------------------------------------------------------
  36 .
  37 .nr a \n(.j
  38 .ad l
  39 .nr i \n(.i
  40 .in +\w'\fBgrohtml 'u
  41 .ti \niu
  42 .B grohtml
  43 .
  44 .de OP
  45 .  ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
  46 .  el .RB "[\ " "\\$1" "\ ]"
  47 ..
  48 .
  49 .OP \-bhlnprv
  50 .OP \-a \%aa-text-bits
  51 .OP \-D dir
  52 .OP \-F dir
  53 .OP \-g \%aa-graphic-bits
  54 .OP \-i \%resolution
  55 .OP \-I \%image-stem
  56 .OP \-j \%filename
  57 .OP \-o \%image-vertical-offset
  58 .OP \-s size
  59 .OP \-S level
  60 .OP \-x \%html-dialect
  61 .RI "[\ " files\|.\|.\|. "\ ]"
  62 .br
  63 .ad \na
  64 .
  65 .
  66 .\" --------------------------------------------------------------------
  67 .SH DESCRIPTION
  68 .\" --------------------------------------------------------------------
  69 .
  70 The
  71 .B grohtml
  72 front end (which consists of a preprocessor,
  73 .BR pre-grohtml ,
  74 and a device driver,
  75 .BR post-grohtml )
  76 translates the output of GNU
  77 .B troff
  78 to html.
  79 .
  80 Users should always invoke
  81 .B grohtml
  82 via the groff command with a
  83 .B \-Thtml
  84 option.
  85 .
  86 If no files are given,
  87 .B grohtml
  88 will read the standard input.
  89 .
  90 A filename of
  91 .B \-
  92 will also cause
  93 .B grohtml
  94 to read the standard input.
  95 .
  96 Html output is written to the standard output.
  97 .
  98 When
  99 .B grohtml
 100 is run by
 101 .B groff
 102 options can be passed to
 103 .B grohtml
 104 using
 105 .BR groff \[aq]s
 106 .B \-P
 107 option.
 108 .
 109 .
 110 .PP
 111 .B grohtml
 112 invokes
 113 .B groff
 114 twice.
 115 In the first pass, pictures, equations, and tables are rendered
 116 using the
 117 .B ps
 118 device, and in the second pass HTML output is generated by the
 119 .B html
 120 device.
 121 .
 122 .
 123 .PP
 124 .B grohtml
 125 always writes output in \%UTF-8 encoding and has built-in entities for
 126 all non-composite unicode characters.
 127 .
 128 In spite of this, groff may issue warnings about unknown special
 129 characters if they can\[aq]t be found during the first pass.
 130 .
 131 Such warnings can be safely ignored unless the special characters
 132 appear inside a table or equation.
 133 .
 134 .
 135 .\" --------------------------------------------------------------------
 136 .SH OPTIONS
 137 .\" --------------------------------------------------------------------
 138 .
 139 .TP
 140 .BI \-a aa-text-bits
 141 Number of bits of antialiasing information to be used by
 142 .I text
 143 when generating png images.
 144 .
 145 The default is\~4 but valid values are 0, 1, 2, and\~4.
 146 .
 147 Note your version of
 148 .B gs
 149 needs to support the
 150 .B \%\-dTextAlphaBits
 151 and
 152 .B \%\-dGraphicAlphaBits
 153 options in order to exploit antialiasing.
 154 .
 155 A value of\~0 stops
 156 .B grohtml
 157 from issuing antialiasing commands to
 158 .BR gs .
 159 .
 160 .TP
 161 .B \-b
 162 Initialize the background color to white.
 163 .
 164 .TP
 165 .BI \-D dir
 166 Inform
 167 .B grohtml
 168 to place all image files into directory
 169 .IR dir .
 170 .
 171 .TP
 172 .B \-e
 173 This option should not be directly invoked by the user as it is an
 174 internal option utilized by
 175 .B groff
 176 when
 177 .B \-Thtml
 178 or
 179 .B \-Txhtml
 180 is specified.
 181 It is used by the
 182 .B grohtml
 183 preprocessor to determine whether
 184 .B eqn
 185 should attempt to produce MathML (if
 186 .B \-Txhtml
 187 is specified).
 188 .
 189 .TP
 190 .BI \-F dir
 191 Prepend directory
 192 .IB dir /dev name
 193 to the search path for font and device description files;
 194 .I name
 195 is the name of the device, usually
 196 .BR html .
 197 .
 198 .TP
 199 .BI \-g aa-graphic-bits
 200 Number of bits of antialiasing information to be used by
 201 .I graphics
 202 when generating png images.
 203 .
 204 The default is\~4 but valid values are 0, 1, 2, and\~4.
 205 .
 206 Note your version of
 207 .B gs
 208 needs to support the
 209 .B \%\-dTextAlphaBits
 210 and
 211 .B \%\-dGraphicAlphaBits
 212 options in order to exploit antialiasing.
 213 .
 214 A value of\~0 stops
 215 .B grohtml
 216 from issuing antialiasing commands to
 217 .BR gs .
 218 .
 219 .TP
 220 .B \-h
 221 Generate section and number headings by using
 222 .BR <B> .\|.\|. </B>
 223 and increasing the font size, rather than using the
 224 .BI <H n >\c
 225 \&.\|.\|.\c
 226 .BI </H n >
 227 tags.
 228 .
 229 .TP
 230 .BI \-i resolution
 231 Select the resolution for all images.
 232 .
 233 By default this is 100 pixels per inch.
 234 .
 235 Example:
 236 .B \-i200
 237 indicates 200 pixels per inch.
 238 .
 239 .TP
 240 .BI \-I stem
 241 Determine the image stem name.
 242 .
 243 If omitted grohtml uses
 244 .BI \%grohtml- XXX
 245 .RI ( XXX
 246 is the process ID).
 247 .
 248 .TP
 249 .BI \-j filename
 250 Inform
 251 .B grohtml
 252 to split the html output into multiple files.
 253 .
 254 The
 255 .I filename
 256 is the stem and specified section headings (default is level one)
 257 start a new file, named
 258 .IR filename-n.html .
 259 .
 260 .TP
 261 .B \-l
 262 Turn off the production of automatic section links at the top of the
 263 document.
 264 .
 265 .TP
 266 .B \-n
 267 Generate simple heading anchors whenever a section/number heading is
 268 found.
 269 .
 270 Without the option the anchor value is the textual heading.
 271 .
 272 This can cause problems when a heading contains a \[oq]?\[cq] on older
 273 versions of some browsers (Netscape).
 274 .
 275 This flag is automatically turned on if a heading contains an image.
 276 .
 277 .TP
 278 .BI \-o vertical-offset
 279 Specify the vertical offset of images in points.
 280 .
 281 .TP
 282 .B \-p
 283 Display page rendering progress to stderr.
 284 .B grohtml
 285 only displays a page number when an image is required.
 286 .
 287 .TP
 288 .B \-r
 289 Turn off the automatic header and footer line (html rule).
 290 .
 291 .TP
 292 .B \-s size
 293 Set the base point size of the source file.
 294 .
 295 Thereafter when this point size is used in the source it will
 296 correspond to the html base size.
 297 .
 298 Every increase of two points in the source will yield a
 299 .B <big>
 300 tag, and conversely when a decrease of two points is seen a
 301 .B <small>
 302 tag is emitted.
 303 .
 304 .TP
 305 .BI \-S level
 306 When splitting html output,
 307 split at the heading level (or higher) defined by
 308 .IR level .
 309 .
 310 .TP
 311 .B \-v
 312 Print the version number.
 313 .
 314 .TP
 315 .B \-V
 316 Create an XHTML or HTML validator button at the bottom of each page of
 317 the document.
 318 .
 319 .TP
 320 .BI \-x dialect
 321 Select HTML dialect.
 322 .
 323 Currently,
 324 .I dialect
 325 should be either the digit\~\c
 326 .B 4
 327 or the letter\~\c
 328 .B x
 329 which indicates whether
 330 .B grohtml
 331 should generate HTML\~4 or XHTML, respectively.
 332 .
 333 This option should not be directly invoked by the user as it is
 334 an internal option utilized by
 335 .B groff
 336 when
 337 .B \-Thtml
 338 or
 339 .B \-Txhtml
 340 is specified.
 341 .
 342 .TP
 343 .B \-y
 344 Produce a right-justified groff signature at the end of the document.
 345 .
 346 This is only generated if the
 347 .B \-V
 348 flag is also specified.
 349 .
 350 .
 351 .\" --------------------------------------------------------------------
 352 .SH USAGE
 353 .\" --------------------------------------------------------------------
 354 .
 355 There are styles called
 356 .BR R ,
 357 .BR I ,
 358 .BR B ,
 359 and
 360 .B BI
 361 mounted at font positions 1 to\~4.
 362 .
 363 .
 364 .\" --------------------------------------------------------------------
 365 .SH DEPENDENCIES
 366 .\" --------------------------------------------------------------------
 367 .
 368 .B grohtml
 369 is dependent upon the png utilities
 370 .RB ( \%pnmcut ,
 371 .BR \%pnmcrop ,
 372 .BR \%pnmtopng )
 373 and GhostScript
 374 .RB ( gs ).
 375 .
 376 .B \%pnmtopng
 377 (version 2.37.6 or greater)
 378 and
 379 .B \%pnmcut
 380 from the netpbm package (version 9.16 or greater) will work also.
 381 .
 382 It is also dependent upon
 383 .B \%psselect
 384 from the
 385 .B PSUtils
 386 package.
 387 .
 388 Images are generated whenever a table, picture, equation or line is
 389 encountered.
 390 .
 391 .
 392 .\" --------------------------------------------------------------------
 393 .SH FILES
 394 .\" --------------------------------------------------------------------
 395 .
 396 .B grohtml
 397 uses temporary files.
 398 .
 399 See the
 400 .BR groff (@MAN1EXT@)
 401 man page for details where such files are created.
 402 .
 403 .
 404 .\" --------------------------------------------------------------------
 405 .SH ENVIRONMENT
 406 .\" --------------------------------------------------------------------
 407 .
 408 .TP
 409 .SM
 410 .B GROFF_FONT_PATH
 411 A list of directories in which to search for the
 412 .BI dev name
 413 directory in addition to the default ones.
 414 .
 415 See
 416 .BR @g@troff (@MAN1EXT@)
 417 and
 418 .BR \%groff_font (@MAN5EXT@)
 419 for more details.
 420 .
 421 .
 422 .\" --------------------------------------------------------------------
 423 .SH BUGS
 424 .\" --------------------------------------------------------------------
 425 .
 426 .B Grohtml
 427 has been completely redesigned and rewritten.
 428 .
 429 It is still beta code.
 430 .
 431 .
 432 .\" --------------------------------------------------------------------
 433 .SH "SEE ALSO"
 434 .\" --------------------------------------------------------------------
 435 .
 436 .BR afmtodit (@MAN1EXT@),
 437 .BR groff (@MAN1EXT@),
 438 .BR @g@troff (@MAN1EXT@),
 439 .BR psbb (@MAN1EXT@),
 440 .BR groff_out (@MAN5EXT@),
 441 .BR groff_font (@MAN5EXT@),
 442 .BR groff_char (@MAN7EXT@)
 443 .
 444 .
 445 .\" --------------------------------------------------------------------
 446 .SH "LICENSE"
 447 .\" --------------------------------------------------------------------
 448 .co
 449 .
 450 .
 451 .\" Local Variables:
 452 .\" mode: nroff
 453 .\" End: