Hi Ted, hi Raphael, Ted Unangst wrote on Thu, Dec 20, 2018 at 11:36:06AM -0500: > Raphael Graf wrote:
>> The diff inserts some space above the footer. >> This improves readability and makes it similar to the other output formats. >> >> Here is an example found in the wild, demonstrating the problem: >> https://webassembly.github.io/wabt/doc/wasm-objdump.1.html How did that page get generated? By some Github automatic or half-automatic infrastructure, and if so, how exactly? Or did the maintainers of "webassembly" simply generate that file by hand? Also, is that URI linked to from anywhere? It tried clicking around the "webassembly" website, but failed to find any link to the URI you cite. > So I think one answer to this problem is "use the provided mandoc.css". Absolutely. Or if it doesn't meet your needs exactly, edit it, then use your edited version. Or if it doesn't meet your needs at all, write your own, using mandoc.css as documenation of the available classes. > However, that's not the default. > But perhaps it, or a variant of it, should be. I certainly love sensible defaults and hate the lack of them, but in the past, i considered sensible defaults impossible for "-O style=" because it is kind of hard to guess the file system layout on the user's system, so we don't know which absolute path to use in the line <link rel="stylesheet" href="..." type="text/css" media="all">. Let's try again. What do you think about the following plan: 1. Let's install /var/www/htdocs/mandoc.css by default. 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. If the user then goes ahead and copies these files onto a webserver, they of course cannot work because the document root must be stripped from the "-O style=" argument in that case. Also, if the user copies these files onto a non-OpenBSD system, they stop working there, too. 3. To build HTML without any <link rel="stylesheet"> whatsoever, require "-O style=" to be explicitly specified with an empty path. 4. Document all that in the mandoc(1) manual page below "HTML Output". 5. In man.cgi(8), we already use the equivalent of "-O style=/mandoc.css" by default, unless CSS_DIR is configured in cgi.h. That won't change. > I guess one objection to always using mandoc.css is that it's > another file that may get lost. That's not really a counter-argument because nothing becomes worse. Currently, by default, you never have a good stylesheet, and if you configure one, it can already get lost, maybe even more easily because it is not installed by default. With the above plan, you get a working stylesheet by default for some simple cases, and you can still build HTML files with a different one or even without any if you want to. By the way, not that man.conf(5) already supports the output style /path/to/my.css directive. > And perhaps it's a touch too large to inline? Not a very convincing counter-argument either. If you use an external stylesheet, which is almost always by far the most sensible thing to do, nothing gets inlined in the first place. With the above plan, in the unusual case that the user explicitly request that no external stylesheet be used, inlining the whole thing is still better than inlining something stunted, like we do now, i think. Look at arbitrary websites nowdays: almost all serve ridiculous amounts of boilerplate styling stuff. The size of mandoc.css is really not a problem by comparision, and much less for a corner case that isn't recommended anyway. > But we can trim it down some to where I think it can be reasonably inlined in > every html and I don't think there will be many complaints about bloat. > > This is only a start. I noticed there's a lot of redundant definitions, and by > inverting the selector property grouping we can trim many lines off the file. > I don't think this impedes readability of maintenance. On the contrary, > (personally) I find it easier to see all the italic tags in one place versus > scanning a list of mostly identical looking elements. But that may just be the > way I look at it. > > A few more operations like this, and elimination of the emtpy { } sets and I > think we can consider inlining this as a default style instead of the current > minimal one. Maybe we embed this minimized version but provide the full file > complete with empty blocks for local customization? Right, the full version has the dupes and empties to help customization, so i do not want to delete those from the full version. I'm not opposed to inlining the version you suggest instead of the current minimal stylesheet, and the additional maintenance effort seems tolerable. It isn't zero though, there is a risk of both versions getting out of sync. So should i go ahead and do the following? 1. Install /var/www/htdocs/mandoc.css by default. 2. Make "-O style=/var/www/htdocs/mandoc.css" the default in mandoc(1). 3. Inline your version if the user says "-O style=''". Yours, Ingo
