From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 30592 invoked from network); 20 Sep 2023 20:52:51 -0000 Received: from minnie.tuhs.org (2600:3c01:e000:146::1) by inbox.vuxu.org with ESMTPUTF8; 20 Sep 2023 20:52:51 -0000 Received: from minnie.tuhs.org (localhost [IPv6:::1]) by minnie.tuhs.org (Postfix) with ESMTP id DE21A4158A; Thu, 21 Sep 2023 06:52:44 +1000 (AEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tuhs.org; s=dkim; t=1695243165; h=from:from:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-owner:list-unsubscribe:list-subscribe:list-post; bh=vXpVNT8HYDUYp6jTcgJRL/TtAggkKlADwwaMSyDcIIs=; b=qPkbsziUnTVRsmQ2S5px9fM4qXpV/R1LfC+dHOR5TK4XoaeLFAS1Uyc2tt7NOAHUPzTdFq BQqAs3P0VxSUOyMu9DMPiUoZKVtiHY02i+MxkBdTFnIZb5e1OHSpwM6a7ACwC98DCdE2LC DVY+n/1Ekb+IrQ95bJ6IEn4RuvN7TOw= Received: from mail-4319.protonmail.ch (mail-4319.protonmail.ch [185.70.43.19]) by minnie.tuhs.org (Postfix) with ESMTPS id A6A1D4157A for ; Thu, 21 Sep 2023 06:52:38 +1000 (AEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1695243154; x=1695502354; bh=vXpVNT8HYDUYp6jTcgJRL/TtAggkKlADwwaMSyDcIIs=; h=Date:To:From:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=h/8LNw3BzYOThmeEEuGB2tM3btIkTBA0DVP9lADPm++E6s1fgOvnsvHZ2WcfoJStw 8TzTagrivQi69j6X4g3X7KY0RmR51M6HRRqjQ/FqMGM2woaP0CYzRYnOThYnWisvjc J/0sLlk8GrLRsueeAqh40bshaKq9xzSv2xSMzYsubi9NQVdaXSdkxRwP6Wq9rVfwMi NtHZFXGbyyHFEPgyCS6OmjO8KDno0TCg6HMkx+Rk0Eo6SAYPhwS+hvJ6rs9UXUV44N TOHntqlD8BNAg1mT6qZO9knGmCiT5VPRznTdrc0Hdcy4QTSAorD3rfYQ1f0ZBsKuXd f/FdqwWoMrK5A== Date: Wed, 20 Sep 2023 20:52:23 +0000 To: The Eunuchs Hysterical Society Message-ID: In-Reply-To: <20230920195635.GG28844@mcvoy.com> References: <4CmySC-mFud1dlrqfAq1itmNKoTWVi8cTuAqCvtUengKvv5CWEoYCFf6-I18dwf5BVSZWAxC-B6BP6Y1e0Gi_mlga344b5cxu5TlUCLXHeg=@protonmail.com> <20230919233925.GB28844@mcvoy.com> <20230920195635.GG28844@mcvoy.com> Feedback-ID: 35591162:user:proton MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: CCINRVOMESO7BEUXZUOZEB3TZGQU5L37 X-Message-ID-Hash: CCINRVOMESO7BEUXZUOZEB3TZGQU5L37 X-MailFrom: segaloco@protonmail.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.6b1 Precedence: list Subject: [TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition List-Id: The Unix Heritage Society mailing list Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: segaloco via TUHS Reply-To: segaloco > > Yeah, I'm less angry at GNU now--I didn't search as hard, but when I fo= und > > out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is stil= l > > actively-ish maintained) then I figured it wasn't something classical t= hat > > GNU dropped, just never imported. I feel like it existed on SunOS and > > Solaris but I might be wrong about that? Was it really FreeBSD that > > introduced it? >=20 >=20 > I don't think SunOS had it. The SunOS man pages were pretty terse, the > powers that be wanted just the facts. I remember get beat up for putting > examples in some of the man pages I wrote, they got taken out "because > examples are for user guides, man pages are not user guides, they are a > reference guide" or something like that. >=20 > I like examples in man pages, I think it jump starts you into using the > program more easily but maybe that's just me. > -- > --- > Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat I'm glad I'm not the only one, do I find the dearth of examples on many ref= erence manuals to be quite annoying. The only compelling (to me) reason I'= ve ever heard for flat out avoiding examples is to not imply best practices= . For instance, in my own work, there are times I purposefully have to not= provide use-case examples of some generic bit I put together because then = I find it gets used very narrowly, as if the example given is "how it shoul= d be used" rather than "a way it can be used". Granted, that is a product = of perception, not intention, so outright avoiding guidance altogether or n= ot, you're always going to have people who read something and accept that a= s lore rather than just a helpful suggestion or narrow demonstration. It's= kinda like providing a reference implementation of some general interface = or service. If it works well and is general, folks are just going to use t= hat reference implementation rather than customizing their own logic to dri= ve the interface, defeating the purpose of trying to standardize an interfa= ce instead of just providing a distinct product. Kinda like X these days, = how many *new* X servers or clients have popped up lately? Is everything X= .org now? I don't know enough to speculate on that but might serve as a go= od example. Another way I think about that caveat is, say one is providing an example o= f fseek. A narrow example of seeking to the end of a file would be an effe= ctive example, a perfect use-case for fseek. However, presenting instead a= bulkier example that demonstrates determining filesize *using* the fact yo= u can fseek to the end and then ftell the position, while also demonstratin= g use of fseek perfectly well, might embed itself in someone's mind as sugg= esting *the* way to do this sort of thing in C. Granted, again, that's up = to user perception, but those are the kinds of scenarios that do give me pa= use when drafting examples for documentation: The concern that someone will= take an example as an absolute in every angle that it touches. I think in a full UNIX manual, constituting both volumes (or whatever other= permutations of manpages and doc papers), it does make a bit more sense to= keep examples terse because for many materials needing detail, one could s= imply cite the paper that is also considered a part of that standard docume= ntation package. Sadly with the fragmentary nature of documentation these = days, that sort of packaged manual doesn't really exist anymore, and all of= what would have gone into that arrangement of documents is out leading mul= tiple lives as info, HTML pages, PDFs, etc probably from TeX sources. /usr= (/share)/doc is a thing of the past in its old way of being. I guess these= days what with the internet and all, it's less important for each and ever= y scrap of information being succinctly accessible by a common mechanism on= the system itself...but hoo boy would it be nice...I guess that's what the= y wanted info to be but...yeah that needs no further comment from me. - Matt G.