Re: mandoc -Thtml cleanup

Re: mandoc -Thtml cleanup

[Kristaps Dzonsons]

> 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

Re: mandoc -Thtml cleanup

[Anthony J. Bentley]

Hi Kristaps,

I'm really happy to see the improved HTML output of mandoc. It really
looks great compared to the <div> 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

Re: mandoc -Thtml cleanup

[Kristaps Dzonsons]

Anthony,

> I'm really happy to see the improved HTML output of mandoc. It really
> looks great compared to the<div>  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

Re: mandoc -Thtml cleanup

[Anthony J. Bentley]

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 <link rel="next"> 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