help / color / mirror / Atom feed
From: Robert Mustacchi <rm@fingolfin.org>
To: discuss@mandoc.bsd.lv
Subject: Proper Macro for Types
Date: Sat, 29 Jan 2022 09:12:31 -0800	[thread overview]
Message-ID: <55d4f359-c30a-7df1-2e35-33f73f3c52f4@fingolfin.org> (raw)

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

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.

 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

             reply	other threads:[~2022-01-29 17:12 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-29 17:12 Robert Mustacchi [this message]
2022-03-12  1:49 Paul A. Patience

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=55d4f359-c30a-7df1-2e35-33f73f3c52f4@fingolfin.org \
    --to=rm@fingolfin.org \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: Proper Macro for Types' \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).