Re: [Groff] Groff, Grohtml and Encodings

[Anton Shepelev]

Werner Lemberg:

> These  warning  messages  are harmless.  Reason is
> that grohtml processes the input twice:  One  time
> with  -Thtml  for text and a second time with -Tps
> for everything which grohtml can't  handle.   This
> second run causes the warning messages.
> [...]
> Admittedly, this is badly documented if at all.  I
> would be glad if  you  could  provide  patches  to
> improve that.

Below  is what I've added to the Description section
of grohtml man page. This is the first time  I  have
made  a  documentation  patch, so I thought I better
post it here so you could review it. I am not sure I
did  it correctly, maybe I should have added my text
into a new section  like  "Operation"  or  "Details"
instead of cluttering the succinct "Description"...

    grohtml  invokes  groff  twice. In the first
    pass pictures, equations and tables are ren-
    dered using the ps device, and in the second
    pass HTML output is generated  by  the  html
    device.

    grohtml  always  writes  output in the UTF-8
    encoding and has built-in entities  for  all
    non-composite  unicode  characters. However,
    groff may issue warnings about unknown  spe-
    cial  characters because they were not found
    during the first pass, when their absence is
    harmless  unless  they appear inside a table
    or equation.

The second paragraph is also to go  in  the  grohtml
info manual, although it is a violation of the "Once
and Only Once" principle -- I  don't  know  why  the
documentation is maintained in two formats.

Anton