diff options
| -rw-r--r-- | mandocdb.c | 27 | ||||
| -rw-r--r-- | mdoc.7 | 109 | ||||
| -rw-r--r-- | mdoc_macro.c | 7 | ||||
| -rw-r--r-- | mdoc_validate.c | 37 |
4 files changed, 117 insertions, 63 deletions
diff --git a/mandocdb.c b/mandocdb.c index c26a38a5f233..e8455588d225 100644 --- a/mandocdb.c +++ b/mandocdb.c @@ -1,6 +1,6 @@ -/* $Id: mandocdb.c,v 1.274 2024/05/14 21:19:12 schwarze Exp $ */ +/* $Id: mandocdb.c,v 1.275 2025/06/05 12:33:41 schwarze Exp $ */ /* - * Copyright (c) 2011-2021, 2024 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011-2021, 2024, 2025 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2016 Ed Maste <emaste@freebsd.org> * @@ -151,6 +151,8 @@ static int parse_mdoc_Fn(struct mpage *, const struct roff_meta *, const struct roff_node *); static int parse_mdoc_Fo(struct mpage *, const struct roff_meta *, const struct roff_node *); +static int parse_mdoc_Lb(struct mpage *, const struct roff_meta *, + const struct roff_node *); static int parse_mdoc_Nd(struct mpage *, const struct roff_meta *, const struct roff_node *); static int parse_mdoc_Nm(struct mpage *, const struct roff_meta *, @@ -299,7 +301,7 @@ static const struct mdoc_handler mdoc_handlers[MDOC_MAX - MDOC_Dd] = { { NULL, 0, 0 }, /* Hf */ { NULL, 0, 0 }, /* Fr */ { NULL, 0, 0 }, /* Ud */ - { NULL, TYPE_Lb, NODE_NOSRC }, /* Lb */ + { parse_mdoc_Lb, 0, 0 }, /* Lb */ { NULL, 0, 0 }, /* Lp */ { NULL, TYPE_Lk, 0 }, /* Lk */ { NULL, TYPE_Mt, NODE_NOSRC }, /* Mt */ @@ -1754,6 +1756,25 @@ parse_mdoc_Fo(struct mpage *mpage, const struct roff_meta *meta, } static int +parse_mdoc_Lb(struct mpage *mpage, const struct roff_meta *meta, + const struct roff_node *n) +{ + char *cp; + + for (n = n->child; n != NULL; n = n->next) { + if (n->flags & NODE_NOSRC) + continue; + cp = n->string; + if (n->sec == SEC_SYNOPSIS) + mandoc_asprintf(&cp, "lib%s", cp); + putkey(mpage, cp, TYPE_Lb); + if (n->sec == SEC_SYNOPSIS) + free(cp); + } + return 0; +} + +static int parse_mdoc_Va(struct mpage *mpage, const struct roff_meta *meta, const struct roff_node *n) { @@ -1,7 +1,7 @@ -.\" $Id: mdoc.7,v 1.296 2025/01/27 03:17:33 schwarze Exp $ +.\" $Id: mdoc.7,v 1.299 2025/06/13 16:18:28 schwarze Exp $ .\" +.\" Copyright (c) 2010-2021, 2024, 2025 Ingo Schwarze <schwarze@openbsd.org> .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 27 2025 $ +.Dd $Mdocdate: June 13 2025 $ .Dt MDOC 7 .Os .Sh NAME @@ -192,15 +192,13 @@ See and .Ic \&Nd . .It Em LIBRARY -The name of the library containing the documented material, which is -assumed to be a function in a section 2, 3, or 9 manual. -The syntax for this is as follows: -.Bd -literal -offset indent -\&.Lb libarm -.Ed -.Pp -See -.Ic \&Lb . +The name of the library containing the documented functions. +Using this section is no longer recommended. +If any +.Ic \&Lb +macro is needed, put it at the beginning of the +.Em SYNOPSIS +section instead. .It Em SYNOPSIS Documents the utility invocation syntax, function call syntax, or device configuration. @@ -222,11 +220,12 @@ Commands should be ordered alphabetically. .Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent +\&.Lb libname \e" unless the functions are in libc \&.In header.h \&.Vt extern const char *global; -\&.Ft "char *" +\&.Ft char * \&.Fn foo "const char *src" -\&.Ft "char *" +\&.Ft char * \&.Fn bar "const char *src" .Ed .Pp @@ -460,7 +459,8 @@ in the alphabetical .Op Fl compact .It Ic \&D1 Ta indented display (one line) .It Ic \&Dl Ta indented literal display (one line) -.It Ic \&Ql Ta in-line literal display: Ql text +.It Ic \&Ql Ta normal in-line literal display: Ql text +.It Ic \&Li Ta unquoted in-line literal display: Li text .It Ic \&Bl , \&El Ta list block: .Fl Ar type .Op Fl width Ar val @@ -491,7 +491,7 @@ in the alphabetical .El .Ss Semantic markup for function libraries .Bl -column "Brq, Bro, Brc" description -.It Ic \&Lb Ta function library (one argument) +.It Ic \&Lb Ta function library (>0 arguments) .It Ic \&In Ta include file (one argument) .It Ic \&Fd Ta other preprocessor directive (>0 arguments) .It Ic \&Ft Ta function type (>0 arguments) @@ -1270,9 +1270,9 @@ and .Ic \&Os . .Tg Dl .It Ic \&Dl Ar line -One-line indented display. -This is formatted as literal text and is useful for commands and -invocations. +One-line indented literal display. +This is formatted using a constant-width font +and is useful for commands and invocations. It is followed by a newline. .Pp Examples: @@ -1860,34 +1860,45 @@ but not the whitespace before the semicolon. See also .Ic \&Bl . .Tg Lb -.It Ic \&Lb Cm lib Ns Ar name -Specify a library. -.Pp -The -.Ar name -parameter may be a system library, such as -.Cm z -or -.Cm pam , -in which case a small library description is printed next to the linker -invocation; or a custom library, in which case the library name is -printed in quotes. -This is most commonly used in the +.It Ic \&Lb Cm lib Ns Ar name Op Cm lib Ns Ar name ... +Specify one or more libraries to link against. +Putting this macro at the beginning of the .Em SYNOPSIS -section as described in -.Sx MANUAL STRUCTURE . +section is recommended, in which case it prints this comment: +.D1 /* Fl l Ns Ar name Oo Fl l Ns Ar name ... Oc */ .Pp -Examples: -.Dl \&.Lb libz -.Dl \&.Lb libmandoc +If used outside the +.Em SYNOPSIS , +this macro prints +.D1 library Dq Cm lib Ns Ar name +instead. +For system libraries, some operating systems +print a short library description. +.Pp +Example: +.Bd -literal -offset indent -compact +\&.Sh SYNOPSIS +\&.Lb libtls libssl libcrypto +\&.In tls.h +\&.Ft int +\&.Fn tls_init void +.Ed .Tg Li .It Ic \&Li Ar word ... -Request a typewriter (literal) font. -Deprecated because on terminal output devices, this is usually -indistinguishable from normal text. -For literal displays, use -.Ic \&Ql Pq in-line , -.Ic \&Dl Pq single line , +Unquoted in-line literal display, always set in a constant-width font. +In most cases, use +.Ic \&Ql +instead because on terminal output devices, +.Ic \&Li +is usually indistinguishable from normal text. +This macro is only useful when enclosing the argument in quotes +is explicitly not desired, for example because it already stands out +due to being wrapped in another macro, e.g. in an +.Ic \&It +head. +.Pp +For longer literal displays, use +.Ic \&Dl Pq single line or .Ic \&Bd Fl literal Pq multi-line instead. @@ -2200,15 +2211,17 @@ Close quoted context opened by .Ic \&Qo . .Tg Ql .It Ic \&Ql Ar line -In-line literal display. +Normal in-line literal display, always set in constant-width font and +additionally enclosed in quotes by many formatters in many cases. This can be used for complete command invocations and for multi-word code examples when an indented display is not desired. .Pp See also -.Ic \&Dl -and +.Ic \&Dl , .Ic \&Bd -.Fl literal . +.Fl literal , +and +.Ic \&Li . .It Ic \&Qo Ar block Multi-line version of .Ic \&Qq . @@ -3024,7 +3037,7 @@ then the macro accepts an arbitrary number of arguments. .It Ic \&Hf Ta \&No Ta \&No Ta n .It Ic \&Ic Ta Yes Ta Yes Ta >0 .It Ic \&In Ta Yes Ta Yes Ta 1 -.It Ic \&Lb Ta \&No Ta \&No Ta 1 +.It Ic \&Lb Ta \&No Ta \&No Ta >0 .It Ic \&Li Ta Yes Ta Yes Ta >0 .It Ic \&Lk Ta Yes Ta Yes Ta >0 .It Ic \&Lp Ta \&No Ta \&No Ta 0 diff --git a/mdoc_macro.c b/mdoc_macro.c index 889b80a64a68..14b1ba0d228a 100644 --- a/mdoc_macro.c +++ b/mdoc_macro.c @@ -1,4 +1,4 @@ -/* $Id: mdoc_macro.c,v 1.235 2022/04/14 16:43:44 schwarze Exp $ */ +/* $Id: mdoc_macro.c,v 1.237 2025/06/13 14:24:56 schwarze Exp $ */ /* * Copyright (c) 2010, 2012-2021 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> @@ -92,7 +92,7 @@ static const struct mdoc_macro mdoc_macros[MDOC_MAX - MDOC_Dd] = { { in_line_eoln, 0 }, /* Fd */ { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Fl */ { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Fn */ - { in_line, MDOC_CALLABLE | MDOC_PARSED }, /* Ft */ + { in_line, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Ft */ { in_line, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Ic */ { in_line_argn, MDOC_CALLABLE | MDOC_PARSED }, /* In */ { in_line, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Li */ @@ -448,8 +448,7 @@ dword(struct roff_man *mdoc, int line, int col, const char *p, if (d == DELIM_MAX) d = mdoc_isdelim(p); - if (may_append && - ! (mdoc->flags & (MDOC_SYNOPSIS | MDOC_KEEP | MDOC_SMOFF)) && + if (may_append && ! (mdoc->flags & (MDOC_KEEP | MDOC_SMOFF)) && d == DELIM_NONE && mdoc->last->type == ROFFT_TEXT && mdoc_isdelim(mdoc->last->string) == DELIM_NONE) { roff_word_append(mdoc, p); diff --git a/mdoc_validate.c b/mdoc_validate.c index c4c8aecfa71e..659ed5fba336 100644 --- a/mdoc_validate.c +++ b/mdoc_validate.c @@ -1,6 +1,6 @@ -/* $Id: mdoc_validate.c,v 1.391 2022/06/08 16:31:46 schwarze Exp $ */ +/* $Id: mdoc_validate.c,v 1.393 2025/06/05 12:38:26 schwarze Exp $ */ /* - * Copyright (c) 2010-2021 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2022, 2025 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> * @@ -991,18 +991,39 @@ post_ex(POST_ARGS) static void post_lb(POST_ARGS) { - struct roff_node *n; - const char *p; + struct roff_node *n, *nch; + const char *ccp; + char *cp; post_delim_nb(mdoc); n = mdoc->last; - assert(n->child->type == ROFFT_TEXT); + nch = n->child; + assert(nch->type == ROFFT_TEXT); mdoc->next = ROFF_NEXT_CHILD; - if ((p = mdoc_a2lib(n->child->string)) != NULL) { + if (n->sec == SEC_SYNOPSIS) { + roff_word_alloc(mdoc, n->line, n->pos, "/*"); + mdoc->last->flags = NODE_NOSRC; + while (nch != NULL) { + roff_word_alloc(mdoc, n->line, n->pos, "-l"); + mdoc->last->flags = NODE_DELIMO | NODE_NOSRC; + mdoc->last = nch; + assert(nch->type == ROFFT_TEXT); + cp = nch->string; + if (strncmp(cp, "lib", 3) == 0) + memmove(cp, cp + 3, strlen(cp) - 3 + 1); + nch = nch->next; + } + roff_word_alloc(mdoc, n->line, n->pos, "*/"); + mdoc->last->flags = NODE_NOSRC; + mdoc->last = n; + return; + } + + if ((ccp = mdoc_a2lib(n->child->string)) != NULL) { n->child->flags |= NODE_NOPRT; - roff_word_alloc(mdoc, n->line, n->pos, p); + roff_word_alloc(mdoc, n->line, n->pos, ccp); mdoc->last->flags = NODE_NOSRC; mdoc->last = n; return; @@ -3057,6 +3078,6 @@ macro2len(enum roff_tok macro) return 10; default: break; - }; + } return 0; } |