From owner-freebsd-doc@FreeBSD.ORG Wed Aug 13 23:52:00 2014 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id F323AE6D; Wed, 13 Aug 2014 23:51:59 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "wonkity.com", Issuer "wonkity.com" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 8B25021CA; Wed, 13 Aug 2014 23:51:59 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.9/8.14.9) with ESMTP id s7DNpvgh089577 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Wed, 13 Aug 2014 17:51:57 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id s7DNpvQT089574; Wed, 13 Aug 2014 17:51:57 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Wed, 13 Aug 2014 17:51:57 -0600 (MDT) From: Warren Block To: Brooks Davis Subject: Re: /etc/motd update In-Reply-To: <20140813230750.GD85079@spindle.one-eyed-alien.net> Message-ID: References: <20140813230750.GD85079@spindle.one-eyed-alien.net> User-Agent: Alpine 2.11 (BSF 23 2013-08-11) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Wed, 13 Aug 2014 17:51:57 -0600 (MDT) Cc: freebsd-doc@FreeBSD.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 13 Aug 2014 23:52:00 -0000 On Wed, 13 Aug 2014, Brooks Davis wrote: > On Wed, Aug 13, 2014 at 02:23:00PM -0600, Warren Block wrote: >> The existing /etc/motd breaks many of our document rules and has some >> weird language constructs. The current version in HEAD: >> http://svnweb.freebsd.org/base/head/etc/motd?view=co >> >> Here is a rewrite. URLs are now the only thing on a line, instead of >> inline and hard to locate. No contractions are used. Odd phrases are >> rephrased: >> >> Here is the proposed new version and a diff: >> http://www.wonkity.com/~wblock/motd/motd >> http://www.wonkity.com/~wblock/motd/motd.diff > >> Making it clear that commands are to be typed without quotes is a little >> difficult. This file is plain text, so no out-of-band highlighting is >> available. ANSI colors or bold could be used, but the terminal is not >> guaranteed to be able to display them. The only really clear way would >> be to put commands on a separate line, indented. That takes up more >> space, maybe not a big deal. >> >> The other issue is whether we should mention the search box on the web >> page, which is not very effective at finding things. >> >> Comments and suggestions welcome. > > My first thought was that it's definitely better, but too long since 25 > rows of text won't fit on the default console. > > My second thought was that a better approach might be to replace most of > the contents with a URL like: > > http://freebsd.org/getting-started-with-freebsd-11 > > and a reference to a local copy of the content a release time. That > would allow unlimited formatting, let us target different user > audiences, and let us improve the online version over time. That would allow much more vertical space in the actual "intro" file, and clearer explanations: Type man man for an introduction to manual pages. Where should the intro file be stored? /usr/doc is not always present.