Re: CVS commit: src/share/man/man5

[Luke Mewburn <luke%mewburn.net@localhost>]

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.