From owner-freebsd-doc@FreeBSD.ORG Tue Jul 23 23:08:04 2013 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id B36D3C7D for ; Tue, 23 Jul 2013 23:08:04 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 5E67E2BAB for ; Tue, 23 Jul 2013 23:08:04 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r6NN83YI061501 for ; Tue, 23 Jul 2013 17:08:03 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r6NN83ol061498 for ; Tue, 23 Jul 2013 17:08:03 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Tue, 23 Jul 2013 17:08:03 -0600 (MDT) From: Warren Block To: doc@FreeBSD.org Subject: screen elements and userinput in XHTML Message-ID: User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; BOUNDARY="3512871622-805574574-1374620883=:61273" X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Tue, 23 Jul 2013 17:08:03 -0600 (MDT) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 23 Jul 2013 23:08:04 -0000 This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --3512871622-805574574-1374620883=:61273 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII In XHTML documents, our current CSS stylesheet does not distinguish between user-typed input and system output. That's my fault, Gabor had user input in bold but I felt it had so much contrast that it distracted rather than clarified. Our screen elements are not separated from other text, either. The current programlisting elements are better, in a box with a gray background. We could make screen elements identical, but there is some value to the reader in making them look different. I checked various web documentation pages for other projects, and most did not distinguish between system output and user input. In some cases, that is likely to prompt a user to type a prompt. The best-looking example I found was some Slackware documentation, which uses plain text for system output and bold for user input, but put it on a gray background which helped tone down the contrast. Putting this all together, I've been trying this experimental addition to doc/share/misc/docbook.css. It makes the userinput bold, draws a box around screen elements, but uses a sort of medium tan background so it does not look like a programlisting. The color is questionable, and there may be a better choice. Lighter colors seemed too bright. But I do find this easier to read. Comments welcome. Index: docbook.css =================================================================== --- docbook.css (revision 42404) +++ docbook.css (working copy) @@ -240,6 +240,10 @@ white-space: pre; font-family: monospace; padding: 1ex; + background-color: #ec8; + border: 1px solid #ccc; + border-radius: 6px; + line-height: 1.1; } div.programlisting { @@ -340,7 +344,7 @@ } .userinput { - font-weight: normal; + font-weight: bold; } pre.screen strong { --3512871622-805574574-1374620883=:61273 Content-Type: TEXT/PLAIN; charset=US-ASCII; name=docbook.css-screen.diff Content-Transfer-Encoding: BASE64 Content-ID: Content-Description: Content-Disposition: attachment; filename=docbook.css-screen.diff SW5kZXg6IGRvY2Jvb2suY3NzDQo9PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09DQot LS0gZG9jYm9vay5jc3MJKHJldmlzaW9uIDQyNDA0KQ0KKysrIGRvY2Jvb2su Y3NzCSh3b3JraW5nIGNvcHkpDQpAQCAtMjQwLDYgKzI0MCwxMCBAQA0KIAl3 aGl0ZS1zcGFjZTogcHJlOw0KIAlmb250LWZhbWlseTogbW9ub3NwYWNlOw0K IAlwYWRkaW5nOiAxZXg7DQorCWJhY2tncm91bmQtY29sb3I6ICNlYzg7DQor CWJvcmRlcjogMXB4IHNvbGlkICNjY2M7DQorCWJvcmRlci1yYWRpdXM6IDZw eDsNCisJbGluZS1oZWlnaHQ6IDEuMTsNCiB9DQogDQogZGl2LnByb2dyYW1s aXN0aW5nIHsNCkBAIC0zNDAsNyArMzQ0LDcgQEANCiB9DQogDQogLnVzZXJp bnB1dCB7DQotCWZvbnQtd2VpZ2h0OiBub3JtYWw7DQorCWZvbnQtd2VpZ2h0 OiBib2xkOw0KIH0NCiANCiBwcmUuc2NyZWVuIHN0cm9uZyB7DQo= --3512871622-805574574-1374620883=:61273--