On 23-06-11 14:14, Valery Ushakov wrote:
| On Sun, Jun 11, 2023 at 10:44:33 +0000, Luke Mewburn wrote:
|
| > Module Name: src
| > Committed By: lukem
| > Date: Sun Jun 11 10:44:33 UTC 2023
| >
| > Modified Files:
| > src/share/man/man5: mk.conf.5
| >
| > Log Message:
| [...]
| > Change sub headings to headings; it's easier to read.
| > (I don't know why mdoc doesn't allow blank lines around .Ss)
|
| I'm not sure what do you mean. The difference between .Ss and .Sh is
| only the indent:
|
| ----8<----[ .Ss ]----8<----
| ...
| the system.
|
| NetBSD System Variables
| Listed below are the mk.conf variables that may be set that affect the
| ...
| ----8<--------8<----
|
| vs.
|
| ----8<----[ .Sh ]----8<----
| ...
| the system.
|
| NetBSD System Variables
| Listed below are the mk.conf variables that may be set that affect the
| ...
| ----8<--------8<----
|
| Both have a blank line before and no blank line after.
Ahh, you're right, I misspoke. Tired brain when working on the commit.
IMHO, they both suffer from lack of blank line there, where personally I
would prefer the blank line, especially before a list, and especially
for .Ss because its indent is only 2 in from the main paragraph. But I'm
not considering an mdoc change for that any time soon.
Compare:
----8<----[ old ]----8<----
DESCRIPTION
The mk.conf file overrides various parameters used during the build of
the system.
Listed below are the mk.conf variables that may be set, the values to
which each may be set, a brief description of what each variable does,
and a reference to relevant manual pages.
NetBSD System variables
BSDOBJDIR The real path to the object directory tree for the NetBSD
source tree.
----8<--------8<----
vs using .Sh (for outdenting) and a textual para before:
----8<----[ new ]----8<----
DESCRIPTION
The mk.conf file overrides various parameters used during the build of
the system.
NETBSD SYSTEM VARIABLES
Listed below are the mk.conf variables that may be set that affect the
NetBSD NetBSD system build, the values to which each may be set, a brief
description of what each variable does, references to relevant manual
pages, notes (including any interaction with build.sh), and the default
value of each variable.
BSDOBJDIR The real path to the object directory tree for the NetBSD
source tree.
----8<--------8<----
For me, having a para before it and the outdented heading makes the BSDOBJDIR
"pop" more in a quick eyeball scan, plus easier section searching.
YMMV.
My goal is to get the mk.conf(5) up to date and correct, and more usable.
I intend to remove the duplication in BUILDING and bsd.README
and refer back to mk.conf(5) to avoid the copypasta, with some updated
boilerplate in BUILDING to describe how to find the referenced manual pages
within BUILDING if you're not on an NetBSD system.
Luke.
