From owner-freebsd-doc@FreeBSD.ORG Thu Aug 14 07:03:40 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 F012D11A for ; Thu, 14 Aug 2014 07:03:40 +0000 (UTC) Received: from spindle.one-eyed-alien.net (spindle.one-eyed-alien.net [199.48.129.229]) by mx1.freebsd.org (Postfix) with ESMTP id C7F672B66 for ; Thu, 14 Aug 2014 07:03:40 +0000 (UTC) Received: by spindle.one-eyed-alien.net (Postfix, from userid 3001) id 6C6235A9F24; Thu, 14 Aug 2014 07:03:39 +0000 (UTC) Date: Thu, 14 Aug 2014 07:03:39 +0000 From: Brooks Davis To: Warren Block Subject: Re: /etc/motd update Message-ID: <20140814070339.GE85079@spindle.one-eyed-alien.net> References: <20140813230750.GD85079@spindle.one-eyed-alien.net> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="vOmOzSkFvhd7u8Ms" Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.23 (2014-03-12) 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: Thu, 14 Aug 2014 07:03:41 -0000 --vOmOzSkFvhd7u8Ms Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Aug 13, 2014 at 05:51:57PM -0600, Warren Block wrote: > On Wed, 13 Aug 2014, Brooks Davis wrote: >=20 > > 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=3Dco > >> > >> 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 litt= le > >> 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. >=20 > That would allow much more vertical space in the actual "intro" file,=20 > and clearer explanations: >=20 > Type > man man > for an introduction to manual pages. >=20 > Where should the intro file be stored? /usr/doc is not always present. I'd probably use /usr/share/doc/getting-started.txt or something like that though part of me thinks /GETTING-STARTED would be better if an annoying heir violation. -- Brooks --vOmOzSkFvhd7u8Ms Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAlPsX0oACgkQXY6L6fI4GtQcnwCfZdQzeEBRguQYaSH9kSLo2qb9 kMEAoL6AXThcMsP83aHeYz4Unk87LcO3 =6CBX -----END PGP SIGNATURE----- --vOmOzSkFvhd7u8Ms--