document, <h1> is intended for top level headers, and most of the
sections in a manual page can hardly be considered top-level.
It is more usual to use <h1> only for the main title of the document
of for the site name.
Consequently, move .Sh/.SH from <h1> to <h2> and .Ss/.SS from <h2>
to <h3>, freeing <h1> for use by header.html in man.cgi(8).
Discussed with Anna Vyalkova <cyber at sysrq dot in>.
and use flexbox CSS instead. Improve accessibility by adding role
and aria-label attributes to these header and footer lines.
Using ideas from both Anna Vyalkova <cyber at sysrq dot in> and myself.
As a welcome side effect, this also resolves the long-standing issue
that the rendering was always 65em wide, requiring horizontal scrolling
when the window was narrower. Now, rendering nicely adapts to browser
windows of arbitrary narrowness.
HTML <main> element. The benefit is that it has the ARIA landmark
role "main" by default. To ease the transition for people using
their own CSS file instead of mandoc.css, retain the custom class
for now.
I had this idea in a discussion with Anna Vyalkova <cyber at sysrq dot in>.
Patch from Anna, slightly tweaked by me.
two-value syntax "display: inline flow;" instead. In particular, there
is no need to establish a new block formatting context with "flow-root",
and in fact that's detrimental because it appears to introduce spurious
soft-wrap opportunities.
jmc@ reported a bogus line break between the opening angle bracket
generated by .Aq Mt and the following email address.
font, rather than with the monospace font appropriate for .Bd -literal.
This fixes a minibug reported by anton@.
Implemented by no longer relying on the typical browser default of
"pre { font-family: monospace }" but instead letting <pre> elements
inherit the font family from their parent, then adding an explicit CSS .Li
class only for those displays where the manual page author requested it
by using the -literal option on the .Bd macro.
which has long been know to cause ugly and pointless scroll bars.
Matthew Martin <phy1729 at gmail dot com>
helpfully explained the following two points to me:
1. What we need to do here is establish a new block formatting
context such that the first line of the <dd> content moves down
rather than to the right if the preceding <dt> is wide.
2. A comprehensive list of methods
to establish block formatting context is available in:
https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Block_formatting_context
In that list, i found that "column-count: 1" does the job.
It is part of CSS Multi-column Layout Level 1.
While that is still in Working Draft status according to
https://www.w3.org/Style/CSS/current-work ,
it is fully supported by all browsers according to
https://developer.mozilla.org/en-US/docs/Web/CSS/column-count ,
probably because it was already part of the second draft of this
standard almost 20 years ago: WD-css3-multicol-20010118.
as recommended for accessibility by the HTML 5 standard.
Triggered by a similar, but slightly different suggestion
from Laura Morales <lauretas at mail dot com>.
violated the principle of separation of content and presentation.
Instead, implement the tooltips purely in CSS.
Thanks to John Gardner <gardnerjohng at gmail dot com> for
suggesting most of the styling in the new ::before rules.
having to write empty list elements for non-compact .Bl -tag lists:
1. Add margin-bottom to the <dd>.
Note that margin-top on the <dt> doesn't work because it would put
a short <dt> lower than the <dd>; margin-bottom on the <dt> doesn't
work because it would put vertical space before the <dd> for a long
<dt>; and margin-top on the <dd> doesn't work because it would put
a short <dt> higher than the <dd>. Only margin-bottom on the <dd>
has none of these adverse effects.
2. Of course, margin-bottom on the <dd> fails to take care of the
vertical spacing before the first list element, so implement that
separately by margin-top on the <dl>.
3. For .Bl -tag -compact, reset both to zero.
Required because browsers tend to have inconsistent defaults:
For example, Firefox 62.0.2 sets border-color for tbody, but not for table,
and Pali Rohar reports that Chrome set it for td, but not for tr or tbody.
The td part is from Pali Rohar, the tbody and tr parts from me.
as far as they are on the edges of table cells
rather than going through the middle of cells:
* the box, doublebox, and allbox options;
* the | and || layout modifiers;
* and the _ and = data lines;
- but not yet _ and = in individual layout and data cells.
Missing feature reported by Pali dot Rohar at gmail dot com.
The reason for doing this rather than using the ISC license
is that i guess that in some contexts, a requirement to preserve
a Copyright and license header might be inconvenient, and i really
don't care at all how people use it.
What matters is that they do use it, or something similar - attempts
to use mandoc without any CSS are a constant source of grief and
bogus bug reports because HTML without CSS doesn't look very good:
the more structural and semantic and the less presentational and
old-fashioned the HTML, the more so.
Thanks to Mark Harris <mark dot hsj at gmail dot com> for pointing out
that the permissions on this particular file were unclear.
The 1.2em was an approximate equivalent of the 2n traditionally used
for terminal display, but it is much too wide for HTML rendering.
Issue reported by mikeb@.
a uniform indentation in CSS adapted to the viewport width and
ignore the value of the argument taken from mdoc(7). While
author-specified widths somewhat work as a micro-optimization in
terminal and typeset output, they are nothing but harmful in HTML
style= attributes because they break responsive design, whereas
using a reasonable default indent almost never results in ugly
output. Admittedly, the author-specified width might occasionally
look even better, but only slightly so, and only for some viewport
sizes.
Based on guidance provided by John Gardner.
of double selectors like "element.class" is considered poor style.
When doing selection mainly by elements is not appropriate because
most elements require several different styles, exclusively selecting
by class is less cumbersome, more concise, and more flexible.
So drop the elements from the selectors, except where they are
required for disambiguation and except where they add clarity due
to the presence of child selectors.
John Gardner and others tell me it produces more predictable results
and is generally considered better style.
Also use 0em instead of 0ex, in general.
Some macros (Nd, Oo) can contain blocks but rendered as elements that
can only contain phrasing content, resulting in invalid HTML nesting.
Switch them to <div>.
Also move the related "display: inline" style from the HTML to the CSS.
Reminded during a conversation with John Gardner.
syntax element macros .Nm, .Fl, .Cm, .Ic, .In, .Fd, .Fn, and .Cd.
Adjust both the internal and external style sheets such that
rendering remains unchanged in typical browsers.
Based on feedback from John Gardner <gardnerjohng at gmail dot com>.
allowed to the right of them are dd.It-tag.
Fixes overlapping rendering after long tag lists without bodies,
for example in the Xenocara apm(4) manual. Issue reported by tj@.
attributes into .It blocks; suggested by Steffen Nurpmeso <steffen
at sdaoden dot eu> on <groff at GNU dot org> in April 2017.
Delete margin-bottom and margin-top style names and the 'v' argument
letter from print_otag() because they are no longer used.
to HTML output. For certain macros appearing at the beginning of .It
heads, write HTML id="..." attributes such that deep linking works.
Write HTML <a> attributes such that you can easily copy out link
targets with the mouse. Try: http://man.openbsd.org/vmctl.8#create
Feature suggested by <guettliml at Thomas dash Guettler dot de>,
some details of the design and implementation by me.
It is NOT used during "make build" and NOT installed, but it is
helpful for people trying to read and understand html.c and mdoc_html.c,
and maybe even for users of mandoc -Thtml.
OK deraadt@
