From nobody Sat Feb 21 20:40:18 2026 X-Original-To: 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 4fJJsX246Wz6SDlQ for ; Sat, 21 Feb 2026 20:40:32 +0000 (UTC) (envelope-from adrian.chadd@gmail.com) Received: from mail-qv1-f41.google.com (mail-qv1-f41.google.com [209.85.219.41]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4fJJsX0Z9nz3HwX for ; Sat, 21 Feb 2026 20:40:32 +0000 (UTC) (envelope-from adrian.chadd@gmail.com) Authentication-Results: mx1.freebsd.org; none Received: by mail-qv1-f41.google.com with SMTP id 6a1803df08f44-8947404b367so36780006d6.3 for ; Sat, 21 Feb 2026 12:40:32 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1771706431; cv=none; d=google.com; s=arc-20240605; b=JJroqjuVBsmPjDRTgyH2DPlEPGaNqFnJpk31nESxBdhqN81tDKMHLxxi5E+gksYSbu kulo8eADYOzZK883ZXWdKOgyV40pKrz8snXeQkYGC1js5prVtIPcEsjs9XIxNNW30mkL SrozOdBj0iAFbnAxZLKkOfSv+DMW8b98AE1Szvw6USEDEPIpXeeU/n5PTkBqBjOrpJl/ Nnfpop371MiByFxHw26BcR/ANS6N4eFQZuZwcioY1qP6yoSG2IenBlrwW/HKzxghQaHG Wt/aQmsFWhe+3MgMTj2m2dotuDhann6xUdGotTkKyJpCN8gafNTyXeSMhjii9RgCQ/zL V+pg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version; bh=JF6j8ICxSG9WxxkrNbtSl5EzSmUhs1+P0RGeU2Jo5Nc=; fh=DRHPNr4K+xMkkAeYfSzaUNXhG67ANNN+lnacs6OWBL0=; b=gPwv5PLhCpRd8FK6F+9aSLnXNDIIQnQV6zCD0YuxHio4kIe0TNUWY3R9exir+A5XBi 5f2Pwgd+shzlOkyUsZujQEuCbbqG07GbWFruSQSILeOk5w9YouVB2x8DrshAXhxLwAC2 F0e61XwVfcw+mvt3t35TXdsNuoI/vIS97l0hIYYwNWQMaawWVwNfwv3+pCIMwS8oOi6p jCIOe5QfqoVJCblCS7SmC2pjPsg44ovH9c1D5AcH0rKrYKvs4mVZ+kCj7NrPlehlosVR rAFGAxFR/3s2T9f9wVZqzKF37OzbHLde57AnUNFljnvQ8Q5vasbBbSfly+1J/i7kghYx r9kA==; darn=freebsd.org ARC-Authentication-Results: i=1; mx.google.com; arc=none X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1771706431; x=1772311231; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=JF6j8ICxSG9WxxkrNbtSl5EzSmUhs1+P0RGeU2Jo5Nc=; b=eKn/VlObUjMSjQWTtyIhAIxF7yXgW4G1DeBYOlTAtDQ2rl67U16mvN4p00kBby4bbQ wOtT7LBuDP0fsrbPr8dz/PTvZ2QIpxyYNxZlOmVDiFPXd+tkv9R+COPb4xluQB+g4WD4 4+CbdIm8Yl+6B/nQSSjlqyQYkrNT/RGwU/8PTSeYtCghmCZp5FUkvTKnIYXBbsd1mHHD IVmu3PTdGH2vQi1QKqie9ocnReZZiHKhf/ZTast/pe5UkgBC8lXZhuHOEqZEaH6ihuNP ALZWquo64z0Q0b7Q3frKEvxn2xmS9OjgORcjjCZSnfWtdbcvTykN5tGjRQUE9O9kOGuW dw7Q== X-Forwarded-Encrypted: i=1; AJvYcCUixj+kvUXLVIfnlv145UHPSgslq4QZNAZh/GKJTSaAiyjQcBYPVQlPioRPdA6neghtz3c=@freebsd.org X-Gm-Message-State: AOJu0YxctqsiMQ5REYgESBpbCsg2PczXBjSNevx9ZCLcypOm/7PjkEDr NCrVY4MWaoAKDgiTHawLrbPd8RYrB/YsHTI7kFB2yPg+GRlM1qOTjahXYtbxRUWegz8kwy40NJA 1DJR/3Gk5uL4n5AF5Eap7aLsHtlYUrVk= X-Gm-Gg: AZuq6aK/MzO71n27VsQSImnN7dW/quHV2f683Kj3uxQim44jxreqQ0zEa+dkpTlJ890 gu4xA2RExd/gkyZ6RZFiZG0Y08OUk1rS2vukJCd1WPtxRHXymo/9qRowuGPjTvz2M1gm53WA4MV fXWFOSclqnNkn+VmR2kvwMn9XhjWeo5v4/54WTH17NVKPQwWl8OjHm0rYlWge/iSld88evVd30N QQDaNsBzOjGswIkmjuHkoXGygfZ6vcwTPoZGMWb83Rr2xC3hczvMHTXUEHP1P3C00qf4W0Goivk 0WuOh98ErApPq3NsAF8PpmKM/+bFD8URbD5tJc9sfgOk6YRgDtAl0L4ncKgvW11szoXZV+TKgQU 2BKtrCBAKuZKPumbQG65himIl9poHyoadZ0r+aEmbkK+9QNUFFx74ynsupMs1Kwszc7OZ X-Received: by 2002:ad4:5c6b:0:b0:895:49e5:c55f with SMTP id 6a1803df08f44-89979d3b42emr67757366d6.32.1771706431000; Sat, 21 Feb 2026 12:40:31 -0800 (PST) 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 References: <699a0480.48403.1557781e@baud> In-Reply-To: <699a0480.48403.1557781e@baud> From: Adrian Chadd Date: Sat, 21 Feb 2026 12:40:18 -0800 X-Gm-Features: AaiRm536rB364KOYaPZUDJE7Zy6Hzx0GVbtrArsbjahAfDSNA49Kz4uJLBEs_8Y Message-ID: Subject: Re: man: Merging LIBRARY and SYNOPSIS To: ziaee@freebsd.org Cc: arch@freebsd.org, doc@freebsd.org, ivy@freebsd.org, kib@freebsd.org Content-Type: text/plain; charset="UTF-8" X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; TAGGED_FROM(0.00)[]; ASN(0.00)[asn:15169, ipnet:209.85.128.0/17, country:US] X-Rspamd-Queue-Id: 4fJJsX0Z9nz3HwX X-Spamd-Bar: ---- On Sat, 21 Feb 2026 at 11:16, wrote: > > hello, > > i want to merge the library section into the synopsis section in the > rest of our manuals, following changes to the mdoc language upstream > in mandoc and groff that shipped in 15.0-R and the upcoming 14.4-R. > this represents the cross-platform evolution of the over half-century > old tradition of unix manual pages in 21st century q2. > > i want to switch the rest of them over all at once; with this change: > + how to link the library is still shown on the same line > + duplicate info and an empty line is freed for information > + synopsis is strengthened as the "just how to use it" section > + description is strengthened as "describe what it is" section > + doing what everyone else is doing lowers the load on everyone > + we're cleanly implementing the absolute cutting-edge technology > > i sent a mail to doc@ last july when i imported the change to mandoc. > no one responded, and we shipped a few manuals this way in 15.0/14.4. > so far kib and ivy said they didn't really like it but neither objected. > > here is a draft attempting to do this for the c library as an example: > https://reviews.freebsd.org/D55411.diff > What's this buy us vs cost us? Like, having a LIBRARY section means we can build an index on all pages that have a library section in common? -adrian