From nobody Mon Nov 22 21:20:53 2021 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id B22B518939EC for ; Mon, 22 Nov 2021 21:21:08 +0000 (UTC) (envelope-from rockyhotas@firemail.cc) Received: from mail.cock.li (mail.cock.li [37.120.193.124]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4HygDf1BXKz3QmR for ; Mon, 22 Nov 2021 21:21:05 +0000 (UTC) (envelope-from rockyhotas@firemail.cc) Date: Mon, 22 Nov 2021 22:20:53 +0100 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=firemail.cc; s=mail; t=1637616056; bh=z8YXFV6InwFYq6sbsMyj1JY38FBTJcnkwfRebxubK2U=; h=Date:From:To:Subject:Reply-To:From; b=cG3FBWlt6V07mP3ijE14x6VxhvUbO9WjtIxwXitRSlFNCqSRgyfa2klzM4o+Lw8GB 7l3rduCF+qKRhy/Znp7hAmLBzwSH+mJL0yTx8vxoSC3K97Lalgs9ksg62JJAZGpF3C RRZxN3vmbqbH3My7F0uSxZPPt5686cwEyul4Qcgmcr5R3iGpTthjEveBUFCWs+2Ass tsXFmfvmohoj7EI/4ADF5Moh+Si+HJA5mZZRLJprdcURNsEbvsy8d8zmGtDDnajW1X 63k3b17/DM4f858QmKjVQJly23LnOaW6JqFQ0dfp1LAA6NQgmhLJ8bwzaabMz/kLF7 pqWbJFzCd/28Q== From: Rocky Hotas To: freebsd-doc@FreeBSD.org Subject: mdoc macro to mention packages in manpages Message-ID: <20211122212053.rtyfct52k26kl3lb@delpotro> Reply-To: Rocky Hotas List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline X-Rspamd-Queue-Id: 4HygDf1BXKz3QmR X-Spamd-Bar: - Authentication-Results: mx1.freebsd.org; dkim=pass header.d=firemail.cc header.s=mail header.b=cG3FBWlt; dmarc=none; spf=pass (mx1.freebsd.org: domain of rockyhotas@firemail.cc designates 37.120.193.124 as permitted sender) smtp.mailfrom=rockyhotas@firemail.cc X-Spamd-Result: default: False [-1.73 / 15.00]; HAS_REPLYTO(0.00)[rockyhotas@firemail.cc]; ARC_NA(0.00)[]; R_DKIM_ALLOW(-0.20)[firemail.cc:s=mail]; REPLYTO_EQ_FROM(0.00)[]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; R_SPF_ALLOW(-0.20)[+ip4:37.120.193.120/29]; MIME_GOOD(-0.10)[text/plain]; TO_DN_NONE(0.00)[]; DMARC_NA(0.00)[firemail.cc]; RCPT_COUNT_ONE(0.00)[1]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_MEDIUM(-0.96)[-0.956]; NEURAL_SPAM_SHORT(0.23)[0.228]; DKIM_TRACE(0.00)[firemail.cc:+]; RCVD_COUNT_ZERO(0.00)[0]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; MID_RHS_NOT_FQDN(0.50)[]; ASN(0.00)[asn:9009, ipnet:37.120.193.0/24, country:GB]; RWL_MAILSPIKE_POSSIBLE(0.00)[37.120.193.124:from] X-ThisMailContainsUnwantedMimeParts: N Hello! It seems that the current manpages do not use a standard, uniform way to mention a package/port name. I'm not very skilled about mdoc(7), but after some `zgrep' in /usr/share/man/man* (as suggested in par. `10.3.5. Important Macros' in the Handbook), I found several different solutions. Descriptions are from mdoc(7): - `Pa' (``An absolute or relative file system path, or a file or directory name'') - `Dv' (``Defined variables such as preprocessor constants, constant symbols, enumeration values, and so on'') - `Sy' (``Request a boldface font'', but also: ``When none of the semantic macros fit, it is also adequate for syntax elements that have to be given or that appear verbatim'') - `Sq' (``Encloses its arguments in `typewriter' single-quotes'') - `Fa' (``Function argument or parameter'' Maybe there is no specific macro to show a package/port. `Pa' has probably been more frequently used. Which is the most correct macro to be used? (Not necessarily between the ones above). And should also the category of the package/port be shown (for example, `devel/cloudabi-toolchain') or not? Any suggestion is welcome. Bye! Rocky