From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,T_TVD_MIME_EPI autolearn=no autolearn_force=no version=3.4.4 Received: from mandoc.bsd.lv (bsd.lv [66.111.2.12]) by inbox.vuxu.org (Postfix) with ESMTP id 3C5BD21719 for ; Fri, 13 Sep 2024 20:48:06 +0200 (CEST) Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 69aa59b3 for ; Fri, 13 Sep 2024 18:48:05 +0000 (UTC) Received: from nyc.source.kernel.org (nyc.source.kernel.org [147.75.193.91]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id fa153631 for ; Fri, 13 Sep 2024 18:48:05 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by nyc.source.kernel.org (Postfix) with ESMTP id 6D181A45712 for ; Fri, 13 Sep 2024 18:47:57 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5A2F3C4CEC0 for ; Fri, 13 Sep 2024 18:48:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1726253284; bh=t8zeh9BGPHFYmEz80NvlvpNiLW8qKZV7UgrSHKO/i3k=; h=Date:From:To:Subject:References:In-Reply-To:From; b=KrM6agtt9aKbRWyfMo9+X0vAArip+KxQowt4LzWr0chtQfOb4EuzqETx9T6dzVnOY tlYmHQoQbYkAES3Ru67Y0uqJ4YkFEvlZdc90wbx63EBg3Bmh/N5Jf4+HNWnqynCfSw RkftGYtRBw2Ig6umfDpe2VVo7Evwrbu5PhgpOQv/wTdAkQTwiuC3xLNhsPQCfPK2Zx MNURRLvT+AkTrpGIGbdjIMziiwVcSHbphWjJUIuFrxFeuBgDRq1/mxNtnEC+/H07sX yHk1anuVPJR2iDaeN2VFEI3Utm08oMc/gfVjxf4sUTjAeGU1I9VdxKrq6OpCtF+kI8 qOFc6DmFM2jAA== Date: Fri, 13 Sep 2024 20:48:02 +0200 From: Alejandro Colomar To: tech@mandoc.bsd.lv Subject: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering) Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="d2rex2qevvhkngd2" Content-Disposition: inline In-Reply-To: --d2rex2qevvhkngd2 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: tech@mandoc.bsd.lv Subject: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering) References: MIME-Version: 1.0 In-Reply-To: Hi Ingo, On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote: > MANUAL STRUCTURE > [...] > NAME > The name(s) and a one line description of the documented mater= ial. > The syntax for this as follows: >=20 > .Nm name0 , > .Nm name1 , > .Nm name2 > .Nd a one line description > [...] > MACRO REFERENCE > [...] > Nd line > A one line description of the manual's content. This is the > mandatory last macro of the NAME section and not appropriate > for other sections. >=20 > Examples: > .Nd mdoc language reference > .Nd format and display UNIX manuals >=20 > The Nd macro technically accepts child macros and terminates wi= th > a subsequent Sh invocation. Do not assume this behaviour: some > whatis(1) database generators are not smart enough to parse more > than the line arguments and will display macros verbatim. >=20 > So the behaviour is more or less documented to be undefined for your > input. Maybe the manual should discourage child macros below .Nd in > even stronger terms. >=20 > The decision to not attempt formatting in the apropos(1) output module > but simply print the one-line strings verbatim is deliberate. There are > two reasons for this decision. >=20 > First, simplicity and maintainability. The database lookup code in > apropos(1) is already quite complex. Hooking into the full mdoc(7) > and man(7) formatting modules, which are even more complex, would > send complexity through the roof. In general, for a small UNIX-style > program, its a good idea to have no more than one source of complexity > to not risk losing track of what is going on. Besides, fancy > formatting is really beside the point of the apropos(1) program, > it's all about providing a simple, straighforward index. >=20 > Second point, robustness. A small number of crazy piople do all > kinds of crazy stuff below the .Nd macro. In extreme cases, i > have even seen paragraph breaks and the like in there. If apropos(1) > would try to honour such madness in formatting, that might utterly > mess up the formatting of the apropos(1) output, which is supposed > to be a simple list of one-line entries. Where to draw the line? > Which macros should be honoured here, which shouldn't? Even if you > make such set of a decisions, it is very hard to implement because > the renderes are recursive and you will have a hard time passing in > information from the outside where to stop processing at which lower > level. Do you have similar limitations for the NAME section in man(7)? I'm wondering if some of the pages in the Linux man-pages would cause problems. (I'm not maintaining them at the moment[1], but I should have a look at this in case I come back to the project.) [1] Have a lovely night! Alex --=20 --d2rex2qevvhkngd2 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmbkiNsACgkQnowa+77/ 2zLJ5A/8CEXDprxwYfLV4yXASOpbIC1I9ZZLznnBA2mtDi1ez/ZVD440SU8lZkP6 bS6M8F6fZxEETd3lam201q9ClB5uCq//30excV76hm09VPayjFLdcPcMFw30tRQj 8bqa0qkufauIEwywaol2f4C7rn3bnO/vdzNIKXP74z0pPXv3PLiN7KzdAXffLGih ckxJ13G1BuwdfUO/6hxiCFuV8ivlOP9kz3f4RLzV8H6TXEarBNzgduTAI7fLByiz dDTnqdwa53f048sAERCXsaZ81uiwHktkD4ocBHr2UqhLI2/1U1yP3mFwwNGd59YC lPNX7UNncs49sSnksxJhlvBxcVBsmrN/WBWgYbPIlxdFDfUjyZsz1xF0YHLhTOId 1pi8Q1uW3yY4GoCXLfckaEv5RFl+L8J2LqOlgXNIOEYlZr+QmQVZGgBSSe8BZxPd e2RPq6HcbqQRaOlyOav5zSEb6lZTpQQjGqSPlmRTA9+E5J8m43Hn9Oa2Tk5p96Uh dC8Ns4aL/sf0q+0FP7NYal6Rng2Sjan8jJh0cdKkdevgMK6eEicKoe/ujnMTQdJG UnFDskXvhaqmKH+ytC65vrnsRJvOtOytx107koYqDP7nInSkqvxfvM9gEmeVFShf RhGgafbdHH3RyLYsvFpFtw5uqxj7q73C9mkNBsl2gpeeffYAg3A= =N0c3 -----END PGP SIGNATURE----- --d2rex2qevvhkngd2-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv