Re: mandoc -Thtml cleanup

[Kristaps Dzonsons <kristaps@bsd.lv>]

> 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<P>  and<TABLE>  instead of<DIV>.
>>>  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,<TABLES>  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<P>  for a paragraph of text, not<DIV>, which
> could be anything.  Likewise, real<UL>  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