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=-3.3 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 17031 invoked from network); 4 Aug 2021 06:31:08 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 4 Aug 2021 06:31:08 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1628058668; b=nsHfZXeoPJOmWDYm3BhR0hQyLMDNPg3joc4VU+bEeb8ZpQGSMWwC+N0q2YquV0vT7q+Rp5K7uf 89M/M5hZcKQTvhuvwUD1LgI1kAAvJNuweC+JHknLvN+L51zn7LTUAG/qb/d2Y4OFQr37OJzq50 S65Ezf3kGTwsyaZTCEumF8mPasnLpnLDeKZe3C7pOfPCEnqyIZwgNoqNpc+JCKfub7m0omtZfR qNvKh8pQ9YI54/mYXrRdswLAWjc7ydO1jI4YwkQ14NltCvInkdSecpIeJs9FG/niZntngqMK3D 8P1aIYKafdfUzY0pdynMUrAdDb7duRy2Aj9R8CFwB9rTWw==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (a.mx.sigpipe.cz) smtp.remote-ip=37.221.242.114; dmarc=none header.from=sigpipe.cz; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1628058668; bh=yFLHhSpuwh8hr5WnUYBSUbLucU3yM2LlQlyxp57XUAg=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:In-Reply-To:Content-Type:MIME-Version:Message-ID:Subject:To: From:Date:DKIM-Signature; b=i/xAVtO4oipXAG5FSjv3yASJWmIsNWt51Osg5zzub9/4gJtuZmQRbk0cGgaXGiVLYkKxaHkc40 TKsCTai7PYwizObclxxb8QeB/VQRSkKRNFLEu0zBXPnEJro6dEeMrRQLY8MomP8Z7Xl5PoUDBR y3wJT3X4nQbL8uS9fd0xM8NlKLdIpES9ZHe7mJL0At7SWbuuJVOHVP7B2YIt5Wo+RHB90e5tjj aV1u7u+Zolz0FnpD0mNZp28LH+XHA+vQS7adwI3aXsAmbzbZD6nSeF9GvbigCL+3UmWiRf0my/ sdO4ilMIOup/onF5bH1z2kB0X/HDPxjku9XwsNHjPq4/JQ==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20210803; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:In-Reply-To:Content-Type:MIME-Version :Message-ID:Subject:To:From:Date:Reply-To:Cc:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:References; bh=HP8TaQaJdxiVm/hoz6NiP4PFfIyfC+oOkRT/Lrd43vA=; b=Iz4qLQ77FITrFajFLZ/udd/44z DN0tZGgvCUiQxrFvoBDw0AnZvgEz1EhitMMmU8DJOS72F0z5rKhZHAi2UFnq1uhImXmRIu/F9P0+K o0CJdQTMFuOpYGh/0jSm7Jkw8ZxE4SY2CbiycTAgMq8yDoHktyKb7Mc1Nmdrbx3eDUeFcOJhCMsW9 sEBbdPc7541z5osMxQb70e5Rj1DvfSVpB+fgkDBJhm5heANaG628PwdaWRg6HL25OyltNqeenIRdt 7RmUr/epG8QEIk4qzj/9JU03VO7njGesJaHLsu7Ut6kD7KFvSbYEd6XVXkwkal8Cq/ZsZtyOw0BFA N5X0tR5Q==; Received: from authenticated user by zero.zsh.org with local id 1mBAQm-000Nyj-7N; Wed, 04 Aug 2021 06:31:08 +0000 Authentication-Results: zsh.org; iprev=pass (a.mx.sigpipe.cz) smtp.remote-ip=37.221.242.114; dmarc=none header.from=sigpipe.cz; arc=none Received: from a.mx.sigpipe.cz ([37.221.242.114]:4281) by zero.zsh.org with esmtps (TLS1.3:TLS_AES_256_GCM_SHA384:256) id 1mBAPq-000NFj-5j; Wed, 04 Aug 2021 06:30:10 +0000 Received: by a.mx.sigpipe.cz (Postfix, from userid 1001) id 807C915550340D; Wed, 4 Aug 2021 08:30:08 +0200 (CEST) Date: Wed, 4 Aug 2021 08:30:08 +0200 From: Roman Neuhauser To: Zach Riggle , Zsh Users Subject: Re: Better Help Docs Searching? Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210801163314.toawcsrtj6eqydxr@chazelas.org> X-Seq: 26849 Archived-At: X-Loop: zsh-users@zsh.org Errors-To: zsh-users-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-users-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: # zachriggle@gmail.com / 2021-08-01 05:44:52 -0500: > A good example is the builtin 'read'. Even knowing it's a builtin, > and searching the docs [1] / man pages for builtins, it's still not > very straightforward to find the docs on 'read'. (There are 91 > matches for "read" on the online docs and 82 in zshbuiltins). "/^ *read \[" (without the quotes) followed by ^J or ^M will get you there, but boy, the ergonomy of three consecutive key presses with a stretched out pinky finger... :( # zachriggle@gmail.com / 2021-08-03 00:45:22 -0500: > One thing that I really like / prefer about man pages is the $MANPAGER > variable, which I have configured to use bat(3) [1] as my pager, which > gives syntax highlighting, highlights command names, and flag names. > Is there an equivalent for "info" pages? that's an impossible task, metadata in info files only goes as far as ^L preceding menus from what i've seen... man pages can be styled by your pager because the file you're viewing in the pager includes the style info. roff is a cumbersome markup language, but it's what you make it to be. while most man pages you'll find on linux are written using the man(7) macro set, mdoc(7) provides a semantic marup language. man(7) from https://mandoc.bsd.lv/ (found in many BSDs and Linux distros): The man language was the standard formatting language for AT&T UNIX manual pages from 1979 to 1989. Do not use it to write new manual pages: it is a purely presentational language and lacks support for semantic markup. Use the mdoc(7) language, instead. just to clarify, this is not about abandoning man pages. man(7) and mdoc(7) are "just" different markups to write man pages in. btw, zsh's man pages use man(7), as is usual with generated man pages. man(7) gives you this level of info: .PD 0 \fBcd\fP [ \fB\-qsLP\fP ] [ \fIarg\fP ] .TP .PD 0 \fBcd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP .TP .PD = vertical margin \fB = bold font \fI = italic font \fP = previous font .TP = "tagged paragraph", normally term + definition in a list of definitions. not here though. they're on different levels, and i can see why someone writing manuals for linux would find man pages pointless. this could have been (in mdoc(7)): .Ic cd .Op Fl qsLP .Op Ar arg . .Ic cd .Op Fl qsLP .Ar old .Ar new .Ic = interactive command, .Op = optional, .Ar argument. the Op macro generates the brackets around its argument. totally different level of discourse. two more examples; these three are entirely different and perfectly distinguishable: .\" optional flag to the program .Op Fl n .\" optional flag to the program, requires an argument .Op Fl n Ar DIR .\" mandatory operand to the program .Ar DIR environment variables don't get mixed up with syntax non-terminals: .Ev TERM .Sy TERM and if i go looking for all parts of git which accept --origin, i won't drown in all the passing mentions of the flag elsewhere. cooking with gas! meanwhile... as long as our software vendors deliver man pages marked up in man(7) we're out of luck: their pages may be pretty (if you ever bothered to print one) but otherwise quite useless. it's different with mdoc(7), tools to mine the data don't exist yet afaik, but at they are feasible. mdoc(7) is better than man(7) but still quite unpleasant to write (better than docbook! low standard, i know), and certainly not sufficient for things like finegrained links (all you get is semantic markup for a list of references at the bottom, and intra-document links targeting other *sections*). but it's already here and people seem unwilling to give man pages up. a good way forward imo is to deprecate the current man+pager model, this coupling is too loose, man/whatis/apropos simply sucks, and the pager can't fill the shoes either. there's no reason we shouldn't be able to follow links between man pages or have ad-hoc indexes generated from our in-viewer queries. info is not magic. i believe that GNU could have spent a fraction of the effort they put into texinfo on man instead, and we'd all be much happier today. anyway, if your software vendors provide you with man(7)-based pages, demand better! (you may have to roll up your sleeves though. :) -- roman