src/devices/grohtml/grohtml.1.man

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