[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] grohtml shortcomings
|
From: |
James K. Lowden |
|
Subject: |
[groff] grohtml shortcomings |
|
Date: |
Mon, 3 Dec 2018 16:46:31 -0500 |
I converted the Heimdal kf.1 page to html recently, and found what I
consider to be problems with both appearance and HTML style.
https://github.com/heimdal/heimdal/blob/1d4ebc0df798cb1d8edca910b806e55c6c19bccb/appl/kf/kf.1
GNU groff version 1.22.3
Command:
groff -man -T html man1/kf.1 > html1/kf.1.html
The appearance problem is layout. The problem might be related to the
mdoc .Oo and ..Oc macros. The SYNOPSIS reads as follows:
<p style="margin-top: 1em"><b>SYNOPSIS</b></p>
<p style="margin-left:10%;"><b>kf</b> [</p>
<p><b>−p</b> <i>port</i> |
<b>−−port</b>=<i>port</i> ] [ <b><br>
−l</b> <i>login</i> |
<b>−−login</b>=<i>login</i> ] [ <b><br>
−c</b> <i>ccache</i> |
<b>−−ccache</b>=<i>ccache</i> ]
[<b>−F </b>| <b>−-forwardable</b>]
[<b>−G </b>| <b>−-no-forwardable</b>]
[<b>−h </b>| <b>−-help</b>]
[<b>−−version</b>] <i>host ...</i></p>
Those <br> tags aren't desirable. I suspect they are artifacts of the
linefeeds in the input:
.Nd securely forward tickets
.Sh SYNOPSIS
.Nm
.Oo
.Fl p Ar port |
.Fl Fl port Ns = Ns Ar port
.Oc
My other complaint is the way style is used. grohtml offers no way
to include alternative CSS at the top of each page, and imposes quite a
bit of style on a per-tag basis, instead of by class. That overrides
site-provided CSS, which is pretty much never what you want.
IMO groff should produce valid, unstyled HTML by default, with classes
assigned to divisions, spans, and other tags named to reflect the input
macros that generated them. Optionally it would generate either a
default <style> or one provided by the user.
For example, at the top is
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title></title>
(Unfortunately, grohtml generates no title in this case.)
This sets H1 headers to be centered, and paragraph text as
top-aligned. I have no idea why those particular choices were made, and
I have no way to defeat it.
I happen to like the advice offered by Richard Rutter in "The Elements
of Typographic Style Applied to the Web"
(http://webtypography.net/2.2.1). Based on his recommendation, I use:
p, dt, dd { line-height: 1.3 }
There is no convenient way to include that in the grohtml output, either
directly or by reference to an external CSS file.
I imagine most people work around the restriction by post-processing
the HTML or perhaps by adding device-specific escapes prior to
processing with groff. I'm considering diving into the code to
1. replace the per-tag styles with classes
2. constrain all CSS to the <head> section
3. add an option to replace the default CSS with inclusion or
reference to CSS of the user's choosing.
Before I roll up my sleeves, I thought I'd ask for comments about that
approach versus the current one.
By the way, since we've been talking about the manual lately, I will
mention that under BUGS, grohtml says:
"Grohtml has been completely redesigned and rewritten. It is
still beta code."
and groff_www says, in DESCRIPTION:
"... the html device driver (grohtml) has been completely
rewritten but still remains as in an alpha state."
Not sure which to believe.... :-/
On a more positive note, the output of the completely redesigned
grohtml is better than it was. A colleague tried 1.18.1.4; it used HTML
tables to control the layout, for some value of "control". That output
was more along the lines of what I remember from an earlier excursion
into this area. So despite my complaints I would say we're moving in
the right direction.
--jkl
- [groff] grohtml shortcomings,
James K. Lowden <=