source@mandoc.bsd.lv
 help / color / mirror / Atom feed
* mandoc: Weaken the recommendation to use conventional sections; the
@ 2025-01-27  3:18 schwarze
  0 siblings, 0 replies; only message in thread
From: schwarze @ 2025-01-27  3:18 UTC (permalink / raw)
  To: source

Log Message:
-----------
Weaken the recommendation to use conventional sections; the wording
"absolutely necessary" was an exaggeration that confused people.  
I noticed this problem because <onf at disroot dot org> quoted 
the text on the groff mailing list.

While here, strengthen the recommendation to not use macros inside
title lines of sections and subsections, and to keep title lines unique.

Feedback and OK jmc@

Modified Files:
--------------
    mandoc:
        mdoc.7

Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.295 -r1.296
--- mdoc.7
+++ mdoc.7
@@ -2297,13 +2297,14 @@ Close single-quoted context opened by
 Begin a new section.
 For a list of conventional manual sections, see
 .Sx MANUAL STRUCTURE .
-These sections should be used unless it's absolutely necessary that
-custom sections be used.
-.Pp
-Section names should be unique so that they may be keyed by
-.Ic \&Sx .
-Although this macro is parsed, it should not consist of child node or it
-may not be linked with
+Use the conventional sections where applicable.
+For unusually long and complicated manual pages,
+adding custom sections is occasionally useful.
+.Pp
+Avoid using macros inside the
+.Ar TITLE LINE
+and keep that line unique within the manual page,
+such that it can be pointed to with
 .Ic \&Sx .
 .Pp
 See also
@@ -2353,10 +2354,10 @@ the conventional sections described in
 .Sx MANUAL STRUCTURE
 rarely have subsections.
 .Pp
-Sub-section names should be unique so that they may be keyed by
-.Ic \&Sx .
-Although this macro is parsed, it should not consist of child node or it
-may not be linked with
+Avoid using macros inside the
+.Ar Title line
+and keep that line unique within the manual page,
+such that it can be pointed to with
 .Ic \&Sx .
 .Pp
 See also
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2025-01-27  3:18 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2025-01-27  3:18 mandoc: Weaken the recommendation to use conventional sections; the schwarze

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).