Hi Ted, Ted Unangst wrote on Fri, Dec 21, 2018 at 02:53:19PM -0500: > Ingo Schwarze wrote:
>> 2. When calling "mandoc -T html" without specifying "-O style=", >> fall back to "-O style=/var/www/htdocs/mandoc.css" by default. >> That might be sensible because it is adequate for local >> viewing of the file, which is likely intended with files >> generated in such a manual way. > I think this is probably not true. I would guess people are running > mandoc -T html to generate static files for a web server. Maybe. But if that is true, then inlining the full set of CSS rules is not a sensible default at all. If you install mandoc HTML files on a web server, you almost always want to use an external style sheet. I'm not saying that an inline style sheet is a poor choice in each and every case, but the cases where that might make sense are very rare and unusual. And something that is very rarely useful certainly must not be the default. Actually, if your guess what people are doing with files manually generated with mandoc -T html is true, then inlining the full set of CSS rules by default clearly makes matters worse than they are now. For that purpose, you really *have* to specify -O style=. If you do that, then the proposal to inline the full set of CSS rules by default provides no benefit. If you forget it, then with the status quo, it is obvious for you that you did something wrong because the pages look bad. It is even obvious what the problem is, simply by a casual look at the pages: lack of a style sheet. So it's easy for the user to notice, diagnose, and fix their error. If we inline the full set of CSS rules by default, we merely hide that typical user error. People may never even notice they did something stupid. If we think people predominantly use mandoc -T html to generate files to serve from static webservers, then i think we could make -O style=/mandoc.css the default, but *without* installing the file /var/www/htdocs/mandoc.css file by default. On a webserver serving static manual pages, having the style sheet in the document root is a sensible default (certainly not the only possibility, but one simple option that makes sense). So it will work out of the box for some, including man.openbsd.org, and those who want to put the stylesheet elsewhere can easily give a different -O style=. > I would suggest using a relative URL here, just "mandoc.css", I don't consider a relative URI a sensible default at all, assuming that people want to copy the files to a web server. Copying the style sheet to each and every directory containing manual pages doesn't seem sane at all, and besides, i would rarely want to mix HTML and CSS files in the same directory on a web server. > so the files can be copied around and viewed by people not > running OpenBSD. For offline viewing, a relative URI makes even less sense. The style sheet will almost never be in the same directory as your HTML files, unless you constantly copy it around. > But see below. > > Local OpenBSD users are probably just using the text tty output of man. > >> 1. Install /var/www/htdocs/mandoc.css by default. > I think this is a bad idea. Right, that idea was unanimously shot down. >> 2. Make "-O style=/var/www/htdocs/mandoc.css" the default in mandoc(1). > Maybe, maybe not, but as above, I'd argue for simply "mandoc.css". > However, I don't think we really need to make changes here. >> 3. Inline your version if the user says "-O style=''". > I would say just inline this by default. Leave the behavior of -O alone. I dislike that direction. It makes a fringe case the default and hides typical user errors. Here is another, hopefully better proposal. What about making -O style= *compulsory* unless "option style" is defined in man.conf(5)? Just error out when no style sheet is configured? That can be combined with inlining the full set of rules when -O style=inline is explicitly specified. Yours, Ingo
