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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-yi0-f49.google.com (mail-yi0-f49.google.com [209.85.218.49]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oBOIg5it017929 for ; Fri, 24 Dec 2010 13:42:06 -0500 (EST) Received: by yib2 with SMTP id 2so1208238yib.36 for ; Fri, 24 Dec 2010 10:41:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:received:to :subject:in-reply-to:references:comments:date:from; bh=ohs3SUooOOECy9NqzUXqeKXSLtgV6/R8UEYngeYpjwQ=; b=dAlAF/dH+DGMCOhTFyuTWgGFJu5zgf5yaUHEi5Wj94dZDBu5VCgAvJvc2hCmjh7wJT M3vd2FY9aZTVCXwdqxAH5ZNofRWOKbR7AkraNJme5U/BrWNCPpbJqB4GjO8FEL2f4aSU aYe/1RWd1XQE7SXfmTbQ07KCb1p+U3uPWmjI4= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:to:subject:in-reply-to:references:comments:date:from; b=JeYaaYJrymGsmZlD41xA7clNzVSQ1W9RTRC/8zerhp5acNgOHIpIxhXNFNHjZZUKsK A16O4WMgPBqA8B7SPiw/1D43ly4+8mGbJ+5XbXyu0JhWcuyzdLeNznB0uW2Lix4DDU79 5hKfX8q1II91NNh1oNe+XkNLAVNGdtKn4S2nQ= Received: by 10.100.46.7 with SMTP id t7mr5837795ant.174.1293216119510; Fri, 24 Dec 2010 10:41:59 -0800 (PST) Received: from pinetree.gateway.2wire.net (97-119-170-153.albq.qwest.net [97.119.170.153]) by mx.google.com with ESMTPS id i10sm14100572anh.12.2010.12.24.10.41.57 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 24 Dec 2010 10:41:58 -0800 (PST) Message-ID: <4d14e976.0aeb640a.6fa9.ffffb4b9@mx.google.com> Received: from pinetree.gateway.2wire.net (localhost [127.0.0.1]) by pinetree.gateway.2wire.net (OpenSMTPD) with ESMTP id 1293216114.exgjADYdiUkXGjYI for ; Fri, 24 Dec 2010 11:41:54 -0700 (MST) To: discuss@mdocml.bsd.lv Subject: Re: mandoc -Thtml cleanup In-reply-to: <4D14B277.6070204@bsd.lv> References: <201012222235.oBMMZ5ZA025569@cvs.openbsd.org> <20101222225049.GE1480@hera.home> <20101223202724.GA8744@iris.usta.de> <4D14B277.6070204@bsd.lv> Comments: In-reply-to Kristaps Dzonsons message dated "Fri, 24 Dec 2010 16:47:19 +0200." Date: Fri, 24 Dec 2010 11:41:54 -0700 From: "Anthony J. Bentley" X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Hi Kristaps, I'm really happy to see the improved HTML output of mandoc. It really looks great compared to the
    output from before. I notice there's a redundant 'font-family: monospace;' declaration in style.css that is immediately overwritten with 'font-family: Times, serif;': http://mdocml.bsd.lv/cgi-bin/cvsweb/style.css?rev=1.19&content-type=text/x-cvsweb-markup&cvsroot=mdocml > 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 FYI, A NAME and A ID are more-or-less interchangeable, and you might want to use ID for consistency since mandoc uses IDs elsewhere. Or not, since there's almost no difference between the two. http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 > There's > always that Table of Contents, which man.cgi generates but we don't... There are some link types that may be useful semantically for this kind of thing: http://www.w3.org/TR/html401/types.html#type-links http://www.w3.org/TR/html401/struct/links.html#h-12.3 I do think it would be funny to see mdoc beat texinfo at its own game (namely, hyperlinking)! ;) -- Thanks, Anthony J. Bentley -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv 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 oBONLFCw001556 for ; Fri, 24 Dec 2010 18:21:16 -0500 (EST) Received: from smtp-2.sys.kth.se (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id D13E114C223 for ; Sat, 25 Dec 2010 00:21:09 +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 JCtx9gpdOl2E for ; Sat, 25 Dec 2010 00:20:58 +0100 (CET) X-KTH-Auth: kristaps [46.109.54.191] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.bsd.lv Received: from macky.local (unknown [46.109.54.191]) by smtp-2.sys.kth.se (Postfix) with ESMTP id C732C14C133 for ; Sat, 25 Dec 2010 00:20:56 +0100 (CET) Message-ID: <4D152AD8.9040300@bsd.lv> Date: Sat, 25 Dec 2010 01:20:56 +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: discuss@mdocml.bsd.lv Subject: Re: mandoc -Thtml cleanup References: <201012222235.oBMMZ5ZA025569@cvs.openbsd.org> <20101222225049.GE1480@hera.home> <20101223202724.GA8744@iris.usta.de> <4D14B277.6070204@bsd.lv> <4d14e976.0aeb640a.6fa9.ffffb4b9@mx.google.com> In-Reply-To: <4d14e976.0aeb640a.6fa9.ffffb4b9@mx.google.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Anthony, > I'm really happy to see the improved HTML output of mandoc. It really > looks great compared to the
    output from before. > > I notice there's a redundant 'font-family: monospace;' declaration in > style.css that is immediately overwritten with 'font-family: Times, serif;': > http://mdocml.bsd.lv/cgi-bin/cvsweb/style.css?rev=1.19&content-type=text/x-cvsweb-markup&cvsroot=mdocml Fixed, thanks! >> 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 > > FYI, A NAME and A ID are more-or-less interchangeable, and you might want > to use ID for consistency since mandoc uses IDs elsewhere. Or not, since > there's almost no difference between the two. > > http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 This page is quite useful. I'll get some of this integrated to avoid superfluous tags (using IDs instead of NAMEs). >> There's >> always that Table of Contents, which man.cgi generates but we don't... > > There are some link types that may be useful semantically for this kind > of thing: > > http://www.w3.org/TR/html401/types.html#type-links > http://www.w3.org/TR/html401/struct/links.html#h-12.3 Those look really cool! Unfortunately, I don't see Firefox (for one) actually using this data in any way---I could easily supply SECTION and SUBSECTION fragment href's instead of having some clunky TOC, but that doesn't get me anywhere if the links aren't listed. > I do think it would be funny to see mdoc beat texinfo at its own game > (namely, hyperlinking)! ;) I don't know much about texinfo's "hyperlinking", but mdoc's semantic annotation makes a great deal possible (e.g., function names linking to the SYNOPSIS prototype, etc.). Thanks again, Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-yx0-f177.google.com (mail-yx0-f177.google.com [209.85.213.177]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oBP08YGU012372 for ; Fri, 24 Dec 2010 19:08:34 -0500 (EST) Received: by yxm34 with SMTP id 34so3530241yxm.36 for ; Fri, 24 Dec 2010 16:08:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:received:to :subject:in-reply-to:references:comments:date:from; bh=4alb+NQQ02uOLHNZ+bw1d/mGNNpGN8d+7cT9e6Z7zsY=; b=mGsfSmK+9IdLvQyqsiVi3nxaqKPYs/g8Tsn3cPZR/dDFGq63cA8Y6gEYw/4AJSz/pe jUqk44C6rlcYkgguVtamLbJCArrgvHIZ2eYVCTREG4RLGppd0+iHxdIrjngC+eBpKsFV 4xYI/8+6McT1KjsXQL76AeUiXpKCHFUEhLYl4= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:to:subject:in-reply-to:references:comments:date:from; b=pwbzyIFkkXAo3Nzyrj2xyYBdc13p3BqmgtWFyV62wkmMx8BAxqkkphw0FjirLfqkzX cvCRdNFU1O58FVXGW27Vb2nYxoc6bNOaERMOeDEjpgJV2Bwu1JJM0CDrDNh6Mx5FGQLa CbW8fy7EmJjHRjVaTygNXVIBmj03UP9FGbU/s= Received: by 10.101.165.31 with SMTP id s31mr6066908ano.216.1293235707724; Fri, 24 Dec 2010 16:08:27 -0800 (PST) Received: from pinetree.gateway.2wire.net (97-119-160-231.albq.qwest.net [97.119.160.231]) by mx.google.com with ESMTPS id b27sm14394273ana.28.2010.12.24.16.08.25 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 24 Dec 2010 16:08:26 -0800 (PST) Message-ID: <4d1535fa.1b35640a.6a0c.ffffb6e2@mx.google.com> Received: from pinetree.gateway.2wire.net (localhost [127.0.0.1]) by pinetree.gateway.2wire.net (OpenSMTPD) with ESMTP id 1293235703.H18phDxA6V8zwOsd for ; Fri, 24 Dec 2010 17:08:23 -0700 (MST) To: discuss@mdocml.bsd.lv Subject: Re: mandoc -Thtml cleanup In-reply-to: <4D152AD8.9040300@bsd.lv> References: <201012222235.oBMMZ5ZA025569@cvs.openbsd.org> <20101222225049.GE1480@hera.home> <20101223202724.GA8744@iris.usta.de> <4D14B277.6070204@bsd.lv> <4d14e976.0aeb640a.6fa9.ffffb4b9@mx.google.com> <4D152AD8.9040300@bsd.lv> Comments: In-reply-to Kristaps Dzonsons message dated "Sat, 25 Dec 2010 01:20:56 +0200." Date: Fri, 24 Dec 2010 17:08:23 -0700 From: "Anthony J. Bentley" X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Hi Kristaps, > >> There's > >> always that Table of Contents, which man.cgi generates but we don't... > > > > There are some link types that may be useful semantically for this kind > > of thing: > > > > http://www.w3.org/TR/html401/types.html#type-links > > http://www.w3.org/TR/html401/struct/links.html#h-12.3 > > Those look really cool! Unfortunately, I don't see Firefox (for one) > actually using this data in any way---I could easily supply SECTION and > SUBSECTION fragment href's instead of having some clunky TOC, but that > doesn't get me anywhere if the links aren't listed. There's an extension for that: https://addons.mozilla.org/en-US/firefox/addon/2933/ Opera does have the buttons available. Also I believe that Opera will, e.g., follow a if you hit space at the end of a page. But yes, it's a real shame that most browsers don't have these easily accessible to the user. They're neat features. Search engines might use them as well but I don't know any details. -- Hope this helps, Anthony J. Bentley -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv