Date: Thu, 14 Aug 2014 07:03:39 +0000 From: Brooks Davis <brooks@freebsd.org> To: Warren Block <wblock@wonkity.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: /etc/motd update Message-ID: <20140814070339.GE85079@spindle.one-eyed-alien.net> In-Reply-To: <alpine.BSF.2.11.1408131744140.86015@wonkity.com> References: <alpine.BSF.2.11.1408131411390.3442@wonkity.com> <20140813230750.GD85079@spindle.one-eyed-alien.net> <alpine.BSF.2.11.1408131744140.86015@wonkity.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20140814070339.GE85079>