From: schwarze@mandoc.bsd.lv
To: source@mandoc.bsd.lv
Subject: mandoc: Simplify and clarify instructions for .Ql, and deprecate .Li.
Date: Sun, 23 Dec 2018 11:56:05 -0500 (EST) [thread overview]
Message-ID: <05f6816702c04943@fantadrom.bsd.lv> (raw)
Log Message:
-----------
Simplify and clarify instructions for .Ql, and deprecate .Li.
The macros .Ql, .Dl, and .Bd -literal leave no room for any
valid use case for .Li whatsoever.
General direction discussed with jmc@.
Modified Files:
--------------
mandoc:
mdoc.7
Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
retrieving revision 1.272
retrieving revision 1.273
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.272 -r1.273
--- mdoc.7
+++ mdoc.7
@@ -522,7 +522,6 @@ in the alphabetical
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
-.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
.It Sx \&No Ta return to roman font (normal) (no arguments)
.It Sx \&Bf , \&Ef Ta font block:
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy
@@ -1474,9 +1473,8 @@ to save the pattern space for subsequent
.Ed
.Pp
See also
-.Sx \&Bf ,
-.Sx \&Li ,
.Sx \&No ,
+.Sx \&Ql ,
and
.Sx \&Sy .
.Ss \&En
@@ -1776,12 +1774,13 @@ Examples:
.Dl \&.Ic alias
.Pp
Note that using
-.Sx \&Bd Fl literal
+.Sx \&Ql ,
+.Sx \&Dl ,
or
-.Sx \&D1
-is preferred for displaying code; the
+.Sx \&Bd Fl literal
+is preferred for displaying code samples; the
.Sx \&Ic
-macro is used when referring to specific instructions.
+macro is used when referring to an individual command name.
.Ss \&In
The name of an include file.
This macro is most often used in section 2, 3, and 9 manual pages.
@@ -1915,21 +1914,15 @@ Examples:
.Dl \&.Lb libz
.Dl \&.Lb libmandoc
.Ss \&Li
-Denotes text that should be in a
-.Li literal
-font mode.
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
-.Pp
-On terminal output devices, this is often indistinguishable from
-normal text.
-.Pp
-See also
-.Sx \&Bf ,
-.Sx \&Em ,
-.Sx \&No ,
-and
-.Sx \&Sy .
+Request a typewriter (literal) font.
+Deprecated because on terminal output devices, this is usually
+indistinguishable from normal text.
+For literal displays, use
+.Sx \&Ql Pq in-line ,
+.Sx \&Dl Pq single line ,
+or
+.Sx \&Bd Fl literal Pq multi-line
+instead.
.Ss \&Lk
Format a hyperlink.
Its syntax is as follows:
@@ -2046,7 +2039,7 @@ Examples:
.Pp
See also
.Sx \&Em ,
-.Sx \&Li ,
+.Sx \&Ql ,
and
.Sx \&Sy .
.Ss \&Ns
@@ -2244,14 +2237,8 @@ Close quoted context opened by
.Sx \&Qo .
.Ss \&Ql
In-line literal display.
-This can for example be used for complete command invocations and
-for multi-word code fragments when more specific markup is not
-appropriate and an indented display is not desired.
-While
-.Xr mandoc 1
-always encloses the arguments in single quotes, other formatters
-usually omit the quotes on non-terminal output devices when the
-arguments have three or more characters.
+This can be used for complete command invocations and for multi-word
+code examples when an indented display is not desired.
.Pp
See also
.Sx \&Dl
@@ -2655,11 +2642,10 @@ program.
.Ed
.Pp
See also
-.Sx \&Bf ,
.Sx \&Em ,
-.Sx \&Li ,
+.Sx \&No ,
and
-.Sx \&No .
+.Sx \&Ql .
.Ss \&Ta
Table cell separator in
.Sx \&Bl Fl column
--
To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv
reply other threads:[~2018-12-23 16:56 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=05f6816702c04943@fantadrom.bsd.lv \
--to=schwarze@mandoc.bsd.lv \
--cc=source@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).