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=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 21695 invoked from network); 29 Jan 2022 17:12:42 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 29 Jan 2022 17:12:42 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id dc787376 for ; Sat, 29 Jan 2022 12:12:37 -0500 (EST) Received: from wnew1-smtp.messagingengine.com (wnew1-smtp.messagingengine.com [64.147.123.26]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 73ca0233 for ; Sat, 29 Jan 2022 12:12:34 -0500 (EST) Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailnew.west.internal (Postfix) with ESMTP id 623AA2B00068 for ; Sat, 29 Jan 2022 12:12:33 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute5.internal (MEProxy); Sat, 29 Jan 2022 12:12:33 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=fingolfin.org; h=cc:content-transfer-encoding:content-type:date:date:from:from :in-reply-to:message-id:mime-version:reply-to:sender:subject :subject:to:to; s=fm1; bh=LMKeQpkRCBcAs7VG6oUamfeUYkeMi5EOp//esn spMUY=; b=YuFF4JmDQ+r5zN8VM1CnLyKeZHcqulihjpFzp4dPeJpNsQIQzXh6Ey h0quTGOWcLZMijkF+POVz6sIZmYEOOFdLnAOTJMdXhAqtmuPubmx6McsmiobvThp CZOwvP9dvYrJZS7UeJZ/ojZeczwaeeF93A6phsJHZq7KSHHHABzWJisComwe2Hxt NXYLc2DpVf03raqBPD/5lPpsKjTcS9BPv7WJzXIVXqv62wTDBApN/jziNnSxbHNZ uJboh0ZxF+CU+gbkBjfJ2MljjiYakPBOnbtknruezdQeNk7FmRuFSULgRtAnf9rR sf4IiNzrwehJiaM+fiN3BAtNSo3HLoXw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:date:from:from:in-reply-to:message-id:mime-version :reply-to:sender:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=LMKeQpkRCBcAs7VG6 oUamfeUYkeMi5EOp//esnspMUY=; b=HzJojU77WVc1ADV1YEx+dfdu8bs123x+W zym1Pc7s8VKws5Dl+j+AVptHS5/n0eGvS8tXq5dbngbiZNPeIzgnpL/Ki9SuC204 WFDCOiSG01jOuGjOPETKCocwj8y4s5NeXnK67RK6oTeATQVOOxo+LsRPROIDGTve rmBd2LUCPBHrkiGNBYFYbP+A4w5BxNpJvhdaDltzTYcKIwb2tdiSntXtdz7ccIRU uZF7jfwevSMhBQZHJ+AlI3+SPXA5qG9I2cnOewl9Okb91MY+gJJPY5333V+9I3DL sAIX5ysm4WlGR+tj8k7f+6wWc6Uj1TU2UMxB+0V3OZkOVTk9GBO5g== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvvddrfeejgddutddtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefkffggfgfvhffutgfgsehtjeertd dtfeejnecuhfhrohhmpeftohgsvghrthcuofhushhtrggttghhihcuoehrmhesfhhinhhg ohhlfhhinhdrohhrgheqnecuggftrfgrthhtvghrnhepieegtdeiveeufeeffffghfdvgf effedvjeelvdfhfffgjeeltdehvefgtdejfedtnecuvehluhhsthgvrhfuihiivgeptden ucfrrghrrghmpehmrghilhhfrhhomheprhhmsehfihhnghholhhfihhnrdhorhhg X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA for ; Sat, 29 Jan 2022 12:12:32 -0500 (EST) Message-ID: <55d4f359-c30a-7df1-2e35-33f73f3c52f4@fingolfin.org> Date: Sat, 29 Jan 2022 09:12:31 -0800 X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.5.0 Content-Language: en-US To: discuss@mandoc.bsd.lv From: Robert Mustacchi Subject: Proper Macro for Types Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Hi there, While guiding new folks through writing manual pages in illumos, there is one area that comes up frequently and generates a little confusion for folks, which is the proper markup for the name of a type (generally a structure, but could be a typedef) and for members/fields of structures. The mdoc(7) manual makes the latter of these pretty obvious with the use of .Fa with "This macro is also used to specify the field name of a structure." When it comes to types themselves more generally, it's a little less clear. We have .Ft and .Vt, which deal with types that are part of a function synopsis (or related to the function in later prose) and the latter is meant to deal with an explicit variable type. However, in a lot of the illumos documentation we are often discussing a structure or type that is not always directly related to a function signature or global variable (for example, because we're in an overview section). As an attempt at a more concrete example, consider a discussion of a file system (illumos has chapters on various file systems, ioctl interfaces, etc.) and wanting to discuss a time_t (or some other time related C structure). In this context there is no function or variable that is being referred to. For types which are not directly related to a function or variable, in illumos we've been using .Vt. Is this correct? If not, what is the right macro to use? Either way could we perhaps add a statement to mdoc(7) about the right macro to use for this? The statement regarding .Fa has been very helpful and makes it quite clear what to do. Thanks, Robert -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv