From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oBOEldnp021067 for ; Fri, 24 Dec 2010 09:47:40 -0500 (EST) Received: from smtp-2.sys.kth.se (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id E340014C133; Fri, 24 Dec 2010 15:47:33 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([127.0.0.1]) by smtp-2.sys.kth.se (smtp-2.sys.kth.se [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 3YBmeUSb7zTm; Fri, 24 Dec 2010 15:47:21 +0100 (CET) X-KTH-Auth: kristaps [195.13.162.34] X-KTH-mail-from: kristaps@bsd.lv Received: from macky.local (unknown [195.13.162.34]) by smtp-2.sys.kth.se (Postfix) with ESMTP id A688514C022; Fri, 24 Dec 2010 15:47:20 +0100 (CET) Message-ID: <4D14B277.6070204@bsd.lv> Date: Fri, 24 Dec 2010 16:47:19 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.12) Gecko/20101027 Thunderbird/3.1.6 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: Ingo Schwarze CC: Thordur Bjornsson , discuss@mdocml.bsd.lv Subject: Re: mandoc -Thtml cleanup References: <201012222235.oBMMZ5ZA025569@cvs.openbsd.org> <20101222225049.GE1480@hera.home> <20101223202724.GA8744@iris.usta.de> In-Reply-To: <20101223202724.GA8744@iris.usta.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit > As i'm not really working on the -Thtml part of mandoc - > that's almost purely Kristaps' domain - i'm Cc:ing Kristaps, > i hope you don't mind, your remark wasn't really of private > nature, i think... I'm also cross-posted to discuss@ in case people want to chime in with ideas and/or suggestions. > >>> CVSROOT: /cvs >>> Module name: src >>> Changes by: schwarze@cvs.openbsd.org 2010/12/22 15:35:05 >>> >>> Modified files: >>> usr.bin/mandoc : man_html.c >>> >>> Log message: >>> Use yet more standard HTML tags, >>> this time some more

and instead of
. >>> From kristaps@. > >> This is kind of funky, as the "current best practices" in >> HTML for websites is to get ride of table and such in favor >> of div's > > Hmm, i guess you are talking about web site layout here. > Indeed, it used to be common to (ab)use tables (and frames) > for layout purposes in the past. > > But in mandoc, are mostly used for columnated lists > (Bl -column). The other uses are minor ones: > - page header line > - page footer line > - man(7) IP: indented paragraph with header word > - man(7) HP: indented paragraph with hanging first line > - mdoc(7) SYNOPSIS Nm: very similar to man(7) IP > > Tables are not used for any large-scale layout. > > The point of the recent series of changes was to strengthen structural > markup, like using real

for a paragraph of text, not

, which > could be anything. Likewise, real
    for lists etc. etc. Right, as Ingo said, before I was kind of abusing DIV and CSS to get the terminal-mode output look. Consequently, it didn't work in older browsers or text-mode browsers (printing was a sonofabitch). It now works quite nicely in these with only minimal deviation from expected output (e.g., lists not showing on the same line, which apparently can be fixed by using CSS float stuff). DIVs are still used for non-structural annotation, say, for sections and subsections. SPANs are used quite heavily for semantic mark-up that don't have a default style (e.g., bold for `Nm'). >> (and CSS, which isn't viable here...) > > Kristaps _does_ maintain CSS sheets for mandoc -Thtml output. > I just don't import those into OpenBSD; i'm not interested > in layout details, only in structural markup. Oh man, does everybody think me so clueless? ;) Feast your eyes on http://mdocml.bsd.lv/style.css , generating, along with all other manuals on the mdocml site, http://mdocml.bsd.lv/mandoc.1.html . These are based on my skeleton style-sheet, http://mdocml.bsd.lv/cgi-bin/cvsweb/example.style.css?cvsroot=mdocml If you pass -Ostyle=xxxxx to mandoc, it will use any style-sheet you give to it. The mandoc.1 manual specifically mentions this: % mandoc -Owidth=68 mandoc.1 |less [snip] The example.style.css file documents style-sheet classes available for customising output. If a style-sheet is not specified with -Ostyle, -Thtml defaults to simple output readable in any graphical or text-based web browser. You'll notice that almost every macro has its own possible style. >> Well, mandoc doesn't have to be Web 2.0 I guess :-) > > I don't know about Web 2.0; but what mandoc does not need is the > kind of fine-tuned web layout making sure each pixel ends up in > exactly the right place in all kinds of broken browsers. I don't know about web-2.0, but I welcome any advice, help, or plain old patches you'd like to submit regarding the HTML and XHTML output. mandoc, as I've said, was originally designed to make navigable, cross-linked, and elegant HTML manuals. Yes, this feature is second to terminal output, but I think there's certainly something to be said to have all manuals cross-linked and locally accessible in one's browser. So there's lots of room to do neat things, in this regard (I'd like, for example, to tag function prototypes and utility syntaxes in the SYNOPSIS section with an A NAME, then link up to them from within the document itself). Other things, like having -Thtml generate a fragment and use an ad hoc CSS namespace (i.e., just a prefix), allow embedding of manuals in other content. Also cool and pretty easy to do. There's always that Table of Contents, which man.cgi generates but we don't... Thanks! Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv